efoo-team モジュール境界設計スキル
機能の境界をどこに引き、何を同じ側に置き、何を分けるかを判断するための思考手順。
原則
機能境界は 処理の順序 ではなく 変更理由の独立性 で決まる。
そしてもう一つ。境界を「引く」だけでは不十分で、その境界を「成立させる」必要がある。責務を分けただけでは境界にはならない。境界が意味を持つのは、公開面・状態の所有・依存方向・不変条件の守備範囲が明確になったときである。
適用範囲
このスキルを使う場面
- 機能の境界が曖昧で、どこで切るべきか判断が必要なとき
- モジュールやクラスが肥大化していて分割を検討するとき
- 変更の影響が広範囲に波及している構造を改善するとき
- 抽象化の妥当性に疑いがあるとき
- 既存の責務配置を見直すとき
このスキルの対象外
- 単純な CRUD の実装判断
- 差分レベルのコードレビュー
- API のインターフェース設計（境界は決まっていて表面だけ考える場合）
- 依存方向の違反検出だけが目的の場合
思考手順
Step 1: 機能文の構造化
設計対象の機能を「〈主語〉が〈対象〉を〈操作〉する」の形に分解する。複数の操作が含まれていれば、操作ごとに分けて書き出す。
ユーザーが使った言葉をそのまま使わない。「何を受け取り、何を保全し、何を変換し、何を出力するか」という責務が見える動詞に置き換える。
Step 2: 境界候補の発見
以下の4つの観点から、境界の候補を洗い出す。どれか1つではなく、4つすべてを順に確認する。
2-A: 対象の置換（共通性・可変性の識別）
機能文の中の対象（目的語）を、現実的にありうる別の対象で3つ以上置き換える。
- どの置換でも処理が変わらない部分 → 共通層（抽象化してよい）
- 置換すると処理の内容・ルール・制約が変わる部分 → 専用層（ドメイン固有に残す）
3つ以上なのは、2つでは偶然の一致と本質的な共通性の区別がつかないため。ただし3つ目が現実に存在しない場合は、無理に一般化せず継ぎ目だけを意識する。
2-B: 意味の分裂の検出
同じ言葉（名詞）が、文脈によって異なる意味で使われていないかを確認する。
同じ「ユーザー」でも、認証では「認証主体」、課金では「支払者」、サポートでは「問い合わせ者」を意味するなら、それぞれ別の境界に属する可能性が高い。意味が変わる地点は境界候補になる。
確認方法:
- 機能文に登場する主要な名詞を列挙する
- 各名詞の意味が、機能のどの文脈でも同一かを問う
- 意味がずれる地点があれば、そこに境界候補を置く
- 境界をまたぐ場合に翻訳（変換層）が必要かを判断する
2-C: 不変条件の特定
「一緒に壊れてはいけないルール」を特定する。あるルール群が1つのトランザクションや1つの整合性制約で結びついているなら、それらは同じ境界に留めるべき可能性が高い。
確認方法:
- この機能が守るべきビジネスルール・整合性制約は何かを列挙する
- そのルールが成立するために、どのデータが同時に参照・更新される必要があるかを特定する
- 同じ不変条件に縛られるデータと処理は、同じ境界に置く
不変条件が境界をまたぐ場合、調整コスト（saga、eventual consistency、手動整合）が発生する。そのコストを許容できるかどうかが、境界を分けるかどうかの判断材料になる。
2-D: 所有と変更頻度の確認
誰が、どのくらいの頻度で、その部分を変更するかを確認する。
- 変更の起点が異なるもの（法務起点 vs 開発起点 vs 顧客要望起点）は、別の境界候補
- 変更頻度が極端に異なるもの（年1回変わるルール vs 週次で変わるルール）は、分離した方が安定する
- 所有者（継続的に面倒を見る人・チーム）が異なるものは、別の境界にした方が実務上強い
所有者が曖昧な境界は、設計がどれだけ綺麗でも時間とともに崩壊する。
Step 3: 変化軸の特定と境界の確定
Step 2 で見つけた境界候補を「なぜ変わるのか」で分類し、最終的な境界を確定する。
- 「この部分が変わるとき、他のどこが一緒に変わるか？」→ 一緒に変わるものは同じ境界
- 「この部分が変わるとき、他はそのままでいられるか？」→ いられるなら、そこが境界
変化軸が異なるものは、見た目が似ていても・処理フロー上は隣接していても分ける。変化軸が同じものは、処理フロー上は離れていても束ねる。
Step 4: 差分の吸収方法の選択
境界内の可変部分をどう設計に取り込むかを、差分の性質に応じて選ぶ。
値だけが異なる場合（型・構造は同一）: パラメータ化する。
振る舞い・アルゴリズムが異なる場合: インターフェースを抽出し、実装を差し替え可能にする。
処理の流れ自体が異なる場合: 別のモジュール・サービスとして独立させる。
判断の閾値:
- パラメータが3つ以下で条件分岐が増えない → パラメータ化してよい
- パラメータに応じて内部の制御フローが変わる → インターフェース抽出を検討
- 統合後に型チェックや条件分岐が増えた → 抽象を解体して戻す
Step 5: 境界の成立条件の確認
境界を引いたら、その境界が実際に機能するかを確認する。境界が成立するには、以下の4つが明確である必要がある。
公開面（Public Contract）: この境界が外部に提供するインターフェースは何か。何を受け取り、何を返すか。公開面が言語化できないなら、境界が不明確である。
状態の所有: この境界が排他的に所有するデータは何か。他の境界が直接読み書きしてよいデータはあるか。共有される可変状態があるなら、境界は名目上のものでしかない。
依存方向: この境界は何に依存し、何がこの境界に依存するか。循環依存があれば、境界の引き方を見直す。
通信方式: 境界間はどう連携するか。直接呼び出し、イベント、非同期メッセージ、変換層のどれが適切かは、境界の独立性の要求水準で決まる。
Step 6: 変更マトリクスによる検証
想定される変更シナリオを5つ程度並べ、各シナリオで影響を受けるモジュールを特定する。影響が1〜2モジュールに閉じていれば妥当。3モジュール以上に波及するなら、境界の引き直しを検討する。
Step 7: 抽象化の範囲の制限
抽象化は「広げること」だけでなく「受け入れる可変性を制限すること」でもある。
- 初期実装では今ある具体例だけで動くものを作る
- インターフェースは切っておくが実装は1つだけにする
- 2つ目・3つ目の具体的な要件が現れた時点で、必要な分だけ一般化する
まだ存在しない要件のために抽象化すると、必要な柔軟性ではなく不要な複雑性が生まれる。間違った抽象を共有するより、重複を許容する方がコストが低い。
重要な区別: 境界設計と内部構造は別の問題
設計相談では、以下が頻繁に混同される。
- 境界設計: どの責務をどのモジュールに配置するか。意味・変化軸・不変条件・所有で決める
- 内部構造: 境界の中をどう整理するか。vertical slice、layer、CQRS などは内部戦略
この2つは別の問題であり、別の判断基準で決める。「feature ごとに切るべきか、domain ごとに切るべきか」という問いが出たら、まず「それは境界の話か、内部構造の話か」を切り分ける。
命名の原則
責務名で命名する。実装技術名で命名しない。 名前が「何の技術を使っているか」を説明しているなら実装名であり、悪い兆候。名前が「何の責任を負っているか」を説明しているなら責務名であり、良い兆候。
1つの名前に複数の責務が含まれていないか検査する。 And / Or / Manager / Handler / Processor のような汎用語は、複数の変化軸が1つに混ざっている可能性を示す。
反パターン
以下は境界・責務配置の観点で扱う。リファクタリングを「いつ・どの規模で実施するか」の判断は refactor-mindset の担当。
1. フロー順分割
処理フローの順番（Step1, Step2, Step3）でモジュールを切る。変化軸をまたぐ境界になりやすい。
2. 間違った抽象の共有
共通化した結果、対象種別ごとの条件分岐・パラメータ・例外ケースが増殖する。統合前より複雑になったら、抽象を解体して重複に戻す。
3. 全能サービス
XxxManager, XxxHandler, XxxProcessor に責務が集中する。検出したら、そこに含まれる責務を列挙し、変化軸ごとに分離候補を出す。
4. 貧血ドメインモデル
データだけがエンティティにあり、ロジックがすべてサービスにある。境界内の責務配置が崩れているサイン。データとそのデータに対する操作が別の場所に散っている場合、それらを同じ場所に寄せることを検討する。
5. 名詞の類似性による統合
名前が似ているという理由だけで処理を統合する。操作集合・不変条件・エラー境界が一致しない限り、統合は避ける。
6. 過剰な先行抽象
具体例が1つしかないのに汎用フレームワークを作る。「将来必要になるかもしれない」は分割の根拠にならない。
7. 状態の暗黙共有
パッケージやフォルダは分かれているが、可変な状態を複数モジュールが直接読み書きしている。境界は名目上のものでしかなく、実質的に密結合。
8. 肥大化した境界
1つの境界の中に、実際には独立に変化する複数のサブドメインが同居している。境界自体は正しいが、粒度が粗すぎる。分割が必要になったら、最も変更頻度が高く他と独立しているサブドメインから切り出す。
理論的根拠
各ステップ・反パターンの理論的出典（SCV 分析・情報隠蔽・SRP・Bounded Context・Aggregate・Wrong Abstraction・Team Topologies 等）は references/theory.md を参照。