domain-modeling

ドメインモデリング

設計を進める中で、プロジェクトのドメインモデルを積極的に構築し、磨き上げます。これは能動的な取り組みです。用語に異議を唱え、エッジケースのシナリオを考案し、用語や判断が固まったらその場で用語集や決定事項を書き留めます。語彙を確認するためにCONTEXT.mdを読むだけでは、このスキルに該当しません。それはどのスキルでもできる、たった一つの習慣です。このスキルは、単にモデルを利用するのではなく、モデルを変更するときのものです。

ファイル構成

ほとんどのリポジトリには、単一のコンテキストがあります。

/
├── 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のどちらを指していますか？この2つは別のものです。」

具体的なシナリオを話し合う

ドメイン間の関係について話し合う際は、具体的なシナリオで検証します。エッジケースを探り、概念の境界を明確にする必要があるシナリオを考案してください。

コードと照合する

ユーザーが機能の仕組みを説明したら、コードの内容と一致するか確認します。矛盾が見つかった場合は指摘します。「コードではOrder全体をキャンセルしますが、先ほど一部だけキャンセルできると言っていました。どちらが正しいですか？」

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

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

CONTEXT.mdには、実装の詳細を一切含めないでください。CONTEXT.mdを仕様書、メモ帳、実装上の決定事項を保管する場所として扱ってはいけません。ここに記載するのは用語集だけです。

ADRの提案は慎重に行う

次の3つすべてに当てはまる場合に限り、ADRの作成を提案します。

1. 変更が難しい — 後から考えを変えるコストが無視できない
2. 背景がないと意外に思われる — 将来の読者が「なぜこの方法にしたのだろう？」と思う
3. 実際のトレードオフの結果である — 現実的な代替案が複数あり、具体的な理由から1つを選んだ

3つのうち1つでも当てはまらない場合は、ADRを作成しません。ADR-FORMAT.mdの形式を使用します。

ADR文書を作成する際は、次の点に留意してください。

• 機能の一部に実装が難しいと考えられる部分があるか（具体的な指示がなければ、小規模なAI エージェントやサブエージェントが実装に苦労したり、失敗したりする可能性があるか）、またはセッション中に特定のクラス、データ構造、設計が提案されたかを評価します。
• 該当する場合は、今後の実装の指針となるコードスニペット（インターフェース、データ構造、主要なクラス、アルゴリズムの骨格など）をADRに含めます。
• 実装を担当するサブエージェントがコーディングの精度を高めるために参照できるよう、作業中のワークスペースにある関連ファイルやプロジェクトのパスまたは参照情報を明記します。
• 単純なタスクや設計の場合は、現在の形式を保ち、ADRを最小限にします。