When a prompt gives you the wrong thing, do not rewrite it from scratch and do not add the word "please." Run a loop instead: read what you got, name the single gap between that and what you wanted, change one thing, and run it again. Repeat until the result is right twice in a row. This page teaches that loop with Claude and the Claude Code CLI.
The loop in one diagram
The discipline is the "one thing" rule. If you change three parts of the prompt at once and the output improves, you do not know which change helped, so you cannot repeat it. Change one variable per run and you learn something every time.
Why is my prompt giving the wrong result?
Read the output before you touch the prompt. The first instinct is to edit it. Resist that. Read the output you got and compare it line by line to what you wanted. The fix is almost always written in the gap between the two.
Sort the failure into one of four buckets. The bucket tells you which lever to pull.
| Symptom | What it usually means | Lever |
|---|---|---|
| Right shape, wrong facts | Model lacks the source material | Add context |
| Right facts, wrong format | Output target is unstated | Constrain the format |
| Wandered off the task | Instruction was buried or vague | Move the ask, sharpen it |
| Confident and wrong | Task needs reasoning it skipped | Ask it to think first |
If you cannot pick a bucket, the result is not the problem yet. Ask Claude to tell you what it thought you wanted.
A mismatch in that restatement is the bug. You found it without editing a single instruction.
Step 2: name exactly one gap
Write the gap as a single concrete sentence. "It is bad" is not a gap. "It returned a paragraph when I needed a JSON array of objects" is a gap. "It invented a function called getUserToken that does not exist in the file" is a gap.
A named gap maps to a specific edit:
- Wrong facts → the source was missing, so add it.
- Wrong format → the target was unstated, so state it.
- Wrong scope → the boundary was loose, so draw it.
- Wrong reasoning → the steps were skipped, so require them.
If you find yourself listing three gaps, you have three runs ahead of you, not one. Fix the gap that blocks everything else first. A format problem rarely matters while the facts are still wrong.
Step 3: change one thing, then run again
Each lever below is one change. Apply one, run, and read the new result against the same wanted output.Common gotchaThe one-thing rule covers the prompt, but the failed run is still sitting in the conversation, and that history is a hidden second variable: the model may self-correct from its own earlier mistake rather than from your edit, so a "fix" that only works mid-thread breaks the moment you start clean.Re-test each change in a fresh context (or /rewind the conversation only) so you are measuring the prompt, not the chat that preceded it.
Lever: add the missing context
A model cannot cite a file it never saw. If the facts are wrong, the source is usually absent. In the Claude Code CLI you attach a file with an @-mention so Claude reads the real code instead of guessing.
This is the most common single fix. Vague results are often a context problem wearing a prompt-wording costume.Common gotchaAttaching a file is not the same as the model using it. If the source is huge or the wrong file, the answer still guesses while you assume it read the truth.Ask it to quote the exact lines it relied on, so a context gap shows up as a missing quote instead of a confident wrong fact. See context engineering for how to fill the window with exactly what the task needs.
Lever: constrain the format
If the content is right but the shape is wrong, state the shape. Show the exact structure rather than describing it.
A worked example of the output beats three sentences describing it. Pin one good example with few-shot prompting and the model copies the pattern.
Lever: draw the scope boundary
If Claude edited files you did not mention or solved a bigger problem than you asked, the boundary was loose. State what to touch and what to leave.
The "stop and tell me" clause turns silent over-reach into a question you can answer.
How do I make Claude reason before it answers?
Confident, wrong answers usually skip a step the task needed. In the Claude Code CLI, the keyword think in your prompt allocates more reasoning budget before the model answers, and stronger keywords raise that budget further.
The escalation ladder is think, then think hard, then ultrathink for the deepest budget. Reach for a stronger keyword when the problem is tangled, not for routine edits, since more reasoning costs more tokens and time.
Step 4: lock the win so it sticks
A prompt that worked once is not reliable. Two things make a one-off fix durable.
How do I know my prompt fix is reliable?
Run the working prompt on the same input a second time, and ideally on a second similar input. If both pass your check, the prompt is reliable. If the second run drifts, you fixed the example, not the prompt, and a constraint is still missing. A model produces a range of outputs for the same input, so one good result is a sample, not a guarantee.
Move durable rules into a memory file
If a constraint matters for every task, do not retype it each turn. Put it in a CLAUDE.md at the repo root. Claude Code loads that file at the start of every session, so the rule applies without you pasting it again.
# Project rules
- Never edit files outside the directory I name in my request.
- When you finish a change, run the test command and paste the output.
- Match the existing code style in the file you are editing.Keep this file short. Every line is read on every turn, so a stale rule is noise the model still weighs. See rules and memory files for the full pattern.
What if a fix makes things worse?
Sometimes the fix breaks more than it solves. The Claude Code CLI checkpoints your code and conversation before each edit, so you can roll back instead of fighting forward from a bad state.
Type /rewind to open the checkpoint menu, or double-tap the Esc key to reach the same list. Pick a point and choose what to restore.
| Restore choice | What it does |
|---|---|
| Code only | Reverts file edits, keeps the conversation |
| Conversation only | Rewinds the chat, leaves files as they are |
| Both | Returns code and chat to the chosen point |
One caveat: /rewind reverts file edits, not external side effects. A git push, a package install, or a network call already happened and will not be undone. Checkpoints are automatic per prompt and persist across sessions, with old ones cleared after roughly thirty days.
Rewind to the last point where the result was right, then run the loop again with one smaller change.
A worked example
You ask for a summary of a config file and get a wandering paragraph that misnames two settings.
Two changes, one per run, each tied to a named gap. You never guessed. By run three you have a prompt you understand and can reuse, and you confirmed it by running it twice.
What should you not do when fixing a prompt?
- Do not add "please be accurate" or "do not make mistakes." These add tokens and change nothing. The model was already trying.
- Do not rewrite the whole prompt after one bad run. You throw away the parts that worked and learn nothing.
- Do not stack five constraints at once before testing any of them. Add the one the current gap needs.
- Do not accept the first good result as proof. Run it again on a fresh input.
- Do not paste a summary of an error. Paste the full error text. The detail you cut is often the clue.
Checklist
Before you decide a prompt is fixed:
- Did you read the actual output against the wanted output, not just skim it?
- Can you name the single gap in one concrete sentence?
- Did you change exactly one thing this run?
- Did the working prompt pass twice, on two inputs?
- Did durable constraints move into
CLAUDE.mdso they apply next time? - Do you know which change fixed it, so you can do it again?
A prompt that passes this list is not lucky. It is debugged, and you can explain why it works.