improve-codebase-architecture

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

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

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

• アーキテクチャ用語（モジュール、インターフェース、深さ、継ぎ目、アダプター、レバレッジ、局所性）とその原則（削除テスト、「インターフェースがテスト対象の表面」、「アダプターが1つなら仮説上の継ぎ目、2つなら実際の継ぎ目」）については、/codebase-design スキルを実行してください。すべての提案でこれらの用語を正確に使い、「コンポーネント」、「サービス」、「API」、「境界」などに言い換えないでください。
• CONTEXT.md のドメイン用語は適切な継ぎ目に名前を与え、docs/adr/ の ADR は、このコマンドで再検討すべきではない決定を記録しています。

プロセス

1. 調査

スキャンの前に範囲を定めます — YAGNI。 モジュールを深化させることで、将来の変更が容易になります。そのため、コードベースのうち最近変更された部分をより重視してください。調査する場所を先に決めます。

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

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

次に、サブエージェントを起動してコードベースを調査させます。固定的なヒューリスティックに従うのではなく、自然に調査し、摩擦を感じる箇所を書き留めます。

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

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

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 のいずれかをバッジとして表示

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

ドメインについては CONTEXT.md の用語を、アーキテクチャについては /codebase-design の用語を使います。CONTEXT.md で「Order」と定義されている場合は、「FooBarHandler」や「Order service」ではなく、「Order 受付モジュール」と表現します。

ADR との競合：候補が既存の ADR に反する場合、ADR を見直すほど実際の摩擦がある場合に限り、候補として提示します。カード内では明確に示してください（例：警告コールアウトで 「ADR-0007 と矛盾しますが、…のため再検討する価値があります」）。ADR が禁じている理論上のリファクタリングをすべて列挙しないでください。

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

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

3. 掘り下げのループ

ユーザーが候補を選んだら、/grilling スキルを実行し、制約、依存関係、深めたモジュールの形、境界の内側に置くもの、維持されるテストについて、決定木に沿ってユーザーと検討します。

決定が固まるのに合わせて、副作用をその場で反映します。進行中にドメインモデルを最新に保つため、/domain-modeling スキルを実行します。

• CONTEXT.md にない概念にちなんで、深めたモジュールに名前を付ける場合：その用語を CONTEXT.md に追加します。ファイルが存在しない場合は、必要になった時点で作成します。
• 会話中に曖昧な用語を明確化する場合：その場で CONTEXT.md を更新します。
• ユーザーが重要な理由を挙げて候補を却下した場合：ADR に記録するか提案します。「今後のアーキテクチャレビューで同じ提案が再び出ないよう、これを ADR に記録しますか？」という形で尋ねてください。将来の検討者が同じ提案を繰り返さないために実際に必要となる理由がある場合に限り、提案します。一時的な理由（「今はそこまでの価値がない」など）や自明な理由の場合は提案しないでください。
• 深めたモジュールの代替インターフェースを検討したい場合：/codebase-design スキルを実行し、並列サブエージェントを使って複数の設計案を検討するパターンを使います。