Plan and specify: the contract before the code

Planning and specifying with AI agents means producing the contract an agent builds against: intent.md, a spec.md with numbered requirements, acceptance criteria that already exist as failing tests, architecture decisions and, for UI work, an accepted visual contract. A named human approves that contract before any code exists, and reviewers check the result against it instead of reading every line.

This section is for developers who hand work to Claude Code, Codex, or Cursor, and for tech leads who approve that work. The agent opens a 1,200-line pull request that compiles, passes its own tests, and solves a slightly different problem from the one in the ticket. Review turns into rediscovering the requirements from the diff. The pages here move that discussion to before the code, where it is cheap.

Which planning guide fits your problem?

Your situation	Start with
The spec goes stale the week after it is written	Spec-driven development
“Done” is argued about in review, not decided up front	Executable acceptance criteria
The agent quietly breaks layering or picks a new library	Architecture decisions agents can follow
A new UI flow needs agreement on states and breakpoints before coding	Four-artifact design-to-code pipeline
Design iterations never converge	Evidence-based rating loop
Product owners already write Gherkin scenarios	Behavior-driven development
Agents mix up domain terms across services	Domain-driven design
Sprint capacity is limited by review, not by coding	Agile workflows

In what order do the planning artifacts get made?

Match the artifact cost to the risk. A two-line bug fix needs a failing test, not an ADR. A new customer-facing flow needs all five steps.

1. Capture intent. Write the problem, outcome, affected users, and constraints in intent.md. The product owner accepts it. See capturing intent.md.
2. Write the spec. Turn accepted intent into spec.md with numbered requirements and open questions. See writing spec.md.
3. Make acceptance executable. Each requirement gets a Given/When/Then scenario and a test that fails now. Lock those tests against agent edits.
4. Record decisions that constrain code. Write a short ADR, plus a machine check where one exists, when the change touches architecture. See architecture decisions agents can follow.
5. Accept the visual contract. For UI work, approve a prototype or an annotated screenshot before implementation. See visual acceptance before frontend work.

Only then does the agent produce an implementation plan and start building.

How do you run a planning session in each tool?

Every tool has a planning mode in which the agent reads and proposes before it edits. Use it for steps 2 to 4, so the agent studies the codebase and drafts the contract before any file changes. Checked against Claude Code 2.1.283 and Codex CLI 0.157.1; Cursor from its documentation on 2026-08-28.

Claude Code

Start in plan mode from the terminal, or switch an open session with /plan or Shift+Tab:

claude --permission-mode plan

Plan mode is one of the permission modes. The session reads and proposes; it does not edit until you approve the plan. Tool-specific planning workflows are in planning with Claude Code.

Codex

Start codex in the repository and type /plan in the session. Codex drafts the plan before it writes code. Tool-specific planning workflows are in planning with Codex.

Cursor

Switch the agent to Plan Mode, which “creates detailed implementation plans before writing any code”. Tool-specific planning workflows are in planning with Cursor.

If you want a packaged spec workflow instead of hand-written files, see OpenSpec on spec-driven development and the planning skills in agent frameworks.

Copy-paste prompt: turn accepted intent into a reviewable spec

Read intent.md and the modules it names. Do not write or change any code.
Draft spec.md with:
- Scope and explicit non-goals.
- Numbered requirements (REQ-1, REQ-2, ...). Each one states observable
  behavior with concrete example values, not implementation.
- For each requirement, one Given/When/Then acceptance scenario.
- Open questions: every place where intent.md is ambiguous or where the
  codebase contradicts it. Do not resolve them yourself.
Finish by listing the files a change would touch and which requirement
each one serves. Stop and wait for my review.

Copy-paste prompt: attack the spec before anyone builds it

You are reviewing spec.md in a fresh session. You did not write it.
For each requirement, answer:
1. Could two competent engineers implement it differently and both claim
   it passes? Quote the ambiguous words.
2. Is the acceptance scenario able to fail? Name an implementation that
   would pass it while missing the intent.
3. What edge case (empty input, permissions, concurrency, time zones,
   partial failure) does it not mention?
Output a table: requirement ID, problem, proposed rewrite. Do not edit files.

How do you check a plan without reading it line by line?

Check the contract’s structure mechanically and spend human attention only on decisions.

• Traceability. Every requirement ID appears in at least one test name, and CI fails when one is missing. The spec-driven development page has the check.
• Tests fail for the right reason. Run the acceptance tests before implementation. Each should fail on missing behavior, not on a syntax error or a missing import.
• Independent critique. A fresh session runs the second prompt above. A human reads only the rows it flags.
• Open questions are closed or owned. A spec with an unowned open question is not ready.
• Named sign-off. The product owner approves intent and acceptance criteria. The tech lead approves ADRs. The design owner approves the visual contract.

The accepted contract then becomes part of the evidence bundle that the implementation pull request must satisfy.

What goes wrong when agents plan, and how do you recover?

Failure	Signal	Recovery
The plan is approved on a skim	Review of the pull request reopens scope	Approve requirements and scenarios, not the prose plan; run the critique prompt first
The agent edits acceptance tests to pass	Test files change in an implementation PR	Keep tests outside the agent’s edit scope with a CI guard: see protecting the oracle
The spec drifts from the code after merge	Behavior changes with no spec change	Require a spec delta in every behavior-changing PR
Planning costs more than the change	A one-line fix waits on a spec review	Scale artifacts to risk: a failing test alone for small fixes
UI is coded before visual acceptance	Rework after stakeholder demo	Gate implementation on an accepted prototype: see visual acceptance before frontend work

Where to go next after planning

• Prerequisite: the lifecycle view of Plan and Design, and where each tool fits in the tool map.
• Why specs replace diff reading as you climb the ladder: Level 4: you write the specs.
• Next stage: build with agents against the approved contract.