improve-codebase-architecture

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

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

用語集

提案では、以下の用語を必ずそのまま使ってください。一貫した用語を使うことが重要です。「コンポーネント」「サービス」「API」「境界」などに言い換えないでください。定義の全文は LANGUAGE.md を参照してください。

• モジュール - インターフェースと実装を持つものすべて（関数、クラス、パッケージ、スライス）。
• インターフェース - モジュールを使うために呼び出し側が知っておく必要があるすべてのこと（型、不変条件、エラーの種類、順序、設定）。型シグネチャだけではありません。
• 実装 - モジュールの内部にあるコード。
• 深さ - インターフェースがもたらすレバレッジ。小さなインターフェースの背後に多くの振る舞いがある状態です。深い = 高いレバレッジ。浅い = インターフェースが実装とほぼ同じくらい複雑な状態。
• シーム - インターフェースが存在する場所であり、その場で編集せずに振る舞いを変更できる場所です。（「境界」ではなく、こちらを使ってください。）
• アダプター - シームにあるインターフェースを満たす具体的なもの。
• レバレッジ - 深さによって呼び出し側が得られるもの。
• 局所性 - 深さによって保守担当者が得られるもの。変更、バグ、知識が一か所に集約されます。

主な原則（一覧は LANGUAGE.md を参照してください）：

• 削除テスト：モジュールを削除したと想像してください。複雑さがなくなるなら、そのモジュールは処理をそのまま通していただけです。複雑さが N 個の呼び出し側に再び現れるなら、そのモジュールには存在意義がありました。
• インターフェースがテスト対象です。
• アダプターが 1 つなら仮説上のシーム、2 つなら実在するシームです。

このスキルは、プロジェクトのドメインモデルから_示唆を得て_います。ドメイン言語は優れたシームに名前を与え、ADR はこのスキルが再検討すべきでない判断を記録します。

プロセス

1. 調査する

スキャンする前に対象範囲を定めてください — YAGNI。 モジュールを深める価値は、今後の変更を容易にすることにあります。そのため、誰も触らないコードを深める機会は、恩恵を得ることのないリファクタリングです。調査する場所を、調査を始める前に決めてください。

• ユーザーが対象を指定している場合（モジュール、サブシステム、問題点など）は、その指定に従い、以下の推測は省略してください。
• それ以外の場合は、直近の約 20 件のコミット（git log --oneline -20 --name-only）を読み返して、繰り返し変更されているファイルや領域といったホットスポットを特定し、まずそのパスに注目してください。変更が分散していて明確なホットスポットがない場合は、調査範囲を広げてください。

まず、プロジェクトのドメイン用語集と、対象領域の 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 の用語を、アーキテクチャについては LANGUAGE.md の用語を使います。CONTEXT.md で「Order」と定義されている場合は、「FooBarHandler」でも「Order サービス」でもなく、「Order intake モジュール」と表現します。

ADR との競合：候補が既存の ADR と矛盾する場合、その摩擦が ADR を再検討するほど深刻な場合に限って提示します。カード内では明確に示します（例：警告の吹き出しで「ADR-0007 と矛盾しますが、次の理由から再検討する価値があります……」）。ADR で禁じられている、理論上可能なリファクタリングをすべて列挙しないでください。

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

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

3. 掘り下げのループ

ユーザーが候補を選んだら、掘り下げる対話を始めます。制約、依存関係、深めるモジュールの形、シームの背後に置くもの、残すテストについて、決定木に沿って一緒に検討します。

決定が固まるたびに、その場で副作用を反映します。

• CONTEXT.md にない概念を、深めるモジュールの名前に使う場合：その用語を CONTEXT.md に追加します。/grill-with-docs と同じ規律に従います。ファイルが存在しない場合は、必要になるまで作成しません。
• 対話中に曖昧な用語を明確にした場合：その場で CONTEXT.md を更新します。
• ユーザーが、重要な理由を示して候補を却下した場合：ADR として記録するか尋ねます。「今後のアーキテクチャレビューで同じ提案が繰り返されないよう、ADR として記録しますか？」と提案します。同じ提案を再び出さないために、今後の検討者がその理由を知っておく必要がある場合に限って提案します。一時的な理由（「今はそこまでの価値がない」）や自明な理由の場合は提案しません。ADR-FORMAT.md を参照してください。
• 深めるモジュールの代替インターフェースを検討する場合：INTERFACE-DESIGN.md を参照してください。