デバッグループ実践 (テスト→修正→検証)

なぜ Claude Code に「デバッグループ」を任せるのか

Claude Code が一番力を発揮する場面の一つが 「失敗テストを直す」 反復サイクル。 人間がやると退屈な「テスト実行 → ログ読む → コード修正 → 再実行」を、Claude が高速で回します。

典型的な「悪い」依頼

> git bisect を使ってバグの混入コミットを特定してください。
> good: v1.4.0 (確実に動いていた)
> bad: HEAD (今壊れてる)
> 各コミットで pytest tests/test_xxx.py を実行して判定。

→ 何が問題か Claude が推測しなければならず、無駄な探索が増える。

典型的な「良い」依頼

失敗したら:
- ログを丁寧に読む (「ログ全部見て」と促す)
- なぜそのエラーが出たかを 1 文で言語化 (思考を可視化)
- 仮説を 2〜3 個出す (1 つに賭けない)
- 最有力で試す
- それでもダメなら次の仮説

毎ループで状況を 1 行サマリしてください: 「Try N: 仮説 X → 結果 Y」

→ 明示的な 「ループ手順」 と 「停止条件」 がある。Claude は迷わず回せる。

デバッグループ・テンプレート

テンプレ A: 失敗テストを直す

wzxhzdk:2

テンプレ B: バグ報告から再現

wzxhzdk:3

テンプレ C: パフォーマンス問題

wzxhzdk:4

実践: Claude Code に投げるベストな書き方

❌ 雑な書き方

wzxhzdk:5

✅ 良い書き方

wzxhzdk:6

ループ中の振る舞いを制御する Tips

/cost で出費の上限を見張る

長いループで API 課金が膨らみがち。最大ループ回数を明示 する。

Subagent で並列に試す

「修正案 A と B を並列に試して、どちらが先に通るか見たい」というケース:

wzxhzdk:7

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 が 思考を出力 するので、人が異常を察知しやすい。