improve-codebase-architecture

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

コードベースをスキャンして、深める機会を見つけ、ビジュアルな HTML レポートとして提示し、選んだ候補について詳しく掘り下げます。候補を選ぶ前に、アーキテクチャ改善の候補を洗い出したい場合に使用します。次の要望をきっかけに実行します：アーキテクチャを改善したい、深める機会を見つけたい、どこをリファクタリングすべきか知りたい。

このスキルは mattpocock/skills（MIT）からインポートされており、上流ではユーザーが呼び出すスキルです。

このスキルを使用するタイミング

• コードベースをスキャンして、深める機会を見つけ、ビジュアルな HTML レポートとして提示し、選んだ候補について詳しく掘り下げます。
• 候補を選ぶ前に、アーキテクチャ改善の候補を洗い出したい場合に使用します。
• 次の要望をきっかけに実行します：アーキテクチャを改善したい、深める機会を見つけたい、どこをリファクタリングすべきか知りたい。

手順

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

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

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

• Skill ツールを「codebase-design」という名前で呼び出し、アーキテクチャの語彙（モジュール、インターフェース、深さ、継ぎ目、アダプター、レバレッジ、局所性）と、その原則（削除テスト、「インターフェースがテスト面である」、「アダプターが1つなら仮説上の継ぎ目、2つなら実際の継ぎ目」）を確認してください。提案ではこれらの用語を正確に使い、「コンポーネント」、「サービス」、「API」、「境界」へと逸脱しないでください。
• CONTEXT.md のドメイン用語は適切な継ぎ目に名前を与え、docs/adr/ の ADR には、このコマンドで再検討すべきでない決定が記録されています。

プロセス

1. 調査する

スキャンする前に対象を定めてください：YAGNI。 モジュールを深めると、そのモジュールへの今後の変更が容易になります。そのため、最近変更されたコードベースの部分を特に重視してください。調査する前に、どこを見るかを決めます。

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

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

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

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

浅いと思われるものには、削除テストを適用してください。それを削除すると複雑さが集中するでしょうか。それとも、複雑さが移動するだけでしょうか。「はい、集中する」が望ましい兆候です。

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 サービス」ではなく、「Order の受付モジュール」と表現してください。

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

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

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

3. 深掘りループ

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

意思決定が固まるたびに副作用を伴う作業をその場で行います。進行中もドメインモデルを最新に保つため、Skill ツールで「domain-modeling」を呼び出します。

• CONTEXT.md にない概念にちなんで深めたモジュールに名前を付ける場合： その用語を CONTEXT.md に追加します。ファイルがなければ、必要になった時点で作成します。
• 会話中に曖昧な用語を明確化する場合： その場で CONTEXT.md を更新します。
• ユーザーが、重要な理由を挙げて候補を却下する場合： ADR の作成を提案し、次のように尋ねます。「今後のアーキテクチャレビューで同じ案が再提案されないよう、これを ADR に記録しますか？」 将来の検討者が同じ案を再提案しないために実際に必要となる理由がある場合に限って提案してください。「今は取り組む価値がない」といった一時的な理由や、説明不要な理由の場合は提案しません。
• 深めたモジュールの別のインターフェースを検討する場合： Skill ツールで「codebase-design」を呼び出し、その design-it-twice 並列サブエージェントパターンを使用します。

例

• まず狭い範囲でこのスキルを適用し、出力が上記の形に合っていることを確認してから、タスク全体に広げます。
• 手順の途中でリポジトリや環境について事実を確認する必要がある場合は、ユーザーに尋ねるのではなく調べます。

ベストプラクティス

• 元の手順をそのまま維持し、変更があれば黙って独自に対応せず、明示的に記録します。
• このスキルがユーザー自身の判断として定めている各決定ポイントでは、作業を止めてユーザーに判断を委ねます。
• 小さく、元に戻せる変更を優先し、前提を隠さずに明示します。

参考資料

• 上流のスキル：mattpocock/skills skills/engineering/improve-codebase-architecture/SKILL.md（コミット 3cca18b、MIT）
• 関連ドキュメント：references/HTML-REPORT.md
• プロジェクト標準：.agent-skills/skill-standardization/SKILL.md
• バリデータースクリプト：.agent-skills/skill-standardization/scripts/validate_skill.sh