Explore, Plan, Implement, Commit

The single biggest mistake new Claude Code users make is the same one new engineers make: they start editing before they understand the code. Claude is fast and eager, so a vague prompt like "add rate limiting to the API" sends it straight into changing files — and if its picture of your codebase is wrong, you find out only after the diff is already wrong.

The fix is a discipline, not a feature: research first, then execute. Anthropic's recommended end-to-end workflow splits a task into four phases that map cleanly onto how a careful human works:

Explore   →   Plan   →   Implement   →   Commit
(read-only)  (draft)     (code + verify)  (commit + PR)

• Explore — Claude reads the relevant files and builds an accurate picture, without editing anything. You do this in plan mode (read-only).
• Plan — Claude drafts a detailed, step-by-step plan. You read it, correct misunderstandings, and approve.
• Implement — you exit plan mode and Claude writes the code, checking its work against a verifier (tests, build, types).
• Commit — Claude commits the change and opens a pull request.

The load-bearing idea is the seam between phases 2 and 3. A wrong plan costs you ten seconds to read and one sentence to correct. A wrong implementation costs a tangled diff, a burned context window, and a debugging session. Moving the checkpoint earlier — to text, before any edits — is what makes this workflow scale to changes that touch many files.

Exploration means letting Claude gather context — read files, search the codebase, trace how things connect — before proposing any change. You enforce this with plan mode, a permission mode in which Claude is read-only: it can explore and propose, but it cannot edit files or run mutating commands.

Enter plan mode any of three ways:

Now give Claude the task and let it read. Concretely, suppose you want to add an audit-log entry every time a user changes their email — a change that touches the route handler, the service layer, and the database model. In plan mode you'd say:

Explore how email changes are handled. Read the route, the user service,
and the model. Don't write any code yet — I want to plan this first.

Claude opens the relevant files, follows the call chain, and reports back what it found. Because it's read-only, nothing in your working tree changes. This is also where misunderstandings surface for free: if Claude says "the email update lives in legacy/user.py" and you know that file is dead, you catch it now, before a single edit.

Once Claude has explored, ask it to turn that understanding into a concrete plan. In plan mode it produces a detailed, step-by-step proposal — which files it will touch, what it will add, and in what order — and stops for your approval. Nothing is executed yet.

For our audit-log change, a good plan reads like a checklist:

Plan:
1. Add an `AuditLog` model in models/audit.py (user_id, field, old, new, ts)
2. In services/user.py, after a successful email update, write an audit row
3. Wire the route in routes/users.py to pass the actor + old value
4. Add tests in tests/test_user_email.py covering the new audit row
5. Run: pytest tests/test_user_email.py -q

This is the moment to steer. Read the plan critically:

• Did it miss a call site? Add it.
• Is step 1 in the wrong module? Tell it where the model belongs.
• Want a different test strategy? Say so now.

You can edit the plan in your external editor before approving with Ctrl+G (also Ctrl+X Ctrl+E). When the plan is right, exit plan mode (Shift+Tab) to approve and move to implementation.

Note the cost asymmetry one more time: every correction you make here is a one-line comment on text. The same correction made after implementation is a re-do of real code.

With the plan approved, exit plan mode (Shift+Tab) and let Claude execute. It now works through the plan's steps — creating the model, editing the service, wiring the route, adding tests — making real edits to your working tree.

The critical habit here is verification. Claude stops when work looks done; without a check, you become the verification loop, manually finding the bugs it left behind. Give it a verifier and it closes its own loop instead — running the command, reading the failure, fixing, and re-running until it passes.

That's why the plan ended with a test command. After implementing, Claude runs it:

pytest tests/test_user_email.py -q

If the suite is red, Claude reads the failure and iterates automatically. A build, a type-check, a linter, or even a screenshot diff all work the same way — any runnable signal that says "right" or "wrong" turns implementation from a hopeful one-shot into a self-correcting loop. For long unattended runs you can make the success condition explicit with /goal <condition> or a Stop hook.

This is also where the up-front exploration pays off: because the plan was correct, the implementation is mostly mechanical, and verification confirms it rather than rescuing it.

When the change is implemented and verified, hand the last mile to Claude too. Ask it to commit and open a pull request:

Claude writes a descriptive commit message, creates the commit, pushes the branch, and opens the PR (it uses the gh CLI under the hood for GitHub). The result is a reviewable unit of work with a real description — not a pile of uncommitted edits you have to summarize later from memory.

The payoff comes when you return to that work. A single change rarely ends at the first PR — review comments arrive, CI fails, follow-ups appear. You can resume the session linked to a PR with one flag:

claude --from-pr 123

This reattaches Claude to the conversation that produced PR #123 (works with GitHub, GitLab, and Bitbucket; you can pass a number or the full PR URL). All the exploration and decisions from the original session are right there, so addressing review feedback doesn't start from a cold, contextless prompt.

This workflow is a tool, not a tax. Forcing a full plan on a one-line change is pure overhead; skipping it on a sprawling refactor is how you get a bad diff.

Skip the plan phase for small, clear fixes — the change is so obvious that there's nothing to misunderstand:

• fixing a typo
• adding a log line
• a mechanical rename
• a one-line config tweak

For these, just describe the change and let Claude make it. A plan would only slow you down.

Use the full workflow when the change is multi-file, uncertain, or in unfamiliar code — exactly the situations where Claude's mental model is most likely to be wrong and where a wrong guess is most expensive to unwind:

The heuristic: plan when you'd want a design doc from a human. If a junior engineer could safely do the change without one, Claude can too.

The workflow assumes each session is about one coherent change. The fastest way to undermine it is the kitchen-sink session — fixing a bug, then drifting into a refactor, then asking an unrelated question, then starting a third feature, all in the same conversation.

Why it hurts: Claude's context window has a fixed budget, and everything competes for it. Old exploration from task one, a stale plan from task two, and unrelated file reads all crowd out the context that task three actually needs. As the window fills, quality degrades and Claude starts forgetting or conflating things across unrelated work.

The fix is one command: /clear between unrelated tasks. It empties the context so the next task starts clean, with a fresh, focused window. (Your prior conversation isn't lost — it's still resumable via /resume.)

So the real loop at the top level is: run Explore → Plan → Implement → Commit for one task, then /clear and start the next. Each task gets the whole workflow and the whole context window to itself.