なぜ Claude Code に「デバッグループ」を任せるのか
Claude Code が一番力を発揮する場面の一つが 「失敗テストを直す」 反復サイクル。 人間がやると退屈な「テスト実行 → ログ読む → コード修正 → 再実行」を、Claude が高速で回します。
典型的な「悪い」依頼
> このバグ直して
→ 何が問題か Claude が推測しなければならず、無駄な探索が増える。
典型的な「良い」依頼
> 次の手順でデバッグしてください:
> 1. tests/test_auth.py::test_oauth_callback を実行 (失敗するはず)
> 2. エラーログを読み、原因を仮説として 3 つ挙げる
> 3. 最も可能性の高い原因に対して修正を試す
> 4. テストを再実行
> 5. まだ失敗するなら次の仮説に進む
> 6. 通ったら全テスト実行で他に影響がないか確認
>
> 上限 5 ループまで。それでも通らなかったら停止して相談。
→ 明示的な 「ループ手順」 と 「停止条件」 がある。Claude は迷わず回せる。
デバッグループ・テンプレート
テンプレ A: 失敗テストを直す
## 状況
テスト `<test_path>::<test_name>` が失敗している。
エラー: <最初の数行を貼り付け>
## ループ
1. テストを実行して失敗を再現
2. エラー箇所のコードを Read
3. 原因の仮説を 3 つ列挙
4. 最有力仮説で修正
5. テスト再実行
6. 失敗なら次の仮説へ (合計 5 試行まで)
7. 通ったら全テスト実行で regression 確認
## 停止条件
- ✅ テストが通る
- ⛔ 5 試行使い切った → 状況報告して相談
- ⛔ 修正案が「コードベースの大幅変更」になる → 相談
テンプレ B: バグ報告から再現
## バグ報告
ユーザーから「ログイン後に画面遷移しない」という報告。
ブラウザコンソールに `TypeError: Cannot read properties of null (reading 'token')` が出る。
## ループ
1. **再現スクリプト** を `scripts/repro_login.py` に作成 (使い捨て)
2. 再現できなかったら何が違うか仮説 → 環境差・データ差を確認
3. 再現できたら、エラー発生地点の特定 (スタックトレース → ファイル)
4. 修正
5. 再現スクリプトで verify
6. 通常テストスイートでも regression なし確認
7. 再現スクリプトを正式テストに昇格 (`tests/test_login_regression.py`)
## 停止条件
- ✅ 再現スクリプトが緑になり、テスト全件緑
- ⛔ 再現できない (環境固有の可能性) → 報告
テンプレ C: パフォーマンス問題
## 状況
エンドポイント `/api/dashboard` が 3 秒以上かかる (目標は 500ms 以下)。
## ループ
1. **計測**: `pytest --benchmark` または apache bench で現状値を取得
2. **プロファイル**: cProfile / py-spy / Chrome DevTools で hotspot を特定
3. **仮説**: top 3 を列挙 (例: N+1, 同期 IO, JSON serialize)
4. **修正**: top 1 を改善
5. **再計測**: 改善幅を確認
6. 目標未達なら次の hotspot へ (3 ループまで)
## 停止条件
- ✅ 500ms 以下達成
- ⛔ 3 ループしても 50% 以上の改善が出ない → アーキテクチャ変更が必要
実践: Claude Code に投げるベストな書き方
❌ 雑な書き方
このテスト落ちてる、直して
✅ 良い書き方
tests/test_payment.py::test_refund が失敗。
エラー: AssertionError: expected 1000, got 980
これをデバッグループで直してください:
- 最初に test を実行して失敗を再現
- 仮説 → 修正 → 再実行 を最大 5 回
- 修正前後で別テストへの影響を確認
- 通ったら git diff を見せて
- 行き詰まったら停止して相談
CLAUDE.md にあるコード規約を守って、過度な変更は避けて。
ループ中の振る舞いを制御する Tips
/cost で出費の上限を見張る
長いループで API 課金が膨らみがち。最大ループ回数を明示 する。
Subagent で並列に試す
「修正案 A と B を並列に試して、どちらが先に通るか見たい」というケース:
> 次を並列に試してください。
> Subagent A (worktree A): 仮説 1 で修正
> Subagent B (worktree B): 仮説 2 で修正
> 両方走らせて、先に通った方を採用。
Plan Mode で計画レビュー
修正範囲が大きそうな時は、最初に Plan Mode で計画を取って、人がレビュー → 実装に移行。
git bisect の活用
「いつから壊れた」がわからない時は:
> git bisect を使ってバグの混入コミットを特定してください。
> good: v1.4.0 (確実に動いていた)
> bad: HEAD (今壊れてる)
> 各コミットで pytest tests/test_xxx.py を実行して判定。
Claude Code が自動で bisect の二分探索を進めます。
ループから抜けられない時のシグナル
以下が出たら 人が介入 すべき:
- 🚨 同じファイルを 5 回以上編集している (本質を捉えていない)
- 🚨 テストを書き換えている (本来直すべきはコード側)
- 🚨 「これで動くはず」と言って実行してない (verify を sukip)
- 🚨 エラーメッセージが毎回違う (前の修正が新たなバグを生んでいる)
- 🚨 30 分以上同じバグ (アーキテクチャ問題の可能性)
→ 即 Esc で止めて、状況を整理し、人が判断を入れる。
「自己修復」を引き出すプロンプトの工夫
Claude Code は、テスト失敗のログから自分で軌道修正する能力があります。 それを最大化するプロンプト:
失敗したら:
- ログを丁寧に読む (「ログ全部見て」と促す)
- なぜそのエラーが出たかを 1 文で言語化 (思考を可視化)
- 仮説を 2〜3 個出す (1 つに賭けない)
- 最有力で試す
- それでもダメなら次の仮説
毎ループで状況を 1 行サマリしてください: 「Try N: 仮説 X → 結果 Y」
→ Claude が 思考を出力 するので、人が異常を察知しやすい。
▶ デバッグループ依頼
あなたは Claude Code です。次のバグを上記テンプレートに従ってデバッグしてください (実行できない環境ですが、論理的なループ手順を提示)。
バグ: 「ユーザーが商品を 11 個以上カートに入れると、合計金額が 0 になる」
テスト: tests/test_cart.py::test_large_cart