pstack

무엇인가

pstack은 AI 코딩 에이전트가 코드를 작성·수정·검증하는 전 과정에 적용할 절차와 판단 기준을 파일 묶음으로 주입하는 스킬 팩이다. 단일 규칙 파일이 아니라 `skills/<이름>/SKILL.md` 형태의 독립 스킬 여러 개로 구성되며, 각 스킬은 재현, 테스트 우선 작성, 타입 규범, 리뷰 응답, 벤치마크 판정, 서브에이전트 분업 같은 서로 다른 작업 국면을 담당한다. 규율하는 대상은 코드 자체가 아니라 에이전트의 작업 순서다. 무엇을 먼저 확인하고, 어떤 근거가 있어야 수정을 시작하며, 언제 멈추고 사람에게 되돌릴지를 규칙으로 고정한다. 결과물의 목표는 코드 줄 수의 증가가 아니라 검증 가능한 변경의 밀도다. 저장소는 Cursor 플러그인 `cursor/plugins/pstack`의 독립 미러로 유지되며, Cursor 없이도 임의의 하네스에서 동작하도록 재작성된 사본을 함께 배포한다.

어떻게 동작하나

이 규칙이 없을 때 나타나는 실패는 대체로 세 가지다. 첫째, 요청 범위를 넘는 변경이다. 버그 하나를 고치라는 지시에 주변 함수의 이름을 바꾸고 추상화 계층을 새로 만들며, diff가 검토 불가능한 크기로 커진다. 둘째, 검증 없는 완료 선언이다. 재현 절차를 세우지 않은 채 추측으로 수정하고 수정했다는 문장으로 끝내며, 실제로 문제가 사라졌는지 확인하지 않는다. 셋째, 근거 없는 확신이다. 테스트를 돌리지 않았는데 통과했다고 쓰거나, 실패한 검사를 언급하지 않고 요약한다. pstack은 이 세 가지를 각각 다른 스킬의 하드 제약으로 분리해 막는다. 재현 스킬은 수정 전에 실패를 관찰하도록 요구하고, 테스트 우선 스킬은 구현보다 테스트를 먼저 쓰게 하며, 작업 보고 스킬은 무엇을 확인했고 무엇을 확인하지 못했는지 구분해 쓰게 한다.

무엇과 다른가

각 규칙은 권고가 아니라 통과 조건으로 쓰인다. 가능하면 테스트를 작성하라는 문장이 아니라, 테스트가 실패하는 것을 먼저 관찰하지 않으면 구현 단계로 넘어갈 수 없게 배치한다. 이 형태를 택한 이유는 에이전트가 문장형 권고를 요약 과정에서 흘려보내기 때문이다. 절차의 순서 자체를 제약으로 만들면 규칙을 잊는 대신 단계가 막힌다. 예외도 같은 원리로 명시한다. 외부 규칙(의존성, 플랫폼, 프로토콜)에 대한 주석은 검사할 수 없을 때 삭제하지 않고 검토 표시를 남기도록 미러에서 수정되었고, 리뷰가 거부되어도 전체 실행이 중단되지 않게 바뀌었다. 판단이 필요한 지점에서는 규칙이 결론을 강제하지 않고 근거를 남기게 한다. 즉 규칙은 무엇을 하라보다 무엇을 확인하지 않으면 진행할 수 없다의 형태로 설계되어 있다.

어떻게 쓰나

배포 형태는 평범한 폴더다. `skills/<스킬명>/SKILL.md`가 각 스킬의 본문이고, 여기에 절차 단계와 판정 기준이 들어간다. 별도 런타임이나 빌드 산출물이 필요하지 않으며, `npx skills add backnotprop/pstack`이 이 폴더를 선택한 에이전트의 스킬 디렉터리에 설치한다. 설치 시 CLI가 스킬 목록을 보여주고 검색·선택하게 한 뒤, 적용할 에이전트를 고르게 한다. Claude Code에서는 플러그인 마켓플레이스 경로도 제공되며, 이 경우 명령과 에이전트 이름에 `pstack:` 접두사가 붙는다. 로드 시점은 상시가 아니라 호출 시점이다. 사용자가 작업 시작에 `/poteto-mode`를 부르면 이 스킬이 요청을 읽어 플레이북을 고르고, 그 단계가 필요로 할 때 다른 스킬을 호출한다. 개별 스킬은 서로를 호출하지 않으므로 단독으로도 동작한다.

전제와 한계

내부 구성은 라우터 역할의 `poteto-mode`와 상황별 스킬로 나뉜다. `poteto-mode`는 23개의 플레이북을 갖고, 요청을 읽어 하나를 고른 뒤 그 단계의 항목을 그대로 복사한 할 일 목록을 연다. 나머지 스킬은 서로를 호출하지 않아 단독으로도 동작한다. `unslop`은 문장에서 군더더기를 걷어내고, `tdd`는 테스트 우선 순서를, `typescript-best-practices`는 타입 규범을, `benchmark-checklist`는 벤치마크 판정 기준을 담당한다. `interrogate`·`reflect`·`in-your-own-words`·`sharpen`은 요구와 답변을 되묻고 다듬는 쪽이고, `figure-it-out`·`automate-me`·`correct`·`how`는 조사와 교정 절차다. `arena`·`swarm`은 병렬 실행, `show-me-your-work`·`statechart`는 작업 노출과 상태 표현을 맡는다. 서브에이전트를 띄우는 스킬은 `poteto-mode`의 Subagents 절을 참조해 각 서브에이전트의 노력 수준을 정하고, 이 절이 없으면 기본값을 쓴다. 미러에는 `no-comments`와 `orchestrate` 스크립트의 `--base` 옵션 같은 커뮤니티 수정도 들어 있다.

프롬프트를 매번 직접 쓰는 방식과의 차이는 재사용 단위다. 프롬프트는 메시지마다 사라지지만 pstack은 파일로 남아 선택한 에이전트의 스킬 디렉터리에 설치되고, 호출될 때만 로드된다. `CLAUDE.md`·`AGENTS.md` 같은 단일 규칙 파일과도 다르다. 그쪽은 항상 로드되는 한 덩어리라 규칙이 늘어날수록 컨텍스트를 상시 점유하고, 작업 국면별로 다른 규칙을 분리하기 어렵다. pstack은 국면별로 파일을 쪼개 두고 라우터가 필요한 것만 부른다. 플러그인과 비교하면 배포 경로가 둘이다. Cursor 플러그인 마켓플레이스로 설치하거나, `npx skills add`로 평범한 폴더를 임의 하네스에 복사한다. 또 여러 스킬이 단일 모델에 의존하지 않고 모델별 강점을 나눠 쓰는 다중 모델 워크플로를 전제로 쓰였다. 기본 패널은 opus 5.5와 grok이고, 기능·리팩터링·버그 수정·성능·힐클라임 같은 코드 위임은 grok으로, 가장 어려운 변경과 산문·판단은 opus 5.5로 보낸다.

설치 경로는 두 갈래다. 하네스를 가리지 않으려면 `npx skills add backnotprop/pstack`을 실행한다. CLI가 스킬 목록을 보여주고 검색·선택하게 한 뒤 적용할 에이전트를 고르게 한다. Claude Code에서는 `/plugin marketplace add cursor/plugins` 후 `/plugin install pstack@cursor-plugins`로 설치한다. 설치 후 첫 단계는 `/setup-pstack`이다. 추론 예산과 사용할 모델을 고르면 Claude Code에서는 그 선택이 `~/.claude/rules/pstack-models.md`에 기록된다. 다음으로 엄격한 작업에 `/poteto-mode`를 붙여 쓴다. 슬래시 메뉴에서 먼저 고른 뒤 작업을 입력해야 스킬이 메시지에 붙는다. 어느 스킬을 쓸지 모르겠으면 `/poteto-help`로 묻는다. Claude Code는 서드파티 마켓플레이스의 자동 업데이트를 꺼 두므로, `/plugin`의 marketplaces 탭에서 `cursor-plugins`를 골라 켜거나 `claude plugin update pstack@cursor-plugins`로 수동 갱신한다. 저장소를 직접 고쳤다면 루트에서 `node scripts/generate-pstack-harness-trees.mjs`를 돌려 생성 사본을 커밋해야 한다.

지원 대상은 Claude Code, Codex, Pi, Cursor, OpenCode 등이며, 스킬 본문은 특정 하네스에 묶이지 않도록 재작성되었다. 다만 Claude Code에서는 이름 규칙이 달라진다. 플러그인 명령과 에이전트에 `pstack:` 접두사가 붙어 `/poteto-mode`가 `/pstack:poteto-mode`가 되고, 어댑터가 나머지 Cursor 이름을 매핑한다. bugbot이나 automations처럼 Cursor 전용 기능이 필요한 단계는 한 줄 메모와 함께 건너뛴다. `poteto-mode` 없이 서브에이전트를 띄우는 스킬을 쓰면 각 서브에이전트의 노력 수준은 기본값으로 떨어진다. 이 미러는 업스트림에 아직 없는 커뮤니티 수정 두 건을 포함하므로, 업스트림과 내용이 완전히 같지 않다. Claude Code에는 저장소 루트 `harness/pstack/`의 생성 사본이 함께 설치되며, 이 사본이 최신이 아니면 CI가 실패한다. 즉 규칙을 고치는 작업과 배포 사본을 맞추는 작업이 분리되어 있지 않다.

선택 기준은 작업의 검증 가능성과 변경 위험도다. 재현이 가능하고 실패를 관찰할 수 있는 버그 수정, 리팩터링, 성능 개선이면 `poteto-mode`를 켜고 `tdd`·`benchmark-checklist` 계열 절차를 태운다. 여러 에이전트를 동시에 굴려야 하는 병렬 작업이면 `arena`·`swarm`과 서브에이전트 노력 수준 설정을 함께 본다. 반대로 한 줄 수정이나 탐색적 질문처럼 실패를 관찰할 대상이 없는 작업에는 라우터를 켜는 비용이 이득보다 크다. 모델 선택을 조직 규칙으로 고정해야 하면 `/setup-pstack`으로 `pstack-models.md`를 먼저 쓰고, 그렇지 않으면 기본 패널을 그대로 쓴다. Cursor 전용 기능에 의존하는 절차가 핵심이면 Cursor 플러그인 경로로 설치하고, 여러 하네스를 섞어 쓰면 `npx skills add` 경로로 필요한 스킬만 골라 설치한다. 규칙을 직접 고칠 계획이면 생성 사본 갱신 절차까지 감수할 때만 미러를 포크한다.