improve-codebase-architecture

コードベースのアーキテクチャを改善する

アーキテクチャ上の摩擦を明らかにし、深める機会を提案します。つまり、浅いモジュールを深いモジュールに変えるリファクタリングです。目標はテスト容易性と AI によるナビゲーションのしやすさです。

このコマンドは、プロジェクトのドメインモデルから情報を得て、共有された設計語彙に基づいています。

• Skill ツールを呼び出し、codebase-design を指定して、アーキテクチャの語彙（モジュール、インターフェース、深さ、シーム、アダプター、活用度、局所性）とその原則（削除テスト、「インターフェースがテスト対象の境界である」、「アダプターが 1 つなら仮説上のシーム、2 つなら実際のシーム」）を取得します。提案では、これらの用語を正確に使い、「コンポーネント」、「サービス」、「API」、「境界」などに言い換えないでください。
• GLOSSARY.md のドメイン用語は適切なシームの命名に役立ちます。docs/adr/ の ADR には、このコマンドで再検討すべきでない決定が記録されています。

手順

1. 調査

まずスキャン範囲を絞ります。YAGNI。 モジュールを深める価値は、将来の変更を容易にすることです。そのため、最近も変更が続いているコードベースの領域に注目してください。調査を始める前に、どこを見るかを決めます。

• ユーザーが方向性（モジュール、サブシステム、または問題点）を指定している場合は、その方向を調査し、以下の推論は省略します。
• それ以外の場合は、十分な期間のコミット履歴（git log --oneline）をさかのぼり、繰り返し変更されているファイルや領域を見つけて、そうしたホットスポットを優先的に調査します。変更が広く分散していて、明確なホットスポットがない場合は、範囲を広げます。

まずプロジェクトのドメイン用語集（GLOSSARY.md）と、対象領域の ADR を読みます。

次に、コードベースを調査するサブエージェントを起動します。固定的なヒューリスティックに当てはめず、自然に調査し、摩擦を感じた箇所を記録します。

• 概念を理解するために、多数の小さなモジュール間を行き来する必要がありますか？
• インターフェースが実装とほぼ同じくらい複雑な、浅いモジュールはどれですか？
• テスト容易性のために純粋関数を切り出しているものの、実際のバグはその関数の呼び出し方に潜んでいる箇所はありますか（局所性がない状態）？
• 密結合したモジュールがシームの外側に漏れ出している箇所はありますか？
• テストされていない、または現在のインターフェースを通じてテストするのが難しいコードベースの箇所はどこですか？

浅いと疑われるものには、削除テストを適用します。それを削除すると複雑さが集約されますか、それとも別の場所に移動するだけですか？「はい、集約される」ことが求める兆候です。

2. 候補を HTML レポートで提示する

自己完結型の HTML ファイルを OS の一時ディレクトリに書き込み、リポジトリにファイルが残らないようにします。一時ディレクトリは $TMPDIR から解決し、設定されていない場合は /tmp（Windows では %TEMP%）を使用します。<tmpdir>/architecture-review-<timestamp>.html に書き込み、実行ごとに新しいファイルを作成します。ユーザーが開けるようにします。Linux では xdg-open <path>、macOS では open <path>、Windows では start <path> を使い、絶対パスをユーザーに伝えます。

レポートのレイアウトとスタイルには Tailwind via CDN を、構造を確実に伝えられる図には Mermaid via CDN を使用します。Mermaid と手書きの CSS／SVG ビジュアルは併用できます。関係がグラフ状（呼び出しグラフ、依存関係、シーケンス）なら Mermaid を使い、編集的な表現（マス図、断面図、折りたたみアニメーション）が必要なら手書きの div／SVG を使います。各候補には 変更前／変更後の可視化を含めます。図で視覚化してください。

各候補はカードとして表示し、以下を含めます。

• ファイル - 関係するファイル／モジュール
• 問題 - 現在のアーキテクチャが摩擦を生む理由
• 解決策 - 何が変わるのかを平易な言葉で説明
• メリット - 局所性と活用度の観点から利点を説明し、テストがどう改善されるかも記載
• 変更前／変更後の図 - 並べて表示し、浅さと深める方法を自作の図で示す
• 推奨の強さ - Strong、Worth exploring、Speculative のいずれかをバッジとして表示

レポートの最後に第一候補の推奨セクションを設け、最初に取り組む候補とその理由を示します。

ドメインには GLOSSARY.md の語彙を、アーキテクチャには /codebase-design の語彙を使用してください。 GLOSSARY.md に「Order」が定義されているなら、「FooBarHandler」や「Order service」ではなく、「Order intake module」と呼びます。

ADR との衝突：候補が既存の ADR と衝突する場合、摩擦が実在し、ADR を再検討する価値があるときに限り提案します。カードには明確な印を付けます（たとえば、警告の吹き出しで 「ADR-0007 と矛盾しますが、……のため再検討する価値があります」 と記載します）。理論上 ADR で禁止されているリファクタリングをすべて列挙しないでください。

完全な HTML のひな形、図のパターン、スタイルのガイダンスについては、HTML-REPORT.md を参照してください。

ここではまだインターフェースを提案しないでください。ファイルを書き終えたら、ユーザーに「どれを詳しく検討しますか？」と尋ねます。

3. グリリングの反復

ユーザーが候補を選んだら、Skill ツールを呼び出して grilling を指定し、意思決定ツリーに沿ってユーザーと検討します。制約、依存関係、深めたモジュールの形状、シームの先に配置するもの、維持できるテストを扱います。

決定に応じた副作用をその場で反映し、Skill ツールを呼び出して domain-modeling を指定し、ドメインモデルを最新の状態に保ちます。

• 深めたモジュールの命名に、GLOSSARY.md にない概念が必要ですか？ その用語を GLOSSARY.md に追加します。ファイルが存在しない場合は、必要に応じて作成します。
• 対話の中で曖昧な用語を練り上げましたか？ すぐに GLOSSARY.md を更新します。
• ユーザーが重要な理由を挙げて候補を却下しましたか？ 次のように提案します。「将来のアーキテクチャレビューで同じ提案が再び出ないよう、これを ADR として記録しましょうか？」 今後の調査担当者が同じ提案を避けるために、その理由を本当に必要とする場合に限って提案します。一時的な理由（「今は取り組む価値がない」）や明白な理由の場合は提案しません。
• 深めたモジュールの別のインターフェースを検討しますか？ Skill ツールを呼び出して codebase-design を指定し、その中の「2 つの設計を並行して検討する」サブエージェントパターンを使用します。