ebal5 coupling-design-advisor
目的
設計の意思決定段階で、候補案の結合バランスを定量的に比較し、最も均衡の取れた選択肢を推奨する。 単なる「疎結合にしよう」という定性論を超え、統合強度・距離・変動性の3次元スコアと均衡結合方程式に基づく根拠を持った設計議論を支援する。 対話を通じて情報を引き出し、最終的に ADR（Architecture Decision Record）形式で意思決定を記録できる形にまとめる。
発火条件（詳細）
以下のいずれかに該当する場合に本スキルを起動する:
- 新しいマイクロサービス・モジュール・コンポーネントの境界設計
- 2つ以上の候補設計案の比較評価（イベント駆動 vs 直接呼び出し など）
- サブドメイン境界の見直し・再定義
- モジュール分割または統合の判断
- 「結合バランスで設計レビューしたい」という明示的な依頼
本スキルを使わないケース:
- 既存コードベースの結合度計測 →
coupling-auditを使う - 純粋な実装タスク（コードを書くだけ）
前提
本スキルを起動する前に、skills/coupling-model/SKILL.md を読み込むこと。
用語定義・1-10 スケール・均衡結合方程式・解釈帯の 正式な定義はすべて coupling-model が単一ソース である。
ここではそれらを再掲しない。
ケーススタディは本スキル配下の references/case-studies.md に自前で保持している
（設計時フレーミング）。将来の coupling-rebalance は改善時フレーミングで
自前の case-studies を持つ想定。
ワークフロー
ステップ 1: コンテキスト確認
目的: 議論の前提を揃える。
以下をユーザーに確認する:
- 設計対象のモジュール名・サービス名
- ビジネス上の位置づけ（コアサブドメイン / 支援サブドメイン / 汎用サブドメイン）
- 既存の設計制約（チーム境界、言語・技術スタック、デプロイ単位）
出口条件: 対象モジュールと大まかなサブドメイン種別が確定した時点で次へ。
ステップ 2: 候補案の整理
目的: 比較対象を明確にする。
ユーザーから 1〜3 案を引き出す。案が 1 つしかない場合でも、対案（例: 現状維持、より疎結合な選択肢）を提示して比較対象を用意する。
出口条件: 候補案が 1 件以上、それぞれの概要が明確になった時点で次へ。
ステップ 3: 各案の 3 次元評価
目的: 定量スコアを算出する。
各候補案について問いかけテンプレート（後述）を使い、3 つのスコアを推定する。推定には強度推定ヒューリスティック（後述）を参照し、不確かな場合はユーザーに確認する。
各案の (強度, 距離, 変動性) が確定したら、coupling-model の方程式
均衡度 = max(|s - d|, 10 - v) + 1 で計算する。
精度が要る場合は coupling-model の公開 CLI を呼び出してもよい。
具体的な呼び出し方は coupling-model の references/api.md に記載。
出口条件: 全候補案の (強度, 距離, 変動性, 均衡度) が出揃った時点で次へ。
ステップ 4: 比較と推奨
目的: 最適案を論理的な根拠とともに提示する。
候補比較フォーマット（後述）で表を作成し、均衡度が最も高い案を推奨する。ただし均衡度が同等の場合は変動性の高い案（将来変化に強い設計）を優先する。アンチパターン（後述）に該当する組み合わせには警告を付記する。
出口条件: 推奨案とその根拠がユーザーに伝わった時点で次へ。
ステップ 5: ADR 化支援
目的: 意思決定を記録に残す。
ADR 出力フォーマット（後述）に沿ってドラフトを生成する。ユーザーが調整したい項目があれば対話的に修正する。
出口条件: ユーザーが ADR ドラフトに合意した時点で完了。
問いかけテンプレート
3 次元を引き出す際の標準的な質問セット。
| 次元 | 問い | 評価軸 |
|---|---|---|
| 統合強度 | 下流は上流の何を知る必要がありますか？（API契約だけ / データモデル / 内部ロジック / 実装詳細） | 知識の範囲が狭いほど強度が低い |
| 距離 | 同じプロセス内ですか、別サービスですか、別ベンダーですか？ | 物理・組織的距離が遠いほど高スコア |
| 変動性 | このモジュールの要件は四半期でどのくらい変わりそうですか？コアサブドメインに属しますか？ | 変化が激しいほど、コアに近いほど高スコア |
強度推定ヒューリスティック
advisor が対話で 3 次元スコアを引き出す際の初期推定表。ユーザー確認で補正する。
| 依存の形 | 推定強度 |
|---|---|
| DBスキーマ共有、内部フィールドへの直接アクセス | 10（侵入結合） |
| 共有ライブラリ内の詳細型を参照 | 8（機能結合） |
| DTO/エンティティの具象型を公開API経由で共有 | 5（モデル結合寄り） |
| インターフェース/契約のみ依存 | 1〜3（コントラクト結合） |
候補比較フォーマット
| 案 | 統合強度 | 距離 | 変動性 | 均衡度 | 判定 | 備考 |
|---|---|---|---|---|---|---|
| A案 | - | - | - | - | - | |
| B案 | - | - | - | - | - | |
| C案 | - | - | - | - | - |
均衡度が高い案を推奨。同点の場合は変動性が高い案（将来の変化への耐性）を優先する。
ADR 出力フォーマット
# ADR-XXXX: [設計決定のタイトル]
**日付**: YYYY-MM-DD
**ステータス**: 提案中 / 承認済み / 廃止済み
## Context
[なぜこの決定が必要になったか。背景・制約・問題の説明]
## Decision
[選択した案と、その根拠]
## Consequences
**良い影響**:
- [期待される恩恵]
**悪い影響・トレードオフ**:
- [受け入れるコストやリスク]
## Coupling balance
| 案 | 統合強度 | 距離 | 変動性 | 均衡度 | 判定 |
|----|---------|------|--------|--------|------|
| 採用案 | - | - | - | - | - |
| 却下案 | - | - | - | - | - |
採用根拠: [均衡度と hints に基づく説明]
アンチパターン警告
以下の組み合わせが検出された場合、ユーザーに明示的に警告する。
| パターン | 問題 | 対処 |
|---|---|---|
| 強度↑ × 距離↑ × 変動性↑ | 最悪の組み合わせ。マイクロサービス化の失敗典型。大規模リファクタ必須 | 強度を下げる（契約化）か、距離を縮める（統合）かを選ぶ |
| 強度↓ × 距離↓ × 変動性↓ | 過剰な疎結合。YAGNI 違反の可能性が高い | 不必要な抽象化を削除し、距離を縮めることを検討 |
| 対称機能結合（複製ロジック） | マイクロサービス間で同一ロジックが複製される場合、均衡度1になりやすい | 統合して単一所有者を定義する |
ケーススタディ参照
本スキルの few-shot 参考として、書籍『ソフトウェア設計の結合バランス』の代表ケースを
設計相談の Q&A 形式に翻案した 4 件を 本スキル配下の
references/case-studies.md に収録している（設計時フレーミングで保守）。
- 例 1: 強度が不可避 → 距離で救う（設計時の境界選択）
- 例 2: 戦略的変更への反応（サブドメイン昇格 → 強度削減）
- 例 3: 過剰疎結合の抑制（変動性が低ければ許容、YAGNI 原則）
- 例 4: 対称機能結合アンチパターン（本書最悪例、均衡度 1）
類似する設計パターンに遭遇した場合は同ファイルを参照すること。 プロンプトテンプレート断片と選定ロジックも同ファイル末尾に記載。
coupling-model 側には case-studies を置かない方針（Issue #19 対処）: consuming skill が文脈に合わせて自前で保持することで skill 間の raw-path 結合を回避している。