improve-codebase-architecture

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

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

このスキルは、共有された設計用語に基づき、プロジェクトのドメインモデルを参考にしています。

• codebase-design スキルでは、アーキテクチャの用語、つまり module、interface、depth、seam、adapter、leverage、locality と、その原則である削除テスト、「インターフェースがテスト対象の境界である」、「アダプターが1つなら仮説上の境界、2つなら実際の境界」を扱います。コードを調べる前にこれを読み、すべての提案でこれらの用語を正確に使ってください。
• CONTEXT.md では適切な境界に名前を付け、docs/adr/ の ADR では、このスキルが再検討すべきでない決定を記録しています。どちらの形式も、grill-me スキルが併せてインストールされている場合は、CONTEXT-FORMAT.md と ADR-FORMAT.md に記載されています。

プロセス

1. 調査する

調査の前に対象範囲を定めます。 モジュールを深化させると、今後そのモジュールを変更しやすくなります。そのため、変更が繰り返されているコードベースの領域を重視します。調査する前に、どこを見るかを決めてください。

• ユーザーが方向性、つまりモジュール、サブシステム、課題を指定した場合は、その対象に取り組み、以下の推測は省略します。
• 指定がない場合は、コードベースのホットスポット、つまり頻繁に変更されているファイルや領域を見つけるため、git log --oneline をかなり遡って確認し、まずそれらのパスに注目します。変更が広範囲に散らばっていて、明確なホットスポットが見つからない場合は、対象を広げます。

まず、その領域に関する既存のドキュメントを読みます。

• CONTEXT.md（または、複数のコンテキストを持つリポジトリの場合は CONTEXT-MAP.md と各 CONTEXT.md）
• docs/adr/ にある関連する ADR（およびコンテキスト単位の docs/adr/ ディレクトリ）

これらのファイルが存在しない場合は、何も言わずに先へ進み、存在しないことを指摘したり、あらかじめ作成を提案したりしないでください。

次に、読み取り専用の探索サブエージェントにコードベースを調査させます（Claude Code では Explore エージェントタイプを使用します）。固定的なヒューリスティックには従わず、柔軟に調査し、摩擦を感じる箇所を記録してください。

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

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

2. 候補を提示する

各候補には、次の内容を含めます。

• ファイル — 関係するファイル／モジュール
• 問題 — 現在のアーキテクチャが摩擦を生んでいる理由
• 解決策 — 何を変更するのかを平易な言葉で説明します
• メリット — 局所性とレバレッジの観点に加え、テストがどう改善するかも説明します
• 推奨度 — Strong、Worth exploring、または Speculative

最後に最優先の推奨案として、最初に取り組む候補とその理由を提示します。

アーキテクチャはグラフ状です。深まりを示す変更前／変更後の図は、段落で説明するよりも強く伝わります。rich-page が利用可能な場合は、候補の一覧を自己完結型の HTML レポートとして作成します。各候補をカードにまとめ、浅さと深まりを示す変更前／変更後の図と、バッジで示す推奨度を含め、リポジトリ外の一時パスに書き出して、ユーザーに開いて提示してください。利用できない場合は、同じ項目をチャットで番号付きリストとして提示します。

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

ADR との矛盾：候補が既存の ADR と矛盾する場合でも、摩擦が ADR の見直しを正当化するほど大きいときに限り、その候補を提示します。その場合は、（例：「ADR-0007 と矛盾しますが、……のため見直す価値があります」）のように明記してください。ADR が禁じている理論上のリファクタリングをすべて列挙しないでください。

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

3. 掘り下げの対話

ユーザーが候補を選んだら、掘り下げの対話に入ります。インストールされている場合は grill-me スキルを使用します。制約、依存関係、深めたモジュールの形、境界の内側に置くもの、維持できるテストについて、ユーザーと一緒に設計ツリーをたどってください。

決定が固まったら、その場で副次的な変更を行います。ubiquitous-language と同じ規律で、ドメインモデルを常に最新の状態に保ってください。

• CONTEXT.md にない概念の名前を、深めたモジュールに付ける場合： その用語を CONTEXT.md に追加します（CONTEXT-FORMAT.md を参照）。ファイルが存在しない場合は、必要になった時点で作成します。
• 対話中に曖昧な用語を明確にする場合： その場で CONTEXT.md を更新します。
• ユーザーが重要な理由を挙げて候補を退けた場合： ADR として記録するか提案します。提案時の文言は、「今後のアーキテクチャレビューで同じ提案が繰り返されないよう、これを ADR に記録しますか？」 とします。将来の検討者が同じ提案を避けるために実際に必要となる理由がある場合に限って提案してください。一時的な理由（「今はそこまでする価値がない」など）や、自明な理由は対象外です。ADR-FORMAT.md を参照してください。
• 深めたモジュールの別のインターフェースを検討する場合： codebase-design の design-it-twice パターンを使用します。

---

mattpocock/skills をもとにしています。MIT © 2026 Matt Pocock。このファイルをコピーする場合は、この行を残してください。