grill-with-docs

name	grill-with-docs
description	計画・設計をラウンド制の反復質問で徹底的に詰めながら、確定した用語を CONTEXT.md に、重い決定を docs/adr/ に即時記録するスキル。「設計を詰めて」「グリルして」「計画を叩いて」「用語を固めて」「ユビキタス言語を作って」「ADR を残して」「このリポジトリのドメインを文書化して」などで発動する。1 セッションで決着する規模の変更、またはドメイン文書が無いリポジトリの棚卸しに使う。
metadata	{"version":"1.0.0","tier":"stable","category":"design","tags":["grilling","domain-modeling","adr","glossary","ubiquitous-language"]}

グリル＋ドキュメント化

概要

計画や設計について、ユーザーと同じ理解に到達するまで質問を浴びせる。同時に、その場で固まった用語をリポジトリの CONTEXT.md に、覆しにくい決定を docs/adr/ に書き込む。

他のブレスト系スキルとの違いは状態を残すことの一点にある。会話が終わったらセッションは消えるが、このスキルはファイルを残す。用語が決着した瞬間に CONTEXT.md へ書く。まとめて最後に書かない。

フロンティアが空になり、ユーザーが「認識が揃った」と明示するまで、実装に着手しない。コードを書く・スキャフォールドする・実装系スキルを呼ぶ、いずれも禁止。

使いどころ

手元にあるもの	使うスキル
作業ディレクトリ外の、リポジトリに紐づかない相談	brainstorming
リポジトリがあり、1 セッションで決着する規模の変更	このスキル
ドメイン文書が一切無いリポジトリの棚卸し	このスキル（変更ではなくリポジトリ自体に向ける）
1 セッションに収まらない規模（新規構築・大型機能）	requirements-definer → decomposition
誰か他人の頭の中にある知識で詰まっている決定	本人に投げる質問票を doc-coauthoring で作る

進め方

Step 0: 既存のドメイン文書を読む

質問を始める前に、リポジトリの現状を掴む。

1. ルートに CONTEXT-MAP.md があるか。あれば複数コンテキスト構成。マップを読んで、今回の話題がどのコンテキストに属するか推定する。判別できなければユーザーに聞く。
2. 無ければルートの CONTEXT.md を読む。単一コンテキスト構成。
3. docs/adr/ の既存 ADR に目を通す。番号の最大値を控える。
4. どれも無ければ、ゼロから始める。事前に空ファイルを作る必要はない。

Step 1: 設計ツリーを立て、フロンティアを特定する

決定を木として捉える。ある決定が決まると、その下にぶら下がる決定が答えられるようになる。

フロンティアとは、前提がすべて決着済みで、いま聞ける質問の集合を指す。まだ開いている質問の答えに依存する質問は、このラウンドではなく後のラウンドに属する。

Step 2: フロンティア全部を 1 ラウンドで聞く

1 問ずつ小出しにしない。フロンティアの質問に番号を振り、それぞれに自分の推奨案を添えて一度に出す。

❓ **Q1** - **<質問のタイトル>**: <質問本文。複数段落でも、選択肢の列挙でもよい>

➡️ <推奨する答えと、その理由>

推奨案は必ず書く。「どうしますか？」だけの丸投げはユーザーの時間を奪う。

Step 3: 事実は自分で調べ、判断だけをユーザーに聞く

事実の調査は自分の仕事。ファイルシステム・コード・設定・外部ドキュメントを読めば分かることをユーザーに聞かない。調べる必要があればサブエージェントを飛ばす。

調査でブロックしない。走っている調査は「未決着の前提」なので、その下流の質問だけが待つ。残りのフロンティアは今すぐ聞く。

判断はユーザーのもの。トレードオフのある選択、優先順位、事業上の制約は、推奨案を添えて必ず本人に投げ、答えを待つ。

Step 4: 回答を受けてツリーを組み直し、次のラウンドへ

回答が入るたびに木の形が変わる。決着した決定がフロンティアを外へ押し出し、依存していた質問が解放される。フロンティアを計算し直して次のラウンドを出す。

Step 5: フロンティアが空になったら終了

木の全枝を訪れ、暗黙の前提が残っていない状態が終了条件。ユーザーが認識合わせの完了を確認するまで、そこから先へ進まない。

終わったら次の行き先を 1 つ提示する。仕様書に落とすなら doc-coauthoring、チケットに割るなら decomposition、すぐ作れる規模なら実装へ。

セッション中の記録

質問と並行して、以下をその場で行う。ラウンドの終わりにまとめて処理しない。

用語がグロッサリと衝突したら即座に指摘する

ユーザーの使った語が CONTEXT.md の既存定義とずれていたら、その場で止める。

グロッサリでは「キャンセル」を注文全体の取り消しと定義していますが、いまの話は明細単位の取り消しに聞こえます。どちらですか。

曖昧な語を精緻化する

多義的な語には、正典となる用語を提案する。

「アカウント」と言われましたが、それは Customer ですか User ですか。別の概念です。

具体シナリオで境界を叩く

概念間の関係を議論するときは、エッジケースを突くシナリオを自分で発明してぶつける。境界が曖昧なまま合意した気になるのを防ぐ。

コードと突き合わせる

ユーザーが「こう動く」と言ったら、コードがそれに同意しているか確かめる。矛盾を見つけたら表に出す。

コードは Order 単位でしかキャンセルしていませんが、いま部分キャンセルがあると仰いました。どちらが正ですか。

用語が決着したら CONTEXT.md を更新する

決着した瞬間に書く。後でまとめない。

CONTEXT.md はグロッサリであって、それ以外の何物でもない。実装の詳細、仕様、作業メモを書かない。

# {コンテキスト名}

{このコンテキストが何であり、なぜ存在するかを 1〜2 文で}

## 用語

**Order（注文）**:
顧客が確定させた購入意思の単位。
_使わない_: Purchase, Transaction

**Invoice（請求書）**:
納品後に顧客へ送る支払い依頼。
_使わない_: Bill, 支払い依頼

**Customer（顧客）**:
注文を行う個人または組織。
_使わない_: Client, Buyer, Account

書くときのルール:

• 態度を決める。同じ概念に複数の語があるなら、最良の 1 つを選び、残りを _使わない_ に落とす。
• 定義は締める。1〜2 文まで。何を「する」かではなく、何で「ある」かを書く。
• このプロジェクト固有の語だけ。タイムアウト、エラー型、汎用ユーティリティのような一般的なプログラミング概念は、どれだけ多用されていても入れない。追加前に「これはこのコンテキスト固有の概念か、一般概念か」を自問する。
• 自然な塊が出てきたら見出しでグループ化する。全部が 1 領域に収まるならフラットな列挙で足りる。

ADR は絞って提案する

以下の 3 つがすべて成り立つときだけ ADR を提案する。

1. 戻しにくい — 後で気が変わったときのコストが実際に高い
2. 文脈なしでは驚かれる — 将来の読み手が「なぜこうした？」と思う
3. 本物のトレードオフの結果 — 現実的な代替案があり、理由を持って一方を選んだ

1 つでも欠けたら書かない。簡単に戻せるならどうせ戻す。驚かれないなら誰も理由を探さない。代替案が無かったなら「当たり前のことをした」以上の記録価値はない。

多くのセッションでは ADR が 1 件も出ない。それは正常な結果であって、失敗ではない。

書式（docs/adr/0001-slug.md。既存の最大番号 + 1 で採番。ディレクトリは最初の 1 件が出るまで作らない）:

# {決定の短いタイトル}

{文脈・決めたこと・理由を 1〜3 文で}

1 段落で終わってよい。価値は「決定があったこと」と「その理由」が残ることで、節を埋めることではない。

任意の追加要素は、実際に価値があるときだけ足す。

• Status フロントマター（proposed | accepted | deprecated | superseded by ADR-NNNN）— 決定が後で見直される見込みがあるとき
• 検討した選択肢 — 却下した案を覚えておく価値があるとき
• 影響 — 自明でない下流影響を明示する必要があるとき

ADR に値する典型:

• アーキテクチャの形（モノレポ採用、書き込みモデルはイベントソーシング等）
• コンテキスト間の統合方式（同期 HTTP ではなくドメインイベントで繋ぐ、等）
• ロックインを伴う技術選定（DB、メッセージバス、認証基盤、デプロイ先）。差し替えに四半期かかるものだけ。ライブラリ 1 つ 1 つは対象外
• 境界とスコープの決定（顧客データは Customer コンテキストが所有し、他は ID 参照のみ）。「やらない」の明示も同じ価値がある
• 明らかな道からの意図的な逸脱（ORM ではなく手書き SQL を使う理由）。次の担当者が「直してしまう」のを止める
• コードから見えない制約（コンプライアンス上 AWS を使えない、パートナー API の契約で 200ms 以内、等）

ファイル構成

単一コンテキスト（大半のリポジトリ）:

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

複数コンテキスト（ルートに CONTEXT-MAP.md がある場合）:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← システム全体の決定
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                 ← このコンテキスト固有の決定
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

CONTEXT-MAP.md の中身:

# コンテキストマップ

## コンテキスト

- [Ordering](./src/ordering/CONTEXT.md) — 顧客注文の受付と追跡
- [Billing](./src/billing/CONTEXT.md) — 請求書生成と入金処理
- [Fulfillment](./src/fulfillment/CONTEXT.md) — 倉庫のピッキングと出荷

## 関係

- **Ordering → Fulfillment**: Ordering が `OrderPlaced` を発行し、Fulfillment がピッキングを開始
- **Fulfillment → Billing**: Fulfillment が `ShipmentDispatched` を発行し、Billing が請求書を生成
- **Ordering ↔ Billing**: `CustomerId` と `Money` の型を共有

ファイルは遅延生成する。書くものが出てから作る。

既知の限界

書き手は 1 人を前提にしている。同じリポジトリで複数人が並行してこのスキルを回すと、ADR の引用や README の記述がドリフトする。人が手で書いたドキュメントほどドリフトが速い。定期的な棚卸しは持たない。リンク切れと引用の整合を CI の決定的チェックに落とすほうが効く（codd-gate / doc-drift-detector）。

決めたことの大半はファイルに残らない。CONTEXT.md はグロッサリに限定され、ADR は 3 条件で絞られる。それ以外の合意は会話の中にしかない。セッションを閉じる前に doc-coauthoring へ渡して仕様に落とす。順序保証・否定要件・数値のデフォルトのような精密な答えは、下流で曖昧な散文に丸められやすい。仕様が出来たら自分の回答と突き合わせて読み直す。

無関係な変更で何度も回すと文書が混ざる。1 リポジトリに話題の違う用語と ADR が積み上がる。セッションごとの分離は仕組みとして持っていない。

検収基準

• CONTEXT.md がセッション中に用語ごとに変わっている。最後に一括で現れていない
• グロッサリが純粋な語彙になっている。実装詳細も仕様めいた散文も混ざっていない
• コードを読めば分かる質問がユーザーに投げられていない
• ADR は 0〜数件。出たものは、後でひっくり返されたら腹が立つ類の決定になっている
• 既存グロッサリと食い違う語をユーザーが使ったとき、その場で指摘できている