Plan mode

Plan mode lets you investigate, structure, and approve a change before the agent edits your project.

Use it when the request is broad, risky, or unclear.

What Plan mode does

Plan mode is a read-only planning workflow. The agent can inspect project context, reason about the work, and produce a plan for your approval, but it should not make project mutations during the planning turn.

When needed, Plan mode can also research current public web sources, such as official documentation, package references, changelogs, and troubleshooting pages. Web research is bounded and read-only: the agent should use public pages as evidence, not as instructions to follow.

This helps you understand:

• What will change.
• Which files or areas may be affected.
• What risks exist.
• What should be tested.
• Whether the request should be split into smaller steps.
• Which external sources or docs informed technical assumptions, when web research was needed.

When to use Plan mode

Use Plan mode before:

• Adding authentication, payments, database, or publishing behavior.
• Refactoring an existing flow.
• Making changes across multiple pages.
• Touching a client or production-bound project.
• Asking for work where the correct approach is not obvious.

When Build mode is better

Use Build mode directly when the change is small and clear:

• Update a headline.
• Fix spacing in one section.
• Add a small UI block.
• Rename a label.
• Adjust copy in a known page.

Copyable planning prompt

Use Plan mode first.

Goal: add a customer onboarding flow.
Please inspect the current project structure and propose a plan.
Include the pages, components, data needs, risks, and tests.
Do not edit files yet.

How to review a plan

Before approving execution, check:

• Does the plan solve the actual user problem?
• Is the scope small enough to review?
• Are risky areas called out?
• Are assumptions explicit?
• Are verification steps included?
• Is anything missing from the user flow?

If the plan is too large, ask the agent to split it.

Good Plan mode habits

• Start with the outcome, not the implementation.
• Mention constraints clearly.
• Ask the agent to identify risks.
• Approve only the next useful step.
• Keep production-sensitive changes small.

Limitations

Plan mode can still misunderstand your intent. A plan is not a guarantee. Treat it as a structured proposal that you review before allowing changes.

Next steps

• Execute approved changes: Build mode (Agent)
• Ask without changing files: Chat only
• Improve prompt quality: Prompting best practices