improve-codebase-architecture

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

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

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

• アーキテクチャ用語（モジュール、インターフェース、深さ、シーム、アダプター、レバレッジ、局所性）と原則（削除テスト、「インターフェースがテスト対象」、「アダプターが1つなら仮説上のシーム、2つなら実際のシーム」）を確認するために、「codebase-design」スキルを読み込みます（SKILL.mdを読みます）。すべての提案でこれらの用語を正確に使い、「コンポーネント」、「サービス」、「API」、「境界」に話を逸らさないでください。
• GLOSSARY.md のドメイン用語は、優れたシームに名前を与えます。docs/adr/ のADRには、このコマンドで再検討すべきでない決定が記録されています。

プロセス

1. 調査する

スキャンする前に対象を絞る：YAGNI。 モジュールを深くすることで、将来の変更が容易になります。そのため、最近変更されたコードベースの箇所を重視します。調査を始める前に、どこを見るかを決めてください。

• ユーザーが方向性（モジュール、サブシステム、問題点）を指定した場合は、それに従い、以下の推定手順は省略します。
• 指定がない場合は、コミット履歴をかなり遡って（git log --oneline）、頻繁に変更されているコードベースの注目箇所やファイルを探し、まずそれらのパスに注目します。変更が広範囲に分散していて明確な注目箇所がない場合は、調査対象を広げます。

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

次に、新しいコンテキストウィンドウを持つサブエージェントを起動し、コードベースを調査させます。画一的なヒューリスティックには従わず、自然に調査しながら、摩擦を感じた箇所を記録します。

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

浅いと思われるものには、削除テストを適用します。それを削除すると複雑さが集約されますか、それとも単に別の場所へ移るだけですか？「はい、集約されます」が求めるシグナルです。

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

レポートの言語は、ユーザーとの会話に合わせます。 ユーザーが使用している言語でレポートを作成します（英語で話している場合は英語、中国語で話している場合は中国語など）。アーキテクチャ用語は、初出時に英語表記を残し、その後にレポートの言語での訳を括弧書きで添えます（例：locality（局所性））。以降は、より自然に読める表記を使用します。サブエージェントによる調査メモも、同じ言語に従います。

リポジトリに何も書き込まれないよう、OS の一時ディレクトリに自己完結型の HTML ファイルを作成します。一時ディレクトリを明示的に解決し（Windows では $env:TEMP、Linux／WSL／macOS では $TMPDIR、なければ /tmp）、<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 のいずれかをバッジとして表示

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

ドメインには GLOSSARY.md の用語を、アーキテクチャには /codebase-design の用語を使用してください。 GLOSSARY.md で「Order」が定義されている場合は、「FooBarHandler」や「Order service」ではなく、「Order intake module」と表現してください。

ADR との矛盾：候補が既存の ADR と矛盾する場合は、その ADR を見直すほどの現実的な摩擦がある場合に限り、候補として取り上げます。カード内では明確に示してください（例：警告コールアウトで 「ADR-0007 と矛盾しますが、見直す価値がある理由は……」 と記載）。ADR が禁じる理論上のリファクタリングをすべて列挙してはいけません。

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

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

3. 質問を重ねるプロセス

ユーザーが候補を選んだら、「grilling」スキルを読み込み（SKILL.md を読む）、意思決定ツリーに沿ってユーザーと検討します。制約、依存関係、深めるモジュールの形、シームの背後に置くもの、残すテストについて話し合います。

判断が固まるたびに、その場で副作用を反映します。進めながらドメインモデルを最新の状態に保つため、「domain-modeling」スキルを読み込み（SKILL.md を読む）、以下のように対応します。

• GLOSSARY.md にない概念にちなんで、深めるモジュールに名前を付ける場合：その用語を GLOSSARY.md に追加します。ファイルが存在しない場合は、必要になった時点で作成します。
• 会話中に曖昧な用語の意味が明確になった場合：その場で GLOSSARY.md を更新します。
• ユーザーが、根本的な理由を挙げて候補を却下した場合：ADR に記録することを提案し、次のように尋ねます。「今後のアーキテクチャレビューで同じ案が再提案されないよう、この内容を ADR に記録しますか？」 将来の検討者が同じ案を再提案しないために、その理由を知っておく必要がある場合に限って提案します。「今はその価値がない」といった一時的な理由や、誰にとっても明白な理由は対象外です。
• 深めるモジュールの代替インターフェースを検討したい場合：「codebase-design」スキルを読み込み（SKILL.md を読む）、その「design-it-twice」並列サブエージェントのパターンを使用します。