사용하기는 쉽다. 하지만, 그 내부 메커니즘이 궁금해진다
pstack은 Cursor의 공식 플러그인 중 하나입니다. /poteto-mode에 태스크를 전달하면, 에이전트가 절차를 선택하고 작업을 수행하며 실제 결과물로 확인하는 단계까지 진행합니다.
사용만 한다면 헤맬 부분이 없습니다. 무엇을 하든 /poteto-mode에 넘겨주기만 하면 되며, 어떤 스킬을 사용할지는 에이전트가 결정해 줍니다. 하지만 저는 아무래도 내부 메커니즘이 너무 궁금했습니다.
지난 글에서는 pstack이 어떻게 만들어져 왔는지 추적했습니다. 이번에는 내부 메커니즘에 초점을 맞춰, 스킬 간의 참조 관계를 한 장으로 그려보았습니다. 전체는 3개의 레이어와 옆에 놓인 도구 상자로 구성되어 있습니다.
pstack은 3개의 레이어와 도구 상자로 이루어져 있다
3개의 레이어는 진입점인 /poteto-mode, 태스크별 절차서인 Playbook, 그리고 판단의 규칙 원칙입니다. 그 옆에 도구 상자가 있습니다. 구성 요소 수는 다음과 같습니다 (v0.15.25 기준).
**/poteto-mode**는 무엇이든 받아들이는 pstack의 진입점입니다. 여기에는 원칙 인덱스와 Playbook 목록이 들어 있습니다.
Playbook은 태스크별 절차서입니다. /poteto-mode는 태스크에 맞는 것을 하나 선택하여, 그 절차에 따라 작업을 진행합니다. 예를 들면 다음과 같은 것들이 있습니다.
- Bug fix: 버그 수정
- Feature: 기능 추가
- Investigation: 조사(코드 변경 없이 탐색)
**원칙(Principle)**은 판단의 근거가 되는 규칙이며, 하나하나가 하나의 스킬이 됩니다. 예를 들면 다음과 같은 것들이 있습니다.
- Fix Root Causes: 증상이 아닌 근본 원인을 고치기
- Prove It Works: 실제 작동 여부를 확인하기
- Subtract Before You Add: 추가하기 전에 먼저 불필요한 것을 덜어내기
인덱스에는 원칙별로 '언제 사용해야 하는지'가 짧게 적혀 있습니다. 에이전트는 이것을 보고, 해당하는 원칙의 본문만 읽으러 갑니다. Playbook 역시 23개 중 15개가 절차 내에서 사용할 원칙을 지정하고 있습니다.
**도구 상자(Toolbox)**는 나머지 단독 스킬입니다. 절차나 /poteto-mode 본체에서 호출되는 것들로는 다음과 같은 것이 있습니다.
/how: 메커니즘을 설명하기/why: 왜 그렇게 되었는지 히스토리에서 조사하기/architect: 코드를 작성하기 전에 타입과 구성을 결정하기
도구 상자에는 절차를 통해 호출되지 않고, 사람이 직접 입력하여 사용하는 것들도 있습니다.
/teach: 이해할 때까지 설명하기/recall: 과거 채팅에서 작업의 맥락을 복원하기
태스크를 전달하면 어떻게 흐르는가
/poteto-mode가 태스크를 받은 후의 기본 흐름은 어떤 태스크에서도 동일합니다.
적합한 Playbook이 없으면, /figure-it-out이라는 스킬이 그 자리에서 절차서를 만듭니다.
에이전트는 절차서에 없는 원칙도 사용합니다. 인덱스는 태스크 초반에 읽습니다. 해당하는 원칙이 있으면, 그 본문도 읽습니다. 작업이 끝나면 에이전트는 작업 보고를 반환하며, 사용한 원칙이 있다면 그 이름과 그것으로 인해 바뀐 판단까지 기록합니다.
예시: 버그 수정을 전달했을 경우
README에 있는 예를 한국어로 번역하여 사용했습니다.
/poteto-mode 이 PR에, 아무것도 하지 않아도 750ms마다 스크롤이 어긋나는 버그가 있다.
먼저 재현한 다음, 고치고 확인해라.
/poteto-mode는 이것을 Bug fix Playbook으로 분류하고, 6개의 절차를 할 일 목록(todo list)에 표시합니다. todo list는 에이전트가 작업 중에 화면에 보여주는 '할 것 목록'입니다. 절차가 순서대로 나열되므로, 현재 어디까지 진행 중인지 알 수 있습니다.
- 버그가 발생하는 것을 실제로 확인하기
- 원인을 좁히기 (
/how, /why로 가설 세우기) - 수정 계획하기 (필요하다면 /architect)
） - 동일한 환경에서 버그가 발생하지 않았음을 확인한다
- 버그가 발생하는 것을 보여주는 테스트 등을 먼저 커밋하고, 수정 사항을 그 위에 쌓는다 (원칙의 Sequence Work into Verifiable Units 지정)
- PR(Pull Request)을 열기 위한 플레이북 'Opening a PR'로 이동
예문에서는 재현과 확인까지 요청하지만, 요청하지 않아도 흐름은 같습니다. 절차 1과 절차 4에 이미 포함되어 있습니다.
원인을 좁힐 때는, 절차서에 없는 Fix Root Causes(근본 원인 수정)도 색인을 보고 사용합니다.
마지막으로, 무엇이 고장 났는지, 근본 원인, 수정 사항, 그리고 어떻게 확인했는지를 나열한 작업 보고서를 제출합니다.
내용을 읽으려면 이 순서가 충분하다
시스템을 알고 싶어진 사람들을 위해 읽는 방법도 적어둡니다.
/poteto-mode
의 SKILL.md. 특히 원칙 색인과 플레이북 목록 - 자신의 작업에 가까운 플레이북 1개
- 원칙은, 작업 보고서에 이름이 언급되면 그때 읽는다
다음 시간에는, 월 2,500건의 PR을 내는 작성자가 pstack으로 무엇에 집착하는지 살펴보겠습니다.
참고
- pstack (cursor/plugins)
- pstack v0.15.25 (cursor/plugins): 본 기사에서 읽은 버전
Route work through /poteto-mode: 공식 가이드의
/poteto-mode
챕터 - pstack의 미스터리를 풀다: Cursor의 폭속 개발을 지탱하는 스킬은 어떻게 만들어졌는가: 지난 기사. pstack이 어떻게 만들어져 왔는지
Discussion
