domain-modeling

ドメインモデリング

設計を進めながら、プロジェクトのドメインモデルを積極的に構築し、磨き上げます。これは「能動的な」規律です。用語に疑問を投げかけ、エッジケースのシナリオを考案し、用語集や決定事項を書き留めます。内容が固まったらすぐに記録します。語彙を知るために CONTEXT.md を「読む」だけでは、このスキルには該当しません。それはどのスキルでもできる、たった一行の習慣です。このスキルは、モデルを利用するだけでなく、モデルを変更するときに使います。

このスキルは、ドメイン語彙と長期的に参照する決定記録を管理します。shape-design は機能の動作と要件を管理します。ADR は、変更が難しい決定がなぜ行われたかを記録するものであり、仕様書や実装計画ではありません。

このスキルは、planning-contract の記録チェックポイント（契約バージョン：1）における、語彙と決定事項のパートを実行します。解決済みの用語や条件を満たす決定事項を記録する必要がある場合、設計を整える側からこのスキルを呼び出します。分類、権限の範囲、引き継ぎルールを確認するため、その契約を読み込んでください。インストールされていない場合は、既存のルールや独自に考案したルールに基づいて進めず、planning-contract のインストールを依頼して停止してください。

ファイル構成

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

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

ルートに CONTEXT-MAP.md が存在する場合、またはプロジェクトで複数のコンテキストが明示的に宣言されている場合、そのリポジトリには複数のコンテキストがあります。マップには、それぞれのコンテキストの場所が記載されています。

/
├── CONTEXT-MAP.md
├── project/
│   └── adr/                         ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── project/adr/              ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── project/adr/

ファイルは必要になったときに作成します。書き留める内容ができるまでは作成しないでください。CONTEXT.md が存在しない場合は、最初の用語が解決した時点で作成します。単一コンテキストのプロジェクトであれば、設定済みかどうかは問いません。複数コンテキストとして設定されたプロジェクトでは、ルートに CONTEXT.md を作成しないでください。ADR ディレクトリ（既定では project/adr/、レガシー構成では docs/adr/）が存在しない場合は、最初の ADR が必要になった時点で作成します。

コンテキストの所有者を特定する

用語集を書く前に、project/agents/domain.md（レガシー構成では docs/agents/domain.md）が存在する場合は読みます。明示された単一／複数コンテキストの宣言は設定として扱い、名前を独自に考案する理由にしないでください。そのうえで、次の手順に従います。

1. CONTEXT-MAP.md が存在する場合は読み、実際に記載されているパスに従います。
2. 関連するパッケージやコンテキストのディレクトリを調べ、既存の CONTEXT.md や用語集ファイルを確認します。
3. ある用語が複数のコンテキストに属する可能性がある場合、黙って決めるのではなく、どの実際のコンテキストが所有するのかを尋ねます。
4. 明示的な設定と、既存のマップや用語集に記載された情報が食い違う場合は、その食い違いを伝え、どちらを更新するか所有者に尋ねます。どちらの情報源も自動的に書き換えてはいけません。
5. 明示的に複数コンテキストとして設定されているプロジェクトで、マップが存在しない、または所有者を特定できない場合は、作業を中断し、実際のコンテキストの所有者を尋ねます。マップがないという理由だけで、ルートに CONTEXT.md を作成してはいけません。 所有者が判明したら、マップまたはコンテキストの用語集を必要に応じて作成します。
6. 単一コンテキストとして設定されたプロジェクト、またはマップのない未設定のプロジェクトでは、単一コンテキストへのフォールバックを維持します。ルートの CONTEXT.md を使用し、用語が実際に解決した時点で必要に応じて作成します。用語集がまだない、単一コンテキストとして設定されたリポジトリでも、同じように最初の実際の用語集を作成します。そのためにコンテキストマップを作成する必要はありません。

インストーラーは、プレースホルダーの用語集や架空のドメイン名を作成しません。コンテキストマップは、実在するコンテキストとその関係を示す場合にのみ意味を持ちます。

セッション中

用語集との不一致を指摘する

ユーザーが CONTEXT.md にある既存の用語と食い違う用語を使った場合、すぐに指摘します。「用語集では『キャンセル』を X と定義していますが、Y の意味で使っているようです。どちらでしょうか？」

曖昧な表現を明確にする

ユーザーが曖昧な用語や複数の意味を持つ用語を使った場合、正確な標準用語を提案します。「『アカウント』と言っていますが、Customer と User のどちらを指していますか？ これは別々の概念です。」

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

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

コードとの相互確認

ユーザーが何かの動作について説明したら、コードと一致しているか確認します。矛盾が見つかった場合は、その点を提示します。「コードでは Orders 全体をキャンセルしていますが、先ほど部分キャンセルが可能だとおっしゃいました。どちらが正しいですか？」

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

用語が確定したら、その場で該当する CONTEXT.md を更新します。まとめて後から更新せず、確定した時点で記録します。形式は context-format.md を使用してください。

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

ADR の提案は慎重に行う

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

1. 変更が困難：後から判断を変えるコストが大きい
2. 背景がないと意外に思われる：将来の読者が「なぜこの方法にしたのだろう？」と思う
3. 実際のトレードオフの結果：現実的な選択肢が複数あり、特定の理由から 1 つを選んだ

いずれか 1 つでも当てはまらない場合は、ADR を作成しません。記録の確認時に該当する場合は、ADR を無理に作るのではなく、不要であることを伝えてください。形式は adr-format.md を使用してください。

ADR を記録したら、呼び出し元の設計ワークフローに戻ります。決定によって外から見える動作、不変条件、または受け入れ基準が変わる場合は、ADR を膨らませるのではなく、仕様に記録してください。

出典

mattpocock/skills の commit 3cca18b368ae95cdbdebbff572ccafa662551015（MIT）を基にしています。