improve-codebase-architecture

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

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

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

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

プロセス

1. 調査する

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

次に、Agent ツールで subagent_type=Explore を使ってコードベースを調査します。固定的なヒューリスティックに従うのではなく、自由に調査し、摩擦を感じた箇所に注目します。

• 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 intake module」と呼んでください。

ADR との競合：候補が既存の ADR と矛盾する場合、ADR を見直す価値があるほど実際の摩擦が大きいときに限り、その候補を提示します。カード内には明確に記載してください（例：警告コールアウトで "contradicts ADR-0007 — but worth reopening because…"）。ADR で禁じられている理論上のリファクタリングをすべて列挙しないでください。

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

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

3. グリリングのループ

ユーザーが候補を選んだら、/grilling スキルを実行して、制約、依存関係、深めたモジュールの形、シームの背後にあるもの、残すテストについて、ユーザーと一緒に設計ツリーをたどります。

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

• CONTEXT.md にない概念で、深めたモジュールに名前を付ける場合：その用語を CONTEXT.md に追加します。存在しない場合は、必要になった時点でファイルを作成します。
• 会話中に曖昧な用語を明確にする場合：その場で CONTEXT.md を更新します。
• ユーザーが、設計上重要な理由を添えて候補を却下した場合：ADR として記録するか尋ねます。「今は優先度が低い」といった一時的な理由や、自明な理由は除き、今後の検討者が同じ提案を繰り返さないために本当に必要な場合に限ります。問いかけは次のようにします："今後のアーキテクチャレビューで同じ提案が繰り返されないよう、これを ADR として記録しますか？"
• 深めたモジュールの代替インターフェースを検討する場合：/codebase-design スキルを実行し、その「2 回設計する」並列サブエージェントのパターンを使います。