deep-codebase-audit

深いコードベース監査

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

このスキルの参考資料は references/ フォルダーにあります。

• GLOSSARY.md — 提案で使用する用語
• DEPTH-GUIDE.md — 依存関係の分類と、継ぎ目をまたいだテストの方法
• INTERFACES.md — 代替インターフェースの検討方法

使用するタイミング

次のような場合に、このスキルを使用してください。

• ユーザーが、コードベースが雑然としている、変更しづらい、または「AI に対応できる状態ではない」と言っている場合。
• テスト容易性を高め、今後の TDD や自律型エージェントの作業をより効果的にしたい場合。
• AI 主導の変更に多大な投資をする前に、まずリスクを減らしたい場合。

ユーザーが小さな機能をリリースしたいだけの場合は、このスキルを使用しないでください。代わりに /incremental-tdd を使用してください。

用語集

すべての提案で、以下の用語をそのまま使用してください。用語を統一することが目的です。「コンポーネント」、「サービス」、「API」、「境界」などに置き換えないでください。定義の全文は GLOSSARY.md を参照してください。

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

主な原則（全リストは GLOSSARY.md を参照してください）。

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

プロセス

0. まずコンテキストを読む

何かを調べる前に、プロジェクトに次のものがあるか確認してください。

• ドメイン用語集（CONTEXT.md、docs/glossary.md など）がある場合は、それを読み、モジュールや継ぎ目に名前を付ける際にその語彙を使用します。
• アーキテクチャ決定記録（docs/adr/ など）がある場合は、調査する領域を制約する、または判断材料となる決定事項を確認します。

どちらもない場合は、それらを作成せずに先へ進んでください。

1. 調査する

subagent_type=Explore を指定して Agent ツールを使い、コードベースを自然にたどってください。固定のチェックリストに従うのではなく、自然な入り口（メインアプリ、最上位のルート、CLI コマンド、またはユーザーが指定した領域）から調査し、次のような摩擦を感じる箇所を記録してください。

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

浅いと思われるものには、削除テストを適用してください。それを削除すると、呼び出し側に複雑さが集約されるでしょうか。それとも単に複雑さがなくなるだけでしょうか。「はい、集約される」という答えが、求めている兆候です。

最初にユーザーへ、この状況で「より良いアーキテクチャ」が何を意味するのかを尋ねてください。AI による変更のしやすさ、テストの改善、認知負荷の軽減、回帰の減少などです。また、期間、技術スタック、チームの経験など、どのような制約があるかも尋ねてください。それらを調査の指針にしてください。

2. 候補を提示する

深掘りの機会を番号付きリストで提示します。候補ごとに、次の項目を記載します。

• ファイル — 関連するファイル／モジュール
• 問題 — 現在のアーキテクチャが摩擦を生んでいる理由
• 解決策 — 何を変更するのかを平易な言葉で説明します
• メリット — 局所性とレバレッジの観点、およびテストがどう改善されるかを説明します

名称にはプロジェクトのドメイン用語を使います（例：CONTEXT.md で「Order」が定義されている場合は「Order intake モジュール」）。アーキテクチャの用語には GLOSSARY.md の語彙を使います（「service」「boundary」「API」ではなく、module、seam、depth、leverage を使います）。

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

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

3. 掘り下げのやり取り

ユーザーが候補を選んだら、掘り下げの対話に入ります。制約、依存関係、深くしたモジュールの形、seam の背後に置くもの、維持されるテストについて、ユーザーと一緒に設計を検討します。

決定が固まるにつれて、関連する更新もその場で行います。

• ドメイン用語集にない概念を深くしたモジュールの名前にする場合：その用語を CONTEXT.md に追加します（ファイルがなければ、その場で作成します）。
• 対話の途中で曖昧な用語を明確にした場合：その場で CONTEXT.md を更新します。
• ユーザーが重要な理由を挙げて候補を却下した場合：ADR として記録するか尋ねます。「今はそこまで重要ではない」や自明な理由の場合は提案しません。「今後のアーキテクチャレビューで同じ提案が繰り返されないよう、記録しておきますか？」
• 深くしたモジュールの代替インターフェースを検討する場合：INTERFACES.md を参照してください。

依存関係の分類と seam をまたぐテスト戦略については、DEPTH-GUIDE.md を参照してください。

動作とルール

1. 解決策を提案する前に、まず現状を描写します。 解決策に飛びつく前に、コードベースを扱う際の感触を説明する時間を取ります。
2. レバレッジを優先します。 小さな調整ではなく、今後の多くの変更を容易にする変更に重点を置きます。
3. 深いモジュールの観点で考えます。 ロジックがあちこちに散らばっているのを見つけたら、「これを担う深いモジュールは何か」と考えます。
4. 制約を尊重します。 ユーザーが短時間でできる改善だけを望んでいる場合は、それに合わせて提案を調整します。
5. フレームワークの教条主義を避けます。 既存の言語やフレームワークの慣用的な方法を使い、新たなアーキテクチャの流行に合わせてプロジェクトを作り直さないでください。
6. 人とエージェントの両方に向けて書きます。 説明と提案は、人間のエンジニアにも、レポートを読む将来の AI エージェントにも理解できるものにします。
7. 定められた語彙を使います。 すべての提案で GLOSSARY.md の用語を使います。「component」「service」「API」「boundary」に置き換えないでください。

例

ユーザー： 「この TypeScript バックエンドは、どこを見ればいいのか分からず、テストも難しいです。AI にとって扱いやすくしてください。」

あなた（大まかな流れ）：

1. CONTEXT.md と ADR があるか確認します。存在する場合は読みます。
2. 「AI にとって扱いやすい」とは何を意味するのか（例：自律的な変更をより安全にする、リグレッションを減らす）と、制約があるかを尋ねます。
3. 主なエントリーポイントから調べ、主要なモジュールを整理し、浅く散在するロジックに注目します。候補には削除テストを適用します。
4. ファイル、問題、解決策、メリットを含めて、深掘りの候補を 3～5 件、番号付きで提示します。
5. どの候補を検討するか尋ねます。その候補について掘り下げの対話に入ります。
6. 設計が固まったら、INTERFACES.md を参照し、並行してインターフェースを検討します。
7. 次に使えるスキルとして、大規模なアーキテクチャ施策には /incremental-tdd、/spec-writer、/slice-the-spec を提案します。