improve-codebase-architecture

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

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

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

• リポジトリ独自の用語を使って、モジュールのインターフェース、実装の複雑さ、動作の境界を特定します。実際の複雑さを、より小さなインターフェースの背後に隠せる機会を優先してください。
• GLOSSARY.md のドメイン用語は適切な境界に名前を与え、docs/adr/ のADRは、このコマンドで再検討すべきでない決定を記録しています。

プロセス

1. 調査する

スキャンする前に範囲を決めましょう。YAGNIです。 モジュールの深化によって、今後そのモジュールを変更しやすくなります。そのため、最近変更されたコードベースの領域を重視してください。調査する場所を、調査を始める前に決めます。

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

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

次に、サブエージェントを起動してコードベースを調査します。決まりきったヒューリスティックに従うのではなく、実際に感じた摩擦に注目しながら、自然に探索してください。

• ある概念を理解するために、多数の小さなモジュールを行き来する必要があるのはどこですか？
• インターフェースが実装とほぼ同じくらい複雑な、浅いモジュールはどこですか？
• テスト容易性のためだけに純粋関数が切り出されているものの、実際のバグはその呼び出し方に潜んでいる（局所性がない）のはどこですか？
• 密結合したモジュールが、その境界を越えて互いの詳細を漏らしているのはどこですか？
• テストされていない領域や、現在のインターフェースを介してテストするのが難しい領域はどこですか？

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

2. 候補を提示する

特に指定がなければ、候補は会話内で Markdown として提示してください。レビューの要点は以下の内容であり、プレーンテキストとしても問題なく読めます。ユーザーから HTML レポートを求められた場合、または候補の構造を理解するのにビフォー／アフターの視覚化が不可欠な場合に限り、自己完結型の HTML レポートを作成してください。

HTML を使う場合は、リポジトリに何も残らないよう、ファイルを OS の一時ディレクトリに書き込んでください。一時ディレクトリは $TMPDIR から取得し、設定されていなければ /tmp（Windows では %TEMP%）を使用します。実行のたびに新しいファイルが作られるよう、<tmpdir>/architecture-review-<timestamp>.html に書き込んでください。ファイルをユーザー向けに開きます。Linux では xdg-open <path>、macOS では open <path>、Windows では start <path> を使い、絶対パスを伝えてください。

HTML レポートでは、レイアウトとスタイルに CDN 経由の Tailwind を使い、グラフ／フロー／シーケンス図で構造を確実に伝えられる場合は、図の作成に CDN 経由の Mermaid を使います。Mermaid と、手作りの CSS／SVG ビジュアルを組み合わせてください。関係性がグラフとして表せる場合（呼び出しグラフ、依存関係、シーケンスなど）は Mermaid を使い、より編集的な表現（マス・ダイアグラム、断面図、折りたたみアニメーションなど）には手作りの div／SVG を使います。各候補にビフォー／アフターの視覚化を含めてください。視覚的に表現してください。どちらの CDN も、オフライン時やスクリプトがブロックされている環境では警告なしに読み込めないため、その環境から CDN にアクセスできない場合は CSS をインライン化し、SVG を手作りしてください。

各候補について、次の項目を説明してください。

• ファイル — 関連するファイル／モジュール
• 問題 — 現在のアーキテクチャが摩擦を生んでいる理由
• 解決策 — 何を変更するかを平易な言葉で説明
• メリット — 局所性と効果の観点から、またテストがどう改善されるかを説明
• ビフォー／アフター — 浅い構造と深めた構造を並べて提示。HTML では独自に描画した図、Markdown では同じ対比を文章で説明
• 推奨の強さ — Strong、Worth exploring、Speculative のいずれかをバッジとして表示

最後に最有力候補のセクションを設け、最初に取り組む候補とその理由を示してください。

ドメイン用語には GLOSSARY.md の用語を使い、アーキテクチャ用語は平易に説明してください。 GLOSSARY.md で「Order」が定義されている場合は、「Order 受付モジュール」と表現し、「FooBarHandler」や「Order サービス」とは呼ばないでください。

ADR との矛盾：候補が既存の ADR と矛盾する場合、その摩擦が ADR の再検討に値するほど大きい場合に限って取り上げてください。カード内では明確に示します（例：警告の吹き出しで 「ADR-0007 と矛盾しますが、…のため再検討する価値があります」 と記載）。ADR が禁じる、理論上あり得るリファクタリングをすべて列挙する必要はありません。

HTML を使う場合の HTML のひな形、図のパターン、スタイルに関するガイダンスは、HTML-REPORT.md を参照してください。

インターフェースはまだ提案しないでください。候補を提示したら、ユーザーに「どの候補を検討しますか？」と尋ねてください。

3. 掘り下げのループ

ユーザーが候補を選んだら、Skill ツールに「grilling」を渡して呼び出し、制約、依存関係、深めたモジュールの形、境界の内側に置くもの、残すテストについて、ユーザーと一緒に判断ツリーを進めてください。

決定が固まるたびに、その場で副作用のある処理を行います。進行に合わせてドメインモデルを最新の状態に保つため、Skill ツールに「domain-modeling」を渡して呼び出してください。

• GLOSSARY.md にない概念にちなんで、深めたモジュールに名前を付ける場合：その用語を GLOSSARY.md に追加します。ファイルが存在しない場合は、必要になった時点で作成します。
• 会話中に曖昧な用語をより明確にする場合：その場で GLOSSARY.md を更新します。
• ユーザーが、判断の根拠となる理由を挙げて候補を退けた場合：次のように尋ね、ADR として記録することを提案します：「今後のアーキテクチャレビューで同じ提案が繰り返されないよう、これを ADR に記録しますか？」将来の検討者が同じ提案を再度しないために、その理由を知る必要がある場合に限って提案してください。「今はその価値がない」といった一時的な理由や、自明な理由の場合は提案しないでください。
• 深めたモジュールの代替インターフェースを検討する場合：そのモジュールに関係するトレードオフを示し、代替インターフェースを直接比較してください。