improve-codebase-architecture

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

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

このコマンドは、プロジェクトのドメインモデルから_情報を得ており_、共通の設計用語に基づいています。

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

プロセス

1. 調査する

スキャンする前に範囲を定めます。YAGNI。 モジュールを深めることで、今後そのモジュールを変更しやすくなります。そのため、最近変更されたコードベースの領域をより重視してください。調査する場所を、調べ始める前に決めます。

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

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

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

• ある概念を理解するために、多数の小さなモジュールを行き来する必要があるのはどこですか？
• インターフェースが実装とほぼ同じくらい複雑な、浅いモジュールはどこですか？
• テストしやすくするためだけに純粋関数が切り出されているものの、実際のバグは呼び出し方に潜んでいる箇所（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 の受付モジュール」と表現します。

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" を指定して呼び出し、その「2 回設計する」並列サブエージェントのパターンを使います。