ynitto グリル＋ドキュメント化
概要
計画や設計について、ユーザーと同じ理解に到達するまで質問を浴びせる。同時に、その場で固まった用語をリポジトリの CONTEXT.md に、覆しにくい決定を docs/adr/ に書き込む。
他のブレスト系スキルとの違いは状態を残すことの一点にある。会話が終わったらセッションは消えるが、このスキルはファイルを残す。用語が決着した瞬間に CONTEXT.md へ書く。まとめて最後に書かない。
使いどころ
| 手元にあるもの | 使うスキル |
|---|---|
| 作業ディレクトリ外の、リポジトリに紐づかない相談 | brainstorming |
| リポジトリがあり、1 セッションで決着する規模の変更 | このスキル |
| ドメイン文書が一切無いリポジトリの棚卸し | このスキル（変更ではなくリポジトリ自体に向ける） |
| 1 セッションに収まらない規模（新規構築・大型機能） | requirements-definer → decomposition |
| 誰か他人の頭の中にある知識で詰まっている決定 | 本人に投げる質問票を doc-coauthoring で作る |
進め方
Step 0: 既存のドメイン文書を読む
質問を始める前に、リポジトリの現状を掴む。
- ルートに
CONTEXT-MAP.mdがあるか。あれば複数コンテキスト構成。マップを読んで、今回の話題がどのコンテキストに属するか推定する。判別できなければユーザーに聞く。 - 無ければルートの
CONTEXT.mdを読む。単一コンテキスト構成。 docs/adr/の既存 ADR に目を通す。番号の最大値を控える。- どれも無ければ、ゼロから始める。事前に空ファイルを作る必要はない。
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 つでも欠けたら書かない。簡単に戻せるならどうせ戻す。驚かれないなら誰も理由を探さない。代替案が無かったなら「当たり前のことをした」以上の記録価値はない。
多くのセッションでは 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〜数件。出たものは、後でひっくり返されたら腹が立つ類の決定になっている
- 既存グロッサリと食い違う語をユーザーが使ったとき、その場で指摘できている