Claude Workflow

Spec-first feature build (workflow)

Stops the model from coding too early — lock a short spec and a test list before a single line is written.

LLM Mart · 0 points · 21 213

#workflow #planning #coding

## The problem Ask a model to "build feature X" and it dives straight into code. It guesses at the edge cases, invents an interface, picks an error-handling strategy, and decides where the files go — all plausibly, all in about ninety seconds, and all before you've had a chance to disagree with any of it. Then you spend the next hour undoing wrong assumptions, and every correction touches code that has already been written on top of the previous wrong assumption. The cost of a wrong assumption grows with how much has been built on it. This workflow front-loads the assumptions to the point where correcting one costs a sentence. ## The workflow Run these as **separate turns**. The stops are the entire mechanism — a version of this that runs end to end without pausing is just a long prompt, and it doesn't work. ### 1. Restate > Before any code: restate the feature in 3–5 bullets, and list every assumption you're making — > about existing code, data shape, error handling, scope, and who the user is. **Stop and wait.** Read the assumptions, not the restatement. The restatement is almost always fine; the assumptions are where the surprises are. Typical catches at this step: it assumed the feature is authenticated-only, or that a field is unique, or that the existing table can be altered. If the assumption list is short or generic, ask for more: *"List five assumptions you'd be embarrassed to have gotten wrong."* ### 2. Spec > Write a one-paragraph spec plus the public interface: signatures, inputs, outputs, and errors. > No implementation. **Stop.** Judge the *interface*, not the prose. Names, types, what's optional, what it throws or returns on failure. Interfaces are cheap to change now and expensive to change after step 4. Watch specifically for: error cases missing entirely, and success types that can't express partial failure. ### 3. Test list > List the test cases as plain-English names, including edge cases and failure modes. No code. > **Stop.** This is the highest-yield checkpoint in the workflow, because a test list is a specification you can scan in twenty seconds. Missing cases are visible as absences in a way they never are in prose. The standard omissions: empty input, the boundary value, concurrent access, the "already exists" case, the "user lacks permission" case, and whatever your domain's idempotency story is. Add them yourself if they're not there — you'll spot them faster than you can prompt for them. ### 4. Implement > Now implement to satisfy exactly that test list. If a case is ambiguous, **ask instead of > guessing.** By this point the model has the interface and the acceptance criteria, and the implementation is the easy part — which is why letting it start here in the first place was always the mistake. ### 5. Self-review > Review your own diff against the spec and the test list. Which planned items are done, which are > missing, and what did you add that wasn't in the plan? The third question catches scope creep, which is the most common way agent output diverges from what you approved. ### 6. Risk pass > List every assumption from step 1 that the tests do not actually verify. That list is your review checklist, and it's usually shorter and more useful than reading the whole diff line by line. ## Why it works Each stop is a cheap checkpoint. Correcting a wrong assumption in step 1 costs one sentence; correcting it after step 4 costs a rewrite. The workflow is really just a way of moving every decision to the point where reversing it is cheapest. There's a second effect that matters as much: **you end up understanding the feature.** A spec and a test list you reviewed are things you now know. A 400-line diff you skimmed is not. ## When to use it — and when not to **Use it for:** anything touching data models, money, permissions, or a public interface. Anything you'll have to maintain. Anything where "wrong" is expensive. **Skip it for:** a one-line fix, a throwaway script, a spike where the point is to learn what the problem even is. Ceremony on a five-minute task is pure cost, and applying this to everything is how a good workflow gets abandoned. ## Adapting it to your tools - **Claude Code / Codex CLI:** use plan mode for steps 1–3 — it's the same idea with tool support, and plan approval is a real gate rather than a convention. - **Copilot:** Plan mode for 1–3, then hand off to Agent mode for step 4. - **Cursor:** ask in chat for 1–3, then Composer for 4. Put "always produce a test list before implementing" in `.cursor/rules/`. - Whatever the tool, **keep the spec and test list in the PR description.** A reviewer who can see what was agreed reviews the change against intent instead of against taste. ## Failure modes - **It races ahead and writes code at step 1.** Restate the stop, more bluntly: "Output only the bullets and the assumption list. Do not write code." If it happens repeatedly, put it in the project instruction file. - **The assumptions are generic.** "Assumes the code compiles" is filler. Ask for assumptions specific to *this* feature and *this* repo. - **The test list is all happy path.** Ask directly: "What are the failure modes, and what happens at each boundary?" - **The implementation quietly diverges from the plan.** That's what step 5 is for — and if it diverged for a good reason, the plan was wrong, so update it rather than pretending it wasn't. - **You approve every step without reading.** Then this is a slower version of the thing you were trying to avoid. The workflow only pays if you actually stop.

The problem

Ask a model to "build feature X" and it dives straight into code. It guesses at the edge cases, invents an interface, picks an error-handling strategy, and decides where the files go — all plausibly, all in about ninety seconds, and all before you've had a chance to disagree with any of it.

Then you spend the next hour undoing wrong assumptions, and every correction touches code that has already been written on top of the previous wrong assumption.

The cost of a wrong assumption grows with how much has been built on it. This workflow front-loads the assumptions to the point where correcting one costs a sentence.

The workflow

Run these as separate turns. The stops are the entire mechanism — a version of this that runs end to end without pausing is just a long prompt, and it doesn't work.

1. Restate

Before any code: restate the feature in 3–5 bullets, and list every assumption you're making — about existing code, data shape, error handling, scope, and who the user is. Stop and wait.

Read the assumptions, not the restatement. The restatement is almost always fine; the assumptions are where the surprises are. Typical catches at this step: it assumed the feature is authenticated-only, or that a field is unique, or that the existing table can be altered.

If the assumption list is short or generic, ask for more: "List five assumptions you'd be embarrassed to have gotten wrong."

2. Spec

Write a one-paragraph spec plus the public interface: signatures, inputs, outputs, and errors. No implementation. Stop.

Judge the interface, not the prose. Names, types, what's optional, what it throws or returns on failure. Interfaces are cheap to change now and expensive to change after step 4.

Watch specifically for: error cases missing entirely, and success types that can't express partial failure.

3. Test list

List the test cases as plain-English names, including edge cases and failure modes. No code. Stop.

This is the highest-yield checkpoint in the workflow, because a test list is a specification you can scan in twenty seconds. Missing cases are visible as absences in a way they never are in prose.

The standard omissions: empty input, the boundary value, concurrent access, the "already exists" case, the "user lacks permission" case, and whatever your domain's idempotency story is. Add them yourself if they're not there — you'll spot them faster than you can prompt for them.

4. Implement

Now implement to satisfy exactly that test list. If a case is ambiguous, ask instead of guessing.

By this point the model has the interface and the acceptance criteria, and the implementation is the easy part — which is why letting it start here in the first place was always the mistake.

5. Self-review

Review your own diff against the spec and the test list. Which planned items are done, which are missing, and what did you add that wasn't in the plan?

The third question catches scope creep, which is the most common way agent output diverges from what you approved.

6. Risk pass

List every assumption from step 1 that the tests do not actually verify.

That list is your review checklist, and it's usually shorter and more useful than reading the whole diff line by line.

Why it works

Each stop is a cheap checkpoint. Correcting a wrong assumption in step 1 costs one sentence; correcting it after step 4 costs a rewrite. The workflow is really just a way of moving every decision to the point where reversing it is cheapest.

There's a second effect that matters as much: you end up understanding the feature. A spec and a test list you reviewed are things you now know. A 400-line diff you skimmed is not.

When to use it — and when not to

Use it for: anything touching data models, money, permissions, or a public interface. Anything you'll have to maintain. Anything where "wrong" is expensive.

Skip it for: a one-line fix, a throwaway script, a spike where the point is to learn what the problem even is. Ceremony on a five-minute task is pure cost, and applying this to everything is how a good workflow gets abandoned.

Adapting it to your tools

Claude Code / Codex CLI: use plan mode for steps 1–3 — it's the same idea with tool support, and plan approval is a real gate rather than a convention.
Copilot: Plan mode for 1–3, then hand off to Agent mode for step 4.
Cursor: ask in chat for 1–3, then Composer for 4. Put "always produce a test list before implementing" in .cursor/rules/.
Whatever the tool, keep the spec and test list in the PR description. A reviewer who can see what was agreed reviews the change against intent instead of against taste.

Failure modes

It races ahead and writes code at step 1. Restate the stop, more bluntly: "Output only the bullets and the assumption list. Do not write code." If it happens repeatedly, put it in the project instruction file.
The assumptions are generic. "Assumes the code compiles" is filler. Ask for assumptions specific to this feature and this repo.
The test list is all happy path. Ask directly: "What are the failure modes, and what happens at each boundary?"
The implementation quietly diverges from the plan. That's what step 5 is for — and if it diverged for a good reason, the plan was wrong, so update it rather than pretending it wasn't.
You approve every step without reading. Then this is a slower version of the thing you were trying to avoid. The workflow only pays if you actually stop.