Matt Pocock 스킬 저장소의 멘탈 모델

TypeScript 교육자 Matt Pocock이 자기 .claude 폴더를 그대로 공개한 저장소 mattpocock/skills를 딥 다이브한 기록입니다. 기치는 "바이브 코딩이 아니라 진짜 엔지니어링을 위한 스킬"이고, 2026년 4월 GitHub 트렌딩 1위에 오른 뒤 별 13만 개를 넘겼습니다. 이 문서는 개별 스킬의 사용법이 아니라, 스킬들이 딛고 선 멘탈 모델을 한 번에 이해하는 것을 목표로 합니다.

1. 진단: 에이전트와 일하면 왜 실패하는가

1.1 네 가지 실패의 원풍경

코딩 에이전트를 써 본 사람이라면 누구나 겪는 실패가 네 가지 있습니다. 각각 겉보기 현상 밑에 다른 원인이 있습니다.

진단 1. 정렬 실패: 시킨 대로 만들었는데 원한 게 아니다. 에이전트의 능력 문제처럼 보이지만, 원인은 소통 격차입니다. 더 깊은 원인은 "누구도 자기가 뭘 원하는지 정확히 모른다"는 것. 내 머릿속 계획에는 검토 안 된 가지가 항상 있고, 에이전트는 그 빈 가지를 조용히 자기 가정으로 채웁니다.

진단 2. 언어 실패: 말이 장황하고, 매 세션 같은 설명을 반복한다. 원인은 공유 어휘의 부재입니다. 낯선 회사에 매일 처음 출근하는 사람은 한 단어면 될 것을 스무 단어로 돌려 말할 수밖에 없습니다. 같은 설명을 세션마다 다시 하는 것은 반복해서 내는 세금입니다.

진단 3. 피드백 실패: 그럴듯한데 안 돌아가는 코드. 원인은 에이전트가 자기 결과를 확인할 수단 없이 눈 감고 코딩한다는 것입니다. 피드백의 속도가 곧 속도 제한인데, 확인 루프가 없으면 제한속도는 0입니다.

진단 4. 엔트로피 실패: 몇 주 뒤에 보면 진흙탕 코드베이스. 원인은 생성 비용의 붕괴가 부패 속도도 함께 가속한다는 것입니다. 쌓는 게 싸지면 쓰레기도 싸게 쌓입니다.

1.2 네 실패의 공통 뿌리

겉보기에 다른 네 실패는 LLM의 두 성질에서 유도됩니다.

• 확률적이다. 같은 입력에도 다른 출력이 나온다. 진단 1(빈 가지를 매번 다르게 채움)과 진단 3(확인 없이는 추측 코딩)이 여기서 나온다.
• 기억이 없다. 세션마다 초기화되는, 영화 메멘토의 주인공 같은 신입이다. 진단 2(매번 재설명)와 진단 4(과거 결정을 모른 채 쌓음)가 여기서 나온다.

이 진단 위에 그의 기둥 명제 세 개가 섭니다. 아직 해법이 아니라 세계관입니다.

1. 피드백 루프의 품질이 AI 출력의 천장이다. 만들기가 공짜에 가까워질수록, 전체 속도는 "얼마나 빨리 만드나"가 아니라 "얼마나 빨리 확인하나"가 정한다.
2. 코드베이스가 프롬프트보다 큰 변수다. "당신의 코드베이스가, 프롬프트나 AGENTS.md 파일보다 훨씬 더, AI 출력에 가장 큰 영향을 준다."
3. 예측해야 할 것은 출력이 아니라 절차다. 확률적 시스템에서 짜낼 수 있는 결정성은 "매번 같은 결과"가 아니라 "매번 같은 절차"다.

1.3 기존 처방들은 왜 부족한가

같은 문제를 인정하는 다른 진영이 둘 있습니다.

무거운 프레임워크(GSD, BMAD, Spec-Kit). 파이프라인 전체를 도구가 소유합니다. 단계, 산출물, 순서가 도구 쪽에 정의되어 있어 처음에는 난간이 되어 주지만, 프로세스 중간에서 이상한 결과가 나오기 시작하면 어느 숨은 프롬프트가 원인인지 찾을 수 없습니다. 그의 표현으로 "통제권을 가져가고, 프로세스의 버그를 고치기 어렵게 만듭니다."

specs-to-code 운동. 스펙을 잘 쓰면 코드가 나온다고 믿습니다. 그러나 사람이 앉아서 스펙을 쓰면, 생각 못 한 가지는 스펙에도 없습니다. 문서가 정렬을 만드는 게 아니라, 정렬이 먼저 있어야 문서가 의미를 갖습니다.

더 좋은 모델 기다리기. 모델이 좋아져도 정렬 문제는 사라지지 않습니다. 뛰어난 모델은 어긋난 방향으로 더 일관되고 유능하게, 더 멀리 갑니다. 유능한 이탈이 무능한 이탈보다 되돌리기 비쌉니다.

이 절은 해법 없이 끝납니다. 그러면 도대체 어떻게 해야 할까요.

1.4 그가 답을 찾으러 간 곳: 고전들

그의 답은 새 발명이 아니라 수십 년 검증된 소프트웨어 공학 고전의 번역입니다.

그의 자기 규정이 이 장의 결론입니다. "새로울 게 하나도 없다. 좋은 코드베이스는 20년 전부터 이렇게 설계돼 왔다. 사람에게 좋았던 것이 AI에게도 좋다." 답의 재료는 이미 있었고, 문제는 그것을 에이전트의 작업 절차로 번역하는 일이었습니다.

2. 전체 흐름: 일이 흐르는 길

1장의 네 진단에 대한 그의 답이 이 파이프라인입니다. 그림의 세 층(본선, 진입로, 어휘 층)과 점선 상자(세션 경계)를 차례로 풀겠습니다.

2.1 본선: 아이디어에서 커밋까지

어렴풋한 아이디어를 들고 /grill-with-docs를 부르면 에이전트가 코드베이스를 탐색한 뒤 사람을 집요하게 인터뷰합니다. 한 번에 한 질문씩, 질문마다 추천 답을 붙여서요. 대화로 답이 안 나오는 고해상도 질문(UI가 어떤 느낌인지, 상태 모델이 말이 되는지)이 나오면 /handoff로 빠져나가 /prototype에서 버리는 코드를 만져 보고, 결정만 들고 돌아옵니다.

정렬이 끝나면 /to-spec이 그 대화를 새 인터뷰 없이 스펙으로 요약해 이슈 트래커에 올리고, /to-tickets가 스펙을 수직 슬라이스 티켓들로 잘라 차단 관계를 연결합니다. 여기까지가 사람 몫의 정렬 작업입니다.

이후는 기계적입니다. 차단자가 모두 해소된 티켓(frontier)을 하나 집어, 깨끗한 새 컨텍스트 창에서 /implement를 돌립니다. implement는 계획 때 합의한 seam에서 /tdd를 구동해 실패하는 테스트부터 쓰고, 끝나면 /code-review가 표준과 스펙 두 축으로 검사한 뒤 커밋합니다. 티켓이 남아 있는 한 이 바퀴가 반복됩니다.

2.2 진입로: 일이 굴러들어오는 세 가지 상황

• 이슈가 쌓임 → /triage. 남이 올린 날것의 리포트를 검증해 에이전트가 집을 수 있는 계약서로 만들고 본선에 합류시킵니다. 단, /to-tickets가 만든 티켓은 이미 정제되어 태어났으므로 triage에 다시 넣지 않습니다. 정제 공정을 통과한 물건을 다른 정제 공정에 넣으면 비용은 두 배, 품질은 오히려 저하됩니다.
• 뭔가 깨짐 → /diagnosing-bugs. 재현 루프부터 만들고, 수정은 본선의 구현 규율을 따릅니다.
• 크고 안개 낌 → /wayfinder. 한 세션에 안 담기는 일의 지도를 그려 결정을 하나씩 해소하고, 길이 보이면 /to-spec에서 본선에 합류합니다.

2.3 컨텍스트 위생

컨텍스트 창에는 똑똑한 구간(smart zone, 최신 모델 기준 약 12만 토큰)이 있고, 이를 넘기면 광고된 창 크기와 무관하게 판단이 나빠집니다. 그래서 흐름 사이에 창 관리 규칙이 있습니다.

• grill에서 to-tickets까지는 한 번도 끊기지 않은 창에서 잇습니다. 인터뷰, 스펙, 티켓이 같은 사고 위에 쌓여야 하기 때문입니다.
• /implement는 티켓마다 새 창에서 시작합니다. 티켓이 자기완결적 계약서라서 가능합니다.
• smart zone에 다가가면 저하된 채로 밀지 않고 /handoff로 갈아탑니다. "handoff는 분기하고, compact는 계속한다." compact는 도구가 알아서 하는 손실 압축이라 뭐가 살아남을지 모르지만, handoff는 사람이 읽고 고칠 수 있는 문서입니다.

2.4 상태 수명표

이 파이프라인의 본질은 "단계의 연쇄"가 아니라, 대화 컨텍스트에서 가치를 빼내 수명에 맞는 집에 넣는 과정입니다.

맨 아랫줄이 핵심입니다. 대화 컨텍스트만 집이 없습니다. 거기 쌓인 가치는 전부 위의 집들로 옮긴 뒤 세션을 버립니다. 세션은 소모품이고, 상태가 자산입니다.

3. 스킬별 핵심 요소

각 스킬을 같은 틀로 봅니다: 막는 실패(1장의 진단 역참조), 반드시 짚을 규칙, 시그니처 인용, 앞뒤 연결.

3.1 계획 다지기: grilling, grill-me, grill-with-docs

위치: 본선의 첫 단계. 막는 실패: 진단 1(정렬).

구조부터 특이합니다. 인터뷰 절차는 여섯 문장짜리 공용 엔진 grilling에만 살고, grill-me와 grill-with-docs는 각각 한 줄짜리 진입점입니다("Run a /grilling session."). 같은 절차를 두 곳에 복사하지 않기 위한 함수 추출입니다.

• 한 번에 한 질문, 답을 기다린다. 질문 열 개를 쏟아내면 사람은 세 개만 답하고, 나머지는 에이전트의 가정으로 채워집니다.
• 질문마다 추천 답을 붙인다. 사람을 저자가 아니라 검토자로 만들어, 뻔한 질문은 "응" 한 마디로 지나가게 합니다.
• 사실과 결정을 가른다. 코드를 뒤지면 나오는 사실은 에이전트가 직접 찾고, 판단만 사람에게 묻습니다.
• 출구는 사람의 확인. "공유된 이해에 도달했다"고 사람이 확인하기 전까지 실행 금지.
• 질문에는 해상도가 있다. "라우트 URL 뭘로 할까"는 대화로 풀리지만(저해상도), "이 UI가 어떤 느낌이어야 하나"는 대화로 안 풀립니다(고해상도). 고해상도 질문이 나오면 인터뷰를 멈추고 prototype으로 빠졌다가 돌아옵니다.
• grill-with-docs는 여기에 domain-modeling을 얹어, 인터뷰 중 굳어진 용어와 결정을 그 자리에서 문서로 남깁니다. grill-me는 코딩 밖 용도(글쓰기, 브레인스토밍, 의사결정)로 재배치됐습니다.

"사실이 코드베이스를 뒤져서 알 수 있는 것이면 나에게 묻지 말고 직접 찾아라. 그러나 결정은 내 것이다."

핵심 멘탈 모델: 코드 이전의 가장 싼 품질 레버는 질문이고, 질문의 산출물은 문서가 아니라 정렬이다. 그는 grilling이 끝난 뒤 나온 스펙을 읽지도 않습니다. 정렬이 이미 됐으면 문서화는 LLM이 잘하는 요약 작업일 뿐이기 때문입니다.

연결: 출력이 to-spec의 입력이 된다. 고해상도 질문은 prototype으로 우회한다.

3.2 어휘 층: domain-modeling, codebase-design

위치: 모든 단계 밑에서 도는 바닥 층. 막는 실패: 진단 2(언어).

domain-modeling은 두 산출물을 관리합니다. CONTEXT.md는 용어집이고("용어집이며, 그 외의 무엇도 아니다"), ADR은 결정의 이유 기록입니다. 규칙:

• 에이전트는 사서가 아니라 헌병이다. 용어집과 충돌하는 말에 시비 걸고("account라고 하셨는데 Customer인가요 User인가요?"), 엣지 케이스 시나리오로 개념의 경계를 시험하고, 말과 코드가 다르면 어느 쪽이 맞는지 따집니다. 어휘는 사후에 정리하는 게 아니라 대화 중에 단속해야만 살아 있습니다.
• 용어가 굳는 순간 인라인으로 기록한다. 모아서 나중에 쓰지 않습니다.
• ADR은 3중 관문을 전부 통과할 때만. 되돌리기 어렵고, 맥락 없이는 의아하고, 진짜 트레이드오프의 결과일 것. 다 기록하는 것은 안 기록하는 것과 같습니다.
• 표준어 하나에 금지 동의어 목록을 붙인다. 한 개념은 한 단어로만 부릅니다.
• 읽기와 쓰기를 가릅니다. CONTEXT.md를 읽는 것은 어느 스킬이든 하는 한 줄짜리 습관이고, 이 스킬은 모델이 바뀔 때만 발동합니다.

codebase-design은 설계 어휘의 정본입니다. 깊은 모듈(작은 인터페이스 뒤에 많은 동작), 삭제 테스트("모듈을 지웠을 때 복잡성이 사라지면 통과 배관이었고, 호출자들에게 다시 나타나면 제 몫을 하던 것이다"), seam 규율("어댑터가 하나면 가상의 seam이고, 둘이면 진짜다"). 인터페이스를 최대주의로 정의하는 것도 특징입니다: 타입 시그니처가 아니라 불변식, 순서, 에러 모드, 성능까지 호출자가 알아야 하는 모든 것.

"이 용어들을 정확히 그대로 써라. component, service, API, boundary로 바꿔 부르지 마라. 일관된 언어가 곧 요점이다."

연결: 모든 계획·설계 스킬이 이 어휘를 소비한다. tdd와 improve-codebase-architecture가 seam과 깊은 모듈 어휘를 공유한다.

3.3 분해 층: to-spec, to-tickets, wayfinder

위치: 본선 grill 다음. 막는 실패: 진단 1의 증발(정렬이 세션과 함께 사라짐)과 진단 4(무계획 누적).

세 스킬은 "안개의 양"이라는 한 축 위에 놓입니다. 안개가 없고 한 창에 담기면 티켓 없이 바로 구현, 안개가 없지만 여러 창이 필요하면 to-spec과 to-tickets, 질문조차 아직 못 만드는 안개라면 wayfinder입니다.

to-spec: 대화를 스펙으로 굳힙니다.

• 인터뷰 금지. "사용자를 인터뷰하지 마라. 이미 아는 것을 종합만 하라." 수집 국면과 종합 국면을 섞으면 국면이 무한히 늘어집니다. 대화가 이미 스펙이고, 실패는 스펙 부재가 아니라 대화의 증발입니다.
• 유일한 사람 체크포인트는 seam. 기능 목록이 아니라 "어디서 검증할 것인가"를 확인받습니다. seam은 최소로, 최고 높이로, 이상적인 개수는 하나.
• 썩는 것 반입 금지. 파일 경로와 코드 조각은 스펙이 실행될 때쯤 낡아 있으므로 넣지 않습니다. 예외는 결정을 산문보다 정확히 표현하는 프로토타입 조각(상태 기계, 스키마, 타입 모양)뿐.

to-tickets: 스펙을 티켓 그래프로 자릅니다.

• 티켓은 수직 슬라이스다. 스키마부터 UI까지 얇지만 완전한 경로를 관통하는 tracer bullet. 층별(수평)로 자르면 마지막까지 아무것도 돌려볼 수 없습니다. AI의 기본 성향이 수평이므로 명시적으로 거부해야 합니다.
• 티켓 크기 = 새 컨텍스트 창 하나. 에이전트 시대의 프로젝트 관리는 컨텍스트 창 관리입니다.
• 차단 관계를 그래프로 명시한다. "1단계, 2단계" 선형 계획은 손으로 푼 루프일 뿐이고, 그래프로 바꾸면 frontier의 티켓들을 병렬로 집을 수 있습니다. 순서 결정과 진행 제어를 LLM의 판단에서 빼내 트래커의 데이터와 단순한 반복 루프에 맡기는 것입니다.

wayfinder: 안개 낀 큰일의 지도를 그립니다.

• 티켓이 결정을 담지, 작업을 담지 않는다. 티켓 하나를 닫는 것은 뭔가를 만든 게 아니라 결정 하나가 내려진 것입니다. "그냥 일을 해버리고 싶은 충동이 드는 것은, 대개 지도의 가장자리에 도달했으니 넘겨줄 때가 됐다는 신호다."
• fog of war. 아직 질문으로 정확히 진술할 수 없는 것은 티켓이 아니라 안개("Not yet specified")에 둡니다. 볼 수 없는 곳은 지도에 그리지 않습니다.
• 지도는 색인이지 저장소가 아니다. 결정은 자기 티켓 안에만 살고, 지도는 한 줄 요약과 링크만 담습니다. 세션은 저해상도 지도만 로드합니다.
• 세션당 티켓 하나만 해소, 작업 전에 자기를 담당자로 걸어 선점, 사람이 읽는 곳에서는 티켓을 번호가 아니라 이름으로 부릅니다.

"Wayfinding은 길을 찾는 일이지, 목적지로 돌격하는 일이 아니다."

연결: to-spec은 grill의 순금 컨텍스트를 소비한다. to-tickets의 출력은 implement가 집어 간다. wayfinder는 길이 보이면 to-spec으로 합류한다.

3.4 실행 층: implement, tdd, prototype, research

위치: 본선의 에이전트 구간. 막는 실패: 진단 3(피드백).

implement: 전문이 다섯 문장입니다. 스펙이나 티켓을 읽고, 합의된 seam에서 tdd를 구동하고, 타입 체크와 개별 테스트는 수시로 돌리되 전체 스위트는 마지막에 한 번, 끝나면 code-review, 그리고 커밋. 짧다는 것 자체가 설계입니다. 진짜 결정은 전부 상류에서 끝났으므로, 구현 국면은 지루한 파이프라인이어야 한다는 선언입니다. 모델이 스스로 구현을 시작할 수 없게 사람 발동 전용입니다.

tdd: red-green 루프가 간직할 가치가 있는 테스트를 만들게 하는 레퍼런스입니다. TDD가 뭔지는 설명하지 않고(모델이 이미 아는 것을 적으면 낭비), 에이전트가 실제로 저지르는 이탈만 이름 붙여 막습니다.

• 합의 안 된 seam에는 테스트를 쓰지 않는다. 테스트 지점은 계획의 산물이지 즉석 발명이 아닙니다.
• 안티패턴 3종, 각각 탐지법과 함께. implementation-coupled(내부를 모킹, 리팩토링에 깨지는 테스트), tautological(기대값을 코드와 같은 방식으로 재계산해 구조상 실패가 불가능한 테스트. 기대값은 독립된 진실의 출처에서), horizontal slicing(테스트 전부 먼저 쓰기. 상상된 행동을 검증하게 됨).
• 모킹은 시스템 경계에서만. 외부 API, 시간, 난수. 자기 모듈끼리는 절대 금지.
• refactor는 루프에서 잘라내 code-review로 보냈다. 루프는 기계적일수록 안전하고, 재량은 검토가 있는 관문에서 발휘돼야 하기 때문입니다.

prototype: "질문에 답하는 버리는 코드. 질문이 형태를 결정한다." 코딩 전에 질문을 글로 적고 두 갈래 중 하나로 분류합니다. 로직 갈래("이 상태 모델이 말이 되나")는 순수 모듈 + 버리는 터미널 껍데기, UI 갈래("어떻게 생겨야 하나")는 구조가 다른 변형 3～5개를 실제 페이지 안에서 전환하며 비교. 테스트 금지, 영속화 금지, 다듬기 금지. 버리는 비용이 0에 가까워야 매몰 비용이 설계 판단을 오염시키지 못합니다. 끝나면 결정만 승격됩니다: 결정 조각은 스펙으로, 로직 갈래의 순수 모듈은 본 코드로, 프로토타입 전체는 참조용 사료로 버리는 브랜치에.

"살짝씩 손본 카드 그리드 세 개는 UI 프로토타입이 아니라 벽지다."

research: 세 문장짜리 정책 스킬. 백그라운드 에이전트에 위임하고(본 세션은 계속 일한다), 1차 사료만 보고("모든 주장을 그 주장을 소유한 출처까지 따라가라"), 인용 달린 마크다운 파일로 저장소에 남깁니다. 산출물의 수명은 일부러 짧습니다. 낡은 리서치는 자신감 있는 거짓말을 주입하므로 스프린트가 끝나면 버립니다.

연결: implement는 to-tickets의 frontier에서 티켓을 받고, tdd는 to-spec이 합의한 seam을 받으며, refactor 책임은 code-review가 인수한다.

3.5 검증과 수리: code-review, diagnosing-bugs, triage

위치: 본선의 관문과 진입로. 막는 실패: 진단 3과 4.

code-review: 리뷰를 두 축으로 분리합니다. "우리 컨벤션을 따르는가"(표준)와 "시킨 것을 만들었는가"(스펙)는 무관한 질문이라, 섞으면 한 축의 합격이 다른 축의 불합격을 세탁합니다. 두 축을 별도 서브에이전트로 병렬 실행하고, 결과를 합치거나 순위 매기지 않고 나란히 보고합니다. 저장소에 표준 문서가 없으면 Fowler 코드 스멜 12종을 기본선으로 깔되, 문서화된 저장소 표준이 항상 우선하고 스멜은 "판단 대상 힌트"로만 표기합니다.

diagnosing-bugs: 에이전트 디버깅의 고전적 실패(코드를 읽고 그럴듯한 이론을 세워 패치)를 하드 게이트로 막습니다. 이 버그에서 빨간불이 켜지는, 결정적이고 빠른 재현 명령 하나를 만들기 전에는 가설 금지. "올바른 피드백 루프를 만들면 버그는 90% 고쳐진 것이다. 나머지는 기계적인 작업이다." 이후는 소거법입니다: 재현을 최소화하고, 반증 가능한 가설 3～5개를 순위 매겨 보여주고, 변수 하나씩 계측하고, 수정 전에 회귀 테스트를 올바른 seam에 씁니다. 올바른 seam이 없다는 발견 자체가 아키텍처 개선의 입력이 됩니다.

triage: 받은편지함의 혼돈에 상태 기계를 씌웁니다. 카테고리 역할 2개(bug, enhancement)와 상태 역할 5개(needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix)를 이슈마다 정확히 하나씩. "PR은 코드가 첨부된 이슈다. 같은 역할, 같은 상태, 같은 기계." 리포터에게 묻기 전에 재현부터 하고(검증이 대화보다 먼저), ready-for-agent의 조건은 라벨이 아니라 계약서입니다: 행동 계약으로 쓰고 파일 경로는 금지해서 몇 주의 코드베이스 표류를 견디게 합니다. 거절된 제안은 .out-of-scope/에 개념당 파일 하나로 남아 다시 재판받지 않습니다. 단, "이미 구현돼 있어서" 닫은 건은 거절이 아니므로 넣지 않습니다. 가짜 거절이 중복 검사를 오염시키기 때문입니다.

"원래 본문과 토론은 맥락이고, agent brief가 계약이다."

3.6 설계 개선: improve-codebase-architecture

위치: 며칠에 한 번 도는 정기 검진. 막는 실패: 진단 4(엔트로피).

얕은 모듈, 흩어진 로직, 테스트 불가능한 seam은 일상 작업에서 보이지 않으므로, 주기적으로 스캔해서 깊게 만들 기회를 찾습니다. 규칙: 에이전트는 발견만 하고 리팩토링은 사람의 선택입니다. 후보들을 카드 형식의 HTML 보고서(저장소가 아니라 임시 폴더에)로 보여주되 정직성 배지(Strong, Worth exploring, Speculative)를 달고, "아직 인터페이스를 제안하지 말 것", 사람이 고른 후보만 grilling으로 파고듭니다. 기존 ADR은 재소송하지 않고, 거절된 후보는 새 ADR로 기록해 다음 스캔이 같은 제안을 반복하지 않게 합니다.

3.7 세션 관리: handoff, ask-matt

위치: 세션의 경계와 시작점. 막는 실패: 진단 2의 세션판(세션 사이 기억 상실)과 스킬 목록 과부하.

handoff: 세션의 유언장입니다. 대화를 다음 에이전트가 이어받을 문서로 압축하되, 스펙·ADR·커밋에 이미 있는 내용은 복제하지 않고 경로와 URL로 참조만 합니다(복제본은 썩으므로). 내용물은 정확히 "포인터 + 아직 어디에도 안 적힌 잔여 맥락"입니다. 저장 위치는 저장소가 아니라 OS 임시 폴더입니다. 프로젝트 산출물이 아니라 세션 간 조율용 소모품이라는 신분 선언입니다. 다음 에이전트가 켜야 할 스킬 목록(suggested skills)까지 담습니다.

ask-matt: 스킬 수십 개를 사람이 다 기억할 수 없다는 문제의 처방인 라우터입니다. 첫 문장이 전부입니다: "You don't remember every skill, so ask." 본문은 사실상 시스템 설계도로, 본선과 진입로의 그래프, 컨텍스트 위생 규칙, 흐름 사이의 교통 규칙(to-tickets 산출물은 triage 금지)이 여기 삽니다. 개별 부품의 규칙은 부품에, 부품 사이의 상호작용 규칙은 그 부품들을 모두 내려다보는 층에 둔다는 배치 원칙입니다.

3.8 메타: writing-great-skills

위치: 다른 모든 스킬의 스타일 권위. 막는 실패: 스킬 자체의 부패.

"스킬은 확률적 시스템에서 결정성을 짜내기 위해 존재한다. 예측 가능성, 즉 에이전트가 매번 같은 출력을 내는 게 아니라 같은 절차를 밟는 것이 뿌리가 되는 미덕이다."

• 두 화폐 경제. 모델 발동 스킬은 설명문이 매 턴 컨텍스트에 상주하는 컨텍스트 부담을, 사용자 발동 스킬은 사람이 존재를 기억해야 하는 인지 부담을 지불합니다. 스킬을 쪼갤지, 어떤 발동으로 할지, 내용을 본문에 둘지 참조 파일로 뺄지는 전부 "어느 화폐로 내는 게 싼가"의 경제 문제입니다.
• leading word. 모델이 사전 학습으로 깊게 아는 압축 개념(tracer bullet, seam, tight)을 골라 문단 대신 그 단어로 행동을 조종합니다. 최소 토큰으로 최대 행동을 사는 기법입니다.
• 스킬의 실패 유형 6종. premature completion(느슨한 완료 기준), duplication(같은 의미가 여러 곳에), sediment(지우기 무서워 쌓이는 낡은 층. "가지치기 규율이 없는 스킬의 기본 운명"), sprawl(옆 영역까지 삼키는 비대화), no-op(모델이 어차피 하는 행동을 적은 줄. 문장을 통째로 지워 보고 행동이 안 변하면 삭제), negation("코끼리를 생각하지 마"는 코끼리를 활성화하므로 원하는 행동을 긍정문으로).
• 스킬의 결정성은 "이탈 발견, 원인 문장 찾기, 조이기"의 반복으로 얻어지고, 이 루프는 스킬이 읽을 수 있을 때만 돕니다. 읽을 수 없는 프로세스는 고칠 수 없고, 고칠 수 없는 프로세스는 예측 가능해질 수 없습니다.

4. 관통하는 설계 수법 7가지

스킬 열일곱 개를 다 외울 필요는 없습니다. 반복되는 수법 일곱 개를 알면 나머지가 유도됩니다.

1. 상태를 컨텍스트 밖으로. LLM에게서 뺏을 수 있는 결정과 상태는 전부 뺏어서 읽을 수 있는 곳(트래커, 파일, 문서)에 둔다. 티켓 그래프, wayfinder 지도, CONTEXT.md, handoff 문서가 전부 이것.
2. 사실은 에이전트, 결정은 사람. 조회 가능한 것은 에이전트가 직접 찾고, 판단만 사람에게 온다. grilling의 질문 규칙, triage의 선검증, improve-codebase-architecture의 "발견은 에이전트, 선택은 사람".
3. 국면을 섞지 않는다. 수집(grill)과 종합(to-spec), 계획(to-tickets)과 실행(implement), 구현(tdd)과 정리(code-review의 refactor)를 칼같이 가른다. 국면이 섞이면 어느 쪽도 끝나지 않는다.
4. 썩는 것 반입 금지. 파일 경로, 코드 조각, 시점 종속 사실은 오래 사는 문서에 넣지 않는다. 스펙, 티켓, agent brief, handoff 모두 같은 규칙. 예외는 결정을 인코딩한 조각뿐.
5. 수직 슬라이스의 프랙탈. 티켓 수준에서도(to-tickets), 테스트 수준에서도(tdd) 항상 얇은 관통 사격. 층별로 자르면 피드백이 마지막에 몰린다.
6. 실패에 이름과 탐지법을 붙인다. tautological 테스트("구조상 실패 불가능"), sediment, no-op처럼 실패 유형마다 이름과 판별법이 세트다. 이름 붙은 실패만 체계적으로 막을 수 있다.
7. 읽을 수 있어야 조일 수 있다. 스킬도, 티켓도, 지도도, handoff도 사람이 90초에 읽고 고칠 수 있는 크기를 유지한다. 결정성은 한 번에 얻어지는 게 아니라 "읽고, 이탈을 찾고, 조이는" 반복으로 얻어지므로, 읽기 가능성이 그 반복의 속도 제한이다.

1장과 수미를 맞추면: 네 진단은 결국 두 성질(확률적, 무기억)의 문제였고, 일곱 수법은 전부 그 두 성질에 대한 대응입니다. 확률성에는 절차와 검증(2, 3, 5, 6)을, 무기억에는 외부화된 상태(1, 4)를, 그리고 시스템 자체의 유지에는 읽기 가능성(7)을 답으로 내놓은 것입니다.

5. 어휘 사전

그의 체계는 "공유 어휘가 곧 도구"라는 믿음 위에 있으므로, 이 문서도 같은 표기를 유지합니다.

6. 한계와 반감기

6.1 검증된 비판들

• 작은 일에는 과잉이다. grilling 세션은 보통 45분입니다. 컨텍스트 창 하나에 끝날 일이면 인터뷰 없이 바로 구현하는 게 맞고, 그도 그렇게 씁니다.
• tdd는 UI 중심 작업에 약하다. 테스트를 미리 특정하기 어려운 곳에서는 오히려 느립니다. 다만 그의 체계 안에서 이것은 결함이 아니라 신호입니다. 테스트를 미리 못 쓴다는 것은 고해상도 질문이 남았다는 뜻이고, prototype에 갈 차례라는 것입니다.
• 디자인 취향의 채널이 얇다. 이 체계에서 시각 디자인 취향은 "생성된 변형 중 고르기"와 "말로 교정하기"로만 들어가는데, 둘 다 미적 판단에는 저대역 채널입니다. 선택은 창작이 아니고, 후보 공간이 모델의 평균 미학으로 제한됩니다. 디자인이 차별점인 제품에는 이 체계가 디자인 실천을 대체하지 못합니다.
• CONTEXT.md는 유지 부담이 있다. 일주일만 손을 놓으면 에이전트 정확도가 눈에 띄게 되돌아간다는 보고가 많습니다.
• TypeScript, Node, GitHub 편향. Django, GitLab, Trello 사용자는 포크해서 고쳐야 합니다.
• 취향의 재생산 문제. 인터페이스 설계 감각은 구현을 직접 짜며 길러지는데, 이 체계는 취향을 발휘하는 자리는 남기고 취향을 기르는 자리를 없앴습니다. 이 비판에는 체계 안에 답이 없습니다.

6.2 모델이 발전하면

이 저장소에는 반감기가 다른 두 층이 있습니다.

• 썩는 층(보조 바퀴). smart zone 수치, 티켓마다 컨텍스트 비우기, 백그라운드 리서치 위임 정책 같은 것은 현재 모델의 약점 보정이라, 약점이 사라지면 no-op이 됩니다. "이 문장을 지우면 행동이 달라지나"라는 검사를 모델이 발전할 때마다 다시 해서, no-op이 된 줄을 지워야 합니다.
• 남는 층(의도와 검증). 정렬 문제는 지능으로 사라지지 않습니다. 사람 머릿속의 우선순위와 취향은 모델이 조회할 수 없는 정보이고, 검증 가능성은 신뢰의 전제이기 때문입니다. 뛰어난 시니어를 뽑아도 회사가 스펙, 트래커, 리뷰를 없애지 않는 것과 같은 이유로, 스펙·티켓·테스트·ADR로 의도를 외부화하고 검증하는 구조는 형태를 바꿔 남습니다.

위임의 크기는 모델의 능력이 아니라 내가 검증할 수 있는 능력에 맞춰 늘리는 것. 이것이 모델 발전을 가정해도 살아남는 이 저장소의 베팅입니다.

6.3 채택 가이드

전부 설치가 아니라 2～5개만 골라 쓰는 것이 커뮤니티의 표준 사용법입니다. ROI 1위는 grill 계열이라는 데 이견이 거의 없고, 그다음이 tdd, diagnosing-bugs, handoff입니다. 그리고 저장소의 README가 권하는 사용법이 곧 이 문서의 결론이기도 합니다. "작고, 고치기 쉽고, 조합 가능하게. 뜯어고쳐서 당신 것으로 만들어라."