KEN3pei 結合バランスレビュー
レビュー原則
結合を無条件に悪いものとして扱わない。対象システムの変更パターンに対して、その結合が均衡しているかを評価する。
各依存関係を、主に次の3つの次元で評価する。
- 統合強度: 知識、ライフサイクル、振る舞い、データ構造、実行順序、タイミング、同一性、実装詳細をどれくらい共有しているか
- 距離: 結合している要素同士が、コード構造、実行時、デプロイ、所有権、リポジトリ、チーム、リリースライフサイクルの面でどれくらい離れているか
- 変動性: それぞれがどれくらいの頻度で、どのような理由で変更されるか
特に、統合強度が高く、距離が遠く、変動性が揃っていない依存関係を優先的に問題として扱う。
このスキルは本の本文を要約・再現するためのものではない。公式用語をレビューの評価軸として使い、対象コードや設計資料から確認できる根拠を優先する。
確認する入力
推測よりも具体的な証拠を優先する。
- ソースコードとパッケージ/モジュール境界
- 公開API、DTO、スキーマ、OpenAPI、GraphQL、Protocol Buffers定義
- データベーススキーマと所有境界
- イベント定義と利用側
- 依存方向とimport関係
- デプロイ境界と実行時通信
- 変動性を判断するためのGit履歴
- モジュール間の調整を示すテスト
レビュー手順
レビュー対象の境界を特定する。 評価対象がモジュール、サービス、パッケージ、クラス、API、DBテーブル、イベント、ワークフローのどれなのかを明示する。
結合点を洗い出す。 依存関係を具体的に列挙し、直接呼び出し、import、共有モデル、共有DB、イベント、API契約、設定、グローバル状態、継承、生成クライアント、テストフィクスチャ、運用上の依存などに分類する。
モジュール結合を分類する。 該当する場合、内容結合、共通結合、外部結合、制御結合、スタンプ結合、データ結合を確認する。
コナーセンスを分類する。 該当する場合、名前、型、意味、アルゴリズム、位置、実行、タイミング、値、同一性のコナーセンスを確認する。
統合強度を評価する。 侵入結合、機能結合、モデル結合、コントラクト結合の観点で確認する。何の知識が共有されており、片方の変更がなぜ他方の変更を強いるのかを説明する。
距離を評価する。 コード、実行時、デプロイ、所有権、リポジトリ、チーム、リリースライフサイクルの面で、結合している要素同士が近いか遠いかを説明する。
変動性を評価する。 両者が同じ理由・同じ頻度で変わるかを推定する。可能ならGit履歴やドメイン上の変更理由を根拠にする。推測の場合は、推測であることを明示する。
均衡しているか判断する。 統合強度、距離、変動性を組み合わせて評価する。特に次を優先して指摘する。
- 強い結合が遠い境界をまたいでいる
- 変わりやすい要素と安定した要素が強く結合している
- 安定しているべき要素が、変わりやすい要素を知りすぎている
- 独立デプロイや独立リリースの裏に強い意味的結合が隠れている
- 非同期連携の裏に、順序、タイミング、同一性、値の前提が隠れている
再均衡の案を出す。 実行可能な改善案を優先する。コードを近づける、モジュールを分割または統合する、契約を導入または狭める、制御フラグを明示的な操作に置き換える、共有ミュータブル状態を減らす、共有DBアクセスを所有境界に置き換える、安定した概念と変わりやすい概念を分ける、暗黙の順序・タイミング・値の前提を明示する、コントラクトテストや特性化テストを追加する、などから選ぶ。
結合が局所的で安定しており変更コストが安い場合は、抽象化を急がない。弱めるだけでなく、近づける、所有境界を変える、変更頻度を揃える、といった再均衡を検討する。
出力形式
最初に重要度順で指摘事項を出す。各指摘には次を含める。
- 場所
- 結合タイプ
- 根拠
- 統合強度
- 距離
- 変動性
- 均衡しているかどうか
- 推奨する変更
- 確信度
重要度は次で判断する。
- High: 統合強度が高く、距離が遠く、変動性が揃っていない。調整コストや本番リスクにつながりやすい
- Medium: 結合コストはあるが、局所的または一部安定している
- Low: 軽い設計上の摩擦、または将来的な保守性リスク
最後に次をまとめる。
- 結合マップの要約
- 再均衡の選択肢
- 仮定と不明点
- 追加すべきテストまたは測定
出力例
## Findings
### High: `OrderService` と `BillingService` が同じ永続化モデルを共有している
- 場所: `apps/backend/...`
- 結合タイプ: 共通結合 / モデル結合 / コントラクト結合
- 根拠: 両サービスが同じ `orders` テーブルを読み書きし、同じステータス値に依存している
- 統合強度: 高
- 距離: 高。サービスが独立してデプロイされるため
- 変動性: 不一致。注文ワークフローは請求確定ルールより頻繁に変わる可能性がある
- 均衡判断: 均衡していない
- 推奨する変更: 注文ライフサイクルモデルの所有境界を定義し、請求側には決済に必要な狭い契約を公開する。状態遷移にはコントラクトテストを追加する
- 確信度: Medium