Why use plan mode instead of just asking Claude to build the feature?

Because the cheapest place to catch a wrong approach is in a paragraph, not in a 300-line diff. Plan mode makes Claude lay out which files it'll touch and in what order before writing anything, so you review the strategy while correcting it costs a sentence. For a one-line change it's overkill; for anything that touches multiple files or a path you care about, reading the plan first is the highest-leverage minute in the loop.

How much spec is enough before I start?

Enough to write down what "done" means — a one-paragraph summary, 4–6 acceptance criteria you could turn into tests, and an explicit list of what's out of scope. You don't need a formal PRD; you need a contract precise enough that you and Claude agree on the target and the tests have something concrete to pin. If you can't state the acceptance criteria, that's the signal the feature isn't defined yet, not that you should start coding.

What do I do if the plan Claude proposes is wrong?

Critique it in prose and ask for a revision — that's exactly what plan mode is for. Say what's wrong ("don't touch the auth path," "put this behind the existing flag," "split the migration into its own change") and have it re-plan before any code exists. Iterating on a paragraph is fast and cheap; the whole point is to get the approach right while it's still words, not a diff you have to unwind.

Does Claude write the tests too, and can I trust them?

Yes, it writes them — but "trust" is the wrong frame: you verify them. Have it write tests against each acceptance criterion, then read them and confirm each one asserts the behaviour you actually want, because a test that passes against a wrong assertion is worse than no test at all. The green suite is necessary, not sufficient — it proves the tests pass, and your review proves they're testing the right thing.

Ship a feature end to end — plan, build, test, commit

when to reach for this

A feature ticket lands and the easy move is to start typing — or to let Claude start typing — and find out an hour later that the approach was wrong, the diff is 300 lines, and nothing's tested. The better loop is boring on purpose: write down what "done" means, get the plan first and read it while it's cheap prose, then let Claude build behind a suite that proves it works. This is where the three engineering habits meet in one workflow — plan before the diff, prove it with tests, stay the author of record — so it's the loop worth making muscle memory.

gather this first

The repo open in Claude Desktop, with your CLAUDE.md in place (from the project-context playbook) so Claude already knows your conventions, your stack, and the exact command that runs your tests.
A clear, written description of the feature — what it does, who it's for — and a concrete way you'll know it's done (the acceptance criteria, even if rough).
Any real artifacts that pin the scope: the ticket, a design note, the API shape, an example payload. Give Claude the real thing, not your paraphrase of it.

the workflow

Write the spec and lock the scope

Open the folder in Claude Desktop and work the spec in the chat — no terminal needed. Before any code, get "done" in writing: what the feature does, the acceptance criteria, and explicitly what's out of scope. A locked scope is what keeps a 2-file feature from quietly becoming a 9-file one.

you ask

Here's the feature I want to build: [describe it]. Help me turn this into a short spec — a one-paragraph summary, 4–6 acceptance criteria phrased as testable statements, and an explicit "out of scope for now" list. Don't write any code yet.

what you get back A tight spec you can hold in your head — the behaviour, the criteria you'll test against, and a non-goals list. This is the contract the rest of the loop is measured against.

The "out of scope" line is doing real work. Naming what you're not building now is the cheapest way to stop scope creep before it starts.
Get the plan first — and critique it in prose

Turn on plan mode and ask for the approach before a single line is written. Reading a wrong plan in a paragraph costs you a minute; unwinding a wrong 300-line diff costs you an afternoon. Push back on the plan in plain language until it's right.

you ask

Use plan mode. Given this spec, lay out the implementation plan: which files you'll touch and why, the order of changes, the data/types involved, and where the tests go. Don't write code — I want to review the approach first.

what you get back A step-by-step plan you can actually evaluate — files, sequence, and the test strategy — before any diff exists. If the approach is off, you catch it here for the price of a sentence.

Critique it like a design review: "this touches the auth path — don't," "do it behind the existing flag," "split the migration out." Correcting prose is cheap; correcting a diff is not.
Approve the plan and watch the diffs land

Once the plan is right, let Claude implement it. In Claude Desktop each change comes back as a visual diff you accept or reject right in the chat — so you're reviewing as it builds, not rubber-stamping a wall of code at the end.

you ask

The plan looks right — go ahead and implement it. Work in small steps and show me each change as a diff before moving on, so I can accept or reject as you go.

what you get back The feature taking shape as a sequence of readable diffs you accept or reject in the file pane — not one giant change dropped at the end. You stay in the loop while it does the typing.

Accept/reject per change is the point of Desktop here. If a diff drifts from the plan, reject it and say why — don't accept it and plan to fix it later.
Make it prove the new behaviour

A feature with no test is a claim, not a feature. Get tests that pin the new behaviour and the edge cases the spec implied, then run the suite green. The passing tests are the receipt that the criteria from step one are actually met.

you ask

Now write tests that pin the new behaviour against every acceptance criterion, plus the obvious edge cases — empty input, the boundary values, the error path. Run the full suite and show me it's green.

what you get back A test file that maps onto your acceptance criteria, a green suite, and any edge case the spec didn't name surfaced for you to rule on. Running the suite is a Power-Track step — it needs a terminal-enabled session — but the tests themselves are written and reviewed in Desktop.

Cross-check the tests against the criteria yourself: a test that passes against the wrong assertion is worse than no test. "It passes" only counts once you've confirmed it's testing the right thing.
Read the whole diff and commit in logical chunks

Before anything lands, read the full diff end to end — you're the author of record, and git blame will have your name on it. Then commit the work in small, logical chunks with messages that explain why, not just what.

you ask

Show me the complete diff for the whole feature so I can read it end to end. Then stage and commit it in small logical chunks — one concern per commit — and draft a message for each that explains why the change exists, not just what it does.

what you get back A final diff you've actually read, then a clean little stack of commits — each one coherent, each message explaining the reasoning — a history you'd be happy to git blame in six months.

Reviewing the full diff is non-negotiable even when every step looked fine in isolation. The whole is where an unintended interaction hides.

make it your own

Spike, then rebuild: if you don't yet understand the problem, ask for a throwaway prototype first to learn the shape — then discard it and run this loop properly with a real plan. The spike is for learning, not for shipping.
Feature-flag the rollout: ask Claude to put the new path behind a flag so you can merge early and turn it on deliberately — smaller, safer diffs and an instant kill switch if it misbehaves in production.
Capture the shape as a slash command (Power Track): once you've run this loop a few times, the recurring feature-shape (spec → plan → implement → test → commit) is worth saving as a reusable /feature slash command so the next one starts pre-structured (see the Features tab).

watch out for

A plan you didn't read is a diff you'll have to unwind. The whole value of plan mode evaporates if you approve the plan unread — read it, push back, then approve. Correcting an approach in prose is an order of magnitude cheaper than in code.
"It passes" is not "it's done." A green suite proves the tests pass, not that the code is right — you still read the full diff, and you still confirm the tests assert the right thing. Confidence in the output is not evidence.
Keep the scope locked or it gilds the lily. Left open-ended, the agent will keep "improving" adjacent code you never asked it to touch. The non-goals list from step one is your defense — point back at it.
Proprietary specs stay in-boundary. The ticket and design docs may carry customer data, internal architecture, or anything under NDA — keep them in an environment your company approves, and remember the open folder is the boundary Claude reads from.

you'll end up with A feature that's planned before it's built, implemented behind a suite that proves it, tested against the criteria you wrote down, read line by line, and committed in a clean history — shipped the way a senior engineer ships, with Claude doing the typing and you owning every call.

Questions people ask

Why use plan mode instead of just asking Claude to build the feature?: Because the cheapest place to catch a wrong approach is in a paragraph, not in a 300-line diff. Plan mode makes Claude lay out which files it'll touch and in what order *before* writing anything, so you review the strategy while correcting it costs a sentence. For a one-line change it's overkill; for anything that touches multiple files or a path you care about, reading the plan first is the highest-leverage minute in the loop.
How much spec is enough before I start?: Enough to write down what "done" means — a one-paragraph summary, 4–6 acceptance criteria you could turn into tests, and an explicit list of what's out of scope. You don't need a formal PRD; you need a contract precise enough that you and Claude agree on the target and the tests have something concrete to pin. If you can't state the acceptance criteria, that's the signal the feature isn't defined yet, not that you should start coding.
What do I do if the plan Claude proposes is wrong?: Critique it in prose and ask for a revision — that's exactly what plan mode is for. Say what's wrong ("don't touch the auth path," "put this behind the existing flag," "split the migration into its own change") and have it re-plan before any code exists. Iterating on a paragraph is fast and cheap; the whole point is to get the approach right while it's still words, not a diff you have to unwind.
Does Claude write the tests too, and can I trust them?: Yes, it writes them — but "trust" is the wrong frame: you *verify* them. Have it write tests against each acceptance criterion, then read them and confirm each one asserts the behaviour you actually want, because a test that passes against a wrong assertion is worse than no test at all. The green suite is necessary, not sufficient — it proves the tests pass, and your review proves they're testing the right thing.