improve-codebase-architecture

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

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

このコマンドは、プロジェクトのドメインモデルに基づき、共通の設計用語を使います。

• 正確なアーキテクチャ用語（モジュール、インターフェース、深さ、継ぎ目、アダプター、レバレッジ、局所性）と、その原則（削除テスト、「インターフェースがテストの対象面」、「アダプターが 1 つなら仮説上の継ぎ目、2 つなら実際の継ぎ目」）を使います。各提案でこれらの用語を正確に使い、「コンポーネント」、「サービス」、「API」、「境界」に言い換えないでください。
• テストダブルは 2 つ目の実装として数えます。本番用アダプターが 1 つあり、テストで代替するインターフェースは、仮説上の継ぎ目ではなく、実際の継ぎ目です。呼び出し元が 1 つしかなく、代替もないインターフェースだけが、この点で削除テストに不合格となります。（これは /setup-solid が CLAUDE.md に記載する同じルールであり、両者で食い違いがあってはなりません。）
• GLOSSARY.md のドメイン用語は、適切な継ぎ目に名前を与えます。docs/adr/ の ADR には決定事項が記録されているため、このコマンドで再検討してはなりません。

プロセス

1. 調査

調査する前に対象範囲を決めます。YAGNI を守ってください。 モジュールを深める価値は、今後の変更を容易にすることにあります。そのため、最近変更されたコードベースの箇所を重点的に見てください。調査を始める前に、_どこを_見るか決めます。

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

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

次に、サブエージェントを起動してコードベースを調査させます。固定的なヒューリスティックに従うのではなく、柔軟に調査し、どこで摩擦を感じるかを記録します。

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

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

2. 候補を HTML レポートとして提示する

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

レポートのレイアウトとスタイルには CDN 経由の Tailwind を、グラフ／フロー／シーケンスで構造を確実に伝えられる場合の図には CDN 経由の Mermaid を使用します。Mermaid と、手作りの CSS／SVG によるビジュアルを組み合わせます。関係性がグラフ状の場合（呼び出しグラフ、依存関係、シーケンス）は Mermaid を使用し、よりエディトリアルな表現（質量図、断面図、折りたたみアニメーション）には手作りの div／SVG を使用します。各候補に変更前／変更後のビジュアルを用意します。視覚的に表現してください。

候補ごとに、以下を含むカードを表示します。

• ファイル：関係するファイル／モジュール
• 問題：現在のアーキテクチャが摩擦を生んでいる理由
• 解決策：何を変更するかを平易な言葉で説明
• メリット：局所性と効果の観点、およびテストがどう改善されるかを説明
• 変更前／変更後の図：浅さと深さを示す、左右に並べた独自作成の図
• 推奨度：Strong、Worth exploring、Speculative のいずれかをバッジとして表示

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

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

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

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

まだインターフェースを提案しないでください。ファイルを書き込んだ後、ユーザーに「どの候補を検討しますか？」と尋ねてください。

3. 掘り下げのループ

ユーザーが候補を選んだら、Skill ツールで「grilling」を呼び出し、制約、依存関係、深くしたモジュールの形、境界の背後にあるもの、どのテストが維持されるかについて、ユーザーと一緒に判断を進めます。

判断が固まるたびに、副作用をその場で反映します。進行に合わせてドメインモデルを最新の状態に保ちます。

• GLOSSARY.md にない概念の名前を、深くしたモジュールに付ける場合：その用語を GLOSSARY.md に追加します。ファイルが存在しない場合は、必要になった時点で作成します。
• 会話中に曖昧な用語を明確化する場合：その場で GLOSSARY.md を更新します。
• ユーザーが、判断の決め手となる理由から候補を却下した場合：次のように提案し、ADR として記録するか尋ねます。「今後のアーキテクチャレビューで同じ案が再提案されないよう、これを ADR として記録しますか？」 将来の検討者が同じ案を再提案しないために必要となる理由がある場合に限って提案してください。一時的な理由（「今はその価値がない」など）や自明な理由の場合は提案しません。
• 深くしたモジュールの別のインターフェースを検討する場合：2 回設計するアプローチを用います。並行するサブエージェントを起動して代替インターフェースを作成し、比較してください。