이 문서는 pstack의 24개 원칙(principles) 을 긴 지시문 대신 짧은 이름으로 불러 에이전트의 판단을 정확히 조정하는 방법을 설명한다. /poteto-mode는 여러 단계로 이루어진 작업을 시작할 때 원칙 목록을 읽고, 해당 작업에 맞는 원칙을 적용한 뒤 어떤 원칙이 어떤 결정을 바꾸었는지 답변에서 밝혀야 한다. 핵심은 원칙을 외우거나 직접 실행하는 것이 아니라, 문제가 보일 때 그 문제에 맞는 원칙의 이름으로 작업을 조향하는 것이다.

1. 원칙 이름으로 작업을 조향하는 방식

pstack은 24개의 원칙을 각각 독립된 스킬로 제공한다. 사용자가 여러 단계의 작업을 요청하면 /poteto-mode는 시작 시점에 이 원칙들의 색인을 확인하고, 현재 작업이 촉발하는 원칙을 골라 적용한다. 그리고 최종 답변에는 적용한 원칙의 이름뿐 아니라, 그 원칙 때문에 구체적으로 어떤 설계 또는 실행 결정이 달라졌는지 함께 설명해야 한다.

중요한 점은 사용자가 원칙을 별도의 명령처럼 "호출"할 필요가 없다는 것이다. 대신 원칙 이름을 말해 에이전트의 방향을 잡는다. 각 이름은 이미 에이전트가 읽은 완결된 규칙을 가리키므로, 긴 설명을 적는 것보다 훨씬 정밀하게 의도를 전달할 수 있다.

"원칙을 호출하는 것이 아니다. 그 이름으로 방향을 잡는 것이다."

예를 들어 에이전트가 기존 어댑터 3개에 새 어댑터 하나를 덧붙이려 할 때, 다음처럼 말할 수 있다.

"추가하기 전에 먼저 빼라. 오래된 어댑터들을 먼저 삭제하고, 남은 구조를 기준으로 설계해라."

빌드가 성공했다는 이유만으로 작업이 끝났다고 주장한다면, 실제 사용자 흐름을 검증하도록 요구할 수 있다.

"작동함을 증명하라. 실제 import 흐름을 실행하고, 기록이 실제로 작성된 결과를 보여줘."

병렬로 진행되는 두 작업이 같은 브랜치에 쓰려고 한다면, 잠금 장치를 더하기보다 공유를 없애도록 유도할 수 있다.

"공유 상태를 직렬화하기 전에 먼저 분리하라. 각 작업에 별도 worktree를 주고, 잠금은 쓰지 마라."

이 지시들이 강력한 이유는 단순한 구호가 아니라, 각각 구체적인 행동 규칙을 담고 있기 때문이다. 다만 에이전트가 원칙 이름만 언급하고 실제 결정 변화는 설명하지 못한다면, 그것은 원칙을 적용한 것이 아니라 이름만 내세운 것이라는 신호다.

2. 핵심 설계 원칙: 얼마나 만들고 언제 다시 생각할지

첫 번째 묶음은 무엇을 얼마나 구현할지, 그리고 기존 설계를 유지할지 다시 설계할지를 판단하는 원칙들이다. 불필요한 복잡성을 줄이고, 문제의 본질에 맞는 설계를 선택하는 데 초점을 둔다. 🧭

• 게으름 프로토콜(Laziness Protocol): 문제를 해결하는 데 필요한 가장 작은 변경을 선호하며, 가능하면 기능을 더하기보다 삭제한다.
• 기초적 사고(Foundational Thinking): 로직을 작성하기 전에 먼저 핵심 데이터 구조를 선택한다.
• 제1원칙부터 다시 설계하기(Redesign from First Principles): 새 요구사항이 처음부터 존재했던 것처럼 시스템에 자연스럽게 통합한다.
• 전제 공격하기(Attack the Premise): 두 번 이상 실패한 수정들이 공통으로 기대고 있는 전제를 의심한다. 이를 위해 먼저 불균형을 가진 주체들이 누구인지 조사한다.
• 추가하기 전에 먼저 빼기(Subtract Before You Add): 기존의 불필요한 부분과 죽은 구조를 제거한 후 그 위에 새 기능을 만든다.
• 독자의 인지 부담 최소화하기(Minimize Reader Load): 코드를 읽는 사람이 머릿속에 유지해야 하는 계층과 숨은 상태를 줄인다.
• 결과 중심 실행(Outcome-Oriented Execution): 임시 호환 상태를 오래 보존하기보다, 목표 설계에 수렴하도록 재작성 작업을 진행한다.
• 경험 우선(Experience First): 구현 편의성보다 사용자가 실제로 얻는 결과와 경험을 우선한다.
• 설계 공간 충분히 탐색하기(Exhaust the Design Space): 선례가 없는 문제라면 하나만 성급히 만들지 말고, 경쟁 가능한 프로토타입을 2~3개 만들어 비교한다.
• 지렛대 만들기(Build the Lever): 작업을 수행하거나 그 결과를 증명하는 스크립트를 만들어, 검토자가 다시 실행할 수 있게 한다. 에이전트가 같은 수작업을 반복한다면 필요한 도구나 스킬을 직접 만들게 해야 한다. 항상 같은 방식으로 반복할 수 있는 단계는 스크립트에 맡기고, 에이전트는 판단이 필요한 부분에 집중해야 한다.

특히 지렛대 만들기는 일회성 해결보다 재현 가능성과 자동화를 중시한다. 사람이나 에이전트가 손으로 똑같은 과정을 반복하는 대신, 누구나 재실행할 수 있는 도구로 그 지식을 남기는 방식이다.

3. 아키텍처 원칙: 상태와 검증의 위치 정하기

두 번째 묶음은 상태, 검증, 타입, 호환성 같은 구조적 책임을 시스템 어디에 둘지 다룬다. 목표는 규칙이 여기저기 흩어지지 않도록 하고, 잘못된 상태나 불필요한 동기화 문제를 구조적으로 차단하는 것이다.

• 도메인 모델링(Model the Domain): 반복되는 규칙을 여러 조건문에 흩어놓지 말고, 하나의 구조나 모델에 담는다.
• 경계 규율(Boundary Discipline): 시스템의 입력 경계에서 검증하고, 내부에서는 검증된 타입을 신뢰한다.
• 타입 시스템 규율(Type System Discipline): 애초에 잘못된 상태를 표현할 수 없도록 타입을 설계한다.
• 연산을 멱등적으로 만들기(Make Operations Idempotent): 작업을 여러 번 재시도해도 같은 최종 상태에 도달하게 만든다.
• 호출자를 이전한 뒤 레거시 API 삭제하기(Migrate Callers Then Delete Legacy APIs): 호출부를 새 API로 옮기는 일과 오래된 API를 삭제하는 일을 한 번의 흐름으로 처리한다.
• 공유 상태를 직렬화하기 전에 먼저 분리하기(Separate Before Serializing Shared State): 조정·잠금·대기 장치를 덧붙이기 전에, 먼저 공유 자체를 없앤다.

여기서 특히 병렬 작업과 관련된 마지막 원칙은, 충돌을 해결하기 위해 무조건 락(lock)이나 순서 제어를 도입하지 말라고 말한다. 먼저 각 작업이 같은 자원을 공유하지 않도록 분리할 수 있는지 살펴보는 것이 우선이다.

"공유 상태를 직렬화하기 전에 먼저 분리하라."

4. 검증 원칙: 무엇을 증거로 볼 것인가

세 번째 묶음은 "테스트가 통과했다"는 말만으로는 충분하지 않을 수 있다는 점을 강조한다. 실제 산출물과 사용자 행동을 기준으로 검증하고, 숫자와 오류의 원인을 납득 가능하게 설명해야 한다. ✅

• 작동함 증명하기(Prove It Works): 간접 지표나 대리 검증이 아니라, 실제 산출물이 제대로 작동하는지 확인한다.
• 근본 원인 고치기(Fix Root Causes): 코드부터 바꾸지 말고, 먼저 문제를 재현하고 추적해 원인을 찾아낸다.
• 검증 가능한 단위로 작업 순서화하기(Sequence Work into Verifiable Units): 작은 작업 단위 하나를 끝낼 때마다 검증을 마친 뒤 다음 작업으로 넘어간다.
• 구현이 아니라 행동 테스트하기(Test Behavior, Not Implementation): 사용자가 호출하는 방식으로 코드를 실행하고, 기대하는 구체적 값을 검사한다. 모든 import 함수가 undefined를 반환해도 통과할 테스트라면 삭제해야 한다.
• 숫자 설명하기(Explain the Number): 측정한 숫자가 무엇에 의해 제한되는지, 그리고 다른 대상을 잘못 측정한 것은 아닌지를 밝힌 후에야 그 수치를 믿거나 보고한다. /benchmark-checklist는 실제 실행 결과를 바탕으로 답해야 할 일곱 가지 질문으로 이를 구체화한다.

이 원칙들은 단지 "테스트를 더 많이 작성하라"는 뜻이 아니다. 중요한 것은 실제 사용 결과를 확인하는가, 오류의 진짜 원인을 찾았는가, 그리고 측정 수치를 신뢰할 근거가 있는가다.

"실제 산출물을 검증하라. 대리 지표를 검증하지 마라."

5. 위임 원칙: 병렬 작업을 안전하게 다루기

병렬 작업이나 하위 에이전트 활용에서는 작업량과 대화 맥락을 잘 관리해야 한다. 이를 위한 원칙은 두 가지다.

• 컨텍스트 윈도우 보호하기(Guard the Context Window): 대량의 읽기 작업은 하위 에이전트에게 맡기고, 핵심 발견 사항은 메인 대화에 남긴다.
• 사람을 기다리며 멈추지 않기(Never Block on the Human): 되돌릴 수 있는 작업은 사용자 응답을 기다리지 말고 진행하며, 결과를 제시한다.

첫 원칙은 메인 대화의 제한된 맥락 공간을 소중한 판단과 의사결정에 쓰기 위한 전략이다. 두 번째 원칙은 불확실성이 있다고 해서 모든 작업을 멈추지 말고, 되돌릴 수 있는 범위에서는 먼저 전진하라는 의미다.

6. 메타 원칙: 반복된 교훈을 구조에 새기기

마지막 원칙은 반복적으로 등장하는 조언을 사람의 기억이나 주의력에만 맡기지 않는 방법을 다룬다.

• 교훈을 구조에 인코딩하기(Encode Lessons in Structure): 같은 조언을 두 번 반복했다면, 그것을 린트 규칙·검사·스크립트로 바꾼다. /correct는 이 원칙을 저장소 전체에 적용하며, 관련 안내 문서인 "Make it yours" 에서 사용 사례를 보여 준다.

즉, "다음부터 조심하자"라고 말하는 데서 끝내지 말고, 같은 실수가 다시 일어나기 어렵도록 개발 환경과 작업 흐름 자체를 바꾸라는 뜻이다. 반복되는 문제는 개인의 기억력이 아니라 자동화된 구조로 해결해야 한다.

7. 원칙을 익히는 가장 좋은 방법

문서는 24개 원칙을 전부 외우려 하지 말라고 조언한다. 지금은 목록을 가볍게 훑고, 이후 에이전트가 아쉬운 행동을 할 때마다 "이 문제를 막을 수 있었던 원칙 이름이 무엇이었지?" 하고 다시 찾아보면 된다.

"목록을 외우지 마라. 지금 훑어보고, 에이전트가 어떤 이름으로 막을 수 있었던 일을 할 때 다시 돌아와라."

이렇게 원칙 이름을 실제 상황과 연결하다 보면, 긴 지시문 없이도 에이전트의 설계·검증·협업 방식을 바꾸는 공통 어휘가 자연스럽게 자리 잡는다. 다음 안내 문서에서는 이를 자신의 프로젝트와 환경에 맞게 적용하는 방법을 다룬다.