improve-codebase-architecture

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

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

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

• modules.md には、アーキテクチャの語彙（module、interface、depth、seam、adapter、leverage、locality）とその原則（削除テスト、「インターフェースがテスト対象の境界」、「1 つのアダプター = 仮定上の seam、2 つ = 実際の seam」）が記載されています。提案ではこれらの用語を正確に使い、「component」、「service」、「API」、「boundary」へと言い換えないでください。
• 用語集のドメイン用語は適切な seam に名前を与え、意思決定記録には、このコマンドで再検討すべきでない決定が記録されています。

プロセス

1. 調査する

スキャンする前に範囲を定めます。YAGNI。 モジュールを深めるのは、将来の変更を容易にするためです。そのため、最近変更されたコードベースの部分を重視してください。調査を始める前に、どこを見るか決めます。

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

AGENTS.md で参照されている場合は、まずプロジェクトの用語集、対象領域の意思決定記録、規約ファイルを読みます。参照されていないものの該当しそうなファイルがあれば、使用するのではなく、レポートで言及してください。 存在しない場合は、プロジェクトの規約なしで調査し、その旨をレポートに記載してください。

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

• 1 つの概念を理解するために、小さなモジュールをいくつも行き来する必要があるのはどこですか？
• インターフェースが実装とほぼ同じくらい複雑な、浅いモジュールはどこですか？
• テスト容易性のためだけに純粋関数が切り出されているものの、実際のバグはその呼び出し方に潜んでいる（locality がない）箇所はどこですか？
• 密結合したモジュールが seam を越えて漏れ出しているのはどこですか？
• テストされていない箇所、または現在のインターフェース経由ではテストが難しい箇所はどこですか？

浅いと疑われる対象には削除テストを適用してください。それを削除すると複雑さが集中するでしょうか、それとも別の場所へ移るだけでしょうか。「集中する」という答えが、求める兆候です。

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

リポジトリ内の documentation/architecture-audit/ に、自己完結型の HTML ファイルを作成します（ディレクトリがなければ必要になった時点で作成し、作成した場合は最も近い AGENTS.md に、ここがアーキテクチャ監査レポートを格納する場所であることを示す1行を追加します）。ファイル名は architecture-audit-<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 のいずれかをバッジで表示

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

ドメインには用語集の語彙を、アーキテクチャには modules.md の語彙を使用してください。 用語集で「Order」と定義されている場合は、「FooBarHandler」や「Order service」ではなく、「Order intake module」とします。

意思決定記録との不一致：候補が既存の意思決定記録と矛盾する場合、記録を見直すほど実際の摩擦があるときに限り提示します。カード内で明確に示します（例：警告の吹き出し 「意思決定記録 0007 と矛盾しますが、…のため見直す価値があります」）。意思決定記録で禁じられている理論上のリファクタリングをすべて列挙しないでください。

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

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

3. 改良の反復

ユーザーが候補を選んだら、interview method に従って、制約、依存関係、深めたモジュールの形、境界の背後に置くもの、残すテストについて、意思決定ツリーをユーザーと一緒にたどります。

意思決定が固まるたびに、副作用となる作業をその場で行います。

• 用語集にない概念を深めたモジュールの名前に使う場合、または用語が曖昧だと判明した場合：その場で整理します。用語の衝突を明示し、具体的なシナリオで検証し、標準用語を推奨します。ユーザーの同意を得たら、glossary-format.md に従って用語集に追加します。
• ユーザーが、重要な理由を挙げて候補を却下した場合：「今後のアーキテクチャレビューで同じ提案が再び出ないよう、これを意思決定記録に残しますか？」 と尋ね、意思決定記録の作成を提案します。同意が得られたら、decision-record-format.md に従って作成します。将来の検討者が同じ提案を繰り返さないために実際に必要となる理由がある場合に限って提案してください。「今は価値がない」といった一時的な理由や、自明な理由は対象外です。
• 深めたモジュールの代替インターフェースを検討したい場合：design-it-twice.md の並列サブエージェントパターンを使用します。
• 依存関係を踏まえてクラスターを深める場合：依存関係のカテゴリ、境界の規律、テストについて deepening.md に従います。