Plan with Cursor: an accepted plan before any code

The Cursor planning section is three guides for developers and tech leads that turn a goal into an accepted plan before the agent edits any file: starting a new project, designing a database schema, and choosing an architecture. Each guide uses Plan Mode, which Cursor describes as creating “detailed implementation plans before writing any code”.

You asked Cursor’s agent for “team invitations”, and an hour later the branch holds 30 changed files built on a roles table nobody agreed on. The code compiles; the shape is wrong. Planning moves your review to a one-page plan with testable acceptance criteria, and the diff is checked against that contract.

Prerequisite: Cursor installed and signed in, and your test, lint and type-check commands written into a project rule. If you have not done that yet, start with the Cursor quick start.

Which Cursor planning guide do you need?

Your situation	Start with	What you leave with
You are starting from an empty directory with a rough product brief	Start a new project with Cursor’s agent	A written PRD, project rules, and a running scaffold committed to Git
Your feature needs new tables, or you are changing a schema that holds data	Design a database schema with Cursor	`docs/data-model.md`, constraint tests and reversible migrations
You must choose between designs, or split or migrate a system	Design system architecture with Cursor’s agent	A signed ADR, a rule that carries it, and CI checks that enforce it
You have a feature request inside an existing codebase	Turn a PRD into a plan in Cursor	A plan and a todo list the agent works through

Run a planning session in Plan Mode

Use this sequence in any of the guides above. A plan is worth accepting only when a tool can check every claim in it.

Put the goal and its constraints in a file, such as docs/intents/FEATURE.md, so the plan has a source you can point at. The plan stage of the method defines what that intent file holds.
Open a new chat and switch the agent to Plan Mode. Paste the first prompt below. The agent reads code and writes a plan, ending with the open questions the prompt asks for; it edits nothing.
Answer the open questions in the intent file, not in chat, then ask for a revised plan.
Run the second prompt so a second pass attacks the plan before you accept it.
Leave Plan Mode and ask the agent to save the accepted plan as docs/plans/FEATURE.md before its first edit.
Build from that file one milestone at a time, on its own branch or worktree; see checkpoints and branching.

Read docs/intents/FEATURE.md and the code it touches. Do not edit any file.
Produce a plan with exactly these sections:
1. Current state: how the affected code works today, with path:line citations
   for every claim.
2. Acceptance criteria: 3-6 Given/When/Then statements, each mapped to the name
   of a test that fails before the change and passes after it.
3. Files to change, and files you must not touch (existing tests, migrations).
4. Milestones in order, each small enough to review and revert on its own.
5. Verification: the exact test, type-check and lint commands from the project rules.
6. Rollback: how to revert or switch the change off.
End with open questions instead of guessing.

Review the plan above against the codebase as a sceptical reviewer. Do not edit files.
- Check every path:line citation and list any that are wrong.
- Name any caller, background job, config or migration the plan misses.
- For each acceptance criterion, say how it could pass while the feature is broken,
  and tighten it.
- Flag any milestone that cannot be rolled back on its own.
Then output the revised plan with each change marked.

How do you check the result without reading every line?

The plan becomes the contract, and gates check the code against it:

Tests first. Each acceptance criterion names a test that fails before the change. A red-to-green run is evidence the behaviour changed; see executable acceptance criteria.
Scope. The diff touches only files in the plan’s scope list. git diff --stat main...HEAD shows that in one screen.
Machine gates. Type check, lint and the full suite are required CI checks; the agent’s local run is only a preview.
Sign-off. The developer accepts a feature plan; a tech lead accepts any plan that changes an architecture decision. After the build, reviewers read the plan, the test names and the CI result, and open the diff only where the evidence bundle is thin.

The reasoning behind this shift is in evidence, not diffs.

What goes wrong when you plan with Cursor?

Symptom	Likely cause	Recovery
The plan is a generic outline	The prompt named a goal, not sections and constraints	Use the first prompt and point it at the intent file
The plan cites functions that do not exist	Claims written from assumption	Run the review prompt and reject any plan with a wrong citation
The agent edited files during planning	The chat was not in Plan Mode	Discard the edits with `git restore .` (or `git stash`), then restart the chat in Plan Mode; see checkpoints and branching for Cursor’s own undo
Implementation drifts from the plan	The plan lived only in chat	Save it to `docs/plans/`, and start each build chat with “Follow docs/plans/FEATURE.md; stop and ask before deviating”
Each new chat re-litigates settled choices	Decisions were never written where the agent reads them	Record them in an ADR and a project rule, as the architecture guide shows

Where to go after the plan is accepted

Spec-driven development: make the spec, not the code, the thing people review.
The same stage in other tools: plan with Claude Code and plan with Codex.

Build with Cursor Next after an accepted plan: execute it milestone by milestone, on its own branch, behind the same gates