domain-modeling

ドメインモデリング

設計を進める中で、プロジェクトのドメインモデルを積極的に構築し、磨き上げます。 これは積極的に取り組む規律です。用語に疑問を投げかけ、エッジケースのシナリオを考案し、 用語集や決定事項を、明確になったその時点で書き留めます。 （用語を確認するために GLOSSARY.md を読むだけでは、このスキルには当たりません。これはどのスキルでも実行できる一行の習慣です。 このスキルが対象とするのは、モデルを変更するときであり、単に利用するときではありません。）

モデルが変化する会話であれば、設計、実装、レビューのいずれにも適用されます。

ファイル構成

プロジェクトですでに別の場所や別の名前で用語集や ADR を管理している場合 （たとえば CONTEXT.md、または AGENTS.md に記載された場所）には、それらを使います。それ以外の場合は、次の構成を使います。

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

ファイルは必要になった時点で作成します。書き込む内容がなければ作成しません。 GLOSSARY.md が存在しない場合は、最初の用語が確定した時点で作成します。 docs/adr/ が存在しない場合は、最初の ADR が必要になった時点で作成します。

セッション中

用語集に照らして確認する

ユーザーが GLOSSARY.md の既存の用語と矛盾する用語を使った場合は、すぐに指摘します。 「用語集では『cancellation』を X と定義していますが、今おっしゃっているのは Y のようです。どちらでしょうか？」

曖昧な表現を明確にする

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

具体的なシナリオを検討する

ドメイン間の関係について議論するときは、具体的なシナリオで検証します。 エッジケースを探り、概念間の境界を明確にせざるを得ないシナリオを考案します。

コードと照らし合わせる

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

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

用語が確定したら、その場で GLOSSARY.md を更新します。まとめて後から記録するのではなく、決まった時点で書き留めます。 GLOSSARY-FORMAT.md の形式を使います。

GLOSSARY.md に実装の詳細を記載してはいけません。 GLOSSARY.md を仕様書、作業メモ、実装上の決定事項を記録する場所として扱ってはいけません。 用語集以外のものにしてはいけません。

ADR の提案は控えめにする

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

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

いずれか一つでも当てはまらない場合は、ADR の作成を見送ります。ADR-FORMAT.md の形式を使います。

最新の状態を保つ

会話の中で、すでに記録されている内容に変更があった場合は、同じ変更の中で記録も修正します。

• 用語の意味が変わった → 該当する項目を更新します。
• 決定が覆された、または置き換えられた → 新しい ADR を作成し、古い ADR に superseded by ADR-NNNN と記載します。 古い ADR は書き換えません。
• ADR の事実関係に小さなずれが生じた（モジュール名の変更、ファイルの移動など） → その場で修正します。