grill-with-docs

<what-to-do>

この計画のあらゆる側面について容赦なくあなたに質問を続け、共通理解に到達するまで進めます。設計ツリーの各分岐を下り、決定間の依存関係を一つずつ解決していきます。各質問について、推奨回答を提供します。

質問は一つずつ行い、次に進む前に各質問についてのフィードバックを待ちます。

質問がコードベースを調査することで答えられる場合は、代わりにコードベースを調査します。

</what-to-do> <supporting-info>

ドメイン認識

コードベースの調査中に、既存のドキュメントも探してください:

ファイル構造

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

/
├── 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を意味しているようです — どちらですか?」

あいまいな言語を磨く

ユーザーが曖昧またはオーバーロードされた用語を使う場合は、正確な正規用語を提案します。「あなたは『アカウント』と言っていますが、それはカスタマーですか、ユーザーですか? これらは異なるものです。」

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

ドメインの関係性が議論される場合は、具体的なシナリオでそれらをストレステストします。エッジケースを探り、概念間の境界について正確になることを強制するシナリオを発明します。

コードと相互参照する

ユーザーが何かの動作方法を述べる場合は、コードが同意しているかどうかを確認します。矛盾を見つけた場合は、それを提起します: 「あなたのコードはオーダー全体をキャンセルしていますが、あなたは部分的なキャンセルが可能だと言ったばかりです — どちらが正しいですか?」

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

用語が解決されたら、その場で CONTEXT.md を更新します。これらを溜め込まないでください — それが起こった時に捕捉します。CONTEXT-FORMAT.md の形式を使用してください。

CONTEXT.md は実装の詳細が全くないものであるべきです。CONTEXT.md を仕様書、スクラッチパッド、または実装上の決定のリポジトリとして扱わないでください。それは用語集であり、それ以外の何物でもありません。

ADRは控えめに提供する

次の3つがすべて当てはまる場合にのみ、ADRを作成することを提案します:

1. 逆転しにくい — 後で気が変わる場合の費用が意味のあるものである
2. 文脈なしでは驚きがある — 将来の読者は「なぜこのようにしたのか?」と疑問に思うだろう
3. 実際のトレードオフの結果である — 本当の代替案があり、あなたは特定の理由で一つを選んだ

3つのいずれかが欠けている場合は、ADRをスキップします。ADR-FORMAT.md の形式を使用してください。

</supporting-info>