codebase-improver

コードベースの改善

「問題があると思う」状態から、「問題を把握し、優先順位を付け、修正した」状態まで、エンドツーエンドでコードベースを改善します。すべての判断ポイントで人が主導します。

改善エンジンは、ディープモジュール（John Ousterhout 著、A Philosophy of Software Design）を基盤としています。ディープモジュールとは、大規模な実装を小さなインターフェースの背後に隠すモジュールです。ディープモジュールはテストしやすく、AI がコードを把握しやすいほか、内部ではなく境界でテストできます。Deepen ステージの目標は、浅く密結合したクラスターをディープモジュールに変えることです。

このスキルは自己完結型（Python/TS）です。ワーカーロールはデフォルトでインライン実行され、明示的に許可された場合は委任を使用できます。

Map ──► Audit ──► Deepen (recursive) ──► (next round)
 │        │          │
scan    audit      explore → candidates → design N interfaces
        roles      → RFC → optionally implement → recurse

---

ホスト間の移植性

委任権限がない場合は、すべてのワーカーロールをインラインで順次実行してください。これに AgentTool の呼び出しは一切必要ありません。 異なるワーカーを選択する前に、運用上のデフォルトを適用してください。 インラインのロールが独立している、または並列であると主張しないでください。依頼された結果に不可欠な分離が利用できない場合は、その旨を報告してください。

---

基本原則

1. 自己完結型。 マッピングはインラインで行い、チェックと契約は同梱の references/ にあります。他のスキルは不要です。
2. ブループリントはあれば便利ですが、必須ではありません。 より強い手掛かりとなる BLUEPRINT.md があれば使用し、なければ簡易スキャンと同梱のチェックを頼りにします。
3. 目標はディープモジュールです。 改善とは「深める」こと、つまりインターフェースを小さくし、複雑さを隠し、境界でテストすることです。コードを読んでいて感じる摩擦こそが、シグナルです。
4. ワーカーロールを組み合わせ、権限がある場合に限り委任します。 メインエージェントがワークフローを進行し、結果を集約し、チェックポイントを実行して、状態を伴う判断を担います。依頼されたワーカーはユーザーの委任範囲内で作業します。それ以外の場合、同じロールをインラインで実行します。
5. すべての判断ポイントで人が関与します。 対象範囲、取り組む候補、採用するインターフェース、再帰の有無、コミットやプッシュの可否を決して独断で決めないでください。立ち止まって確認してください。（このスキルは設計上、HITL です。AFK の自動操縦とは異なり、人による判断ポイントの決定をでっち上げることはありません。）
6. 主張より証拠を重視します。 すべての指摘に実在する path:line を記載します。
7. 再帰は上限付きで、ユーザーの許可が必要です。 自動的に再帰しないでください。より深いレベルへ進むには、その都度ユーザーの明示的な許可が必要です。また、デフォルトの深度上限があります（「再帰の制御」を参照）。
8. 意識的に下された決定を尊重します。 CLAUDE.md、決定仕様書、またはブループリントに記載された選択は、指摘事項ではありません。
9. 簡潔さより分かりやすさを重視します。 目標は明瞭さであり、行数を減らすことではありません。コードを読みやすくする変換（巧妙さより明示性、中間ステップへの名前付け、入れ子より平坦化）ができるなら、行数が増えてもそちらを優先してください。長くても明快な実装は、短くても密度の高い実装に勝ります。これはモジュール内部の実装に適用されます。モジュールのインターフェースは引き続き小さく保ちます。動作は維持し、テストで証明する必要があります。また、行数を増やすこと自体を目的にしてはいけません。references/simplify-playbook.md を参照してください。
10. 実装はテスト駆動で、品質改善ループを回します。 コード変更では、TDD + レビュー + QA のループ（テスト作成 → 実装 → レビュー → 修正 → QA シミュレーション → 修正を、問題がなくなるまで上限付きで繰り返す）を実施します。references/quality-loop.md を参照してください。

---

ステージ 1 — マッピング

選択した実行モードを使い、読み取り専用のマッピングロールでリポジトリの構造を把握します。

1. スタックを検出します。 対象は Python と TypeScript です（マニフェスト：pyproject.toml/requirements.txt/setup.py、package.json/tsconfig.json）。どちらもなければ、その旨を伝えて終了します。両方ある場合は、それぞれを独立したプロジェクトとして扱います。
2. 簡易的な構造スキャンを行います。

   find . -maxdepth 2 -type f \( -name 'pyproject.toml' -o -name 'requirements.txt' \
     -o -name 'setup.py' -o -name 'package.json' -o -name 'tsconfig.json' \) \
     -not -path '*/node_modules/*' -not -path '*/.venv/*'
   tree -L 3 -I 'node_modules|.venv|venv|dist|build|.next|__pycache__' 2>/dev/null || \
     find . -maxdepth 3 -type d -not -path '*/node_modules/*' -not -path '*/.venv/*' | sort
   

   プロジェクトのルート、推定されるレイヤー、繰り返し現れるフォルダ構成を記録します。
3. ブループリントを確認できれば参照します。 BLUEPRINT.md（.claude/…、docs/…）があれば読み、より強い手掛かりを得ます。なければそのまま進め、作業を止めないでください。
4. （任意）ユーザーが単一ファイルのスナップショットを希望する場合は、 repomix / tree -L 3 を使って LLM 向けにコンテキストをまとめます。

---

ステージ 2 — 監査（リポジトリ全体）

メインエージェントは、選択した実行モードを使って読み取り専用の監査ロールを構成します。カタログ：

• references/universal-checks.md — 言語に依存しないアンチパターン。
• references/audit-catalog.md — Python/TS の健全性シグナルと検出コマンド。
• references/audit-worker.md — すべての監査ロールが従う契約。

1. 分割 — ステージ 1 のスキャンに基づき、リポジトリをスコープに分割します。重要なモジュールごとにサブツリー単位のワーカーを 1 つ割り当ててローカルチェックを行い、さらに横断的なワーカーを 1 つ割り当てます（重複、マニフェストの依存関係の方向、古い依存関係、リポジトリ全体のシークレット）。モジュールごとに約 1 ワーカー、小規模なリポジトリなら 2〜4 ワーカーです。
2. すべてのワーカーを実行 — インラインロールは順次実行し、明示的に許可された委任は並行して実行できます。それぞれにスコープ、カタログ、ブループリントのパス、スクラッチ出力パスを渡します。ワーカーは読み取り専用です。
3. 集約（メインエージェント）：フラグメントを統合し、重複する path:line を排除して、ID を割り当て、重大度順に並べ替えます。
4. 実行モード：どちらのモードでも同じ分割と出力形式を使い、実際の分離状態を記録します。

検出結果の一覧を提示します：

ID	検出事項	根拠（path:line）	カテゴリ	アンカー	重大度

⏸ チェックポイント A（必須）：

「監査で N 件の検出事項が見つかりました。ブロッカーが X 件、修正推奨が Y 件、軽微な問題が Z 件です。深掘りの機会を探す前に確認しますか？ 意図的なもの、またはスコープ外と考えるものはありますか？」

この一覧は Deepen ステージに引き継がれ、摩擦の大きい領域を探索する際の手がかりになります。既定では一時的なものとして扱い、依頼された場合にのみ docs/audit/findings-<YYYY-MM-DD>.md に保存します。

---

ステージ 3 — 深掘り（再帰）

このステージは、単純な「計画してから実行」を置き換えます。deep-module フローを実行し、以下の 3 つの形式で再帰します。扱う候補ごとに 1 回の深掘りパスとなり、パスは入れ子になります。

3.1 深掘りの機会を探す

選択した実行モードで探索ロールを実行し、監査結果を手がかりとして、AI がコードベースをたどるように有機的に調査します。硬直したヒューリスティックには従いません。次のような摩擦が生じる箇所を記録します：

• 1 つの概念を理解するために、多数の小さなファイルを行き来する必要がある。
• モジュールがあまりに浅く、インターフェースが実装とほぼ同じくらい複雑である。
• テスト容易性のためだけに純粋関数を切り出した結果、実際のバグが呼び出し方法に潜んでいる。
• 密結合したモジュールの継ぎ目に統合リスクがある。
• テストされていない部分、またはテストが難しい部分がある。

摩擦そのものがシグナルです。

3.2 候補を提示する

深掘りの機会を番号付きリストで提示します。それぞれについて：

• クラスター — 関係するモジュールや概念。
• 結合している理由 — 共有型、呼び出しパターン、概念の共同所有。
• 依存関係のカテゴリ — references/deep-module-reference.md に記載されている 4 つのうち 1 つ。
• テストへの影響 — どの既存テストが境界テストに置き換わるか。

インターフェースはまだ提案しないでください。

⏸ チェックポイント B： 「どれを詳しく調べますか？」

3.3 問題の範囲を明確にする

選択した候補について、新しいインターフェースが満たすべき制約、依存する必要がある要素、制約を具体的に示すための大まかなコード例を添えて、ユーザー向けに説明します（例はあくまで説明用であり、提案ではありません）。説明を提示したら、直ちに 3.4 に進みます。設計パスの実行中にユーザーが検討できるようにします。

3.4 複数のインターフェースを設計する

デフォルトでは、3 人以上の設計ロール（references/interface-designer.md を参照）をインラインで順番に実行します。 明示的に許可された別個のワーカーは、同時に実行できます。各ロールは、異なる制約のもとで大きく異なるインターフェースを作成します。

• エージェント 1：インターフェースを最小化する — エントリーポイントは最大 1～3 個。
• エージェント 2：柔軟性を最大化する — 多くのユースケースと拡張ポイント。
• エージェント 3：最も一般的な呼び出し元に最適化する — デフォルトのケースを簡単にする。
• エージェント 4（境界をまたぐ依存関係がある場合）：ポートとアダプター。

各ロールは、インターフェースのシグネチャ、使用例、隠蔽する複雑さ、依存関係の戦略、トレードオフを提示します。

設計案を順番に提示し、文章で比較したうえで、独自の明確な推奨案を示してください。最も優れた設計とその理由、または要素をうまく組み合わせられる場合はハイブリッド案を提示します。ユーザーが求めているのは、選択肢の一覧ではなく、踏み込んだ見解です。

**⏸ チェックポイント C：**ユーザーがインターフェースを選ぶか、推奨案を受け入れます。

3.5 RFC として記録する

references/deep-module-reference.md のテンプレートを使用して、docs/ にリファクタリング RFC を Markdown ファイルとして作成します。事前レビューについて尋ねる必要はありません。作成してパスを共有してください。

3.6 （任意）実装 — TDD + QA 品質ループ

Deep-module のフローは、意図的に RFC で終了します。ユーザーがすぐに実装することを希望する場合は、references/quality-loop.md の品質ループを実行します。テスト駆動で、ワーカーロールを組み合わせ、クリーンになるまでレビュー→修正→QA→修正を繰り返します（上限あり）。メインエージェントがオーケストレーションを行い、git/HITL のゲートを維持します。

⏸ チェックポイント D（コードを変更する前）：「この RFC を今すぐブランチで実装しますか、それとも後で使えるよう RFC のまま残しますか？（実装する場合：TDD で進めます。まずテストを書き、その後実装、レビュー、QA シミュレーションを行い、クリーンになるまで繰り返します。）」

「はい」の場合は、次の順に進めます。

1. ブランチを作成する：git switch -c improve/<rfc-slug>（確認すること。明示的な許可なしに push/PR を行わないでください）。
2. **まずテストを書く（red）。**テスト作成ロールが、RFC の受け入れ基準と維持する動作に基づいて境界テストを作成し、実行して目標を定義します。
3. **実装する（green）。**実装ロールが、小さな手順でテストを通し、references/simplify-playbook.md を適用します。
4. レビューする。references/review-rubric.md に従って、正確性と保守性のレビューを行うロールを実行し、指摘事項を統合して重複を排除します。
5. **QA 計画 + シミュレーション。**QA 計画ロールと QA シミュレーションロールを実行し、成功／失敗／スキップの証拠を保持します。
6. **修正してループする。**ブロッキングの指摘事項または QA の失敗がある場合は、修正ロールで対応し、手順 4 に戻ります。MAX_QUALITY_ITERATIONS（デフォルトは 3）を上限とし、その後「人間による対応が必要」と報告します。
7. **報告する。**変更内容、テスト、レビューと QA の状況、path:line を報告します。

ループは完了まで実行してから報告します。ループの途中で確認を求めることはありませんが、判断を捏造することもありません。依存関係のブロックや動作変更の曖昧さなど、人間の判断が本当に必要なものがあれば、そのブランチを停止し、原則 5 に従って明示します。

設定（デフォルト値。平易な言葉で上書き可能）

• MAX_QUALITY_ITERATIONS = 3 — 「人間による対応が必要」と明示する前に行う、レビュー→修正→QA のサイクル数。
• REVIEW_BLOCKING_SEVERITY = high — この重大度以上の指摘事項のみブロックします。それより低い指摘事項は記録しますが、ブロックしません。
• GIT_STRATEGY = branch — ブランチを作成してコミットします。PR/push は明示的な許可がある場合のみ行い、自動マージはしません。

3.7 再帰 — 3 つの形式。それぞれに確認が必要です

各パスの完了後、次に進む方法をユーザーに提示します。自動的に再帰してはいけません。

• 分解（下方向）。 選択した候補が、1 つの単位として掘り下げるには大きすぎる場合は、サブパートに分割し、それぞれに 3.1～3.6 を実行します。サブパートは親のフレーミングを引き継ぎます。
• 再探索（より深く）。 リファクタリングを実装した後、変更した領域に範囲を絞って 3.1 を再実行します。1 つのモジュールを掘り下げると、その下にある次の摩擦点が見つかることがよくあります。簡素化パス（変更したコードに references/simplify-playbook.md を適用すること）も、有効な軽量形式です。
• 再監査（外側へ）。 選択した候補の作業が完了したら、任意で Stage 2 を再実行してリポジトリ全体から次の候補を洗い出し、ここに戻ります。

⏸ チェックポイント E（各パスの後）：

「パスが完了しました。再帰しますか？（a）この候補をさらに分解する、（b）たった今変更した領域を再探索する、（c）リポジトリ全体を再監査して次の候補を探す、（d）ここで終了する。」

---

再帰の制御

再帰は強力ですが、際限なく続きやすいため、上限を設けます。

• 深さのデフォルト上限 = 入れ子 3 レベル（パスの中にパス、その中にさらにパス）。さらに深く進む場合は、明示的に尋ねます。「現在 3 レベルまで進んでいます。続けますか？」
• 必ず確認を挟みます。 深いレベルに進む際は、毎回チェックポイント E を通過します。確認なしで続行してはいけません。
• スタックを記録します。 現在の作業内容が分かるように、payments → refund flow → idempotency key のような短い経路を表示し、ユーザーが流れを見失わないようにします。
• 効果が薄れたら停止します。 あるレベルで細かな指摘しか見つからなかった場合は、その旨を伝え、再帰自体を目的に続けるのではなく、停止を勧めます。

---

ファイルの保存先

成果物	場所	タイミング
検出事項の一覧	デフォルトではチャット内。依頼された場合は docs/audit/findings-<YYYY-MM-DD>.md	Stage 2
リファクタリング RFC	docs/<rfc-slug>.md	Stage 3.5
QA テスト計画	docs/qa/test-plan-<branch>.md	Stage 3.6。実装する場合
コード変更	ブランチ improve/<rfc-slug> 上で直接編集	Stage 3.6
Repomix スナップショット（任意）	リポジトリのルートにある repomix-output.xml	Stage 1。依頼された場合
BLUEPRINT.md	存在する場合に限り読み取ります。このスキルが書き込むことはありません	Stage 1

監査・探索・設計の各作業では、中間生成物をリポジトリではなくスクラッチワークスペースに保存します。docs/ に保存するのは RFC と（依頼された場合の）保存済み一覧のみです。リポジトリ外には書き込まず、同じ日付のファイルを確認なしで上書きしてはいけません。

---

停止して確認するチェックポイントの概要

#	チェックポイント	タイミング
A	検出事項の一覧を確認する	Stage 2 の終了時。必ず実施
B	探索する候補を選ぶ	Stage 3.2。必ず実施
C	インターフェース設計を選ぶ	Stage 3.4。必ず実施
D	今すぐ実装するか、RFC のみとするかを決める	Stage 3.6。コード変更の前
E	再帰するか、停止するかを決める	各パスの後。必ず実施
—	ブランチの作成・コミット・プッシュ	Git に影響する操作を行う直前

本当に曖昧な点があれば、その都度作業を止めて確認します。人間が決めるべきことを勝手に決めてはいけません。

---

このスキルが行わないこと

• 他のスキルには依存しません。マッピング、チェック、設計の契約はすべて組み込まれています。
• ユーザーが候補を選ぶ前にインターフェースを提案したり、ユーザーの許可を得る前に実装したりしません。
• 自ら再帰したり、深さの上限を黙って超えたり、大規模な一括書き換えを行ったりしません。
• 操作ごとの明示的な承認なしに、ブランチをプッシュしたり、PR を作成したり、コミットしたりしません。

---

関連項目

• references/deep-module-reference.md — 4 つの依存関係カテゴリと RFC テンプレート。
• references/simplify-playbook.md — 明瞭さを最優先する変換（より長くなっても、動作を維持します）。
• references/interface-designer.md — インターフェース設計の各ロールの契約。
• references/quality-loop.md — TDD ＋レビュー＋QA の実装ループ（ロールで構成し、上限を設定）。
• references/review-rubric.md — 正確性（再現率重視）と保守性（徹底的）のレビュー基準。
• references/qa-test-plan.md — 手動 E2E QA プランのパイプラインと形式。
• references/audit-worker.md — 監査ロールの契約。
• references/universal-checks.md — 言語に依存しないアンチパターンのカタログ。
• references/audit-catalog.md — Python/TS の健全性シグナルと検出コマンド。