Architecture Design
理想的な役割・協調・契約を確定した後、それらをどの責務境界へ配置し、どう構成するかを決める。
契約設計の不変条件は contract-driven-object-collaboration、依存方向・レイヤー命名等は hierarchical-architecture を正本とする。
設計順序
- 利用目的と理想協調を確認する
interface-first-designで現在必要な最小契約を定義する- 契約だけでユースケースが成立することを確認する
- 各役割を管理 / 提供 / 操作 / Platform 等の責務へ配置する
- 依存方向が上位→下位の一方向か確認する
- 最後に具体実装と構成方式を選ぶ
レイヤーやDI方式から契約を逆算しない。
レイヤー構造
| # | 役割 | 責務 | 命名例 |
| --- | --- | --- | --- |
| 1 | Contract | 理想的な役割・能力・協調の定義 | capability / domain contract |
| 2 | 管理層 | 下位の生成・破棄・ライフサイクル | *Manager, *Context |
| 3 | 提供層 | 同種能力のグルーピング | *Provider, *Registry |
| 4 | 操作層 | 特定リソースへのアクセス | *Accessor, *Client |
| 5 | サブコンポーネント (任意) | ドメイン固有の実装 | domain-specific implementation |
| 6 | Platform | プラットフォーム・外部仕様固有実装 | — |
この表は配置の補助であり、全機能に全レイヤーを作るテンプレートではない。現在不要な層は作らない。
配置判断
各役割について次を確認する。
- 他オブジェクトの内部状態・具体表現を参照していないか
- primitiveや外部形式を契約経由で呼び出し側へ漏らしていないか
- 種別を取得して
if/switchする代わりに能力契約で協調できないか - 取得と描画、取込と実行等の別責務が混在していないか
- 実世界の対象と理想上の対象を同一型・同一責務として扱っていないか
- 具体製品、protocol、storage、frameworkの事情が上位へ漏れていないか
合成優先
- 小さく独立した能力契約を組み合わせて複雑な機能を実現する
- 1つの対象が複数能力を持つ場合、必要な契約を複数満たす形を優先する
- 各実装は他の実装やその内部状態を知らない
- 実装の組み合わせは構成点で決める
- DIは構成の結果であり、DIを行うために契約や層を増やさない
良い設計 / 悪い設計の兆候
良い設計:
- 新しい実装を追加しても既存利用側の条件分岐が増えない
- 契約だけでユースケースを説明・テストできる
- 各オブジェクトが協調相手の内部表現を知らない
- Renderer変更でSourceが変わらない等、責務境界を越えて変更が波及しない
- 実装・外部形式を変更しても理想契約が維持される
悪い設計:
- 新機能のたびに引数、状態property、種別分岐が増える
- 契約にない操作のために具象型へcastする
- 外部仕様変更でCore契約まで変更される
- Mockを作るために大量の内部値や外部形式を再現する必要がある
- DI登録やFactoryだけが複雑化し、理想協調が不明瞭になる
継承を採用してよい場面
「悪い設計の兆候」に該当しないことを条件に、次は継承を許可する。
- フレームワーク/ランタイムが要求する基底
- is-a 関係が明確なドメイン階層
- 言語・フレームワーク上のMixin等が最小手段となる場合
それ以外の独立能力は契約の多重実装・合成を優先する。継承深度は2段までを目安とする。
外部入力・外部形式
外部の生データ、device仕様、通信方式、file format等をアプリケーションの理想契約として扱わない。 理想契約との差異を埋める具体処理は、実装時に差異を確認してからPlatform/境界側へ置く。 Adapter、Translator等を将来予測だけで先に設計しない。
リソースのライフサイクル
生成と利用を分離する。確保と解放はワンセットにし、必要な管理責務がライフサイクルを所有する。 利用側は具体的な確保・解放手順を知らない。
設計レビュー
設計案を確定する前に最低限次の5問へ答える。
- 契約は実装ではなく理想的な役割と協調から作られているか
- 呼び出し側は相手の内部状態・内部表現を取得して判断していないか
- 必要な操作は契約として表現され、その契約だけで処理できるか
- 異なる責務、または実世界と理想世界を混同していないか
- 現在必要でない抽象化や層を追加していないか
複数設計案の比較 (明示要求時のみ)
dispatch形式・並列起動の作法は ${HOME}/.claude/SUBAGENTS.md を参照。
起動条件
以下のいずれかに該当する場合、design-consultantへ複数案の比較を依頼する。
- ユーザーから「複数案を出して」「設計の選択肢を比較したい」と明示要求された
- 理想契約を満たす責務配置に複数の妥当案があり、選択基準が定まらない
- 既存コードが歴史的経緯で破綻しており、再設計の方向性が定まらない
dispatch内容
対象機能の利用目的、確定済みの理想契約、contract-driven-object-collaborationとhierarchical-architectureの不変条件を渡す。
比較対象は実装技術の好みではなく、責務分離、依存方向、変更波及、現在必要な抽象化量とする。
評価軸
| 軸 | 確認内容 | | --- | --- | | 理想契約の純度 | 実装・primitive・外部形式が漏れていないか | | 単一責任 | 各役割が1責務に収まっているか | | 依存方向 | 上位→下位の一方向か | | 変更影響 | 新実装追加で既存利用側が変わらないか | | 抽象化量 | 現在必要な契約・層だけか |
起動しないケース
確定済みの契約と既存patternで配置が自明な局所変更、1クラス追加程度の変更、方針そのものを再検討すべき段階では起動しない。