Ship with skills, not vibes 25개의 skill을 하나의 개발 흐름으로 엮다

이것이 쓰는 것은, 물음 하나에 답하기 위한 일회용 코드입니다. 물음이 먼저 오고, 뒤에 오는 모든 것의 모양을 정합니다. 틀린 물음에 답하는 prototype은 아무리 보기 좋아도 순전한 낭비입니다. '일회용'은, 어떻게 쓰는가에 대한 제약이지 '반드시 없앤다'는 약속이 아닙니다: 테스트 없음, 굴러가는 것 이상의 오류 처리 없음, 추상화 없음, 영속화 없음.

두 갈래에서 나오는 산출물은 크게 다릅니다. '이 로직이나 상태 모델이 맞다고 느껴지는가?'에는, 공유 가능한 단일 HTML 파일이 돌아옵니다 — state panel, free-play 버튼, 탭식 내비게이션을 갖추고 전부 도메인 언어로 이름 붙어 있어서, 디자이너나 도메인 전문가에게 그대로 건네 직접 느껴 보게 할 수 있습니다. 뒤의 로직은 DOM을 건드리지 않는 깨끗한 순수 모듈이라, 검증되면 그대로 정식 코드로 끌어올릴 수 있습니다. '이건 어떻게 보여야 하는가?'에는 같은 route 위에 놓인, 크게 다른 여러 UI 변형입니다. 플로팅 하단 바로 전환합니다. 변형끼리 어긋나야 하는 곳은 색이 아닙니다. 구조입니다. 살짝 손본 card grid 세 개는 벽지이지 prototype이 아닙니다.

그것을 '단단하게 만들고' 있다고 깨닫는 순간, 이미 prototype을 만드는 것이 아닙니다. 테스트를 붙이고, 진짜 데이터베이스에 연결하고, '나중에 필요할지도'를 위해 일반화하는 일이 그것입니다.

산출물을 어떻게 처리할 것인가: 답(판정과 그것이 해결한 물음)은 오래 남는 곳에 둡니다. commit message, ADR, 구현 issue. prototype 자체는 지우지 않지만 main에도 넣지 않습니다. commit 하는 곳은 prototype/<name> branch, 절대 merge 하지 않습니다. 구현 issue에 포인터를 하나 남겨 둡니다.

함정: 정작 구현해야 할 때 agent가 prototype을 하라고 권합니다. 이름의 문제입니다. 흐름에 익숙하지 않은 agent에게는 '티켓이 생긴 뒤의 당연한 다음 단계'처럼 읽힙니다. 그리고 하나 더. app 전체를 prototype 하지 마십시오. 자연스러운 정지점이 없어서 관성으로 그대로 제품이 되고, '테스트도 오류 처리도 없는' 코드가 그대로 사용자 앞에 나갑니다.

이것이 재료로 삼는 것은 하나뿐입니다. 1차 자료입니다. 공식 문서, 소스 코드, 명세, 퍼스트파티 API. 모든 주장을 답을 가진 그 출처까지 거슬러 추적합니다. 대화 안에서는 답해 주지 않습니다. 출력은 파일 하나이고, 모든 주장에 링크가 붙습니다. 결정적인 수는 읽는 부분을 어디서 돌리느냐입니다. 백그라운드 agent.

research는 위임한 발품이지, 외주로 넘긴 생각이 아닙니다.

함정: 자기 자신의 두 번째를 만들어 냅니다(issue 530). skill은 호출한 쪽에 백그라운드 agent를 띄우라고만 하고 agent 종류를 묶지 않기 때문에, 실제로 뜨는 것은 같은 도구와 지시를 쥔 범용 agent이고, 그것이 또 하나를 띄웁니다. 누군가 측정한 값이 이렇습니다. research 작업 하나가 세 번 겹친 실행으로 약 450k token을 태웠습니다. 중복된 쪽은 삼십 분 뒤, 완전히 시야 밖에서 끝났습니다. 호출한 뒤에는 백그라운드 작업 목록을 보고 중복을 멈추십시오.

또 세 가지. 반대 방향의 실패가 있습니다. 전역 지시가 추가 위임을 금지하고 있으면 백그라운드 agent는 정중히 거절하고 skill은 조용히 아무것도 하지 않습니다. '신뢰도 높은 출처'는 모델 스스로의 판단이고 allowlist는 없습니다. 실제로 듣는 완화책은 이것입니다. 인용 두세 개를 무작위로 따라가 보는 것. 그것 자체가 아니라 '그것의 요약'에 도착했다면 그 실행은 실패입니다. 정지 기준이 없습니다. 범위는 스스로 책임져야 합니다. 하나의 API, 하나의 동작, 하나의 버전 주장이 'research X'보다 훨씬 나은 결과를 가지고 돌아옵니다.

research 파일은 ADR이 아닙니다: ADR은 남기고, research 파일은 다 쓰면 보관하거나 지웁니다. 오래된 research 파일은 없느니만 못하고, 이후의 모든 repo 읽기를 오염시킵니다.

여섯 단계: repro 만들기, 최소화하기, 가설에 순위 매기기, 프로브 심기, 회귀 테스트와 함께 고치기, 깨끗이 치우기.

'타이트'한 피드백 루프가 생기기 전에는 agent가 이론을 세우지 못하게 합니다. 이름이 붙은 명령 하나, 이미 한 번 돌려 본 것, 이 bug에서는 레드이고 고치면 그린이 되는 것. bug 보고를 받은 coding agent의 기본 행동은 코드를 읽고 추측하는 것인데, 이 skill이 그것을 막습니다. 레드로 만들 수 있는 명령이 없으면 Phase 2도 없습니다. 그 gate가 이 skill의 가치 전부입니다.

루프가 '있다'는 것이 목표가 아니라 '타이트'한 것이 목표입니다: 빠르고(초 단위), 결정적이고(매번 같은 판정), 날카롭고('crash 나지 않았다'가 아니라 정확한 증상을 단언), agent가 사람 없이 돌릴 수 있어야 합니다. 30초씩 걸리면서 flaky한 루프는 없는 것보다 나을 게 별로 없습니다. 간헐적으로 나는 bug에서 목표는 깨끗한 repro가 아닙니다. 재현율을 높이는 것입니다. 트리거를 루프로 돌리고, 병렬화하고, 부하를 걸고, sleep을 주입합니다.

이것은 충돌을 텍스트 문제로 다루기를 거부합니다. hunk 하나에 손대기 전에, 양쪽을 먼저 여기까지 되짚습니다. 1차 자료입니다. commit message, PR, 원래 issue. 그래서 이 skill이 고르는 것은 이것입니다. 두 의도. 두 덩이의 텍스트 사이에서 고르는 것이 아니며, 양립하는 곳에서는 양쪽을 모두 남깁니다. 정말로 양립하지 않을 때는 이번 merge가 밝힌 목표에 맞는 쪽을 고르고 그 맞바꿈을 말로 밝힙니다. 충돌을 덮으려고 새 동작을 지어내지 않으며, 도중에 포기하지 않습니다: merge는 반드시 완료된 commit까지 옮겨집니다.

repo 자신의 자동화된 검사를 찾아내어 commit 전에 돌리기도 합니다. merge는 git 안에서 '두 branch를 동시에 만족시키면서 양쪽 테스트는 모두 통과하지 못하는' 것이 가장 쉽게 나오는 자리이기 때문입니다.

덧붙이는 실무 지식: 충돌을 피하려고 병렬 작업 사이에서 '파일을 나눠 갖는' 일은 하지 마십시오. 얻는 것보다 드는 비용이 큽니다. 지킬 가치가 있는 유일한 규율은 이것입니다. 큰 리팩터링을 먼저 하기. worktree로 병렬 개발할 때, merge 해서 되돌리는 일은 그 변경을 쓴 session이 하는 것이 가장 좋습니다. 의도를 아는 것은 그 session뿐이기 때문입니다. 모두의 충돌을 마지막 agent 하나에 batch로 몰아주는 것은, 이 skill이 힘들게 다시 세우려는 것을 그대로 버리는 일입니다.

codebase를 훑어 심화 기회를 찾습니다 — 얕은 모듈(인터페이스가 그것이 감추고 있는 것과 거의 같은 정도로 복잡한 모듈)을 깊은 모듈로 바꿀 수 있는 지점입니다. 그 결과를 HTML 리포트로 정리하고, 고른 후보를 놓고 그릴링을 합니다.

코드는 절대 고치지 않습니다. run 전체가 내놓는 것은 'HTML 파일 하나와 대화 한 번'입니다. 리팩터링 자체는 나중에 다른 session에서 정상적인 구축 흐름을 타고 진행합니다. 이것이 이 skill을 리팩터링 도구가 아니라 점검이라고 부르는 이유이고, '아직 손댈 준비가 되지 않은' codebase에 돌려 볼 가치가 있는 이유이기도 합니다.

필터는 두 개: deletion test — 이 모듈을 지운다고 상상해 보십시오. 복잡도가 더 작은 인터페이스 뒤로 모이는지, 아니면 각 호출자 쪽으로 흩어지는지? '모인다'가 되는 사례만 카드로 올라갑니다. 또한 영역을 지정하지 않는 한, 최근 commit 이력을 먼저 읽어 스캔을 지금 변하고 있는 경로 쪽으로 기울입니다 — 아무도 건드리지 않는 코드에서의 심화는, 결코 실현하지 않을 리팩터링입니다.

강도 표시는 세 단계입니다. 'Strong'(deletion test를 명확히 통과하고 마찰도 실재함. 진지하게 볼 것), 'Worth exploring'(말은 되지만 보상은 코드가 앞으로 어디로 가느냐에 달림), 'Speculative'(완전성을 위해 나열했을 뿐, 대부분은 안심하고 무시해도 됨).

자신이 만들지 않은 issue에만 씁니다. 가공되지 않은 bug 보고, 외부에서 온 feature request, 갑자기 나타난 외부 PR입니다. to-tickets skill이 만들어 내는 티켓은 구조상 이미 agent-ready이므로, 거기에 triage를 돌려 봐야 잘해야 헛수고입니다. 이 skill은 제안하고 기다립니다: 분류와 상태에 대한 판단을 이유와 함께 알려 주고, 지시하기 전에는 아무것도 적용하지 않습니다.

triage된 항목은 모두 마지막에 정확히 분류 역할 하나와 상태 역할 하나를 답니다. 분류는 두 가지, bug와 enhancement입니다. 상태는 다섯 가지입니다. needs-triage(당신이 평가해야 하는 것), needs-info(보고자를 기다리는 중. 답이 오면 needs-triage로 복귀), ready-for-agent(완전히 규격화되고 agent brief가 붙은 것), ready-for-human(같은 brief에 '왜 위임할 수 없는지'를 더한 것), wontfix(닫음, 이유는 기록되어 있음).

wontfix 라벨은 세 종류가 있고 그 차이가 중요합니다. 이유는 그중 하나만 지식 베이스에 기록되기 때문입니다: 이미 구현된 것은 그것이 이미 존재하는 위치를 가리키는 댓글을 남기고, out-of-scope에는 쓰지 않습니다 (그것은 이미 만들어진 기능이지 거절된 기능이 아니고, 써 넣으면 중복 검사를 오염시킵니다). 거절한 bug는 정중히 설명한 뒤 닫습니다. 거절한 enhancement는 out-of-scope 디렉터리에 파일을 하나 쓰고, 닫는 댓글에서 링크를 겁니다. 그 디렉터리는 거절된 개념 하나당 markdown 파일 하나입니다 (issue 하나당 하나가 아닙니다). 그리고 triage는 무엇이든 평가하기 전에 디렉터리 전체를 먼저 읽어, 키워드가 아니라 개념으로 대조합니다.

brief를 쓰기 전에 먼저 검증합니다: bug는 보고자의 절차대로 재현하고, PR은 checkout 해서 관련 테스트를 돌린 다음, 세 가지 결과 중 하나를 보고합니다 — 확인됨 (코드 경로 첨부), 재현 불가, 시도하기에는 세부가 부족함 (이 자체가 가장 강한 needs-info 신호입니다). 이 모든 것은 agent brief 품질을 높이기 위한 것이고, 그 brief는 정확하기보다 오래가도록 쓰였습니다: 타입, 시그니처, 동작 계약을 쓰고, 파일 경로와 줄 번호는 절대 쓰지 않습니다. issue는 몇 주씩 방치될 수 있고 그 밑에서 코드는 계속 움직이기 때문입니다.

함정: label은 자동으로 만들어지지 않습니다. 상태 다섯 개로는 부족하다는 것이 가장 자주 언급되는 빈틈입니다 (blocked, deferred, implemented 모두 요청이 있었지만 어느 것도 ship되지 않았습니다). backlog 전체를 한 번에 풀어놓고 돌리지 마십시오 — "주의가 필요한 것을 보여 달라"는 그 pass는 골라내기 위한 값싼 목록입니다. 한 번에 스무 개의 issue를 돌리면 agent는 그것을 조용히 증거의 바탕으로 삼아 버립니다. 게다가 이 skill은 issue 본문만 돌려주고 댓글은 돌려주지 않습니다.

이 skill이 맡는 것은 agent session 하나에 담기에는 너무 큰 작업입니다. 말할 수 있는 것은 목적지이지만 경로는 아직 보이지 않습니다. 그것을 tracker 위의 공유된 한 장의 지도로 그리고, decision 티켓으로 구성한 다음, 한 번에 한 장씩 풀어 경로가 뚜렷해질 때까지 진행합니다.

계획은 하되 실행은 하지 않습니다. 티켓 한 장은 '풀리면 결정이 나오는' 질문 하나를 쥐고 있는 것이지, 실행해야 할 구축 조각이 아닙니다. 지도가 끝났다는 정의는 이렇습니다: 누군가 이것을 만들러 가기 전에 아직 결정해야 할 것이 아무것도 남아 있지 않습니다. 이 규칙은 agent가 가장 자주 어기는 규칙입니다.

이것과 grill-with-docs 사이의 경계는 session 개수이지 프로젝트 크기가 아닙니다: 대화 하나에 담기면 grilling을 씁니다 (더 싸고 더 좋습니다). 담기지 않을 때만 wayfinder입니다. 범위가 잘 잡힌 기능에 wayfinder를 꺼내 드는 것은 흔한 실수입니다.

지도에 실리는 네 가지: Destination — 끝까지 갔을 때 어떤 모습인가입니다. 그것을 어떤 티켓이 존재하기 전에 먼저 이름 붙입니다. Decisions so far — 닫힌 티켓 한 장에 한 줄씩, 각각 세부가 실제로 사는 곳으로 링크합니다. Not yet specified, 즉 전쟁의 안개입니다 — 다가오는 것은 보이지만 아직 정확히 표현할 수 없는 결정들입니다. 판단 기준은 그 질문을 지금 정확히 말할 수 있는가이지, 답할 수 있는가가 아닙니다. Out of scope — 목적지 바깥이라고 판정한 작업입니다. 닫고, 결코 졸업시키지 않습니다. 지도는 저장소가 아니라 색인이고, 결정은 자기 티켓 안에만 삽니다.

Frontier — '열려 있고, 막혀 있지 않고, 아직 아무도 맡지 않은' 티켓을 말합니다. session은 어떤 작업이든 시작하기 전에 티켓을 자신에게 assign 해서 맡습니다. 그래서 assignee가 곧 맡았다는 표시입니다. 티켓은 처음부터 끝까지 이름으로 부르고, 맨 번호는 쓰지 않습니다 — issue 번호가 늘어선 벽은 서술 속에서는 읽히지 않습니다.

현재 대화를 한 편의 인수인계 문서로 압축합니다 — 워크스페이스가 아니라 OS 임시 디렉터리에 쓰이는 markdown 파일이며, 완전히 새로운 agent가 이것을 읽으면 곧바로 이어받을 수 있습니다.

이것이 사는 것은 이식성이지 압축이 아닙니다. 그래서 들리는 것보다 훨씬 좁은 용도입니다: 파일이 필요한 것은 작업이 이동해야 할 때뿐입니다. 트리거는 네 가지 — harness 교체, 다른 디렉터리나 repo로 이동, 동료에게 작업 넘기기, phase 도중에 발견한 곁가지를 분기해 내보내기.

가장 자주 건너뛰는 사용법은 분기입니다. 자신은 자기 session에 남은 채, 쌓아 둔 context의 복사본을 병렬로 일하는 두 번째 agent에게 넘깁니다. prototype 갈림길이 바로 이렇게 쓰입니다: 깊은 설계 대화 한복판에서 실행해 봐야만 풀리는 문제에 부딪혔는데, 힘들게 쌓아 올린 thread를 그 조사에 쓰고 싶지는 않습니다 — prototype session으로 handoff 하고, 답을 받고, 그 답을 가지고 돌아와, 원래 thread에서 인용합니다. 두 번의 건넘, 살아 있는 대화 하나, 다시 설명할 것은 없습니다.

무엇이 여행하는가: 문서는 살아 있는 thread(지금 무엇이 진행 중인지, 왜인지, 다음은 무엇인지)와 권장 skill 한 묶음을 가지고 갑니다. 비밀은 쓰기 전에 가려집니다. 이미 적혀 있는 것은 의도적으로 일절 가져가지 않습니다 — spec, 계획, ADR, issue, commit, diff는 모두 경로나 URL로 참조할 뿐 절대 복사하지 않습니다.

함정: 파일은 임시 디렉터리에 있고 경로가 길며 OS마다 다르므로, 경로를 물어보고 적어 둔 다음에 진행하십시오. session 사이에 temp를 지우는 환경도 있으니, 다음 session이 곧바로 시작되지 않는다면 직접 오래 남는 곳으로 복사해 두십시오. 다음 agent에게 넘기는 방법은 경로를 가리키는 것입니다. 요약을 shell 명령에 붙여 넣지 마십시오 — 특수 문자가 든 요약은 망가지고, 전형적인 실패는 조용한 잘림입니다. "what은 잡지만 why는 잡지 못한다"는 정당한 비판이므로, '다음 session은 무엇을 위한 것인가'를 파라미터로 넘기십시오. 그리고 검증되지 않은 믿음을 사실처럼 적어 두지는 않는지 살피십시오.

혼자서는 결정할 수 없는 사안을 한 부의 설문지로 바꾸어, 부족한 조각을 쥐고 있는 사람에게 넘깁니다.

캐묻는 대상은 '이번 발송'이지 주제가 아닙니다. 주제에 대해 당신을 인터뷰하는 것은 여기서 아무 의미가 없습니다 — 주제를 모른다는 것이야말로 다른 사람에게 써서 보내는 이유입니다. 그래서 언제나 답할 수 있는 두 가지만 묻습니다: 누구에게 보내는가(상대의 역할, 전문성, 나와의 관계 — 이것이 어투와, 문서가 스스로 얼마나 많은 context를 담아야 하는지를 정합니다), 그리고 무엇을 돌려받아야 하는가(혼자서는 해결할 수 없는 구체적인 결정이나 사실 — 이것이 결과물을 재는 체크리스트가 됩니다). 그다음은 전부 초안 작성입니다.

문서의 모양: 한 줄짜리 purpose, 그리고 '당신 머릿속에 한 번도 들어와 본 적 없는 사람'을 위한 짧은 context. 질문은 가장 중요한 것을 먼저, 주제별로 묶습니다. 한 질문에 하나의 생각, 복합 질문은 절대 만들지 않기. "모르겠습니다"라고 답해도 된다고 명시하기 — 표시된 불확실성은 쓸모가 있지만, 사실처럼 읽히는 자신만만한 추측은 쓸모가 없습니다. 마지막에는 catch-all 하나.

이것은 의도적으로 일절 분기하지 않고, 일절 여러 수신자를 받지 않습니다. 세 사람이 세 조각의 답을 쥐고 있다면 세 번 돌립니다. 가장 흔한 사용법은 막혀 버린 grilling입니다: 같은 대화 안에서 돌리십시오 — 이 skill에는 ingest 단계가 없고, grilling 뒤에 동작하는 것은 순전히 그 session이 이미 context에 들어 있기 때문입니다.

agent가 방금 말한 것을 다시 한 번 팔아 봅니다: 빠져 있던 context를 채우고, 쉬운 말로 쓰고, 프로젝트의 CONTEXT.md에 있는 어휘를 사용합니다.

이 skill은 단 세 줄이며, 그것은 미완성 초고가 아니라 설계입니다. 장황함과 싸우는 skill은 길어지면서 실패합니다: 사백 줄짜리 '간결하게 쓰라'를 읽어도 모델은 여전히 장황해집니다. 모델이 읽는 것은 호소가 아니라 분량이기 때문입니다.

이름이 곧 메커니즘입니다. 맨 앞에 오는 단어는 wait입니다. "좀 더 간결하게"는 agent의 출력에 대한 지시라서, 모델은 '단어를 깎는' 방식으로 따르고, 그 결과 당신은 더 길을 잃습니다. wait가 가리키는 것은 당신의 상태입니다: "이해가 여기서 무너졌다"라고 말하는 것입니다. "짧게 하라"는 말을 들은 agent는 전보를 씁니다. "잠깐, 나를 놓쳤어요"라는 말을 들은 agent는 되돌아가 다시 설명합니다. 유행하는 해법은 하나같이 출력을 이름 붙이고, 그래서 모델은 더 짧지만 더 명확하지는 않은 어투로 과잉 교정합니다. 듣는 사람을 이름 붙이면 두 조각을 한꺼번에 얻습니다: 더 적은 말, 그리고 당신에게 없던 그 전제.

의도적으로 "다시 설명할 것은 그것"이라고 말하지 "직전 메시지"라고 말하지 않습니다 — 당신을 놓친 것은 대개 한 문단보다 크고, 얼마나 뒤로 돌아갈지는 agent가 정합니다. 진짜 해독제는 미리 공유 언어를 만들어 두는 것이고, wait-what이 고치는 것은 이미 어긋나 버린 그 한 건입니다.

이것을 실행한 디렉터리를 상설 학습 워크스페이스로 바꾸고, 일련의 자체 스타일을 갖춘 짧은 HTML 레슨으로 여러 session에 걸쳐 한 가지 주제를 가르칩니다.

모델이 이미 알고 있는 것에서 가르치지 않습니다. parametric knowledge는 믿을 수 없는 것으로 취급됩니다: 가르치기 전에 먼저 신뢰도 높은 자료를 찾아 자료 파일에 기록하고, 모든 레슨에서 그것을 인용합니다. 그리고 이것은 상태를 가집니다 — mission, 자료, 레슨, 학습 기록이 모두 파일 형태로 디렉터리 안에 살고 있습니다:

핵심 개념은 storage strength(장기 보존)이지 fluency(그 순간의 회상감 — 읽을 때는 통달한 것처럼 느껴지지만 일주일 뒤에는 사라집니다)가 아닙니다. 이것은 바람직한 어려움을 사용해 전자를 만듭니다. 지식이 먼저입니다 (이 단계에서 어려움은 적이며, 이해에 필요한 작업 기억을 잡아먹습니다). 기량은 그다음에 타이트한 피드백 루프로 단련합니다 (이 단계에서 어려움은 도구입니다). 레슨은 좀처럼 다시 읽히지 않지만 레퍼런스 문서는 다시 읽힙니다 — 그래서 한 레슨의 압축된 핵심은 레퍼런스 디렉터리에 속하며, 그것을 도입한 레슨 안에 묻히는 것이 아닙니다.

함정: 파일이 엉뚱한 곳에 쓰일 수 있으니 (issue 377, 어떤 사람의 레슨이 전역 skill 디렉터리에 쓰였습니다), 시작할 때 디렉터리 이름을 분명히 말하십시오. 쪽지 시험의 정답이 늘 첫 번째 선택지입니다(여러 모델에서 확인됨, 미수정. 어떤 기여자는 9개 레슨 33회가 모두 A에 몰렸다고 보고했습니다). 능력 평가 단계가 없습니다. 첫 메시지에서 자신의 기존 지식과 공백을 말해 두십시오. 간격 반복 일정도 없습니다. 복습하고 싶으면 직접 요청하십시오.

코드에만 쓰는 것이 아닙니다 — 기록을 보면 코드가 아닌 용도가 더 큰 비중을 차지합니다. 코드에서 가장 강한 용도는 언어를 처음부터 배우는 것이 아니라, 낯선 codebase나 새 팀의 기술 스택에서 방향을 잡는 것입니다. 저자는 멋진 조합을 하나 언급했습니다. 캐물리는 도중에 모르는 것에 부딪히면, grilling을 멈추고 배우러 가지 마십시오 — 학습 워크스페이스로 handoff 해서 거기서 배운 뒤, 돌아와 이어 가십시오.

이것은 대화형 bash script를 생성해 사람을 한 단계씩 수동 절차에 따라 안내합니다 — 서드파티 서비스 연결, 일회성 마이그레이션 실행, 프로젝트를 상태 A에서 상태 B로 옮기기.

agent가 script를 쓰지만, 그것을 실행하는 일은 결코 없습니다. 실행은 각자의 기계에서 직접 합니다. 그래서 wizard는 그대로 따라 하기만 하는 설명서가 아니라, 프로세스를 구동하고 상태를 쥐고 있는 프로그램이며, 사람이 맡는 몫은 클릭과 붙여넣기, 그리고 Enter 누르기입니다. Stage는 '한 화면에 하나의 집중된 작업'이고, script는 stage 사이에서 터미널을 비웁니다.

script를 쓰기 전에 먼저 scoping: 아무것도 모른 채 묻는 대신 repo를 읽습니다 — 환경 파일, compose 파일, framework config, 그리고 CI 설정 안의 모든 secret과 변수 참조. 그 하나하나가 wizard가 만들어 내야 하는 값입니다. 그런 다음 순서를 매긴 stage 목록을 보여 주고 확인을 받은 뒤에야, 각 stage를 사람이 지나갈 정확한 경로에 대응시킵니다. 지금 UI가 어떻게 생겼는지 모를 때는 묻거나 문서를 찾아보며, 클릭을 지어내지 않습니다.

template이 이미 UX를 해결해 두었습니다: 진행 표시, 확인 게이트, 크로스 플랫폼 URL 열기, secret 가림 입력, 환경 파일 멱등 기록, CI secret 기록, 그리고 '무엇을 건너뛰어야 했는지'의 마무리 요약. 고정 라이브러리 쪽 절반은 어느 wizard에서나 같고, 손으로 고치는 일이 결코 없습니다. 일관성이 바로 핵심입니다. wizard를 쓰는 agent는 그것을 엔드투엔드로 실행하지 않고 정적 검증으로 대신합니다. 첫 실행은 직접 하는 것이고, 그 한 번이 그대로 테스트입니다.

함정: 도중에 이전 단계로 돌아갈 수 없습니다. 3번째 스테이지에서 잘못 입력하면 중단하고 다시 돌립니다 (다시 돌리는 비용은 싸고, 환경 파일에 이미 기록된 값은 기본값으로 되돌아옵니다). 프롬프트에서는 방향키에 bug가 있고(issue 741), backspace는 동작합니다. 서드파티 서비스의 상태를 조회하러 가지는 않습니다. API key는 모델 context에 들어가지 않습니다 — 다만 scoping 때 key를 채팅에 붙여 넣었다면, 그것은 붙여 넣은 다른 어떤 텍스트와도 마찬가지로 context 안에 있습니다.

이것은 설계를 진행하는 동시에 프로젝트의 ubiquitous language를 만들고 벼려 나갑니다 — 용어집과 충돌하는 표현에 이의를 제기하고, 모호한 말을 썼을 때 정확한 말을 끌어내며, 구체적인 시나리오로 하나의 관계를 경계가 또렷해질 때까지 압박 테스트합니다.

이것은 능동적인 규율이지 수동적인 것이 아닙니다. 그냥 CONTEXT.md를 읽어 어휘를 빌리는 것은 어떤 skill이든 할 수 있는 한 줄짜리 습관입니다. 이것은 모델을 바꾸고 있을 때 쓰는 것입니다. 이것이 바로 끼어드는 이유입니다: 용어가 정리되는 바로 그 순간, 대화 도중에 CONTEXT.md에 씁니다 — 배치 버전은 한 session의 요약이고, 실시간 버전은 그 session의 실제 산출물.

산출물 둘, 기준 둘. CONTEXT.md에 담기는 것은 용어(어떤 것이 무엇인지, 한두 문장)입니다. 기록 문턱은 '모호한 말이 정식 용어가 되는 순간'이고, 시점은 실시간입니다. 절대 담기지 않는 것은 구현 세부, spec, 메모장, 일반적인 프로그래밍 개념입니다. ADR에 담기는 것은 하나의 결정(한 문장에서 세 문장: context, 선택, 이유)입니다. 기록 문턱은 세 가지 모두 해당될 것 — 되돌리기 어려울 것, context가 없으면 뜻밖으로 느껴질 것, 실제 트레이드오프의 결과일 것 — 이며, 게다가 제안이지 기본값이 아닙니다.

정말로 기억해야 할 것은 CONTEXT.md의 그 규칙입니다. 실전에서 깨지는 것이 바로 그 규칙이기 때문입니다: 그것은 용어집이고, 용어집일 뿐입니다. 내버려 두면 모델은 'CONTEXT.md에 쓴다'를 '받은 답을 모두 영속화해도 된다'는 허가로 받아들이고, 파일은 굴러가는 spec이 되어 버립니다 — 이것은 이 skill에서 가장 많이 보고된 문제이며, 여러 모델에 걸쳐 나타납니다.

이 skill의 진가를 느끼게 하는 동작: 어떤 것이 어떻게 동작하는지 말하면, 코드를 뒤져 모순을 펼쳐 놓습니다 — "코드는 Order 전체를 취소하는데, 방금 부분 취소가 가능하다고 했습니다. 어느 쪽이 맞습니까?" 이렇게 해서, 어느 한쪽이 고쳐지기 전에 언어와 코드는 소리 내어 정렬되도록 강제됩니다. 제한: 코드와 이미 commit된 문서만 교차 참조하고, issue tracker는 뒤지지 않습니다. 그래서 몇 달 전에 이미 닫힌 issue 안에서 다 다투고 일부러 확정한 이름 충돌이 새것처럼 다시 올라옵니다.

함정: CONTEXT.md가 500줄 이상으로 커집니다 — 크기는 증상이지 병이 아닙니다. 곧바로 간결하게 줄이고 구현 세부를 없애라고 지시하십시오. 파일이 정말로 군더더기 없이 얇은데도, 독자가 동시에 머리에 담고 싶지 않은 두 영역을 여전히 다루고 있을 때에만 분할을 고려하십시오 — 비대해진 파일을 쪼개도 비대해진 파일이 여러 개 생길 뿐입니다. 자동 트리거는 이 skill의 가장 약한 부분입니다: 그릴링을 한 차례 끝까지 돌렸는데도 CONTEXT.md 파일이 전혀 바뀌지 않았다면 바로 그 일이 일어난 것입니다. 지목해서 지시하십시오. 사람의 검토를 거치지 않은, agent가 쓴 용어집은 없는 것보다 나쁩니다: 자신 있게 들리는 전설이 되어, 이후 session이 그것을 진실로 받아들입니다.

skill, 지시 파일, spec, runtime prompt, README — agent가 읽는 문서라면 무엇이든 해당합니다. 포장은 달라도 쓰는 법은 같습니다.

이 skill의 기본 동작은 설명이 아니라 삭제입니다. agent에게 다른 agent용 지시를 쓰게 하면 분량의 대부분은 모델이 이미 아는 것을 설명하는 데 들어갑니다. 그 줄들은 하나같이 no-op입니다. context 값은 치르면서 행동은 하나도 바꾸지 않습니다. 이 참고 자료는 바로 그런 줄을 찾아내는 렌즈입니다. 그래서 값을 하는 곳은 빈 파일만이 아닙니다. 이미 가지고 있는 문서에서도 최소한 그만큼의 값을 합니다.

부담은 두 가지입니다. Context load 쪽은 항상 로드되는 재료가 agent의 창에서 치르는 비용입니다. 지시 파일의 한 줄, skill description, 트리거되든 아니든 매 turn context에 들어 있는 모든 것이 여기에 들어갑니다. Cognitive load 쪽은 비용을 무는 주체가 다릅니다. 사람에게 드는 비용입니다. 어떤 문서가 있는지, 언제 어느 것을 꺼내야 하는지 — 그 색인이 바로 당신입니다. 이것은 최소화할 비용이 아니라, 사람이 주도권을 쥐기 위해 치르는 값입니다. 이 둘이 머릿속에서 정리되면, 글을 쓸 때의 판단은 대부분 같은 맞바꿈을 자리만 바꿔 가며 하는 일이 됩니다.

다섯 개의 지렛대: Context pointer(context 안에 있으면서 context 밖의 재료를 지목하고 '언제 가지러 갈지'까지 부호화한 참조. agent가 그것을 통해 얼마나 확실하게 손을 뻗는지를 정하는 것은 가리키는 대상이 아니라, pointer에 쓰인 말입니다), Information hierarchy('파일 안의 절차'에서 '파일 안의 참고'로, 다시 'pointer 뒤에 둔 참고'로 올라가는 사다리), Completion criteria(조기 완료를 막는 방어선), Leading words(모델의 사전 학습에 이미 들어 있는 압축된 개념. 닻은 두 번 내립니다 — body에서는 실행을 위해, pointer에서는 트리거를 위해), Pruning(단일 진실 원천, 관련성, 그리고 한 문장씩 적용하는 no-op test).

no-op test는 미학이 아니라 행동으로 판정합니다: 그 줄을 지우고 agent의 행동이 달라지는지 물으십시오. 통과하지 못한 문장은, 문장째로 삭제합니다. 표현만 손보는 것이 아닙니다. 의견이 갈릴 때는, 그 문서를 돌려 보는 것으로 해결하십시오. 논쟁하지 마십시오. 판단 기준은 문서가 좋아지는 동시에 짧아지는 것, 그리고 남은 분량이 이렇게 적은가 하고 놀라게 되는 것입니다. 하나 더, 같은 말이 두 번 나오지 않는다는 것 (반복은 '이 문서는 한 번도 시험된 적이 없다'는 가장 확실한 징후입니다).

이 skill이 다루는 것은 하나뿐입니다. 설익은 아이디어입니다. 그것을 놓고, 거기에 몸을 실을 수 있을 때까지 인터뷰합니다. 다 짜인 계획이 있어야 시작할 수 있는 것은 아닙니다. 그 계획을 만들어 내는 것이 바로 이 session의 용도입니다. 그리고 이 skill의 성격은 한마디로, 무상태입니다. 파일도 쓰지 않고 작업 공간도 남기지 않으며, 남는 것은 머릿속에서 더 날카로워진 판본뿐입니다. 주제가 코드일 필요도 없고 repo도 필요 없습니다.

plan mode는 꺼 두십시오. 이것은 agent에게 계획을 빨리 내놓으라고 재촉하는데, '질문 안에 머무른다'와 정확히 반대입니다.

제대로 돌아갈 때의 모습: 무언가에 이의를 제기하게 됩니다. 한 번도 되밀지 않은 session은 애초에 필요 없던 session입니다. 질문은 길게 이어지는 물방울이 아니라 '몇 번의 라운드'로 도착하고, 뒤쪽 라운드는 앞에서 한 말 위에 눈에 띄게 쌓입니다. 어떤 질문이 그동안 암묵적으로 내리고 있던 결정을 뒤집어 내기 때문에, 예상하지 못한 곳에 다다릅니다. 끝날 무렵에는 모든 선택을 그 자리에 없었던 사람 앞에서 변호할 수 있습니다.

라운드를 세십시오. 질문 수를 세지 마십시오. 46문항을 4라운드로 나누는 것이 평범한 한 판입니다. 200문항은 범위가 너무 넓다는 뜻이고, 지나치게 긴 session은 dumb zone, 곧 context window가 가득 차서 질문의 품질이 떨어지는 구간으로 떠내려갑니다. 캐묻기가 끝나고 하기로 마음을 굳혔다면, 새 session을 열지 마십시오. 그 대화의 context가 바로 가치입니다.

이것은 추천하고, 거기서 멈춥니다. grill도 하지 않고, spec도 쓰지 않고, 파일도 열지 않고, 방금 지목한 skill을 대신 띄워 주지도 않습니다 — 손에 들어오는 것은 '다음에 무엇을 칠지'뿐이고, 치는 쪽은 사람입니다. 건네주는 사고의 단위는 flow: 하나의 skill이 아니라, 여러 skill을 가느다란 길 하나가 한 줄기 길입니다.

알아 두어야 할 정직한 한계. 이것은 지도입니다. 손으로 쓴 것이라 repo보다 뒤처지고, 이 pack의 skill만 압니다. 게다가 이런 일까지 벌어집니다. "skill의 절반이 설치되어 있지 않다"고 말합니다. 알려져 있지만 아직 고쳐지지 않았습니다. 라우팅되는 skill 대부분은 user-invoked이고, harness는 그것들을 agent에 주입하는 목록에 넣지 않으며, agent는 그 목록을 완전한 것으로 여겨 존재하지 않는다고 보고합니다. 그 skill들은 설치되어 있습니다.

그리고 이런 일도 있습니다. 다른 skill의 동작을 잘못 설명할 수도 있습니다: skill 본체가 아니라 자기가 가진 한 줄 요약에서 답하기 때문입니다. 어떤 상세 보고는 한 session 안에서 그런 사례를 세 번 추적했는데, 'thread를 spec으로 바꾸는 것'이라는 거친 인상만으로 to-spec를 건너뛰라고 권한 경우도 들어 있었습니다. 그 SKILL.md 파일은 한 번도 열리지 않았고, 그 대가로 진짜 seam 점검이 한 번 빠졌으며 잘라 낸 티켓은 작업량을 과소평가했습니다. 다른 skill에 대해 핵심적인 단언을 할 때는 먼저 열어 보게 하십시오 — 바로 그 SKILL.md.

자리매김: ask-matt은 이 묶음 전체 위에 있는 secondary source입니다. router와 SKILL.md 파일이 서로 어긋날 때, SKILL.md 파일 쪽이 옳습니다.

상황: 고객이 "가끔 전송을 누르면 500이 난다"고 알려 왔는데, 스스로는 재현하지 못합니다.

1. 다른 사람이 알려 온 건이니 먼저 진입로를 탑니다: /triage. 알려 준 절차대로 재현이 됩니까. 재현되지 않으면 needs-info, 아니면 지금 쫓기로 결정합니다.
2. 지금 쫓기로 했다면, 새 session을 엽니다: /diagnosing-bugs. 그리고 "먼저 빨개지는 루프부터 만들어 달라"고 분명히 말합니다.

이다음은 기계적입니다. 최소화(남은 요소는 하나하나 왜 핵심적인지 말할 수 있어야 합니다), 3개에서 5개의 순위를 매긴 반증 가능한 가설(사람이 확인하는 유일한 지점), 꼬리표를 단 프로브 심기, 고치기 전에 회귀 테스트부터 쓰기, 뒷정리, 그리고 맞아떨어진 가설을 commit message에 적기.

알아 둘 갈림길이 하나 있습니다: 그 회귀 테스트를 놓을 올바른 seam이 없을 때는, 헛된 안심을 주는 얕은 테스트를 쓰지 말고 그렇다고 말해야 합니다. 'seam이 없다'는 사실 자체가 발견입니다. 넘길 곳은 improve-codebase-architecture.

상황: 8년 된 프로젝트에 막 합류했거나, vibe-coded된 repo를 넘겨받았습니다. ADR도 없고 도메인 언어도 없고 설계 원칙도 없습니다.

1. 첫날: /setup-matt-pocock-skills 명령으로 tracker와 문서 배치를 잡습니다.
2. 첫날: /grill-with-docs로, 이 기존 repo를 CONTEXT.md 파일로 세워 달라고 요청하십시오. 인터뷰 길이를 미리 각오하십시오. 아주 깁니다. 파일이 형태를 갖추기까지 50문항 이상 걸렸다는 보고도 있습니다. 그리고 능동적으로 방향을 잡아 주십시오 — 이 skill은 코드를 읽고 자기가 찾은 것을 물어보지만, '코드에 이미 있는 말 가운데 어느 것이 옳은 말인가'는 사람이 정합니다.
3. 둘째 날: /improve-codebase-architecture를 부르고, 첫마디로 "캐묻지 말고 먼저 보고서를 주십시오"라고 말합니다. 전부 Speculative라면 사실은 아무것도 찾아내지 못했다는 뜻입니다. Strong 후보를 하나 고르십시오.
4. 둘째 날: 후보는 한 번에 하나씩. 그 후보를 대상으로 grilling 하게 하고, 산출물은 diff가 아니라 '결정'입니다. 그다음에 to-spec, to-tickets, implement.
5. 그 이후: 며칠에 한 번씩 아키텍처 점검을 다시 돌려 유지 보수로 삼습니다.

솔직한 기대치: 정말로 손을 쓸 수 없게 된 프로젝트에서는 "조금은 도움이 됐지만 그래도 부족하다"는 보고가 있었습니다. 8년 된 legacy codebase에서는 모델이 제자리를 맴도는 것을 본 사람도 있고, 같은 skill이 잘 정돈된 repo에서는 깔끔한 그림을 내놓습니다. 현재 이 사례를 전담하는 skill은 없습니다.

상황: 새 제품 모듈을 처음부터 만들어야 하는데 경로가 전혀 보이지 않고, 한 번의 대화로 끝낼 수 있는 일이 아닌 것이 분명합니다.

1. 먼저 다섯 개의 wayfinder: label이 존재하는지 확인하십시오 (없는 label을 쓰면 gh 명령이 그대로 실패합니다).
2. /wayfinder. 가장 먼저 할 일은 destination에 이름을 붙이는 것입니다. 여기서 묻는 것은 '지도 전체의 목적지'이지 이번 session의 목적지가 아닙니다. 범위를 경계가 분명한 하나의 epic으로 좁히십시오. 'V1 구현'은 안 됩니다.
3. 너비 우선으로 grilling을 한 번 수행해 Destination, Decisions so far, 안개, Out of scope를 그려 냅니다. 안개와 티켓을 가르는 판단 기준은 그 질문을 '지금' 정확히 말할 수 있는지 여부입니다. 첫 grill에서 안개가 하나도 나오지 않으면 "이건 지도가 필요 없을 만큼 작은 일입니다"라고 말하며 멈춰야 합니다.
4. research 티켓은 지도를 그리는 동안 곧바로 발사해 병렬로 태웁니다. 나머지 티켓은 한 번에 한 장씩. 자신에게 assign 해서 맡습니다.
5. 한 장을 풀 때마다 resolution 코멘트를 붙이고, 티켓을 닫고, 지도에 한 줄을 남긴 다음 멈추십시오. 앞쪽의 안개를 걷어 내고, 지금 말로 표현할 수 있게 된 것을 새 티켓으로 졸업시킵니다.
6. 지도가 비면: /to-spec #<map_issue>(전달하는 것은 메인 지도이고, 개별 decision 티켓이 아닙니다). 그다음에 /to-tickets, /implement.

치명적인 함정 세 가지는 06절 wayfinder 항목에 이미 나와 있습니다: agent가 정식 코드를 쓰기 시작한다는 것, 그리고 to-spec을 건너뛰지 말 것, grilling 티켓을 병렬로 돌리지 말 것.

상황: 비즈니스 판단을 고민하는 중입니다 — 새 제품 라인을 낼지 말지, 제안서 가격을 어떻게 정할지, 글 하나의 논증 뼈대를 어떻게 세울지.

1. 깨끗한 대화를 하나 엽니다 (어떤 repo 안에 있을 필요도 없습니다). plan mode를 끄고, /grill-me.
2. 한 라운드씩 답하고, 번호를 붙여 한꺼번에 돌려줍니다. 너무 얕은 질문은 되밀고, 범위가 흔들리면 말합니다. "모르겠습니다"도 진짜 답입니다.
3. '직접 보지 않으면 답할 수 없는' 질문을 만나면 그것은 ungrillable입니다. 코드가 아닌 상황에서는 대개 한 장짜리 초안을 먼저 만들거나, 표를 하나 먼저 계산하거나, 고객 한 명에게 먼저 물어보는 일입니다.
4. '답이 다른 사람의 머릿속에 있는' 질문을 만나면, 같은 대화 안에서 마지막으로 /to-questionnaire. 그것을 그 사람에게 보내고, 답이 오면 다음 라운드를 엽니다.
5. 이것은 상태를 남기지 않습니다. 파일을 쓰지도, 워크스페이스를 남기지도 않습니다. 남는 것은 머릿속에 있는 더 날카로워진 판뿐입니다.