Grill With Docs: ドメイン言語と ADR を使用して AI にプロジェクト メモリを装備する

失敗モード: 「AI が冗長すぎる」

マットのスピーチの 2 番目の失敗モード:

AI は単純なことをたくさんの言葉で表現します。それはあなたに2つの言語を話しているようなものです。

これはコードの量とは関係なく、語彙の間違いです。 AI はデフォルトで一般的な用語 (「アイテム」、「データ」、「ハンドラー」) を使用しますが、あなたの頭の中にあるプロジェクトの実際の用語は、「コース」、「ドラフト バージョン」、「ゴースト レッスン」などである可能性があります。 AI はこれらの単語がプロジェクト内で特定の意味を持っていることを認識していないため、それらの周囲に同義の新しい単語を大量に作成します。結果は次のとおりです。

• 長々とした思考プロセス (独自の言葉を避ける)
• 実装が頭の中にある設計とずれている (同じ意味空間にないため)
• セッション間では再利用できません (会話ごとにコンテキストを再確立する必要があります)

古典的な理論: DDD のユビキタス言語

マット氏はエリック・エヴァンスの「ドメイン駆動設計」を引用した。この本は 2003 年に出版され、ユビキタス言語 の概念を提案しました。

同じ一連の用語を使用して、ドメインの専門家、開発者、コードを結び付けます。製品ディスカッション、コード コメント、変数名、ドキュメント内の単語 - それらは同じことを意味する必要があります。

DDD の目標は、コードをドメイン専門家の頭脳のように見せることです。 AI 時代には、LLM もこの言語である必要があるという新しい役割があります。 LLM はスタンドアップ ミーティングに参加しておらず、製品要件の会議も見ることができず、グループのスラングも理解できません。LLM は、与えられた文書からしか学ぶことができません。

Matt はこれをスキルに変えました。コード ベースをスキャンして用語を抽出し、マークダウン ファイル CONTEXT.md を生成し、それを人間と AI の両方に合わせて調整します。

スキルの進化: ユビキタス言語からドキュメントを使ったグリルまで

最も初期のスキルは ubiquitous-language と呼ばれていました。これは、コード ベースをスキャンして用語集を生成するという 1 つのことだけを行いました。しかしマットは後に、単にドキュメントを生成するだけでは十分ではないことに気づきました。

• ドキュメントは古くなります: ドキュメントは今日生成され、コードは明日変更されますが、用語集は更新されていません。
• 人々は率先してそれを見ようとはしません: そこに置いたら死んでしまいます

彼はそれを grill-with-docs にリファクタリングし、次の 3 つを組み合わせました。

1. 拷問条件 (グリルミーからすべての能力を継承)
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 の ADR のうち 18 がアカウントを実行しています。 Matt この三角測量は素晴らしいツールです。ADR は 3 つの条件が同時に満たされた場合にのみ価値があります。それ以外の場合は、CONTEXT.md 内でダイジェストされ、コード内でダイジェストされます。

インストールと使用方法

前提条件: 最初に /setup-matt-pocock-skills を実行します (CONTEXT.md を配置する場所と ADR ディレクトリを配置する場所を尋ねられます)。

電話: /grill-with-docs

一般的なプロセス:

1. やりたいことを説明する
2. /grill-with-docs
3. クロードは最初に CONTEXT.md と docs/adr/ を スキャンし、既存の用語と決定をコンテキストにロードします
4. プロセス中に拷問を開始します。

• CONTEXT.mdと矛盾する単語を使用 → その場で指摘
• 曖昧な単語を使用した (たとえば、「アカウント」は顧客またはユーザーのいずれかになる可能性があります) → 2 つのうちの 1 つを選択して文書にドロップします。
• 指摘された動作は既存のコードと矛盾しています → 矛盾を指摘してください

5. 決定に達したら CONTEXT.md を同期的に更新します (バックログやバッチ処理はありません)。
6. 重要な不可逆的な決定 → ADR を生成するかどうかを尋ねる

プロジェクトに CONTEXT.md と docs/adr/ がまだない場合は、遅延して作成されます。最初の用語を書き、最初の ADR を構築する必要があるまで、ファイルは生成されません。最初から空のテンプレートを提供するわけではありません。

##複数のコンテキスト プロジェクト (CONTEXT-MAP.md)

プロジェクトが大きすぎて 1 つの CONTEXT.md に収まらない場合 (たとえば、注文と請求が 2 つの独立した境界付きコンテキストである場合)、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-with-docs

直観に反する利点: AI に「黙る」ことを学習させる

CONTEXT.md は AI だけのためのものではなく、将来の AI セッションのためのものです。新しい会話が始まるたびに、クロードは CONTEXT.md を読み取ることでプロジェクトのコンテキストに即座に入ることができ、長いオンボーディングを節約できます。

さらに微妙なのは、マットはスピーチの中で、CONTEXT.md を追加した後、AI の 思考痕跡 を見ることができると述べました—

「これにより、AI はあまり冗長ではない方法で考えることができるようになります。」

なぜですか？ CONTEXT.md がないと、AI は考えるときに常に独自の用語を定義しなければなりません - 「ユーザー、つまり商品を注文した人を指します。以下、...」と呼びます。 CONTEXT.md を使用すると、「顧客」と直接表示されるため、思考チェーンがはるかに短くなり、応答が速くなります。

LLM のトークンエコノミクスは、思考経路の短縮 = より速く、より正確で、より安価な成果物であると判断します。 CONTEXT.md は、この効率化のための隠れたレバーです。

注意事項

CONTEXT.md は最初の実行時に大幅に変更されます。プロジェクトにすでに手書きの CONTEXT.md がある場合は、最初に git stash するか、実行する前に予行演習します (プロンプトに「最初に変更する内容をリストします。ファイルを直接書き込まないでください」という文を追加できます)。

ADR モデレーションは実質モデレーションです。興奮してすべての決定で ADR を生成しないでください。6 か月後には docs/adr/ がゴミでいっぱいになってしまいます。 Matt の 3 つの基準は厳密に従う必要があります。

CONTEXT.md 実装の詳細を記述しないでください。 Skill には、「CONTEXT.md を実装の詳細と組み合わせないでください。ドメインの専門家にとって意味のある用語のみを含めてください。」という言葉があります。 CONTEXT.md に「PostgreSQL」と記述するのは間違いです。ドメインの専門家はデータベースの選択を気にしません。これは ADR の問題です。

参考リソース

次の記事: to-PRD + to-Issues: 対話から実行可能なチケットへ——拷問の後、対話を実行可能な作業単位に固める方法。