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

重要キーワード

English	日本語	説明
Debug Loop	デバッグループ	失敗するテストを書き、修正し、再度実行する反復サイクル
TDD	テスト駆動開発	Test-Driven Development。テスト先行のスタイル
Repro	再現	バグを確実に再現させるスクリプトや手順
Bisect	二分探索	git bisect でバグ混入コミットを特定

English

日本語

説明

Debug Loop

デバッグループ

失敗するテストを書き、修正し、再度実行する反復サイクル

TDD

テスト駆動開発

Test-Driven Development。テスト先行のスタイル

Repro

再現

バグを確実に再現させるスクリプトや手順

Bisect

二分探索

git bisect でバグ混入コミットを特定

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

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

典型的な「悪い」依頼

from anthropic import Anthropic
client = Anthropic()
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}]
)
print(msg.content[0].text)

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

典型的な「良い」依頼

$ claude
> このリポジトリのバグを直して

→ 明示的な 「ループ手順」 と 「停止条件」 がある。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 の活用

「いつから壊れた」がわからない時は:

wzxhzdk:8

Claude Code が自動で bisect の二分探索を進めます。

ループから抜けられない時のシグナル

以下が出たら 人が介入 すべき:

🚨 同じファイルを 5 回以上編集している (本質を捉えていない)
🚨 テストを書き換えている (本来直すべきはコード側)
🚨 「これで動くはず」と言って実行してない (verify を sukip)
🚨 エラーメッセージが毎回違う (前の修正が新たなバグを生んでいる)
🚨 30 分以上同じバグ (アーキテクチャ問題の可能性)

→ 即 Esc で止めて、状況を整理し、人が判断を入れる。

「自己修復」を引き出すプロンプトの工夫

Claude Code は、テスト失敗のログから自分で軌道修正する能力があります。それを最大化するプロンプト:

wzxhzdk:9

→ Claude が 思考を出力 するので、人が異常を察知しやすい。

▶ デバッグループ依頼

あなたは Claude Code です。次のバグを上記テンプレートに従ってデバッグしてください (実行できない環境ですが、論理的なループ手順を提示)。

バグ: 「ユーザーが商品を 11 個以上カートに入れると、合計金額が 0 になる」
テスト: tests/test_cart.py::test_large_cart

演習問題

演習 1: 失敗テストをループで直す

あなたのプロジェクトで、わざと壊れたテスト (またはコード) を作って、Claude Code にデバッグループで直させてください。

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

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

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

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

スタータープロンプト:

tests/test_xxx.py::test_yyy が失敗しています。次のループで直してください: 1) 失敗を再現 2) 仮説 3 つ列挙 3) 最有力で修正 4) 再実行 5) 失敗なら次の仮説へ (5 試行まで) 6) 通ったら全テスト regression 確認。毎ループ「Try N: 仮説 X → 結果 Y」で状況サマリ。

ヒントを見る

「テストを書き換えないで」と明示的に書くと、Claude が安易にテスト側を緩めるアンチパターンを防げます。

演習 2: git bisect で混入コミットを特定

あなたのリポジトリで、過去に動いていた機能が今壊れている (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 を特定できたか