Claude Code에게 코드를 작성하게 하면, 동작은 하지만 구조·명명(Naming)·책임 분리 중 어딘가가 "그게 아니야"라는 상태로 결과가 돌아올 때가 있습니다. 수정을 하나 지시할 때마다 에이전트(Agent)가 또 다른 어긋남을 만들어내며 루프가 계속됩니다.

문제는 출발점에 있습니다. 합의가 부족한 상태에서 구현이 시작되었다는 것, 단지 그뿐입니다.

에이전트는 가정을 보완하며 동작한다

인간이 설계를 이야기할 때, 머릿속에 있는 가정을 언어화하지 않은 채 진행합니다.

"사용자는 로그인 상태일 것이다", "이 API는 멱등성(Idempotency)을 가질 것이다", "취소는 주문 단위일 것이다"

에이전트는 이 간극을 스스로 메웁니다. 코드베이스(Codebase)를 탐색하여 그럴듯한 답을 선택합니다. 보완된 내용이 의도와 맞으면 문제가 없지만, 맞지 않으면 동작은 하지만 틀린 코드가 완성됩니다.

설계가 어긋나 있어도 테스트는 통과합니다. 리뷰도 쉽게 통과하기 쉬우며, 팀은 알아차리지 못한 채 다음 구현의 전제로 삼게 됩니다.

mattpocock/skills について

"뭔가 다른데"의 루프는 구현 전 합의가 이루어져 있다면 일어나지 않습니다. 이를 위한 수단으로 mattpocock/skills 가 있습니다.

mattpocock/skills 는 Matt Pocock이 공개한 스킬 모음입니다. 스킬(Skill)이란 AI 코딩 에이전트(AI Coding Agent)에게 읽히는 작은 지시 파일로, 특정 작업 패턴을 에이전트에게 가르칩니다. skills는 CLI로 설치합니다.

npx skills@latest add mattpocock/skills

여러 스킬이 포함되어 있으며, 구현 전 합의를 공고히 하기 위해 사용하는 것이 grill-me와 grill-with-docs입니다.

세션 내에서 /grill-me 또는 /grill-with-docs를 입력함으로써 실행됩니다.

grill-me

── 결정 트리(Decision Tree)를 한 문제씩 확정한다

/grill-me

스킬의 지시는 짧습니다.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask the questions one at a time. If a question can be answered by exploring the codebase, explore the codebase instead.

(번역: 플랜의 모든 측면에 대해 공유된 이해에 도달할 때까지 끊임없이 질문하라. 설계 트리의 각 가지를 따라가며 결정 간의 의존성을 하나씩 해결하라. 각 질문에는 권장 답변을 제공하라. 질문은 한 번에 하나씩 하라. 코드베이스 탐색으로 답할 수 있는 질문이라면 코드베이스를 탐색하라.)

Claude는 질문을 하나씩 던지며, 답변이 돌아올 때까지 다음으로 넘어가지 않습니다. 이전 답변이 다음 질문의 전제가 되기 때문에, 멋대로 추측하는 것이 쌓이는 것을 방지할 수 있습니다. Claude는 각 질문에 권장 답변을 덧붙이므로, 판단은 YES 혹은 NO만으로 충분합니다.

코드베이스에서 답할 수 있는 내용은 Claude가 스스로 코드를 찾아 해결합니다. "이 모델은 어디에 정의되어 있습니까?"라고 사용자에게 묻지 않습니다. 판단이 필요한 질문에만 시간을 쓰도록 설계되어 있습니다.

grill-with-docs

── 어휘를 맞추며 진행한다

/grill-with-docs

grill-me와는 해결하는 문제가 다릅니다. 프로젝트가 성장함에 따라 대화·코드·문서 속의 용어가 어긋나기 시작합니다. "Order"가 어떤 문맥에서는 수주를 의미하고, 다른 문맥에서는 구매 요청을 의미할 수 있습니다. "Account"가 UI에서는 거래처를 의미하고, API에서는 인증 사용자를 의미할 수도 있습니다.

어휘가 제각각인 상태에서 지시를 내리면, 올바르게 지시했다고 생각해도 에이전트는 다른 개념으로 코드를 작성합니다.

grill-with-docs는 리포지토리에서 CONTEXT.md와 ADR을 읽어 들여, 그리링(Grilling) 중에 어휘의 충돌을 검출합니다.

CONTEXT.md는 리포지토리 루트에 두는 도메인 용어집 (Domain Glossary)입니다. 프로젝트에서 사용하는 용어와 그 정의를 작성합니다. 코드 구현 상세는 작성하지 않으며, 도메인 전문가가 읽었을 때 의미를 이해할 수 있는 용어만을 기재합니다. 파일이 없는 경우,

grill-with-docs

는 첫 번째 용어가 확정되었을 때 생성합니다. **ADR (Architecture Decision Record)**은 설계상의 중요한 판단을 기록하는 짧은 문서입니다. 왜 그 판단을 내렸는지, 어떤 대안을 검토하고 어떻게 선택했는지를 남깁니다. docs/adr/ 디렉토리에 일련번호로 배치하는 것이 일반적입니다. 미래의 자신이나 팀이 "왜 이렇게 되어 있는가"를 조사할 때 사용합니다.

어휘의 충돌을 발견하면, Claude는 다음과 같이 확인합니다.

"당신의 용어집(Glossary)에서 "cancellation"은 X로 정의되어 있습니다만, 지금 말씀하시는 것은 Y를 의미하는 것입니까?"

확정되는 즉시, Claude가 그 자리에서 CONTEXT.md를 다시 작성합니다. 세션 마지막에 모아서 업데이트하는 운영 방식은 어휘의 충돌을 간과하는 원인이 됩니다.

ADR을 만드는 세 가지 조건

ADR을 만드는 것은 다음 세 가지가 모두 갖춰졌을 때뿐입니다.

• 나중에 변경할 때의 비용이 크다
• 맥락 없이는 의도가 전달되지 않는다
• 실제적인 트레이드오프 (Trade-off)가 있었다

이 세 가지로 범위를 좁힘으로써, 형식적인 문서가 축적되는 것을 방지합니다.

어느 것을 선택할 것인가

두 스킬 모두 실행하는 시점은 구현 전 10분입니다. 그곳에서 확정된 가정의 수만큼, 이후의 수정 작업이 줄어듭니다.

Discussion