improve-codebase-architecture

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

アーキテクチャ上の摩擦を明らかにし、深さを増す機会を提案します。つまり、浅い module を深い module に変えるリファクタリングです。目的は、テストしやすさと AI によるコードベースの把握しやすさです。

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

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

プロセス

1. 調査する

スキャンする前に範囲を定めます。YAGNI。 module を深くすることで、その module への今後の変更が容易になります。そのため、最近変更されたコードベースの領域に重点を置きます。調査する場所は、調査を始める前に決めてください。

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

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

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

• ある概念を理解するために、小さな module の間を何度も行き来する必要があるのはどこですか？
• interface が実装とほぼ同じくらい複雑な、浅い module はどこですか？
• テストしやすくするためだけに純粋関数が切り出されているものの、実際のバグがその呼び出し方に潜んでいる（locality がない）のはどこですか？
• 密結合した module が 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 回行う並列サブエージェントのパターンを使います。