Matt Pocock의 AI 코딩 스킬 시스템 — 에이전트에게 일 잘 시키는 개발자의 프레임워크

AI 코딩 에이전트의 4대 실패 모드란 무엇인가?

Matt Pocock은 에이전트 협업의 실패를 네 가지로 진단한다. 정렬 오류(Misalignment) — 의도와 다른 결과물, 과잉 언어(Verbosity) — 프로젝트 용어를 모르는 에이전트의 장황함, 코드 품질(Code Quality) — 피드백 루프 부재로 인한 깨진 구현, 아키텍처 부식(Architecture Decay) — 빠른 개발이 가속하는 소프트웨어 엔트로피. 그의 스킬 시스템은 이 네 가지에 대한 구조적 해법이다.

여기서 주목할 점은, 이 실패 모드가 프롬프트의 문제가 아니라는 것이다. 프롬프트를 아무리 잘 써도, 에이전트가 프로젝트의 맥락을 모르고, 피드백 루프가 없고, 아키텍처가 무너지고 있다면 결과는 나빠진다. Pocock의 접근은 프롬프트가 아니라 시스템을 고친다.

CONTEXT.md — 에이전트에게 팀의 언어를 가르치는 방법은?

프로젝트에 CONTEXT.md 파일을 만들어 도메인 용어, 약어, 해결된 모호성(Resolved Ambiguities)을 정리한다. 에이전트가 이 파일을 읽으면 매번 장황하게 설명할 필요 없이 팀의 축약어로 대화할 수 있다. 토큰 소모 감소, 일관된 네이밍, 에이전트의 코드베이스 탐색 정확도 향상이라는 세 가지 이점이 동시에 발생한다.

도메인 주도 설계(DDD)에서 유비쿼터스 언어(Ubiquitous Language)가 팀 커뮤니케이션의 기반이듯, CONTEXT.md는 인간-에이전트 커뮤니케이션의 기반이다. 예를 들어 "materialization cascade"라는 프로젝트 고유 개념을 매번 5문장으로 설명하는 대신, CONTEXT.md에 한 번 정의해두면 이후 대화에서 한 단어로 통한다.

"Resolved Ambiguities" 섹션이 특히 실용적이다. "여기서 user는 end-user를 의미하고, admin은 backoffice 관리자를 의미한다"처럼, 에이전트가 혼동하기 쉬운 용어의 경계를 미리 정리해두는 것이다.

핵심 스킬 6개 — 어떻게 사용하는가?

Pocock의 18개 스킬 중 실무에서 가장 빈번하게 쓰이는 6개는 /implement(스펙 기반 구현), /tdd(테스트 주도 개발), /grilling(결정 트리 질문), /code-review(이중 축 리뷰), /handoff(세션 인계), /diagnosing-bugs(구조적 디버깅)다. 각 스킬은 Claude Code에서 슬래시 명령으로 호출한다.

/grilling이 중요한 이유

에이전트에게 바로 구현을 시키면, 잘못된 방향으로 수백 줄의 코드를 생성한 뒤에야 문제가 드러난다. /grilling은 구현 전에 에이전트의 계획을 체계적으로 검증한다. "설계 트리의 모든 가지를 방문하고, 아무것도 암묵적으로 가정하지 않을 때까지" 질문을 계속한다. 이 단계를 거치면 정렬 오류(Misalignment)가 극적으로 줄어든다.

/tdd의 수직 슬라이스 원칙

일반적인 실수는 테스트를 전부 먼저 작성하는 것이다. Pocock은 이를 "수평 슬라이싱"이라 부르며 명시적으로 금지한다. 대신 수직 슬라이스 — 테스트 하나를 쓰고, 구현하고, 통과시키고, 다음 테스트로 넘어간다. 테스트 문장은 스펙처럼 읽혀야 한다: "user can checkout with valid cart".

agent-rules-books — 소프트웨어 공학 고전 15권을 에이전트 규칙으로 바꾸면?

Pocock의 agent-rules-books 레포는 Clean Code, DDD, A Philosophy of Software Design, Refactoring, DDIA 등 소프트웨어 공학 고전 15권의 핵심 원칙을 에이전트가 소화할 수 있는 마크다운 규칙으로 증류한 것이다. 각 책마다 full, mini, nano 세 가지 크기로 제공되며, 토큰 예산에 따라 골라 쓸 수 있다.

이 레포의 존재 자체가 하나의 주장이다: AI 시대에도 소프트웨어 공학의 기본 원칙은 유효하며, 오히려 에이전트에게 더 명시적으로 가르쳐야 한다. 에이전트는 "좋은 코드"의 암묵적 기준을 스스로 학습하지 않는다. 규칙으로 주입해야 한다.

특히 John Ousterhout의 "A Philosophy of Software Design"에서 가져온 Deep Module 원칙이 Pocock의 전체 아키텍처 철학에 깊이 녹아 있다. 단순한 인터페이스 뒤에 풍부한 기능을 숨기는 "깊은 모듈"이, 에이전트가 코드베이스를 탐색할 때도 유리하다는 것이다. 탐색할 파일이 적고, 인터페이스가 명확할수록 에이전트의 정확도는 올라간다.

에이전트를 위한 글쓰기 — /writing-for-agents 스킬이 알려주는 것은?

에이전트에게 주는 지시 문서에도 "좋은 글쓰기" 원칙이 있다. Pocock은 세 가지를 강조한다. Leading Words(모델이 사전학습에서 이미 알고 있는 개념어를 써서 기존 지식을 활성화), Context Pointers(항상 로드하지 않되 필요할 때 찾을 수 있는 참조 경로 안내), Pruning(에이전트가 기본적으로 이미 하는 행동을 지시하는 무의미한 문장 제거).

특히 "두 가지 예산" 개념이 실용적이다:

• Context Load — 항상 컨텍스트에 로드되는 토큰 양. CLAUDE.md, CONTEXT.md 등 매 세션 자동 로드 파일
• Cognitive Load — "이런 참조 문서가 있다"는 것을 알아야 하는 인간의 인지 부담

정보를 세 계층으로 분류한다: 파일 내 직접 기술(in-file steps), 파일 내 참조(in-file reference), 외부 참조 공개(disclosed reference). 모든 정보를 항상 로드하면 토큰 낭비고, 전혀 알려주지 않으면 에이전트가 찾지 못한다. 이 균형을 잡는 것이 에이전트 협업의 핵심이다.

개발자가 아닌 사람에게도 적용 가능한 원칙은 무엇인가?

Pocock의 프레임워크에서 개발자가 아니어도 즉시 적용 가능한 원칙은 세 가지다. 첫째, 공유 언어를 먼저 정의하라. 프로젝트 용어집을 만들어 에이전트에게 주면 소통 품질이 올라간다. 둘째, 구현 전에 질문하라(/grilling). 에이전트의 계획을 검증하는 단계를 반드시 거쳐라. 셋째, 세션 인계 문서를 남겨라(/handoff). 다음 세션에서 처음부터 반복하는 것을 방지한다.

AI 에이전트를 팀에 합류하는 주니어 개발자로 생각하라. 온보딩 문서 없이 첫날부터 성과를 기대하지 않듯, 에이전트에게도 CONTEXT.md라는 온보딩 문서를 주어야 한다.

이 비유가 Pocock 접근법의 핵심이다. 프롬프트 엔지니어링이 "한 번의 질문을 잘하는 기술"이라면, 스킬 시스템은 "함께 일하는 환경을 설계하는 기술"이다. 후자가 확장 가능하고, 반복 가능하며, 팀 전체가 공유할 수 있다.