Apply iterative refinement techniques for progressive improvement

Claude Code is most effective when you treat it as a collaborator you steer across several turns, not a one-shot code generator. The first output is a draft. The leverage comes from how precisely you correct it, and the fastest teams do not converge by re-explaining the goal in different words. They converge by giving Claude sharper, more concrete feedback signals: worked examples, failing tests, and targeted questions.

The testable idea in this task statement is choosing the right feedback mechanism for the situation. Prose that keeps producing inconsistent results is a signal to switch to examples. A behavior that is hard to describe but easy to check is a signal to switch to tests. An unfamiliar domain is a signal to have Claude interview you first. These are prompting and workflow techniques, not CLI features. There is no special flag that turns them on.

When a prose description ("normalize the phone numbers", "default missing fields") is interpreted inconsistently across runs, the single highest-leverage fix is to show 2-3 concrete input to output pairs rather than rewriting the sentence. Examples remove the ambiguity that natural language leaves open: exact formatting, casing, how blanks versus nulls differ, what an edge row maps to.

This is the same principle as few-shot prompting from domain 4, applied to code transformations. Two or three examples is the sweet spot the blueprint cites: enough to pin the pattern, few enough to stay readable.

Input:  "(415) 555-0100"   Output: "+14155550100"
Input:  ""                 Output: null

If you find yourself typing the same prose instruction a third time with different adjectives, stop and give examples instead.

For behavior that is hard to describe but easy to verify, write the test suite first, covering expected behavior, edge cases, and performance requirements, then have Claude implement against it. You then iterate by pasting the actual failing test output back into the conversation.

A failing test is an unambiguous, machine-checked feedback signal. "test_blank_phone_becomes_null failed: got '' expected None" tells Claude exactly what to fix, which is far more effective than "handle blanks better." Tests also act as a regression guard, so a fix for one case cannot silently break a case that already passed.

def test_blank_phone_becomes_null():
    assert migrate({"phone": ""})["phone"] is None

Sharing the failure text, not a paraphrase of it, is the key move. The exact assertion and observed value are the highest-signal input you can give.

When a specific edge case is mishandled, provide a specific test case with example input and expected output rather than describing the bug abstractly. The blueprint's canonical example is null values in a migration script: instead of saying "it does not handle nulls," give the exact row and the exact expected result.

This is the debugging-time application of the examples principle. Abstract descriptions ("be robust to missing data") leave the model guessing about which of several plausible behaviors you want. A concrete case ("input {signup_date: null} should produce signup_date: \"1970-01-01\"") collapses that ambiguity to one answer and doubles as a permanent regression test.

Before implementing in a domain you do not know well, ask Claude to interview you: to ask clarifying questions that surface considerations you may not have anticipated. This front-loads design decisions instead of letting them get baked in implicitly and wrongly.

Before writing any code, ask me the questions you need
answered about requirements, edge cases, and failure modes.

Typical considerations the interview surfaces include cache invalidation strategy, failure and retry modes, concurrency and idempotency, and boundary conditions like timezones or pre-epoch dates. The pattern is most valuable precisely when you cannot fully specify the task yourself, because Claude's questions expose the gaps in your own mental model before code exists to throw away.

When you have multiple issues to fix, whether to send them together depends on whether they interact. Provide all issues in a single detailed message when the fixes interact, so Claude can reason about them together and produce one coherent change. Fix issues sequentially when they are independent, which keeps each change small and easy to review.

Getting this backwards causes trouble. If two bugs share a helper (say a coerce() function) and you fix them one at a time, each fix can reintroduce or break the other, producing regression whack-a-mole. Conversely, dumping ten unrelated issues into one message makes the diff hard to review and hard to attribute. The rule to memorize: interacting problems go in one message, independent problems iterate sequentially.