The implementation loop

You have an evergreen spec. Now you ship.

The loop:

1. Define some items you’re mostly sure of
2. Have Claude build them
3. Test
4. Update the existing .md based on what was actually built and learned
5. Repeat

The skill is calibrating step 1: how much to define before letting Claude run.

“Mostly sure”: the calibration that matters

The loop doesn’t require certainty. It requires enough confidence to make the first attempt worth making. Underdefined tasks produce drift; overdefined tasks eat a day before any code ships.

A useful heuristic: define enough that you could describe the expected result in one paragraph before Claude starts. If you can’t, you’re not yet mostly sure. Ask Claude to help you get to mostly sure before implementation.

Signs a task is ready:

• You can name the files that will change (at least the main ones)
• You can describe the behavior change in plain English
• You know what “done” looks like: a passing test, a rendered UI, a valid output

Signs a task isn’t ready:

• You’re hoping Claude will figure it out
• The spec doesn’t describe what you’re about to build
• You’re mixing multiple changes and not sure which comes first

One-line prompts vs. plan mode

Not every task needs a formal plan. Calibrate:

• One-line prompt: small, scoped, obvious. “Add an updated_at timestamp to the sessions table and update the writer.” Claude reads the schema, writes the migration, updates the code. Done in minutes.
• Multi-turn conversation: non-trivial but still familiar. You describe intent, Claude proposes an approach, you refine, Claude implements.
• Plan mode: genuinely complex, unfamiliar, or spec-adjacent. Use when you want Claude to explicitly surface its approach before writing any code, so you can correct it cheaply.

The mistake is over-planning small tasks (you pay a tax for no benefit) or under-planning big ones (you pay the tax when the implementation drifts).

Updating the spec is part of the loop

Step 4, “update the .md based on what was built,” is the most-skipped step and the one that matters most.

When you skip it, the spec drifts out of sync with the code. Next session, Claude reads a spec that describes a product that no longer exists, and it produces code based on that stale picture. Errors compound.

When you keep it, the spec stays the source of truth. Claude’s next session starts from an accurate picture.

Specific things to update:

• Any architectural decision you made or changed during implementation
• New concepts introduced (a new data type, a new flow, a new integration)
• Constraints discovered during implementation (rate limits, edge cases, browser quirks)
• What you tried that didn’t work, sometimes more valuable than what did

Recognizing drift

Drift happens when code and spec diverge. Signs:

• Claude asks about behavior that the spec already describes: it can’t find or parse the relevant section
• Claude’s proposed implementation contradicts something in the spec: one of them is stale
• You’re fighting Claude to produce something simple: often the spec contains a constraint that’s no longer true

When you notice drift, stop. Don’t push through. Reconcile the spec first, then resume implementation.

Verify before you trust

The single most important habit inside the loop: don’t take Claude’s word for it.

Claude will tell you a change is done when it isn’t. It’ll report “tests pass” on a run that never happened. It’ll claim a feature works end-to-end after touching one file. These aren’t failures of honesty: the model is summarizing what it intended to do, and its summary gets out of sync with reality.

Counter the drift by making verification cheap and automatic:

• Run the thing yourself. Reload the page. Execute the command. Click through the flow.
• Read the actual diff. Don’t trust the narration; look at what changed in the files.
• Run the tests and read the output. “Tests pass” without evidence is only a claim.
• For UI changes, open the browser. Type-checking and tests don’t verify that the feature looks right or behaves right.

Set the expectation that every “done” is a claim to verify, and you’ll catch confident-but-wrong states before they accumulate. The spec-to-code loop only runs forward when step 3 (test) is rigorous.

Failure modes

Common patterns that break the loop:

• Skipping step 4. Spec rots. Every subsequent session gets harder.
• Running the loop without a spec at all. Works for small things; produces inconsistent output on anything sustained.
• Over-defining step 1. You write the implementation in prose, then Claude translates it to code. Net zero gain.
• Taking “done” at face value. See the section above; always verify.