improve-codebase-architecture

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

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

このスキルは、プロジェクトのドメインモデルを_踏まえて_おり、共有された設計語彙に基づいています。

• /codebase-design スキルを実行し、アーキテクチャの語彙（module、interface、depth、seam、adapter、leverage、locality）とその原則（deletion test、「interface は test surface」、「adapter が 1 つなら seam は仮説、2 つなら実在」）を確認してください。すべての提案でこれらの用語をそのまま使い、「component」、「service」、「API」、「boundary」などに置き換えないでください。
• CONTEXT.md のドメイン用語は、優れた seam に名前を付けています。docs/adr/ の ADR には、このスキルで再検討すべきでない決定が記録されています。

プロセス

1. 調査する

走査する前に範囲を定めます — YAGNI。 モジュールを深める価値があるのは、今後の変更が容易になる場合です。そのため、最近変更されたコードベースの領域を特に重視してください。まず、どこを見るかを決めてから調査します。

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

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

次にサブエージェントを起動し、コードベースを調査させます。厳格なヒューリスティックには従わず、自然に調査して、摩擦を感じる箇所に注目してください。

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

shallow だと思われるものには、deletion test を適用してください。削除すると複雑さが集約されますか。それとも、複雑さが移動するだけですか？「はい、集約される」が、求めるべき兆候です。

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

システムの temp ディレクトリに自己完結型の HTML ファイルを書き込み、リポジトリにファイルが残らないようにします。$TMPDIR から temp ディレクトリを解決し、設定されていない場合は /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 を使います。各候補に 変更前／変更後の可視化を用意します。視覚的に表現してください。

候補ごとに、次の内容を含むカードを表示します。

• Files — 関連するファイル／モジュール
• Problem — 現在のアーキテクチャで摩擦が生じている理由
• Solution — 変更内容を平易な言葉で説明
• Benefits — 局所性とレバレッジの観点から説明し、テストがどう改善するかも示す
• Before / After diagram — 浅いモジュールと深いモジュールへの深化を示す、カスタム作成の左右並列図
• Recommendation strength — Strong、Worth exploring、Speculative のいずれかをバッジとして表示

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

ドメインには CONTEXT.md の用語を、アーキテクチャには /codebase-design の用語を使ってください。 CONTEXT.md で「Order」と定義されているなら、「FooBarHandler」や「Order service」ではなく、「Order のインテークモジュール」と表現してください。

ADR との競合：候補が既存の ADR に反する場合、ADR を再検討するだけの十分な摩擦が実際にあるときに限り、そのことを明示します。カード内ではっきり示してください（例：警告のコールアウトで 「ADR-0007 に反しますが、…のため再検討する価値があります」 と記載）。ADR が禁止する理論上のリファクタリングをすべて列挙しないでください。

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

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

3. 質疑応答のループ

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

決定が固まるごとに副作用をその場で反映します。進行に合わせてドメインモデルを最新の状態に保つため、/domain-modeling スキルを実行します。

• CONTEXT.md にない概念を使って深いモジュールに名前を付ける場合：その用語を CONTEXT.md に追加します。存在しない場合は、必要になった時点でファイルを作成します。
• 会話中に曖昧な用語の意味を明確にした場合：その場で CONTEXT.md を更新します。
• ユーザーが重要な理由を挙げて候補を却下した場合：ADR に記録することを提案します。「今後のアーキテクチャレビューで同じ案が再提案されないよう、これを ADR に記録しますか？」という形で尋ねてください。その理由が、将来の検討者が同じ案を再提案しないようにするうえで本当に必要な場合に限って提案します。一時的な理由（「今はその価値がない」など）や自明な理由は省きます。
• 深いモジュールの別のインターフェースを検討したい場合：/codebase-design スキルを実行し、その並列サブエージェントによる「2 通りで設計する」パターンを使います。