improve-codebase-architecture

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

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

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

• Skill ツールを呼び出して「codebase-design」を指定し、アーキテクチャの用語（module、interface、depth、seam、adapter、leverage、locality）と原則（削除テスト、「インターフェースがテスト対象である」、「adapter が 1 つなら仮定上の seam、2 つなら実際の seam」）を確認してください。すべての提案でこれらの用語をそのまま使い、「component」、「service」、「API」、「boundary」には置き換えないでください。
• GLOSSARY.md のドメイン用語は、優れた seam に名前を付けています。docs/adr/ の ADR には、このコマンドで再検討すべきではない決定が記録されています。

プロセス

1. 調査する

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

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

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

次に、新しいコンテキストウィンドウを使うサブエージェントを起動し、コードベースを調査させます。決まりきった経験則に従うのではなく、自然に探索し、摩擦を感じた箇所を記録してください。

• 1 つの概念を理解するために、多数の小さなモジュールを行き来する必要があるのはどこですか？
• 実装とほぼ同じ複雑さの interface を持つ、浅いモジュールはどこですか？
• テスト容易性のためだけに純粋関数を切り出したものの、本当のバグはその呼び出し方に潜んでいる（locality がない）のはどこですか？
• 密結合したモジュールが seam を越えて漏れ出しているのはどこですか？
• テストされていない、または現在の interface を通じたテストが難しいコードベースの部分はどこですか？

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

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

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

ドメインについては 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 に記録しますか？」という形で ADR を提案します。その理由を知らないと、将来の検討者が同じ案を再提案してしまう場合に限って提案してください。「今は価値がない」といった一時的な理由や、自明な理由の場合は提案しません。
• 深めるモジュールの代替インターフェースを検討したい場合：Skill ツールに「codebase-design」を指定して呼び出し、その設計を 2 回行う並列サブエージェントのパターンを使います。