When a Claude Code run goes wrong, the worst instinct is usually to write a more emotional prompt.
"That still did not work." "Be more careful." "Try again but better."
Those messages feel active, but they hide the only part that actually matters: what kind of failure happened.
Claude Code failures usually belong to one of four buckets:
- setup or auth failure
- permission failure
- scope or memory failure
- task logic failure
If you do not classify the bucket first, the retry becomes guesswork.
Use this map to choose the right repair lane before you touch the prompt again. The point is to reduce the failure, not to restate the whole task more dramatically.
First Split: Is Claude Broken, Or Is The Task Broken?
Before you touch the prompt, answer one blunt question:
did Claude fail to operate, or did it operate on the wrong thing?
Use the setup lane first when any of these are true:
- Claude will not launch cleanly
- login keeps flipping or expiring
- the wrong account or model is active
- shell behavior differs from what you thought you installed
Use the task-debug lane when Claude launches normally but:
- it chose the wrong files
- the validation command still fails
- it ignored a repo rule you thought was obvious
- the diff grew beyond the intended boundary
That distinction matters because a setup failure cannot be solved with a tighter coding prompt.
Run Three Machine Checks Before You Retry The Repo Task
If the session itself feels suspect, step out of the repo briefly and check the machine state:
claude --version
claude doctor
claude auth status --text
Those commands answer different questions:
- is the binary on PATH the one you expected
- is the installation or config unhealthy
- is this machine really logged in the way you think it is
Anthropic's troubleshooting docs also call out a common source of false confusion: an approved ANTHROPIC_API_KEY overrides subscription OAuth. If you have Pro, Max, Team, or Enterprise access but Claude behaves like the org is disabled, check the environment before blaming the session.
Then open Claude and confirm the live state with /status.
Permission Problems Often Masquerade As Reasoning Problems
Claude Code can look "dumb" when the real issue is that the exact command or edit path needed approval.
Current permissions docs split access into read-only tools, shell commands, and file modifications. Shell and write actions can be blocked or gated even when the model's reasoning is fine.
That means a weak-looking run may actually be:
- a denied command
- a command you approved in one directory but not this one
- a write attempt outside the allowed project scope
Check permissions explicitly before rewriting the task:
/permissions
If the failing step was a shell command, say so plainly in the follow-up. Do not rewrite the business goal and hope Claude infers the blocked action.
Name The Failure Signal In The Smallest Possible Form
Do not retry with a summary like "the test still fails."
Retry with the exact failure signal:
- the one failing test line
- the one wrong command output
- the one specific file Claude edited that it should not have touched
- the one repo rule it ignored
Bad retry:
You changed a bunch of things and it still seems broken.
Useful retry:
The failing command is still `pnpm test billing-webhook.test.ts`.
Current failure: expected 200, got 500.
Keep the existing parser change.
Do not touch retry infrastructure or config files.
The smaller the signal, the better chance Claude has of repairing the actual failure instead of inventing a larger new attempt.
File Scope Usually Breaks Before Code Quality Does
In practice, many first Claude Code failures are not wrong code. They are wrong blast radius.
The early warning signs are familiar:
- Claude is already in the right file but keeps reading sideways
- it drifts from a test fix into config cleanup
- it edits a generated or vendor-managed file
- it broadens validation from one command to a whole suite
When that happens, shrink the context immediately with @file and @directory references.
For example:
Retry this inside @src/server/webhooks/billing.ts and @tests/billing/webhook.test.ts only.
Do not inspect other packages unless you first explain why they are required.
That does more real work than a generic request to "stay focused."
Check Whether CLAUDE.md Taught The Wrong Lesson
Some failures look like model drift but are really memory drift.
Claude Code loads project guidance from CLAUDE.md, and the memory docs also expose /memory for inspecting loaded files and auto memory. If Claude keeps repeating a repo-specific mistake, inspect what it is actually reading.
Use:
/memory
Then ask:
- is
CLAUDE.mdtoo long to be followed consistently - did
/initgenerate generic rules you never trimmed - is a stale local preference fighting the current repo task
The docs explicitly recommend shorter, more specific memory files. If CLAUDE.md reads like a giant handbook, you have probably moved too much policy into persistent memory.
Use Debug Logging When The CLI Itself Feels Strange
If Claude behaves inconsistently before the repo task even starts, capture logs instead of guessing.
The current commands docs say /debug starts capturing logs from that point forward if you did not launch Claude with debug already enabled. The CLI also supports writing debug output to a file on startup.
Example:
claude --debug-file ~/claude-debug.log
Use this when:
- login looks fine but the CLI exits or hangs unexpectedly
- a command keeps failing in a way the normal output hides
- you suspect config, MCP, or plugin noise rather than task logic
Do not dump raw debug logs back into the prompt. Read them first, extract the actual symptom, then retry with the relevant line.
Use /rewind Before You Start A Fresh Session
Not every bad turn deserves a brand new chat.
Claude Code has checkpointing and rewind controls for exactly this reason. The current docs say you can press Esc twice or use /rewind to step back to an earlier point in the conversation or code state.
That is usually the right move when:
- the last turn introduced obvious diff sprawl
- the task boundary is still valid
- you know which turn made the session worse
Starting a new session is better when:
- the problem category changed
- the repo boundary turned out to be wrong
- you now need a different auth, permission, or environment lane
Rewind is for cleaning up a good task after a bad turn. New sessions are for new task boundaries.
A Tighter Follow-Up Prompt For Claude Code
Once you know the failure bucket, use a prompt that forces diagnosis before another edit pass:
The previous run did not finish the task correctly.
Current failure signal:
- [paste the exact failing line, wrong diff behavior, or ignored repo rule]
Keep:
- [name the one change worth keeping, if any]
Do not touch:
- [name the files, packages, or behaviors that must stay unchanged]
Before editing again:
1. Explain the most likely cause in 3 to 5 lines
2. Name the smallest file scope that still makes sense
3. Say whether this looks like a permissions, memory, or task-logic issue
Retry rules:
- stay inside @file and @directory references unless expansion is justified first
- use the same narrow validation command
- stop after the smallest fix that addresses the failure
That prompt is deliberately diagnostic. The goal is to stop Claude from continuing momentum from the previous bad turn.
Three Retries That Usually Make Things Worse
Retelling The Whole Backstory
Claude does not need a dramatic recap. It needs the present failure signal.
Asking For A Bigger Rewrite
If the first attempt drifted, a broader second attempt usually doubles the cleanup burden.
Leaving The Approval And Permission Surface Unspoken
If the last turn failed because a command or write path was blocked, pretending it was a pure reasoning issue just reproduces the same failure with nicer prose.
Know When To Stop
A good debug loop should tighten the task, not extend it forever.
Stop retrying in the same session when:
- the failure changes shape
- the file scope keeps expanding despite explicit boundaries
- the repo rules need a real
CLAUDE.mdedit before another attempt - machine-level checks show the auth or install path is not trustworthy
At that point, the honest fix is not another prompt. It is a changed setup or a reset task boundary.
Official References
- Troubleshooting
- Commands
- Authentication
- How Claude remembers your project
- Configure permissions
- Checkpointing
What To Read Next
Read Use Claude Code on One Real Repo Task Without Letting the Shell Loop Drift if the current problem is still a first-task scoping problem rather than a deeper session failure.
Read Install Claude Code Before Your First Real Repo Task if the run now looks more like an auth, shell, or install-path issue than a coding issue.
Read Setup GitHub MCP Server With Cursor or Claude Code if the real missing context is external repository or PR metadata rather than the local code itself.