grill-with-docs

ドキュメントに基づく掘り下げ

Matt Pocock の grill-with-docs（MIT、© 2026 Matt Pocock）を基にしています。Matt のインタビュー手法と、ドキュメントを根拠に掘り下げるルールは、MIT ライセンスの下でそのまま維持されています。このリポジトリで追加したもの：標準ライブラリのみを使うバリデーター 3 種（CONTEXT.md リンター、ADR スキャナー、用語集とコードの整合性チェック）、cs-grill-with-docs エージェント、/cs-grill-with-docs コマンド。詳しくは以下のラッパーによる追加機能を参照してください。

この計画のあらゆる側面について、共通理解に達するまで徹底的に質問してください。設計上の選択肢を一つずつたどり、各判断の依存関係を順番に解決してください。質問ごとに、推奨する回答も提示してください。

質問は一度に一つずつ行い、次の質問に進む前に、それぞれの質問へのフィードバックを待ってください。

コードベースを調べれば答えられる質問の場合は、代わりにコードベースを調べてください。

ドメインの把握

コードベースを調べる際は、既存のドキュメントも確認してください。

ファイル構成

ほとんどのリポジトリでは、コンテキストは一つです。

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

ルートに CONTEXT-MAP.md がある場合、リポジトリには複数のコンテキストがあります。このマップには、それぞれのコンテキストの場所が記載されています。

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

ファイルは必要になってから作成してください。書き込む内容ができてから作成します。CONTEXT.md が存在しない場合は、最初の用語が確定した時点で作成してください。docs/adr/ が存在しない場合は、最初の ADR が必要になった時点で作成してください。

セッション中

用語集との不一致を指摘する

ユーザーが CONTEXT.md にある既存の用語と矛盾する語を使った場合は、すぐに指摘してください。「用語集では『キャンセル』を X と定義していますが、Y の意味で使っているようです。どちらでしょうか？」

曖昧な表現を明確にする

ユーザーが曖昧な語や複数の意味に取れる語を使った場合は、正確な標準用語を提案してください。「『アカウント』と言っていますが、顧客とユーザーのどちらを指していますか？この二つは別のものです。」

具体的なシナリオを検討する

ドメイン上の関係について話し合うときは、具体的なシナリオで検証してください。エッジケースを探り、概念間の境界を明確にするためのシナリオを考案してください。

コードと照合する

ユーザーが何かの仕組みについて述べたら、コードと一致するか確認してください。矛盾を見つけた場合は、指摘してください。「コードでは Order 全体をキャンセルしていますが、先ほど部分キャンセルが可能だと言っていました。どちらが正しいですか？」

CONTEXT.md をその場で更新する

用語が確定したら、その場で CONTEXT.md を更新してください。まとめて後回しにせず、確定した時点で記録してください。CONTEXT-FORMAT.md の形式を使ってください。

CONTEXT.md には、実装の詳細を一切含めないでください。CONTEXT.md を仕様書、メモ帳、実装上の判断を記録する場所として扱わないでください。用語集以外のものではありません。

ADR の提案は慎重に行う

次の条件をすべて満たす場合に限り、ADR の作成を提案してください。

1. 変更が困難 — 後から考えを変えるコストが無視できない
2. 背景がなければ意外に思われる — 将来の読者が「なぜこの方法にしたのか」と疑問に思う
3. 実際のトレードオフの結果である — 真剣に検討した代替案があり、特定の理由でそのうち一つを選んだ

三つの条件のうち一つでも欠けている場合は、ADR を作成しないでください。ADR-FORMAT.md の形式を使ってください。

ラッパーによる追加機能

以下の追加機能は、Matt の上流スキルには含まれていません。これらは、上流のルールを決定論的な標準ライブラリのみのバリデーターとして具体化したもので、インタビューの進行と自然に組み合わせられます。

ワークフロー（ラッパーツールを使用）

1. 事前確認（最初の質問の前）：

   • CONTEXT.md が存在する場合は、scripts/context_md_linter.py CONTEXT.md を実行します。用語集が適切な形式であることを確認してから、それに基づいて質問します。
   • docs/adr/ が存在する場合は、scripts/adr_scanner.py docs/adr/ を実行します。番号の欠落、形式不備の ADR、ステータスのフロントマターの不整合を検出します。
   • scripts/glossary_code_consistency.py --context CONTEXT.md --code src/ を実行します。定義されているものの使われていない用語（使われていない用語集項目）と、定義が必要な可能性のある、コード内でのみ使われている一般名詞を検出します。これらの検出結果を、冒頭の質問に使います。

2. セッション中（Matt のルールを適用）：

   • 1 回のターンにつき質問は 1 つにし、深さ優先で進めます。
   • 用語の定義を明確にしたら、すぐに CONTEXT.md を編集します。構造に関わる編集の場合は、context_md_linter.py を再実行します。
   • ADR が必要な場合は、docs/adr/ に作成し、番号を確認するために adr_scanner.py を再実行します。

3. 終了時：

   • glossary_code_consistency.py を最後に実行し、新たな未定義用語が追加されていないことを確認します。
   • 次の内容を要約します：追加・明確化した用語、作成した ADR、議論したシナリオ、未解決事項。

ツール（標準ライブラリのみ）

ツール	役割の概要
scripts/context_md_linter.py	CONTEXT.md が CONTEXT-FORMAT.md の構造に準拠しているかを検証します。ルールごとに PASS/WARN/FAIL を表示します。
scripts/adr_scanner.py	docs/adr/ を調べ、NNNN-slug.md のパターン、番号の整合性、本文の完全性を確認します。
scripts/glossary_code_consistency.py	CONTEXT.md の太字の用語とコードベースでの使用状況を照合します。使われていない用語集項目と、コード内でのみ使われている一般名詞を検出します。

参考資料（各ルールの根拠）

• references/ubiquitous_language.md — 用語集をソース管理に含める理由（Evans、Vernon、Khononov、Wlaschin、Brandolini、Avram & Marinescu、Fowler）
• references/adr_practice.md — ADR を作成する価値がある場面（Nygard、Tyree & Akerman、Zimmermann の Y ステートメント、MADR、ThoughtWorks Radar、adr-tools、Backstage）
• references/context_md_as_artifact.md — 生きた成果物としての CONTEXT.md（言語の変化に関する Khononov、命名に関する Kernighan、BoundedContext bliki、データ契約に関する Confluent、EventStorming の用語集に関する Brandolini）

関連項目

• エージェント：cs-grill-with-docs（../../agents/cs-grill-with-docs.md を参照）
• コマンド：/cs-grill-with-docs（../../commands/cs-grill-with-docs.md を参照）

---

バージョン： 1.0.0 派生元： Matt Pocock の grill-with-docs（MIT）＋このリポジトリのラッパー