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.

Why it's tested

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.

  1. You write the tests before any implementation exists.
  2. Claude implements, then runs the suite.
  3. The failures return, each named, with expected versus actual.
  4. Claude changes the code and reruns until the suite passes.

Two refinement loops

Comparison of an open refinement loop where the developer is the only verifier and a closed loop where a test suite provides the signal Claude iterates against Prose only: you are the check "normalise the customer records" Claude returns one defensible shape You read it and spot what is wrong OUTPUT YOU READ IT YOU RE-EXPLAIN ↑ A check Claude can run 1 Tests written first 2 Claude implements, runs the suite 3 Failures: expected vs actual SUITE AS THE SPEC TEST RUN 4 FAILURES FED BACK
On the left the requirement stays in your head, so every mistake waits for you. On the right, boxes 1 to 3 and the returning arrow (4) are the four steps above, and the requirement lives in a test file.

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

  1. Run 1 leaves the date as 3/7/1815.
  2. Run 2 reads it as US ordering.
  3. Run 3 fills missing dates with 1970-01-01.
  1. Casing, name order and ISO dates are fixed by example.
  2. The null case is shown, so no run invents a date.

Prose description

Two worked examples

Every run is a defensible reading of "sensibly". The prompt is not wrong, but it is under-specified, so each run resolves the ambiguity differently. The examples show the output instead of describing it, including the null case that "sensibly" left open, so every run returns the same shape.

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.

Interacting issues

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.

Independent issues

One at a time

A log-line typo, then a stale comment in packages/infra, each verified before the next.

Before you send another correction, ask: What would tell Claude it is not done yet?
Runs disagree on the output shapeTwo or three input/output examples.
You can state correct results case by caseTests first, then send the failures.
You cannot yet list what must be decidedThe interview pattern, before any code.
Takeaway
  • 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.

check yourself

0 / 3 answered

A team skill in packages/web turns commit messages into release-note lines. Its instructions say "write short, user-facing notes". Across five runs, one keeps ticket numbers such as WEB-412, one switches to past tense, and one groups lines by component. A release script runs the skill unattended, so nobody reviews a run before it publishes.What is the most effective change to the skill?

Select one.

You are adding rate limiting to the public endpoints in packages/api, and nobody on the team has built it before. Nobody can yet say whether limits apply per replica or across all three replicas, or what a client over the limit should receive, so no expected outputs can be written down.What is the most effective first step?

Select one.

A review of the deploy script in packages/infra finds four problems. The health-check wait is 120 s, but the pipeline step times out at 90 s, and rollback starts only after that wait ends. A log message misspells "deployment". The README still documents a flag that was removed last month.Which TWO ways of sending these fixes best keep each fix correct and easy to verify?

Select two.

sources

  1. Claude Code Docs, "Best practices for Claude Code": "Give Claude a way to verify its work" (without a check, "you become the verification loop"; Claude "runs the check, reads the result, and iterates until the check passes"), example test cases inside the prompt, the "Let Claude interview you" prompt using the AskUserQuestion tool, and "After two failed corrections, /clear". Checked 2026-10-01.
  2. The four techniques, 2–3 examples, test suites covering expected behaviour, edge cases and performance requirements, cache invalidation strategies and failure modes, null values in migration scripts, and interacting versus independent issues: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 3.5. The monorepo layout is this course's Scenario 2 detail.