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

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% 以上の改善が出ない → アーキテクチャ変更が必要 ```

❌ 雑な書き方

このテスト落ちてる、直して

✅ 良い書き方

tests/test_payment.py::test_refund が失敗。
エラー: AssertionError: expected 1000, got 980

これをデバッグループで直してください:
- 最初に test を実行して失敗を再現
- 仮説 → 修正 → 再実行 を最大 5 回
- 修正前後で別テストへの影響を確認
- 通ったら git diff を見せて
- 行き詰まったら停止して相談

CLAUDE.md にあるコード規約を守って、過度な変更は避けて。

/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 にデバッグループで直させてください。

準備: 1. 動いているテストを 1 つ選び、本体コードに 1 文字バグ を仕込む (例: if x > 0 → if x >= 0) 2. テスト実行して失敗を確認

Claude Code への依頼 (テンプレート A を使用):

tests/test_xxx.py::test_yyy が失敗。これをデバッグループで直してください。最大 5 試行、状況を毎ループサマリしてください。

観察ポイント: - 何試行で正解にたどり着いたか - 仮説の出し方 (3 つ並べたか、1 つに賭けたか) - テスト側を書き換えようとしなかったか (アンチパターン)

あなたのリポジトリで、過去に動いていた機能が今壊れている (or 壊しても良い) ケースを用意し、Claude Code に git bisect させてください。

手順: 1. 動作していた古いタグ・コミットを特定 (例: git tag v1.0) 2. 現在 HEAD で壊れていることを確認 3. Claude Code に依頼: > git bisect でバグ混入コミットを特定してください。good=v1.0, bad=HEAD。各コミットで pytest tests/test_xxx.py を実行して判定。

観察ポイント: - bisect の二分探索を正しく進めているか - 各ステップで build / test を回しているか - 最終的に commit hash を特定できたか