Plan Mode in Claude Code: Step-by-Step Guide and 4 Phases in 2026

Additional instructions are in the Ailoot documentation.

What is Plan Mode, and why isn't it enough on its own?#

In normal mode, Claude Code writes code immediately, and if you aren't keeping track, you can get a diff across many files out of nowhere. Plan Mode reverses the steps: first research and planning, then approval, then changes.

Anthropic describes Plan Mode in its official documentation this way:

It sounds simple, but it hides the main shift. Plan Mode changes the rhythm of work: agree first, then act. It is a change of mode, not a cosmetic tweak. The pain for vibe coders is that AI agents tend to rush. If you ask, “Add Google authentication,” in normal mode Claude will write the code in a minute, but half the files will be the wrong ones. In Plan Mode, the same request becomes a text plan that you can read in two minutes and correct before any code is touched.

Here is a trap that nobody writes about in international guides. Plan Mode on its own is a weak tool: the plan exists only in the current conversation. Close the window and the plan is lost. You can't hand it off to another agent. There are no versions or history. If the task is large (refactoring a 30-file module, migrating to a new database), the plan will quickly hit the context window's ceiling and start to degrade.

That's why Plan Mode works well together with a plans/ folder in the repository. The plan is saved as plans/2026-05-21-google-oauth.md, broken into phases with checkboxes, and any next agent can pick it up. That's how context engineering works—managing context before the prompt, not during it.

How do you enable Plan Mode in Claude Code?#

The quickest way during a session is the keyboard:

Shift+Tab           # cycles through modes: default → acceptEdits → plan

After two presses, the indicator ⏸ plan mode on will appear at the bottom of the terminal. A third press returns to normal mode. This is the most convenient method—you switch on the fly when you see the task growing.

The second method is to add a prefix before a single prompt:

/plan write a plan to migrate the database from MySQL to Postgres

This option is useful when you're in auto-accept mode and don't want to change it for the entire session. One request in Plan Mode, and then work continues as before.

The third method is at session launch:

claude --permission-mode plan

Use this when you know in advance that a task needs planning. For example, before a major refactor or migration.

The fourth method is to set the default in .claude/settings.json in the project:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

When is this useful? When a team is working on a complex system where any change could affect adjacent modules. Then the default Plan Mode protects everyone from accidental changes.

A fifth trick that's often overlooked: Ctrl+G opens the plan in a text editor. Use it when the plan is almost right, but you need to rephrase 2-3 points or add a constraint. Edit it manually, save, and Claude will continue with your version.

What are Anthropic's canonical 4 phases in Plan Mode: Explore, Plan, Implement, Commit?#

Many guides describe 3 phases (Explore-Plan-Execute) or just 2 (Plan-Implement). These are simplifications. In its official best practices guide, Anthropic describes exactly 4 phases. The difference matters: Commit as a separate phase makes you record the result instead of leaving it at “I made a few more tweaks here, I'll commit later”—the most common source of lost work.

The more precise the plan, the fewer iterations implementation takes. If you spend 10 minutes on the plan, implementation takes one prompt. If you sketch the plan in a minute, implementation will take an hour of fixes.

Here's what the 4 phases look like for adding Google OAuth (an example from Anthropic Docs):

Prompts are different in each phase, too. In Explore: “read /src/auth and understand how we handle sessions and login”. In Plan: “I want to add Google OAuth. What files need to change? Create a plan”. In Implement: “implement the OAuth flow from your plan, write tests, run the suite and fix failures”. In Commit: “commit with a descriptive message and open a PR”.

An important nuance: Plan Mode does not prevent Claude from running commands for research. Read, LS, Glob, Grep, web fetch, and shell commands for exploration are allowed. Only Edit, Write, and any mutating filesystem operations are prohibited. This means Claude can read the project structure, run git log, and look at tests—but it won't be able to accidentally change anything.

How do you read Claude's plan and decide whether to approve it?#

When Claude has finished creating a plan, it shows options for what to do next:

• Approve and start in auto mode
• Approve and accept edits
• Approve and review each edit manually
• Keep planning with feedback
• Refine with Ultraplan (browser review)

Knowing whether to approve a plan is the key skill in Plan Mode. It's easy to press “Approve” automatically and then have to revert commits. The AI sycophant wants to give a quick answer, and you want to get to the code faster. Both of you are wrong.

A good plan meets 7 criteria:

1. Specific file names. Not “I'll update auth,” but “I'll change src/auth/login.ts:42-58, create src/auth/oauth-callback.ts, and update src/auth/session.ts:103.”
2. The sequence is specified. The plan is divided into phases or steps, rather than “I'll do all this somewhere.”
3. External dependencies are named. If the task requires a new library, it's listed. If environment variables are needed, they're listed.
4. Risks are listed. A good plan says, “The migration may break existing sessions; X needs to be checked.” A bad one is silent about side effects.
5. There are success criteria. “The test/auth tests pass, the linter is clean, and the dev server starts without errors.”
6. There are no “pulled-out-of-thin-air” assumptions. If Claude says “I'll use library Z,” check: did you even install it in the project? If the AI made it up, you'll see that it isn't mentioned in package.json.
7. The plan fits on the screen. If Claude's plan takes up 200 lines for a simple feature, the task is probably too large for one plan. Break it into parts.

When a plan fails the check, there are three options:

• Keep planning with feedback—give Claude a specific comment about what you don't like, and it will rewrite the plan.
• Ctrl+G—open the plan in an editor, edit it manually, and save. Claude will continue with your version.
• Refine with Ultraplan—the plan goes into Claude Code on the web's browser mode, where you review sections and comment, then run it locally or in the cloud.

If something goes wrong mid-implementation, don't force it. Return to Plan Mode and rewrite the plan. That's 10 times cheaper than reverting 40 commits later.

Plan Mode + a plans/ folder: a combination for long context#

Plan Mode is a Claude Code mode. The plans/ folder is a methodology built on top of it. If you use Plan Mode without a folder, you'll hit the ceiling after an hour of work.

Here's the logic. Claude's context window is the session's memory. It can fit 1 million tokens in Opus 4.7, but that's the volume of your entire conversation. If you plan a complex task in one conversation, then ask it to implement, then discuss a bug, then something else, the window gets “inflated.” Claude starts forgetting early decisions, confusing contexts, and asking questions again.

The solution is the golden rule: one task—one conversation.

Here's how to do it:

1. Conversation 1—form the plan. Enable Plan Mode, describe the task, and Claude creates a plan. Save the plan in plans/2026-05-21-feature-name.md. Close the window.
2. Conversation 2—divide it into phases. Open a new chat. Ask: “take plans/2026-05-21-feature-name.md and divide it into phases.” Save the updated file.
3. Conversation 3—implement phase 1. Open a new chat. Ask: “implement Phase 1 from plans/2026-05-21-feature-name.md, and check off items as you complete them.” Close the window.
4. Conversation 4—implement phase 2. Do the same.

What does this do for you? The context window of each conversation stays fresh. Claude in phase 3 doesn't know the details of phase 1, but it knows the plan because the plans/ file lives in the repository. Any next agent (whether a subagent, a new session, or a run via /goal) can pick up the plan and continue.

Comparison of approaches:

When each feature has its own plan file and you need to remember three months later why you chose one payment provider over an alternative, you can open the relevant plan and read the decision history: what was discussed, which options were considered, and why this particular path was chosen.

These are living work plans; static documentation goes stale in a matter of months.

How can you get Claude to work while you sleep using Plan Mode and /goal?#

The main limitation of long AI sessions isn't the model itself, but the person pressing Enter. Every time Claude reaches the end of a turn, it waits for your response. /goal removes that wait.

The syntax is simple:

/goal all tests in test/auth pass and lint is clean, or stop after 20 turns

The condition can be up to 4000 characters. One goal per session. After every turn, the Haiku mini-model looks at the transcript and decides: “condition met—finish” or “not met—next turn.” The evaluator doesn't call tools; it only reads.

Aliases for clearing it: /goal stop, /goal off, /goal reset, /goal none, /goal cancel.

The combination with Plan Mode looks like this:

1. Enable Plan Mode (press Shift+Tab twice).
2. Ask: “create a plan to migrate the database from MySQL to Postgres, save it to plans/2026-05-21-postgres-migration.md with phases and criteria.”
3. Review the plan, edit it, and approve it.
4. Exit Plan Mode (press Shift+Tab once more).
5. Set a goal: “complete all phases in plans/2026-05-21-postgres-migration.md, check off the boxes, all tests pass, or stop after 50 turns.”
6. Close your laptop and go to sleep.

In the morning, check the result: either “✓ goal completed” or “◎ stopped after 50 turns,” with a history of what was done.

There are three essential rules for /goal, or you'll waste tokens:

Rule 1: A measurable final state. “Make it look nice” is bad. “npm test returns 0, npm run lint returns 0, and an entry has been added to CHANGELOG.md” is good.

Rule 2: Explicit verification. The condition should refer to something verifiable: a command, file, or endpoint. Not “everything works,” but “curl localhost:3000/api/users returns 200.”

Rule 3: Limit the number of turns. Always add or stop after N turns. Anthropic explicitly recommends in the documentation:

If you enable /goal without or stop after, your budget could disappear overnight.

What 4-step cycle turns Plan Mode into an engineering process?#

A common mistake is asking “how do I fix it?”: Claude gives a solution, you apply it, but nothing works or things get worse. This is the “AI sycophant”: it's trained to answer quickly, and you want to get to the code faster. A 4-step cycle addresses this.

The 4-step cycle blocks this mode. It is used sequentially within one Plan Mode session:

Step 1. Establish facts without a solution.

Prompt: “I'm experiencing the following: [symptom description]. Your task now is to establish the facts. Any solutions, ideas, and advice are prohibited. Only: what I observe, what steps are reproducible, what data is available, and what data is missing. Hard stop condition: DO NOT propose solutions; only record the diagnosis.”

This blocks the AI's first impulse: “here's the solution.” Claude has to stop at “what is known and what is unknown.”

Step 2. Develop options with precedents.

Prompt: “Now that the diagnosis is established, find precedents online for solving similar problems. At least 3 different approaches. For each: a link to the primary source, a brief description, and pros and cons for our situation.”

This blocks the AI's second impulse: “make up a solution off the top of my head.” We make it go out into the world and bring back approaches that can be checked.

Step 3. Detailed plan with risks.

Prompt: “Take the best option from Step 2 and lay out a detailed plan: which specific files to touch, what to add, what to remove, which tests to write, what could break, and what risks lie 2-3 steps ahead.”

This is the familiar Plan phase, but with one difference: it is based on the verified options from Step 2, not Claude's guesses.

Step 4. Self-check the plan.

Prompt: “Now do a mandatory self-check. Honestly recheck your plan: are there places where you pulled something out of thin air and didn't verify it against code, documentation, or a precedent from Step 2? If so, mark them and revise the plan.”

This is the final filter. Claude has to check its own reasoning and admit where it hallucinated. At least 2 plan items are usually revised in this step.

After the 4 steps, the plan is ready for approval. You move to implementation confident that the task is understood, options have been weighed, and risks considered.

This methodology is meant for diagnosing difficult bugs and making architectural decisions—where the cost of an error is high. Applied to Plan Mode, it removes the main pain of vibe coders: “the AI gave me a solution, I applied it, and everything broke.”

Which 5 ready-to-use prompts work in Plan Mode for common tasks?#

Template 1. Refactoring a module.

I'm enabling Plan Mode. Task: refactor the {module-name} module.

Step 1: Study the current structure of the {module-path} module. Describe:
- which files are part of the module
- which external dependencies it has
- which parts are duplicated
- which functions are overcomplicated

Step 2: Find 2-3 examples online of refactoring similar modules.
At least 1 source must be official Anthropic or related framework documentation.

Step 3: Create a refactoring plan in plans/YYYY-MM-DD-refactor-{module}.md:
- which files to rename
- which functions to extract into separate modules
- which tests to keep and which to rewrite
- risks: what could break for users

Step 4: Self-check. Are there any assumptions in the plan that are "pulled out of thin air"?
Rewrite or remove them.

Template 2. Database migration.

I'm enabling Plan Mode. Task: migrate the database from {old} to {new}.

Step 1: Study the current database schema using {schema-reading-command}. Describe:
- which tables exist and their size
- which relationships, indexes, and constraints there are
- where migrations are stored
- which data is critical

Step 2: Find precedents for {old → new} migrations in production projects.
At least 3 different approaches: pg_dump, dual-write, blue-green.
For each, list the pros and risks for our data size.

Step 3: Create a migration plan in plans/YYYY-MM-DD-db-migration.md:
- phases (backup, migration, verification, switchover)
- success criteria for each phase
- rollback plan if something goes wrong
- downtime or no downtime

Step 4: Self-check. Are all figures supported by documentation?
Have all steps been mentally checked against the dev environment?

Template 3. Adding a new feature.

I'm enabling Plan Mode. Task: add the {description} feature to the project.

Step 1: Study how similar features currently work in the project.
Specifically, look at:
- {file-1}
- {file-2}
- which architectural patterns are used
- which tests are written for similar features

Step 2: Find how this feature is implemented in open-source projects
with a similar architecture. At least 2 different approaches.

Step 3: Create a plan in plans/YYYY-MM-DD-feature-{name}.md:
- list of new files
- list of changed files with specific lines
- implementation sequence
- which tests to add
- what to add to CLAUDE.md as a rule for future sessions

Step 4: Self-check. Does the plan follow the project's architecture?
Does it assume libraries that haven't been installed yet?

Template 4. Writing tests.

I'm enabling Plan Mode. Task: cover the {name} module with tests.

Step 1: Study the {path} module. Identify:
- public functions and their signatures
- internal functions we will NOT test (implementation details)
- edge cases: empty input, errors, concurrent access

Step 2: Find test examples for a similar class of tasks
in popular open-source projects using the same framework.

Step 3: Create a test plan in plans/YYYY-MM-DD-tests-{module}.md:
- for each public function, a list of tests
- which mocks are needed
- which fixtures
- which verification approach (assertion style)

Step 4: Self-check. Do all tests check behavior rather than implementation?
Does the coverage include edge cases?

Template 5. Debugging a complex error.

I'm enabling Plan Mode. Task: understand the cause of the error {symptom-description}.

Step 1: ESTABLISH THE FACTS. Solutions and ideas are prohibited. Only:
- what I observe (exact wording of the error)
- reproducible steps
- what data is available (logs, traces, library versions)
- what data is missing (what needs to be collected additionally)

Step 2: Find precedents for this error. For each of three sources, provide a brief summary of the solution. Search official documentation and official maintainer repositories; use third-party forums only when necessary and clearly label them.

Step 3: Create a diagnostic plan in plans/YYYY-MM-DD-bug-{name}.md:
- which hypotheses to check (sorted by likelihood)
- which commands/scripts to run to check each one
- the expected result of each check

Step 4: Self-check. Are there any hypotheses in the plan that are "pulled out of thin air"?
Are all hypotheses tied to facts from Step 1?

Copy each template, replace {parameters} with your own, and paste it into Claude Code in Plan Mode. The result is a working plan in plans/ that you approve and use for implementation.

Plan Mode vs. normal mode: which should you choose?#

Anthropic says this directly in its documentation:

Skip a separate plan only when the actual diff is small, understood, and low risk. Use planning when you need to discover the approach or coordinate risky changes across components. Knowing the filenames or being able to summarize the goal in one sentence does not remove migration, authentication, or data-integrity risks.

Decision table:

Before choosing the mode, ask whether the approach, side effects, and verification are understood. Work directly on a small, localized, low-risk change with an obvious check. Plan first when there is uncertainty, unfamiliar code, a migration, authentication, or coordination across components—even if you can already name all 3-5 affected files.

How do you combine Plan Mode + CLAUDE.md + subagents for reliable work?#

CLAUDE.md is a file that Claude reads at the start of every session, including Plan Mode. If CLAUDE.md says “never hardcode dates; always get them from the database,” the plan will never suggest hardcoding. If there is no such rule, the plan can suggest anything.

The combination works like this:

Layer 1. CLAUDE.md sets the rules.

The file specifies the project stack, architectural principles, prohibitions (“don't use deprecated APIs”), and requirements (“all emails go through a shared layout”). Detailed guide: How to configure CLAUDE.md.

Layer 2. Plan Mode applies the rules to the task.

When you enable Plan Mode and ask “add OAuth,” Claude reads CLAUDE.md, sees the rules (“store tokens in Redis, not the database”), and takes them into account in the plan immediately. The plan conforms to the project's architecture.

Layer 3. Subagents divide the work.

If the plan is divided into phases, each phase can be assigned to a separate subagent. Each subagent works in its own context window without cluttering the main one. The plan in plans/ remains the central source of truth: subagents read it, carry out their phase, and update the checkboxes.

What 7 mistakes break Plan Mode?#

Mistake 1. The plan exists only in the chat.

Symptom: you wrote a plan, closed the window, and need to return the next day—but nothing is there; the context is gone. Solution: always save the plan in plans/YYYY-MM-DD-feature-name.md in the repository. The chat is a desk; the file is an archive.

Mistake 2. All tasks are in one chat.

Symptom: in one session, you discuss auth, then a migration, then UI design, then a bug. The context window gets “inflated,” and Claude forgets earlier things. Solution: one task—one conversation. Finished the plan? Close the window. Starting implementation? Open a new one.

Mistake 3. One 3000-line plan with no phases.

Symptom: there's a plan, but it has no checkboxes or divisions. It's impossible to tell what's done and what isn't. Delegation is impossible. Solution: divide each plan into 3-7 phases. Each phase is a list of checkboxes with specific actions.

Mistake 4. No deep research before the plan.

Symptom: Claude proposes a solution off the top of its head because you didn't ask it to look for precedents. A week later, you find out open source has had a better approach for ages. Solution: Step 2 of the 4-step cycle—make Claude find 2-3 precedents online before it creates a plan.

Mistake 5. The AI sycophant gives a solution without a diagnosis.

Symptom: you ask “how do I fix error X?”, Claude gives a solution, you apply it, and nothing works or things get worse. Solution: always start with “establish the facts; solutions are prohibited.” Only after the diagnosis do you move on to options.

Mistake 6. Skipping the self-check.

Symptom: the plan looks plausible, but contains 2-3 “pulled-out-of-thin-air” assumptions (an invented library, nonexistent API, or wrong version). Implementation breaks on those points. Solution: Step 4 of the 4-step cycle—make Claude honestly recheck its plan and flag assumptions.

Mistake 7. Vague conditions in /goal.

Symptom: you set /goal make it look nice, leave it overnight, and wake up to find $200 of quota burned. Solution: use only measurable conditions with a verification command and a mandatory or stop after N turns. No “make it good” or “polish it up.”

The eighth mistake, which vibe coders make most often, is ignoring the very concept of a plans/ folder. Plan Mode without a plans/ folder is not a methodology; it's a toy. If you use Plan Mode but don't create files, you get 10% of its capabilities.

What should you do next after your first experience with Plan Mode?#

Three concrete steps in increasing order of difficulty:

Step 1. Configure CLAUDE.md, if you don't have one yet.

Without CLAUDE.md, Plan Mode works “in a vacuum”—Claude doesn't know the project's rules and proposes plans that break the architecture. Full guide: How to configure CLAUDE.md. A minimal CLAUDE.md is 50-80 lines describing the stack, rules, and prohibitions. Length is secondary. Specificity is what matters.

Step 2. Create a plans/ folder in the repository.

Add a plans/ folder to the project root. Agree on a naming format: YYYY-MM-DD-feature-name.md. Each plan gets its own file. After a month, you'll have 20-30 files; after six months, 100+. That's a living history of the project's decisions.

Step 3. Try /goal on one task.

Choose a task you usually do by hand for 30-40 minutes. Enable Plan Mode, create a plan, and save it in plans/. Exit Plan Mode. Set /goal complete all phases in plans/file.md, all tests pass, or stop after 30 turns. Close your laptop for an hour and do something else. Come back and check the result.

Those three steps are the minimum. This builds up gradually; don't try to put it all together in one evening. Start with CLAUDE.md, add plans/ after a week, and try /goal overnight after a month.

When you're ready, meet Ailoot.