review

モジュール性のレビュー

Vlad Khononov による Balanced Coupling モデル（balanced-coupling スキルから事前に読み込まれます）を使用して、コードベースのモジュール性の不均衡を分析します。具体的な設計上の問題を特定し、それぞれについて知識のカプセル化、複雑さ、変更の波及との関係を説明したうえで、設計の改善方法を示すレビューを作成します。

TaskCreate を使用して、次の 4 つの手順を追跡してください：問題領域を把握する、統合ポイントをマッピングする、バランスルールを適用する、レビューを作成する。

対話のルール

ユーザーからの入力には常に AskUserQuestion を使用してください。次の原則に従ってください。

• 一度に質問は 1 つだけです。 複数の質問を 1 つのメッセージにまとめてはいけません。
• 選択式を優先します。 具体的な選択肢を 2～4 個提示してください。自由回答よりも答えやすくなります。
• 「その他」は自動で追加されます。 このツールでは自由記述の「その他」が常に提示されます。手動で追加しないでください。
• 見出しを付けてください。 「範囲」「領域」「チーム」「課題」のような短いラベル（最大 12 文字）を使用してください。

プロセス

ステップ 1：問題領域を理解する

1. AskUserQuestion を使って、コードベースのどの部分を分析するか尋ねます。ヘッダーは「範囲」とします。選択肢は「コードベース全体 — すべてのコンポーネントを分析」「特定のディレクトリ — パスを指定します」「特定のコンポーネント — 名前を指定します」です。ユーザーが特定の範囲を選んだ場合は、詳細を確認します。

2. 質問する前に読みます。 まず docs/ フォルダー内の機能要件ドキュメントをすべて読み、その後、コード自体を読みます。コンポーネントとその責務、およびそれらの連携方法を理解します。推測せず、LSP（findReferences、goToDefinition）、Grep、Glob を使って調べます。

3. 理解した内容を提示します。 ドメインに関する質問をする前に、コードと要件から分かったことを簡潔にまとめて提示します。

   • 見つかったコンポーネントとその責務
   • 観察した連携パターン（共有型、API 呼び出し、データベースアクセス、イベントフロー）
   • ドメイン分類の最善の推測（コア／サポート／汎用）、その理由と確信度 — 確信度の低い領域は、追加質問の有力な候補です
   • チーム構成、デプロイ構成、設計意図についての前提

   AskUserQuestion を使って確認します。ヘッダーは「要約」とします。選択肢は「問題ありません」「一部違います — 修正します」「重要な情報が抜けています」です。ユーザーが訂正や情報を追加した場合は、先にそれを反映してから進めます。

4. 不足している情報を特定します。 Balanced Coupling モデルは把握しています。必要なのは、変動性（ドメイン分類から）、距離（組織構造から）、強度（コードから）です。何が分かれば結合度の評価が変わるかを考え、不足している点について質問します。質問は AskUserQuestion を使い、一度に 1 つずつ行います。分析結果が変わらない質問はしないでください。すべての質問で、評価に影響する不足情報を補う必要があります。

   検討すべきよくある情報不足（コード、要件、またはユーザーの訂正からすでに把握できているものは省略します）：

   • ドメイン分類の不足 — ある領域がコア（競争上の優位性、高い変動性）なのか、サポートなのか、汎用なのか判断できない箇所。最善の推測を示し、ユーザーに確認または修正を求めます。
   • 組織的背景 — チームのオーナーシップの境界、デプロイ構成、共有インフラ。これらは、コード構造から分かる以上に、実質的な距離に影響します。
   • 既知の課題 — 変更に予想外のコストがかかる箇所、デプロイによって問題が起きる箇所、設計に違和感がある箇所。こうした情報をもとに、重要な部分に分析を集中させます。
   • 戦略的な方向性 — 今後の移行、事業の変化、変動性の高い領域に影響する予定変更。
   • 予想外のパターン — 意図的な設計判断か、偶発的な複雑さか判断できない、コード内で見つけたパターン。決めつける前に確認します。

   これらのカテゴリに限定されません。適切な結合度評価にあたり、コード内で確認が必要な点を見つけた場合は質問してください。実際に見つけたコンポーネント、パターン、連携を挙げ、コード上の具体的な観察に基づいて質問します。

ステップ 2：統合をマッピングする

相互に連携するコンポーネントの各ペアについて、次の点を特定します。

• 共有される知識は何か — 実装の詳細、ビジネスルール、ドメインモデル、統合契約のどれですか？
• 統合の強度レベル — 侵襲的、機能的、モデル、契約のどの結合ですか？
• 共有される知識は暗黙的か、明示的か？ 暗黙的な結合（重複するビジネスルール、データベースへの直接アクセス、内部動作に関する想定）は特に危険です。
• 距離 — 同じモジュール、同じサービス、別々のサービス、別々のシステムのどれですか？同じチームですか、それとも別のチームですか？同期処理ですか、それとも非同期処理ですか？
• 変動性 — ビジネスドメインの観点から、この領域はどの程度変更されそうですか？汎用サブドメインについては、機能的変動性（問題の定義）と実装上の変動性（特定のプロバイダーやテクノロジー）を区別してください。

ステップ 3：バランスルールを適用する

統合ごとに、次の式を適用します：BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY

結合がアンバランスかつ変動性が高い統合をすべて指摘します。

• 強度が高い + 距離が大きい + 変動性が高い — 変動性の高い領域における密結合です。緊急の問題です。変更が頻繁になり、コストが高く、予測しにくくなります。
• 強度が低い + 距離が小さい — 凝集度が低い可能性があります。無関係なコンポーネントが同じ場所に置かれ、認知負荷が増し、巨大な泥団子へと向かうおそれがあります。
• 強度が高い + 距離が大きい + 変動性が低い — 技術的負債ですが、許容できます。記録はしても、優先順位を高くしないでください。

ステップ 4：レビューを作成する

（事前に読み込まれている）ドキュメントスキルを使用して、モジュール性レビューを Markdown と HTML の両形式で作成します。構成と出力形式はドキュメントスキルで定義されています。

重要な制約

• コードを読んでください。 構造だけから問題を特定してはいけません。実際に連携する箇所（関数呼び出し、インポート、共有データ構造、データベースアクセスパターン、API 呼び出し）を読んで、実際にどのような知識が共有されているかを判断してください。
• 単一の次元だけで結合を評価してはいけません。 強度、距離、変動性の 3 つすべてを常に考慮してください。
• 本質的な変動性と偶発的な変動性を区別してください。 コミット頻度が高いのは、ドメインの変動性ではなく、設計の不備（偶発的な変動性）を示している可能性があります。ビジネスドメインの観点から変動性を評価してください。
• 何でもかんでも指摘しないでください。 アンバランスかつ変動性の高い統合に焦点を当ててください。軽微な問題を 30 件指摘するレビューより、明確な説明を添えて重大な問題を 5 件特定するレビューのほうが有用です。
• すべての問題をモデルに基づいて説明してください。 その統合に問題がある理由となる、具体的な結合の次元、強度レベル、またはバランスルールの原則を示してください。
• 「とにかくすべてを疎結合にする」と提案してはいけません。 分解すると距離が大きくなります。強度が、増加する距離に対応できるほどすでに低い場合、またはライフサイクルの結合が主なボトルネックである場合にのみ提案してください。
• 組織的な側面も考慮してください。 コード構造が同じでもチームが異なれば、実質的な距離は大きくなります。チームの責任範囲が分析に影響する場合は、チームの担当について確認してください。