デバッグループ実践 (テスト→修正→検証)
重要キーワード
なぜ 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> が失敗している。
エラー: <最初の数行を貼り付け>
ループ
- テストを実行して失敗を再現
- エラー箇所のコードを Read
- 原因の仮説を 3 つ列挙
- 最有力仮説で修正
- テスト再実行
- 失敗なら次の仮説へ (合計 5 試行まで)
- 通ったら全テスト実行で regression 確認
停止条件
- ✅ テストが通る
- ⛔ 5 試行使い切った → 状況報告して相談
- ⛔ 修正案が「コードベースの大幅変更」になる → 相談
### テンプレ B: バグ報告から再現
バグ報告
ユーザーから「ログイン後に画面遷移しない」という報告。
ブラウザコンソールに TypeError: Cannot read properties of null (reading 'token') が出る。
ループ
- 再現スクリプト を
scripts/repro_login.pyに作成 (使い捨て) - 再現できなかったら何が違うか仮説 → 環境差・データ差を確認
- 再現できたら、エラー発生地点の特定 (スタックトレース → ファイル)
- 修正
- 再現スクリプトで verify
- 通常テストスイートでも regression なし確認
- 再現スクリプトを正式テストに昇格 (
tests/test_login_regression.py)
停止条件
- ✅ 再現スクリプトが緑になり、テスト全件緑
- ⛔ 再現できない (環境固有の可能性) → 報告
### テンプレ C: パフォーマンス問題
状況
エンドポイント /api/dashboard が 3 秒以上かかる (目標は 500ms 以下)。
ループ
- 計測:
pytest --benchmarkまたは apache bench で現状値を取得 - プロファイル: cProfile / py-spy / Chrome DevTools で hotspot を特定
- 仮説: top 3 を列挙 (例: N+1, 同期 IO, JSON serialize)
- 修正: top 1 を改善
- 再計測: 改善幅を確認
- 目標未達なら次の hotspot へ (3 ループまで)
停止条件
組み込みコマンド (一部)
| コマンド | 機能 |
|---|---|
/help |
ヘルプ |
| コンテキストクリア | |
/model |
モデル切替 |
/init |
CLAUDE.md 雛形生成 |
/review |
PR レビュー |
/security-review |
セキュリティ観点でのレビュー |
/config |
設定 |
/agents |
サブエージェント一覧 |
/permissions |
権限ルール編集 |
/cost |
セッションのトークン消費表示 |
/compact |
会話の要約圧縮 |
カスタムコマンド
.claude/commands/<name>.md を作るだけで自分の slash command を定義できます。
例: .claude/commands/test.md
Prompt Generator で初版生成
↓
Test Cases で複数入力を試す
↓
Improver で改善案を取得
↓
A/B 比較で勝者を選ぶ
↓
Code export して本番に組み込む
$ARGUMENTS
引数を受け取れます。
wzxhzdk:1
呼び出し:
Prompt Generator で初版生成
↓
Test Cases で複数入力を試す
↓
Improver で改善案を取得
↓
A/B 比較で勝者を選ぶ
↓
Code export して本番に組み込む
階層
~/.claude/commands/...ユーザーグローバル<repo>/.claude/commands/...プロジェクト固有
よく使われる自作コマンド例
| コマンド | 用途 |
|---|---|
/lint-fix |
フォーマッタ + 自動修正 + テスト |
/changelog |
直前のコミット群から CHANGELOG エントリを生成 |
/migrate-test |
DB マイグレーションのテスト |
/triage |
直近の Issues を優先度順にトリアージ |
/release-notes |
リリースノートを下書き |
Frontmatter の主な項目
wzxhzdk:1Plugin としての配布
カスタムコマンド・スキル・MCP を一括配布する Plugin という仕組みもあります。 GitHub に公開して、claude plugin install <user>/<repo> のように受講者全員に配るのに便利。実践: Claude Code に投げるベストな書き方
すぐコピペで使える 本格的な自作コマンド集。.claude/commands/ に置くだけで動きます。
① /review — git diff レビュー
.claude/commands/review.md
```markdown
description: 現在の git diff をレビューし、問題点と改善提案を出す allowed-tools: Bash, Read, Grep
現在のブランチの未コミット変更 (git diff) と、main からの差分 (git diff main...HEAD) をレビューしてください。
ループ中の振る舞いを制御する Tips
初期設計 → Workbench - で出費の上限を見張る
長いループで API 課金が膨らみがち。最大ループ回数を明示 する。
Subagent で並列に試す
「修正案 A と B を並列に試して、どちらが先に通るか見たい」というケース:
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)
Plan Mode で計画レビュー
修正範囲が大きそうな時は、最初に Plan Mode で計画を取って、人がレビュー → 実装に移行。
git bisect の活用
「いつから壊れた」がわからない時は:
$ claude
> このリポジトリのバグを直して
Claude Code が自動で bisect の二分探索を進めます。
ループから抜けられない時のシグナル
- 🚨 同じファイルを 5 回以上編集している (本質を捉えていない)
- 🚨 テストを書き換えている (本来直すべきはコード側)
- 🚨 「これで動くはず」と言って実行してない (verify を sukip)
- 🚨 エラーメッセージが毎回違う (前の修正が新たなバグを生んでいる)
- 🚨 30 分以上同じバグ (アーキテクチャ問題の可能性)
Esc で止めて、状況を整理し、人が判断を入れる。「自己修復」を引き出すプロンプトの工夫
失敗したら:
- ログを丁寧に読む (「ログ全部見て」と促す)
- なぜそのエラーが出たかを 1 文で言語化 (思考を可視化)
- 仮説を 2〜3 個出す (1 つに賭けない)
- 最有力で試す
- それでもダメなら次の仮説
毎ループで状況を 1 行サマリしてください: 「Try N: 仮説 X → 結果 Y」
演習: 失敗テストをループで直す
修正は 適用しないこと。原因特定だけが仕事。 適用するかは人が判断する。 ```
呼び出し: /debug TypeError: Cannot read property 'name' of undefined at user.js:42
④ /cleanup — 削除候補のスキャン
.claude/commands/cleanup.md
```markdown
description: 未使用コード・依存・ファイルの候補をスキャン allowed-tools: Bash, Read, Grep, Glob
このリポジトリから 削除候補 をスキャンしてください。
演習: 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 を特定できたか
まとめ
お疲れ様でした!