Claude Code Plan Mode: Explore, Plan, Code, Commit
On this page
Learning Objective
Use a structured workflow for non-trivial changes: have the agent explore the code without editing, produce a plan you review and correct, implement in verified steps, and commit with a clear message. Use plan mode or an equivalent read-only phase to enforce the separation.
Concept Explanation
The most common failure in agent-driven development is premature implementation. The agent reads two files, forms a theory and starts editing, and twenty minutes later you have a large diff built on a misunderstanding. The fix is the same as with human engineers: think before you type, and agree on the approach before the work begins.
The explore, plan, code, commit workflow, recommended in Anthropic's Claude Code best practices, makes this explicit. In the explore phase the agent reads the relevant code, searches for usages and existing patterns, and reports what it found, without making changes. In the plan phase it proposes an approach: the files it will change, the order, the tests it will write, and the risks and open questions. You review the plan, which is short and cheap to correct, and push back on anything wrong. In the code phase the agent implements the approved plan, ideally step by step with tests run after each step. In the commit phase it commits with a message that explains what changed and why, and opens a pull request if appropriate.
Plan mode enforces the separation. In Claude Code, plan mode, entered with Shift+Tab or the --permission-mode plan flag, lets the agent read and analyze but blocks edits until you approve a plan. Other tools have equivalents: a read-only ask or chat mode, or simply instructing the agent not to edit until you say so. The enforcement matters because a model eager to help will otherwise start implementing as soon as it thinks it understands.
A good plan is specific. It names files and functions, lists the steps in order, says which tests prove each step, and calls out decisions that need your input, such as whether to add a database column or derive a value. A plan that says "update the relevant components" is not a plan. Ask for alternatives when the design choice is significant, and for the risks of the chosen approach.
Plans also have a second life. For larger work, ask the agent to write the plan to a file, such as plans/rate-limiting.md, with a checklist. If the session's context fills up or you need to continue tomorrow, a fresh session can read the plan file and pick up where the last one stopped. This is the bridge to spec-driven development (Day 10).
Not every task needs the full ritual. A typo fix or a one-line change can go straight to code. The workflow earns its cost when a change touches several files, involves a design decision, or affects code you do not know well.
| Phase | Agent does | You do | Edits allowed |
|---|---|---|---|
| Explore | Reads code, finds patterns and usages, reports | Answer questions, add context | No |
| Plan | Proposes files, steps, tests, risks | Review, correct, approve | No |
| Code | Implements step by step, runs tests | Watch, interrupt if it drifts | Yes |
| Commit | Writes a clear commit message, opens a PR | Review the diff before merge | Yes |
Worked Example: A Plan-Mode Session in Claude Code
These are the prompts of a session that adds soft delete to projects. The agent starts in plan mode, so it cannot edit until the plan is approved.
$ claude --permission-mode plan
> Explore how projects are deleted today. Find the delete endpoint, every query that
lists projects, and any background jobs that touch projects. Do not change anything.
[agent reads src/projects/*, greps for "prisma.project.", finds 9 queries and 1 cron job]
> Propose a plan to switch to soft delete (deleted_at timestamp). For each step list the
files, the tests you will add, and anything you need me to decide. Write it to
plans/soft-delete.md as a checklist.
[agent writes the plan; it asks whether deleted projects should still count toward plan limits]
> Answer: they should not count. Also, step 4 misses the search index sync job in
jobs/indexProjects.ts. Update the plan.
[agent updates plans/soft-delete.md; you approve the plan, which switches to an editing mode]
> Implement step 1 only (migration and model), run pnpm test -- src/projects, then stop.
... review, then "continue with steps 2 and 3", and so on ...
> All steps done. Run the full checks, then commit with a message that explains why we
moved to soft delete, and open a draft PR referencing issue #812.The correction about the search index sync job took one sentence at plan time. Found in review, or after release, it would have meant deleted projects reappearing in search results.
Real-World Examples
- Anthropic's "Claude Code: Best practices for agentic coding" recommends the explore, plan, code, commit sequence and notes that asking the agent to plan before coding significantly improves results on problems that require deeper thinking.
- Cursor, Windsurf and GitHub Copilot all added planning or read-only modes in 2025, reflecting the same lesson across tools: separating analysis from editing reduces large, misguided diffs.
Review Questions & Answers
Premature implementation, where the agent starts editing based on a partial understanding and produces a large diff built on a misunderstanding.
It lets the agent read and analyze the codebase but blocks file edits until you approve a plan, enforcing the separation between analysis and implementation.
It names specific files and functions, lists ordered steps, states which tests prove each step, and calls out decisions and risks that need your input.
A fresh session can read it and continue if the context fills up or work resumes later, and it doubles as a reviewable record of the agreed approach.