grill-with-docs

このプランのあらゆる側面について、共通理解に達するまで容赦なく私にインタビューしてください。設計ツリーの各分岐を辿り、決定間の依存関係を1つずつ解消していきます。各質問について、推奨する答えを提示してください。

質問は1つずつ行い、各質問へのフィードバックを待ってから次へ進んでください。

コードベースを探索すれば答えられる質問は、質問する代わりにコードベースを探索してください。

ドメイン認識

コードベース探索中は、既存のドキュメントも探してください。

ファイル構成

ほとんどのリポジトリは単一コンテキストを持ちます:

/
├── 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.md が存在しなければ、最初の用語が解決されたときに作成します。docs/adr/ が存在しなければ、最初の ADR が必要になったときに作成します。

セッション中

用語集に照らして問い詰める

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

曖昧な言語を鋭くする

ユーザーが曖昧または多義的な用語を使ったら、正確な正規用語を提案してください。「『アカウント』と言っていますが、Customer のことですか、それとも User のことですか? それらは別物です。」

具体的なシナリオで議論する

ドメインの関係性を議論しているときは、具体的なシナリオでストレステストしてください。エッジケースを探り、概念間の境界についてユーザーに正確さを求めるシナリオを考案してください。

コードと相互参照する

ユーザーが何かの動作を述べたら、コードが一致するか確認してください。矛盾を見つけたら表面化させます。「コードは Order 全体をキャンセルしますが、部分キャンセルが可能だと今おっしゃいました。どちらが正しいですか?」

CONTEXT.md をインラインで更新する

用語が解決されたら、その場で CONTEXT.md を更新してください。バッチにまとめず、発生するたびに記録します。フォーマットは CONTEXT-FORMAT.md に従ってください。

CONTEXT.md は実装の詳細を一切含むべきではありません。CONTEXT.md を仕様書、スクラッチパッド、実装決定の置き場として扱わないでください。これは用語集であり、それ以外の何物でもありません。

ADR は控えめに提案する

ADR の作成を提案するのは、次の3つすべてが真である場合だけです:

1. 元に戻しにくい — 後で考えを変えるコストが大きい
2. 文脈なしでは意外 — 将来の読者が「なぜこうしたのか?」と疑問に思う
3. 本物のトレードオフの結果 — 真の選択肢があり、特定の理由で1つを選んだ

3つのいずれかが欠けていれば、ADR をスキップしてください。フォーマットは ADR-FORMAT.md に従ってください。