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のようです。どちらでしょうか？」

曖昧な表現の明確化

ユーザーが曖昧な用語や複数の意味に解釈できる用語を使ったら、明確で標準的な用語を提案してください。「『アカウント』と言っていますが、Customer と User のどちらを指していますか？この二つは別の概念です。」

具体的なシナリオについて議論する

ドメイン内の関係について議論する際は、具体的なシナリオを使って厳密に検証してください。境界を明確にするため、エッジケースを探り、ユーザーに正確な説明を促すシナリオを考案してください。

コードとの照合

ユーザーが仕組みについて説明したら、コードと一致しているか確認してください。矛盾が見つかったら、指摘してください。「コードでは Order 全体をキャンセルしていますが、先ほど一部キャンセルが可能だとおっしゃいました。どちらが正しいでしょうか？」

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

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

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

ADR の提案は必要最小限にする

以下の三つすべてに当てはまる場合に限り、ADR の作成を提案してください。

1. 覆しにくい — 後から判断を変えるコストが無視できない
2. 背景がないと意外に思われる — 将来の読者が「なぜこのようにしたのだろう？」と疑問に思う
3. 実際のトレードオフの結果である — 現実的な選択肢を比較し、具体的な理由に基づいて一つを選んでいる

いずれか一つでも当てはまらない場合は、ADR を作成しないでください。ADR-FORMAT.md の形式を使用してください。