Task statement 3.5 · Claude Code configuration and workflows
Apply iterative refinement techniques for progressive improvement
You asked Claude Code for a migration script in packages/api that "normalises customer records". Three runs produced three different output shapes, each a defensible reading of the prompt.
share
When output is inconsistent, the natural move is more prose: more adjectives, a longer specification. That fails because the extra words restate the requirement in the vocabulary that was already read three ways. What fixes behaviour is something Claude can check against: an example to match, a failing test to pass, or an answer you gave before the code existed.
KnowledgeWho closes the loop
Claude stops when the work looks done, so if the only check is you reading the output, every mistake waits for you to notice it. In test-driven iteration you write the test suite first, covering expected behaviour, edge cases and performance requirements. Claude runs it after every change, and the failures tell it what "not yet" means without you saying so.
- You write the tests before any implementation exists.
- Claude implements, then runs the suite.
- The failures return, each named, with expected versus actual.
- Claude changes the code and reruns until the suite passes.
Two refinement loops
SkillExamples beat adjectives
Concrete input/output examples fix a prose description that is interpreted inconsistently. Two or three pairs show the transformation instead of describing it, including the ambiguous case, so no run has to guess. Toggle between the two prompts.
What you send
# the prompt Normalise the customer records in the migration script. Clean up the names and dates, and handle missing values sensibly.
# the prompt Normalise customer records. Examples: in : {"name":" ada LOVELACE ","dob":"3/7/1815"} out: {"name":"Ada Lovelace","dob":"1815-07-03"} in : {"name":"turing, alan","dob":null} out: {"name":"Alan Turing","dob":null}
What comes back
- Run 1 leaves the date as
3/7/1815. - Run 2 reads it as US ordering.
- Run 3 fills missing dates with
1970-01-01.
- Casing, name order and ISO dates are fixed by example.
- The null case is shown, so no run invents a date.
Prose description
Two worked examples
SkillSend the failure, not a new description
Once the suite exists, send its output back, not a paraphrase of it. The first version of the migration fails an edge case and a performance requirement:
$ pytest tests/test_migrate_customers.py -q
FAILED test_null_dob_stays_null
input {"dob": null}
expected {"dob": null}
actual {"dob": "1970-01-01"}
FAILED test_50k_records_under_2s: took 3.8 s
7 passed, 2 failed
Both failures arrive with their evidence, so neither needs interpreting, whereas "handle nulls better" repeats the vague words that produced the bug. When one edge case is wrong and everything else passes, the three lines under the null test are the specific test case to send: input, expected output, actual output. If you have corrected the same issue twice, clear the session and restart with a prompt that includes what you learned, because the failed attempts left in context compete with the next one.
SkillLet Claude interview you first
Tests and examples assume you know what correct output looks like, which in an unfamiliar domain you often do not. The interview pattern is a prompt that has Claude ask you questions before implementing, so it surfaces considerations you had not anticipated. Here nobody on the team has built a cache before:
# the prompt I want a cache in front of the customer lookup in packages/api. Interview me in detail using the AskUserQuestion tool before writing any code. # two of Claude's questions Q1 When a record changes, how does the cache learn? (TTL expiry / delete on write / both) Q2 If the cache is down, fall back to the database or fail fast?
Q1 settles the cache invalidation strategy and Q2 a failure mode, which would otherwise be decided silently in code. Each answer can then become a test.
KnowledgeOne message or several?
Fixes interact when the right value for one depends on the others, so they go in a single detailed message that states the constraint linking them. The packages/web client calls packages/api inside a 2 s page deadline, but its timeout is 5 s, it makes three attempts even on 400 errors, and its pool was sized for 5 s connections. Cut the timeout alone to 1.5 s and three attempts still take 4.5 s. Independent issues share no constraint, so fix them sequentially and verify each, which keeps a bad fix easy to trace.
One message, with the shared rule
Fix these together. Total time, retries included, stays under 2 s. 1. timeout is 5 s 2. 3 attempts, even on 400s 3. pool sized for 5 s connections
Result: 600 ms timeout, one retry on 5xx only, pool resized.
One at a time
A log-line typo, then a stale comment in packages/infra, each verified before the next.
| Runs disagree on the output shape | Two or three input/output examples. |
| You can state correct results case by case | Tests first, then send the failures. |
| You cannot yet list what must be decided | The interview pattern, before any code. |
- A fourth adjective does not fix inconsistent output, but two or three concrete pairs do.
- After a failing run, send the failure itself: input, expected, actual.
- Fixes that constrain each other go in one message with the rule linking them.