ankuro.dev
← ブログ一覧に戻る
【Claude Code中級編 #13】デバッグ・エラー対処——よくある失敗パターンと解決法
2026-04-18#Claude Code#AI#デバッグ#エラー対処

【Claude Code中級編 #13】デバッグ・エラー対処——よくある失敗パターンと解決法

Claude Codeが期待通り動かないとき、原因の多くは「Claude側の問題」ではなくコンテキスト・指示・権限の問題にある。パターンさえ押さえれば、詰まったときに即対処できる。

この記事でわかること：

  • よくある失敗5パターンの症状・原因・対処の早見表
  • ツール拒否・無限ループ・コンテキスト切れなど状況別の立て直し手順
  • 「動かない」から抜け出すための観察 → 仮説 → 最小介入のフロー

よくある失敗パターン早見表

まずは症状から原因を引く早見表。

症状 主な原因 最小対処
ツール実行が拒否される 権限設定・ポリシーのブロック .claude/settings.json の確認
同じエラーを繰り返してループに入る 失敗ログがコンテキストに残存 /clear で失敗履歴を断ち切る
「さっき決めたこと」を無視する コンテキスト肥大・順位の逆転 CLAUDE.mdに書き戻して /clear
的外れなファイル・関数を修正される 指示の曖昧さ・対象の未特定 ファイルパス・関数名を明示して再指示
「完了しました」と言うが実は失敗している 検証ステップが指示に含まれない 実行・テストコマンドまで指示に含める

以下、それぞれを詳しく見ていく。

パターン① ツール拒否（Permission denied）の立て直し

Claude Codeがツール実行に失敗して止まる場合、原因は2系統ある。

① ユーザーが手動で拒否（対話中）
② 設定ファイル・ポリシーで事前にブロック

どちらなのかで対処が変わる。

対話中の拒否

「なぜ拒否したか」をClaudeに伝えないと、同じ提案を繰り返してくる。

❌ よくある流れ
Claude: rm -rf node_modules を実行します
User: [拒否]
Claude: 別のアプローチを試します（また似たコマンド提案）

✅ 意図を伝える流れ
Claude: rm -rf node_modules を実行します
User: [拒否] node_modulesは残したまま package-lock.json だけ再生成したい
Claude: rm package-lock.json && npm install を実行します

拒否の理由を1行添えるだけで、不要な試行錯誤が消える。

設定ファイルでのブロック

.claude/settings.json の permissions や Hook の PreToolUse で先にブロックされるケース。エラーメッセージに「permission」「blocked」といった文言が含まれていれば設定起因の可能性が高い。

# プロジェクトの権限設定を確認
cat .claude/settings.json

# ローカル（コミット対象外）の設定も確認
cat .claude/settings.local.json

# ユーザーグローバル（全プロジェクト共通）の設定を確認
cat ~/.claude/settings.json

意図的なブロックなら迂回手段（別コマンド）を提示、誤設定なら settings.json を修正する。ブロックを無視させるために --dangerously-skip-permissions を使うのは最終手段で、普段使いは避ける。

パターン② 同じエラーを繰り返すループ

最も消耗するパターン。同じテストが3回連続で落ち、Claudeが同じような修正を試して、また落ちる——というループ。

ループのサイン

① 同じエラーメッセージを3回以上見ている
② Claudeの提案が「前にも試した内容」に似てきた
③ 修正が「行ったり来たり」している（Aを直してBが壊れ、Bを直してAが壊れる）

ここに入ったら、追加の指示を重ねず一度セッションを切る。

立て直し手順

ステップ1: 現状把握
  Claudeに「今何がうまくいっていないか1行でまとめて」と聞く
  → 認識のズレがあれば指摘する

ステップ2: CLAUDE.mdに書き戻し
  「ここまでの試行でわかった制約」を明文化
  例: "A関数の戻り値は必ずPromise<void>を返すこと"

ステップ3: /clear で失敗履歴を消す
  失敗した試行がコンテキストに残っていると、同じ方向の提案が再発する

ステップ4: 最小限のコンテキストで再開
  「CLAUDE.mdの制約を守ってA関数を修正して」だけを指示

ループ中の試行錯誤ログは次の判断に必要ない。思い切って捨てる方が早い。

パターン③ コンテキスト切れで決定事項を忘れる

長いセッションで「さっき決めたはずの設計方針を無視した提案が返ってくる」現象。第11回で予防策を扱ったが、起きてしまった後の立て直しを扱う。

まず確認すること

本当に忘れているのか、指示が届いていないのかを切り分ける。

User: 「Redisを使わないと決めたはずだけど」
Claude: 「申し訳ありません、その通りです。DynamoDBで再実装します」
  → 決定は残っているが優先順位を見誤った（新しい情報に引きずられた）

Claude: 「そのような決定を私は確認できません」
  → コンテキストから消えている（/compact で要約されて詳細が落ちた可能性）

立て直し手順

ステップ1: 決定事項の棚卸し
  これまでに決めたことを箇条書きで整理
  User側でリスト化 → Claudeに渡す

ステップ2: CLAUDE.mdに書き戻す
  セッションを跨いで参照される場所に移す
  「今のコンテキストにある」状態は信用しない

ステップ3: /clear → 再開
  CLAUDE.mdに書き戻したら、過去のログは不要

「長いセッションを無理に続ける」より「整理して切る」方が結果的に早い。

パターン④ 的外れな修正をされる

「バグを直して」と伝えたら、別のファイルの無関係な部分を修正された——というケース。

原因はほぼ指示の曖昧さ

❌ 曖昧な指示
「ユーザー登録のバグを直して」
  → Claudeは推測で動く。ファイル特定に時間を使い、勘違いで的外れな修正になる

✅ 具体的な指示
「src/api/users/register.ts の validateEmail 関数でバリデーションが通らないバグを直して。
  再現手順: email に大文字を含めるとバリデーションエラー。
  期待値: 大文字も許可する。」
  → 対象ファイル・関数・症状・期待値が明示されている

修正範囲を広げない指示

Claudeは「ついでに気になった箇所」も直そうとする傾向がある。範囲を限定する一文を添える。

「validateEmail のバグ修正だけに絞ってください。
  他の関数やファイルは変更しないでください。」

既に的外れな修正をされたら、git status と git diff で全変更を確認してから、不要な変更だけを git restore <file> で戻す。

git status                     # 変更されたファイルを確認
git diff src/api/auth/login.ts # 意図しない変更を確認
git restore src/api/auth/login.ts # 不要な変更だけ戻す

パターン⑤ 「完了しました」と言って実は失敗している

最も怖いパターン。Claudeが「実装完了しました」と返答するが、実際は型エラーやテスト失敗が残っている。

なぜ起きるか

Claudeの「完了」判定はコード編集が通った時点で出ることがある。テスト実行や型チェックを指示していないと、動作確認されていない状態で完了扱いになる。

対策：検証を指示に含める

❌ 検証なし
「ユーザー登録APIを実装して」

✅ 検証込み
「ユーザー登録APIを実装して。
  完了後に以下を実行し、成功を確認するまで完了と報告しないでください:
  - npm run type-check
  - npm test src/api/users/
  エラーが出たら修正してから再度実行してください。」

検証の自動化

毎回指示に書くのが手間なら、CLAUDE.mdに運用ルールとして書いておく。

## 実装完了の定義

コード編集後、以下を実行してすべてパスした状態を「完了」とする:

- npm run type-check
- npm run lint
- 関連するテスト（npm test <対象パス>）

これらのいずれかが失敗している場合は「完了」と報告しない。

より強制力を持たせたい場合は、第3回の PostToolUse Hook でファイル編集後に自動で型チェック・lint を走らせる構成にする。

立て直しの基本フロー

特定パターンに当てはまらない「なぜか動かない」状態のとき、以下の順で切り分ける。

① 観察: 何が起きているか事実だけを確認
  - Claudeの出力
  - 実際のファイルの状態（git diff）
  - コマンドの実行結果
  → 推測は一旦置く

② 仮説: 原因の候補を2〜3個挙げる
  - コンテキストに誤った情報が入っている？
  - 指示が曖昧だった？
  - 権限設定がブロックしている？

③ 最小介入: 1つだけ変更して試す
  - 複数の対策を同時にやらない
  - 変更を1つにすると原因が特定しやすい

④ それでもダメなら /clear
  - コンテキストを疑う
  - CLAUDE.mdに最低限の情報を書き出して再開

原則は「増やすより減らす」。指示を追加する前に、溜まっている不要な情報を捨てる方が効果が大きいことが多い。

まとめ

パターン 第一選択の対処
ツール拒否 拒否理由を伝える・.claude/settings.json を確認
無限ループ CLAUDE.mdに制約を書き戻し → /clear → 最小指示で再開
決定事項を忘れる 決定をCLAUDE.mdに移す → /clear → 再開
的外れな修正 ファイル・関数・症状・期待値を明示・修正範囲を限定
「完了」だが実は失敗 検証コマンドまで指示に含める・CLAUDE.mdに完了定義を書く

Claude Codeでのデバッグは「Claudeを直す」のではなく「指示・コンテキスト・権限を調整する」作業。詰まったら追加するより減らす・切り替えるを意識すると、立て直しが速くなる。

← 第12回：Sub agentとWorktreeの組み合わせ——並列開発の設計 ｜ 第14回：Claude Codeに通る指示の書き方——プロンプト設計の基本 →

← ブログ一覧に戻る