improve-codebase-architecture

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

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

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

• Skill ツールを呼び出して「codebase-design」を使用し、アーキテクチャの語彙（module、interface、depth、seam、adapter、leverage、locality）と原則（削除テスト、「インターフェースがテスト対象の境界である」、「アダプターが1つなら仮説上の seam、2つなら実際の seam」）を確認してください。すべての提案でこれらの用語をそのまま使用し、「コンポーネント」、「サービス」、「API」、「境界」などに言い換えないでください。
• CONTEXT.md のドメイン用語は適切な seam に名前を与え、docs/adr/ の ADR には、このコマンドで再検討すべきではない決定が記録されています。

プロセス

1. 調査

スキャンする前に対象を絞ります――YAGNIです。 モジュールを深くすることで、将来の変更が容易になります。そのため、最近変更されたコードベースの箇所を重視してください。調査を始める前に、どこを見るか決めます。

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

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

次に、サブエージェントを起動してコードベースを調査させます。固定的なヒューリスティックには従わず、実際に感じた摩擦に注目しながら、自然な形で調査してください。

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

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

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

自己完結型の HTML ファイルを OS の一時ディレクトリに書き込み、リポジトリに何も残らないようにします。一時ディレクトリは $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 intake module」と表現してください。

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

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

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

3. 詳細な検討のループ

ユーザーが候補を選んだら、Skill ツールに「grilling」を指定して呼び出し、制約、依存関係、深めるモジュールの形、シームの背後に置くもの、維持されるテストについて、ユーザーと一緒に意思決定ツリーをたどります。

意思決定が固まるにつれて、副作用はその場で反映します。Skill ツールに「domain-modeling」を指定して呼び出し、ドメインモデルを最新の状態に保ちます。

• CONTEXT.md にない概念の名前を、深めるモジュールに付けますか？ その用語を CONTEXT.md に追加します。ファイルが存在しない場合は、必要になった時点で作成します。
• 会話の中で曖昧な用語を明確にしますか？ その場で CONTEXT.md を更新します。
• ユーザーが、判断の根拠となる理由を挙げて候補を却下しますか？ ADR として記録するか提案します。次のように尋ねてください：「今後のアーキテクチャレビューで同じ提案が再び出ないよう、この内容を ADR として記録しますか？」将来の検討者が同じ提案を繰り返さないために、その理由を知る必要がある場合に限り提案します。「今は取り組む価値がない」といった一時的な理由や、自明な理由の場合は提案しません。
• 深めるモジュールの代替インターフェースを検討しますか？ Skill ツールに「codebase-design」を指定して呼び出し、design-it-twice の並列サブエージェントパターンを使います。