Grill With Docs: 도메인 언어와 ADR을 사용하여 AI에 프로젝트 메모리 장착

실패 모드: "AI가 너무 장황합니다."

Matt 연설의 두 번째 실패 모드는 다음과 같습니다.

AI는 간단한 말을 여러 장의 말로 표현합니다. 그것은 당신에게 두 가지 언어를 말하는 것과 같습니다.

이는 코드의 양과는 아무런 관련이 없으며 어휘의 잘못된 배치입니다. AI는 기본적으로 일반 용어("아이템", "데이터", "핸들러")를 사용하며, 여러분이 생각하는 프로젝트의 실제 용어는 "코스", "초안 버전", "유령 레슨"일 수 있습니다. AI는 이러한 단어가 프로젝트에서 특정 의미를 가지고 있다는 것을 모르기 때문에 주변에 동의어인 새로운 단어를 많이 생성합니다. 결과는 다음과 같습니다.

• 장황한 사고 과정(독점적인 단어는 피하세요)
• 구현이 마음 속 디자인과 잘못 정렬되었습니다(동일한 의미 공간에 있지 않기 때문).
• 세션 간에 재사용할 수 없습니다(각 대화마다 컨텍스트를 다시 설정해야 함).

고전 이론: DDD의 유비쿼터스 언어

Matt는 Eric Evans의 "Domain-Driven Design"을 인용했습니다. 이 책은 2003년에 출판되었으며 유비쿼터스 언어라는 개념을 제안했습니다.

동일한 용어 집합을 사용하여 도메인 전문가, 개발자 및 코드를 연결합니다. 제품 토론, 코드 주석, 변수 이름, 문서에 나오는 단어는 동일한 의미를 가져야 합니다.

DDD의 목표는 코드를 도메인 전문가의 두뇌처럼 보이게 만드는 것입니다. AI 시대에는 새로운 역할이 있습니다. LLM도 이 언어로 되어 있어야 합니다. LLM은 스탠드업 회의에 참석하지 않고 제품 요구 사항 회의를 볼 수 없으며 그룹의 속어를 이해할 수 없습니다. LLM은 귀하가 제공한 문서를 통해서만 배울 수 있습니다.

Matt는 이것을 기술로 전환했습니다. 코드 베이스를 스캔하여 용어를 추출하고 마크다운 파일 CONTEXT.md을 생성한 다음 이를 인간과 AI 모두에 맞게 조정했습니다.

기술의 진화: 유비쿼터스 언어에서 문서를 이용한 그릴로

가장 초기의 기술은 ubiquitous-language이라고 불렸습니다. 이 기술은 단 한 가지 작업만 수행했습니다. 코드 베이스를 스캔하여 용어집을 생성하는 것이었습니다. 그러나 Matt는 나중에 단순히 문서를 생성하는 것만으로는 충분하지 않다는 사실을 발견했습니다.

• 문서는 최신이 아닙니다: 오늘 생성되었으며 내일 코드가 변경되고 용어집이 유지되지 않습니다.
• 사람들은 그것을 보려고 하지 않을 것입니다: 거기에 놓으면 죽을 것입니다.

그는 이를 세 가지를 결합한 grill-with-docs로 리팩토링했습니다.

1. 고문 요구 사항(grill-me에서 상속된 모든 능력)
2. 기존 용어집에 도전: 귀하가 말한 단어가 CONTEXT.md에 작성된 내용과 일치하지 않습니까? 당장 지적해
3. 결정을 내릴 때 문서를 동시에 업데이트: 고문 과정에서 도달한 새로운 결론은 CONTEXT.md에 인라인으로 기록되거나 새 ADR을 생성합니다.

이는 "정적 문서 생성"에서 "대화는 문서 유지"로의 패러다임 전환입니다.

스킬 전문

engineering/grill-with-docs/SKILL.md의 핵심 구조:

---
name: grill-with-docs
description: Grilling session that challenges your plan against the
  existing domain model, sharpens terminology, and updates
  documentation (CONTEXT.md, ADRs) inline as decisions crystallise.
---

<what-to-do>
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, waiting for feedback on each question
before continuing.

If a question can be answered by exploring the codebase, explore the
codebase instead.
</what-to-do>

<supporting-info>

## Domain awareness

During codebase exploration, also look for existing documentation:

### File structure

Most repos have a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts.

## During the session

### Challenge against the glossary
When the user uses a term that conflicts with the existing language in
CONTEXT.md, call it out immediately.
"Your glossary defines 'cancellation' as X, but you seem to mean Y —
which is it?"

### Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise
canonical term.
"You're saying 'account' — do you mean the Customer or the User?
Those are different things."

### Discuss concrete scenarios
When domain relationships are being discussed, stress-test them with
specific scenarios.

### Cross-reference with code
When the user states how something works, check whether the code
agrees. If you find a contradiction, surface it.

### Update CONTEXT.md inline
When a term is resolved, update CONTEXT.md right there. Don't batch
these up — capture them as they happen.

### Offer ADRs sparingly
Only offer to create an ADR when all three are true:
1. Hard to reverse
2. Surprising without context
3. The result of a real trade-off

</supporting-info>

실제 CONTEXT.md는 어떤 모습인가요?

Matt의 course-video-manager 저장소는 완전한 CONTEXT.md 예제를 제공합니다. 이에 대한 느낌을 얻기 위해 몇 가지 용어를 선택해 보겠습니다.

몇 가지 사항에 유의하세요.

1. 각 용어는 동명사 또는 고유명사입니다 – “주문 상태”와 같은 설명 문구가 아닙니다.
2. 각 정의는 온톨로지 네트워크를 형성하는 다른 용어(강좌 → 버전 → 강의 → 비디오)를 참조합니다.
3. 코드 필드가 직접 나타납니다 (fsStatus = "ghost") - 문서와 코드의 1:1 매핑
4. 결정 설명 포함('게시 차단', '연쇄 반응') - 명사뿐 아니라 규칙도 포함

코드 작성 시 AI가 이 문서를 보면 '파일이 없는 강의' 대신 '유령 강의'를 사용하게 됩니다. 코드, 대화, 커밋 메시지가 모두 통합됩니다.

ADR: 생성 시

스킬에는 중요한 제한 사항이 있습니다.

Only offer to create an ADR when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives

ADR(Architecture Decision Record) 문화는 2011년 Michael Nygard의 블로그에서 시작되었지만 많은 팀에서 이를 사용하여 모든 결정에 대한 ADR을 작성합니다. ADR 20개 중 18개가 계정을 실행하고 있습니다. Matt 이 삼각측량은 훌륭한 도구입니다. ADR은 세 가지 조건이 동시에 충족되는 경우에만 가치가 있습니다. 그렇지 않으면 CONTEXT.md에서 요약하고 코드에서 요약하도록 하세요.

설치 및 사용방법

전제 조건: /setup-matt-pocock-skills을 먼저 실행하십시오(CONTEXT.md를 어디에 넣을지, ADR 디렉토리를 어디에 둘 것인지 묻습니다).

전화: /grill-with-docs

일반적인 프로세스:

1. 하고 싶은 일을 설명해주세요
2. /grill-with-docs
3. Claude는 먼저 CONTEXT.md 및 docs/adr/을 스캔하여 기존 용어와 결정을 컨텍스트에 로드합니다.
4. 그 과정에서 고문을 시작하세요:

• 사용하신 단어가 CONTEXT.md와 충돌합니다 → 즉석에서 지적해주세요
• 모호한 단어를 사용했습니다(예: "계정"은 고객 또는 사용자일 수 있음) → 둘 중 하나를 선택하여 문서에 놓도록 합니다.
• 말씀하신 동작이 기존 코드와 일치하지 않습니다. → 충돌되는 부분을 지적해 주세요.

5. 결정에 도달하면 CONTEXT.md를 동기식으로 업데이트합니다(백로그 없음, 일괄 처리 없음).
6. 되돌릴 수 없는 주요 결정 → ADR 생성 여부를 묻습니다.

아직 프로젝트에 CONTEXT.md 및 docs/adr/이 없으면 느리게 생성됩니다. 첫 번째 용어를 작성하고 첫 번째 ADR을 빌드해야 할 때까지 파일이 생성되지 않습니다. 우리는 즉시 빈 템플릿을 제공하지 않습니다.

##다중 컨텍스트 프로젝트(CONTEXT-MAP.md)

프로젝트가 너무 커서 하나의 CONTEXT.md에 들어갈 수 없는 경우(예를 들어 주문과 청구가 두 개의 독립적인 경계 컨텍스트인 경우) 루트 디렉터리에 일반 디렉터리로 CONTEXT-MAP.md을 넣을 수 있습니다.

/
├── CONTEXT-MAP.md                    ← 总目录
├── docs/adr/                         ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← 模块级决策
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

/grill-with-docs은 CONTEXT-MAP.md의 존재를 자동으로 인식하고 해당 하위 디렉터리로 이동합니다. 이는 DDD의 제한된 컨텍스트 개념을 직접 구현한 것입니다. 각 컨텍스트의 "순서"는 서로 다른 의미를 가질 수 있으며 오염을 방지하기 위해 별도로 유지 관리됩니다.

##과 grill-me의 차이점

단순하고 조악한 판단:

• 개인 대본 작성, 기사 작성, 교육 과정 → /grill-me
• 장기적인 유지관리가 필요한 실제 프로젝트 → /grill-with-docs

직관에 반하는 이점: AI가 "닥치는" 법을 배우게 하세요.

CONTEXT.md는 AI만을 위한 것이 아니라 미래의 AI 세션을 위한 것입니다. 새로운 대화가 시작될 때마다 Claude는 CONTEXT.md를 읽고 즉시 프로젝트 컨텍스트에 들어갈 수 있어 긴 온보딩 시간을 절약할 수 있습니다.

더 미묘한 점은 Matt가 연설에서 CONTEXT.md를 추가한 후 AI의 사고 추적을 볼 수 있다고 말했습니다.

"AI가 덜 장황한 방식으로 생각할 수 있게 해줍니다."

왜요? CONTEXT.md가 없으면 AI는 "사용자, 즉 항목을 주문한 사람, 이하..."라고 생각할 때 자체 용어를 지속적으로 정의해야 하기 때문입니다. CONTEXT.md를 사용하면 "고객"이라고 직접 표시되므로 사고 체인이 훨씬 짧고 응답이 더 빠릅니다.

LLM의 토큰 경제는 사고 경로 단축 = 더 빠르고, 더 정확하고, 더 저렴한 결과를 결정합니다. CONTEXT.md는 이러한 효율성을 위한 숨겨진 레버입니다.

메모

CONTEXT.md는 첫 번째 실행에서 크게 변경됩니다. 프로젝트에 손으로 작성한 CONTEXT.md가 이미 있는 경우 먼저 git stash를 실행하거나 실행하기 전에 시험 실행하도록 합니다("변경할 내용을 먼저 나열하고 파일을 직접 쓰지 마십시오"라는 프롬프트에 문장을 추가할 수 있습니다).

ADR 조정은 실제 조정입니다. 흥분하지 말고 모든 결정을 내리면 ADR이 생성됩니다. 귀하의 문서/adr/은 6개월 안에 쓰레기로 가득 차게 될 것입니다. Matt의 세 가지 기준을 엄격히 준수해야 합니다.

CONTEXT.md 구현 세부 정보를 입력하지 마세요. Skill에는 "CONTEXT.md를 구현 세부 사항에 연결하지 마십시오. 도메인 전문가에게 의미 있는 용어만 포함하십시오."라는 말이 있습니다. CONTEXT.md에 "PostgreSQL"을 쓰는 것은 잘못된 것입니다. 도메인 전문가는 데이터베이스 선택에 관심이 없으며 이는 ADR의 문제입니다.

참조 리소스

다음 글: to-PRD + to-이슈: 다이얼로그에서 실행 가능한 티켓으로——고문 이후, 다이얼로그를 실행 가능한 작업 단위로 굳히는 방법.