2026-11-13에 pstack을 Claude Code에 설치해 읽어 보고, 같은 날 플러그인은 제거했습니다. 대신 새로웠던 부분만 골라 세 곳의 전역 프롬프트에 약 30줄로 옮겼습니다. 이 글은 무엇을 가져오고 무엇을 버렸는지, 왜 그렇게 판단했는지의 기록입니다. 효과를 측정한 결과 보고가 아니라는 점을 먼저 밝혀 둡니다.
pstack은 무엇인가
pstack은 Lauren Tan(poteto)이 공개한 AI 코딩 에이전트용 스킬 모음입니다. 모토는 "if you want to go fast, go deep first"입니다. 제가 살펴본 버전은 0.15.36이고, 구성은 다음과 같습니다.
/poteto-mode진입 스킬: 요청을 읽고 23개 플레이북(feature, bug-fix, refactoring, shipping 등) 중 하나로 보냅니다.- 원칙 스킬 24개: "원인을 고친다", "측정값을 설명한다"처럼 판단 기준을 한 장씩 적은 문서입니다.
- 멀티 모델 스킬: arena, swarm, interrogate. 여러 모델에 같은 문제를 던지고 비교합니다.
설치는 /plugin marketplace add cursor/plugins와 pstack@cursor-plugins로 했습니다. 라이선스는 MIT입니다.
왜 플러그인을 그대로 두지 않았나
설치하고 보니 두 가지가 걸렸습니다.
- 이미 있는 구성과 겹칩니다. 제 환경에는 oh-my-claudecode와 superpowers로 만든 오케스트레이션이 있습니다. 요청 분류, 위임, 검증 절차가 두 벌이 되면 어느 쪽이 우선인지 에이전트가 매번 추측해야 합니다.
- 기본 라우팅이 제 스택에 없는 모델을 가리킵니다. 코드 작업을 위임할 모델의 기본값이 제가 쓰지 않는 모델입니다. 설정 스킬로 바꿀 수는 있지만, 바꿔야 한다는 사실 자체가 이 부분이 제게 맞지 않는다는 신호였습니다.
더 근본적인 이유는 제가 평소 쓰는 컨텍스트 엔지니어링 규칙입니다. 규칙보다 판단을 적는다, 충돌하는 제약은 지운다, 같은 말은 한 번만 한다, 컨텍스트 파일은 매 턴 다시 전송되니 비용으로 크기를 잰다. 23개 플레이북 본문을 상시 로드하면 이 규칙과 정면으로 어긋납니다. 그래서 플러그인 대신 증류를 택했습니다.
어디에 넣었나
에이전트마다 전역 지침을 읽는 방식이 달라 세 파일에 나눴습니다.
| 파일 | 읽는 쪽 | 들어간 내용 |
|---|---|---|
~/.claude/shared/worker-contract.md | Claude 세션, 그리고 Antigravity(agy) 워커에 주입 | 증거 규칙 추가, "Engineering judgment" 섹션 |
~/.codex/AGENTS.md | Codex | 같은 아홉 원칙을 인라인으로 복제 (Codex에는 @import가 없습니다) |
~/.claude/CLAUDE.md | Claude 오케스트레이터 | 워커를 다루는 규칙, 사용자에게 묻기 전의 분기 분류 |
공통 계약 파일 하나에 쓰고 나머지가 참조하는 구조가 이상적이지만, Codex는 파일을 가져올 수 없으니 그쪽만 요약본을 직접 넣고 "손으로 동기화한다"고 주석에 적었습니다.
고른 기준
새로운 것만 가져왔습니다. 기준은 세 가지였습니다.
- 이미 가진 규칙과 겹치지 않을 것
- 한두 문장으로 행동이 바뀌는 지점을 말할 수 있을 것
- 특정 벤더나 도구에 묶이지 않을 것
가져온 아홉 원칙
| 원칙 | 실무에서 달라지는 점 |
|---|---|
| 가장 작은 변경, 빼기 먼저 | 만들기 전에 죽은 코드를 먼저 걷어내고, 추측성 가드나 추상화를 넣지 않습니다. 증거가 요청한 변경을 반증하면 그걸 보여 주고 멈춥니다. |
| 증상이 아니라 근본 원인 | 먼저 재현하고, 시스템이 처음 틀어진 곳과 같은 결함의 다른 사례를 함께 고칩니다. |
| 전제를 공격한다 | 같은 가정을 공유한 수정이 두 번 실패하면, 세 번째 수정 전에 그 가정을 적어 두고 직접 검증합니다. |
| 레버를 만든다 | 반복되거나 사소하지 않은 일은 다시 돌릴 수 있는 스크립트나 검사로 만듭니다. 같은 교훈을 두 번 쓰게 되면 문장이 아니라 린트나 검사로 바꿉니다. |
| 검증 가능한 단위 | 작은 단계마다 검사로 끝내고, 하나를 확인한 뒤 다음으로 갑니다. 실패하는 테스트를 먼저 씁니다. |
| 구현이 아니라 동작을 테스트 | 동작이 깨지면 실패하고 리팩터링에는 살아남아야 합니다. 기대값은 요구사항에서 가져오며 테스트 대상 코드를 돌려서 얻지 않습니다. |
| 숫자를 설명한다 | 측정값을 믿거나 보고하기 전에, 판단을 바꿀 결과가 무엇인지, 실행 횟수와 분산, 한계, 그리고 에러나 캐시, 실행되지 않은 코드를 재고 있지는 않은지 따집니다. |
| 공유 상태 | 동시에 도는 작업은 각자 파일, 브랜치, 키를 갖고 읽는 경계에서 합칩니다. 연산은 재실행하거나 중단 후 재개해도 같은 상태로 수렴해야 합니다. |
| 솔직함 | "아니오", "이건 넣을 가치가 없다"도 유효한 답입니다. 동의가 기본값이 아닙니다. |
실제로 추가된 문장은 이런 식입니다.
Root cause, not symptom. Reproduce first. Fix the first place the system went wrong, and every
other instance of the same fault. A guard, retry, clamp, or swallowed error is a fix only when the
state it handles is legitimate.여기에 증거 규칙 네 줄이 더해졌습니다. 프록시가 아니라 실제 산출물을 확인할 것(파일 수정 시각, 워커의 자기 보고, 캐시된 출력은 프록시입니다), 모든 주장에 measured, inferred, guess 중 하나를 같은 문장에서 붙일 것, 직접 돌릴 수 있는 검사를 사람에게 넘기지 말 것, 읽지 않은 링크나 참고문헌을 인용하지 말 것입니다.
오케스트레이터 쪽에는 다섯 가지가 들어갔습니다.
- 워커의 결과물은 오케스트레이터가 소유합니다. diff나 증거를 직접 보고 요약을 새로 쓰며, 워커의 "완료"를 그대로 전달하지 않습니다.
- 수정이나 재시도 같은 새 라운드는 원래 브리프, 이후 지시, 이전 보고와 브랜치를 합친 범위로 새 워커에게 맡깁니다. 상태가 워커 안에 있을 때만 기존 워커를 재개합니다.
- 결정적인 스크립트가 팬아웃보다 낫습니다.
- 두 번째 의견은 같은 프롬프트를 다른 벤더에 보내 얻고, 일치하면 신호가 강합니다.
- 사람에게 묻기 전에 분기를 분류합니다. 실행해서 관찰할 수 있는 사실이면 사람이 답할 일이 아니므로 돌려 보고, 되돌릴 수 있는 작업은 진행 후 보고합니다. 제품이나 취향 판단, 되돌릴 수 없는 외부 행동만 묻습니다.
충돌 하나를 정리했다
기존 규칙에는 "값을 clamp한다"가 있었습니다. 그런데 근본 원인 원칙은 clamp가 버그를 가릴 수 있다고 말합니다. 둘은 양립하지 않아서 기존 문장을 이렇게 고쳤습니다. 시스템 경계에서 검증하고 clamp하며, 그 안쪽에서는 내부 타입을 신뢰한다. 안쪽 깊은 곳의 clamp는 버그를 숨깁니다. 새 규칙을 얹기 전에 충돌하는 옛 규칙을 지우는 것이 위에서 말한 "충돌하는 제약은 지운다"의 실제 적용이었습니다.
가져오지 않은 것
- 벤더별 모델 라우팅. 제 라우팅 원칙이 이미 있고, 모델 이름은 자주 바뀝니다.
- Cursor 전용 기능. Claude Code 어댑터 문서에도 해당 단계는 건너뛴다고 적혀 있습니다.
- 영어 문체 규칙. 제 글과 대화는 한국어 기준이라 맞지 않습니다.
- 23개 플레이북 본문. 상시 로드하기엔 비싸고, 기존 오케스트레이션과 겹칩니다.
- "커밋과 외부 행동을 묻지 않고 진행한다"는 자율성 규칙. 기존의 "요청받지 않으면 push나 commit을 하지 않는다"와 충돌해서 기존 규칙을 유지했습니다.
로드가 되는지 어떻게 확인했나
지침은 쓴다고 읽히는 것이 아니라서 세 가지를 확인했습니다.
- 새 Claude 세션에 상시 지침에서 새 섹션의 제목을 나열하라고 시켰더니 아홉 개가 모두 나왔습니다.
- 도구 없이 가벼운 모델로 돌린 Codex에도 같은 질문을 했고 아홉 개가 모두 나왔습니다.
- agy 워커에 주입되는 최종 컨텍스트를 조립해 새 문구가 들어 있는지 확인했습니다. agy 모델 자체는 호출하지 않았습니다.
또 자동 관리되는 CLAUDE.md의 oh-my-claudecode 블록이 백업과 바이트 단위로 동일함을 확인했습니다. 수정은 그 블록 밖에서만 이뤄졌다는 뜻입니다.
한계
솔직하게 적자면, 에이전트의 행동이나 결과물 품질이 달라졌는지는 아직 측정하지 못했습니다. 위 검증은 지침이 로드된다는 것까지만 보여 줍니다. 로드와 준수는 다른 문제입니다. 이 글은 무엇을 왜 채택했는지의 기록이고, 효과는 쓰면서 확인할 가설입니다.
같은 지침을 OpenForge 표준 저장소에 docs/engineering-judgment.md로 추가하는 안을 제안하고 있습니다. 이 글을 읽는 시점에는 추가 중이거나 검토 중일 수 있습니다.
원본은 pstack에서 볼 수 있습니다. 이 글의 설명은 설치본을 읽고 제 말로 정리한 것이며 원문은 길게 인용하지 않았습니다.