Iterative refinement techniques

Examples beat description

When a prose description of a transformation keeps producing inconsistent results, the fix is usually not more prose. Two or three concrete input/output examples communicate the expected transformation far more precisely than a paragraph describing it.

This holds for edge cases too. Null handling in a migration script is much better specified by an example pair showing the input and the expected output than by a sentence about nulls.

Test-driven iteration

Write the suite first — expected behavior, edge cases, performance requirements — then iterate by sharing failures. Each failure is specific, reproducible, and unambiguous, which makes it far better iteration fuel than a description of what seems wrong.

A suite is re-run after every change. Instructions and examples in a message are read once, but a test checks the same requirement again each time the suite runs. Add a regression test when a previously fixed edge case keeps returning.

The interview pattern

Have Claude ask you questions before implementing. This surfaces considerations you had not thought to raise — cache invalidation, failure modes, edge conditions — and it's most valuable in domains you don't know well, precisely because that's where you don't know what you've failed to specify.

Batch or sequence?

The deciding factor is whether the problems interact.

• Interacting issues go in a single detailed message. Fixing them one at a time means each fix is made without knowledge of the others, and they undo each other.
• Independent issues are better sequenced. Smaller steps, clearer attribution when something regresses.

Interaction is the test, not ownership: two defects raised by two teams that touch the same code still go together.

Set limits on an automated loop

"Apply a fix, re-run the failing tests, refine until they pass" is reasonable by hand and risky to automate without a limit. Otherwise, only the runner timeout stops the loop. The job can consume all available runner time and block every change waiting behind it in a merge queue.

Choose the maximum number of passes before the run starts. Cap the passes and report the outcome even when tests still fail. “Still failing after three passes” gives the author useful information; an endless run doesn't.