CCAR-F 3.5 — Iterative refinement

The refinement loop

Clear targetexamples, test cases, a screenshot, the exact error
Runnable checktests, build, linter, screenshot diff
Claude attemptsdoes the work, then runs the check
Read the resultpass → done; fail → specific fix

Each failure feeds a specific correction back in — not the same request, louder

The loop only closes on its own when step 2 exists. Without a check Claude can run, “looks done” is the only signal — and you become the verification loop.

Give Claude a way to check its own work

The Claude Code best-practices guide puts this first: Claude stops when the work looks done, and without a check it can run, looking done is the only signal available. Give it something that produces a pass or a fail — a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a screenshot compared against a design — and Claude can do the work, run the check, read the result and iterate until it passes.

Instead of	Refine to
“implement a function that validates email addresses”	“write `validateEmail`. `user@example.com` is valid, `invalid` is not, `user@.com` is not. Run the tests after implementing.”
“make the dashboard look better”	“[screenshot] implement this design, screenshot the result, list the differences and fix them”
“the build is failing”	“the build fails with this error: [error]. Fix the root cause, don’t suppress it, and confirm the build passes.”

Ask for evidence, not assertions. The guide recommends having Claude show the test output, the command it ran and what it returned, or a screenshot of the result — reviewing evidence is faster than re-running the check yourself.

Tests first, then code

Tests are the most precise way to say what “correct” means. Writing them before the implementation turns an ambiguous request into a target that either passes or doesn’t, and every failure tells Claude exactly what is still wrong. The best-practices guide’s example prompt for a bug asks Claude to write a failing test that reproduces the issue, then fix it. For a larger change, it suggests having one Claude session write the tests and another write code to pass them.

Worked example · Shift-swap rules at a hospital

A hospital rota system needs a rule: nurses may swap shifts only if neither ends up working more than 60 hours in a rolling seven-day window, and night-to-day swaps need a 12-hour rest gap. The first attempt, from a prose description, gets the rolling window wrong.

Write the cases down. The engineer asks Claude to write tests first: a swap that pushes a nurse to 61 hours (reject), one that lands at exactly 60 (allow), a night shift ending 07:00 followed by a day shift at 18:00 (reject — 11 hours).
Confirm they fail. Claude runs the new tests against the current code; the rolling-window cases fail, as expected.
Implement to the tests. Claude changes the rule and reruns the suite. One boundary case still fails; the output shows an off-by-one on the window start.
Feed back the failure, not a feeling. The failing assertion goes straight back in; Claude fixes the boundary and the suite passes.
Guard against gaming the tests. The prompt says the tests verify correctness rather than define the solution, and asks Claude to say so if a test looks wrong instead of working around it.

Takeaway: A failing test is the most specific feedback you can give. It names the input, the expected result and the actual result in one line.

Show, don’t describe: concrete examples

When Claude keeps misreading a transformation or format, more adjectives rarely help. A few concrete input-and-output pairs show the pattern directly, including the edge cases a description glosses over. Anthropic’s prompting guidance recommends examples that are relevant, diverse enough to cover edge cases, and clearly marked off from the instructions (few-shot prompting is covered in depth in 4.2).

Refining a request: description versus examples

Vague, repeated more firmlytext

Normalise the order dates so they
are consistent. Make sure they're
all in the same format!! Handle the
weird ones properly this time.

Concrete input → output pairstext

Convert order_date to ISO 8601.
Examples:
"03/04/2025" (UK store) -> "2025-04-03"
"Apr 3 2025"            -> "2025-04-03"
""                      -> null, log it
Add these as test cases, then run
the tests.

The weak version leaves Claude to guess what “consistent” means. The strong version shows three concrete conversions, including the ambiguous and missing cases.

Worked example · A retailer’s order-import script

A retailer merges orders from its UK and US stores. Claude’s first version of the import normalises dates, but UK dates like 03/04/2025 come out as 4 March instead of 3 April. Two follow-ups saying “handle UK dates correctly” produce different wrong results.

Stop re-describing. The engineer recognises that the prose instruction is being interpreted in different ways each time.
Show the pattern. They give three input-and-output pairs, including a UK date, a US-style text date and an empty value.
Make the examples executable. They ask Claude to add the pairs as test cases before changing the code.
Result. The next attempt passes all three; the tests stay in the suite to stop the bug returning.

Takeaway: When a description is being interpreted inconsistently, switch to examples — and turn the examples into tests.

Let Claude ask before it builds

Some refinement should happen before any code exists. For larger features the best-practices guide suggests asking Claude to interview you in detail — about implementation, UI, edge cases, concerns and trade-offs — until everything is covered, then write a spec to a file. The interview surfaces questions you hadn’t considered, and a fresh session then implements against the finished spec with clean context.

Correcting course without drowning the context

Tight feedback loops beat long ones. Press Esc to stop Claude mid-action while keeping its context, so you can redirect. Press Esc twice or run /rewind to restore an earlier checkpoint of the conversation, the code or both. Ask Claude to undo a change. And when a line of attack has clearly failed, cut your losses.

Output isn’t right — what next?

What went wrong?

Format or pattern misread
Give examplesinput → output pairs, as tests
Behaviour wrong
Give a failing testor the exact error text
Heading the wrong way
Esc or /rewindredirect before it goes further
Two corrections failed
/clear and re-promptfold in what you learned

The documentation is specific about that last branch: if you have corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start again with a better prompt that includes what you learned; a clean session with a better prompt almost always outperforms a long one with accumulated corrections.

How you batch feedback matters too. When several problems are connected — a schema change that breaks a query that breaks a report — describe them together in one message so the fix is designed as a whole. When problems are independent, fixing and verifying them one at a time keeps each change small and each failure easy to trace.

Traps the wrong answers are built from

Tempting but wrong	Do this instead
Repeating a vague instruction more forcefully	Replace it with concrete input → output examples or a failing test.
Asking for a change with no way to check it	Give Claude tests, a build or a screenshot to verify against, and ask for the evidence.
Saying “it’s broken” or “the build fails”	Paste the exact error or failing assertion and ask for the root cause.
Correcting the same issue again and again in one long session	After two failed corrections, `/clear` and restart with a better prompt.
Letting Claude special-case the test inputs	Ask for a general solution and for Claude to flag tests it thinks are wrong.

You should now be able to

Give Claude a runnable check and ask for evidence of the result.
Use a test-first loop, feeding failing tests back as feedback.
Replace ambiguous descriptions with concrete input and output examples.
Use an interview to surface requirements before implementing a larger feature.
Choose between Esc, /rewind and /clear to course-correct.
Decide whether related issues should be fixed together or one at a time.

Iterative refinement