Spec-driven development in Claude Code, Codex, Cursor, Grok

Nov 1, 2026

Spec-driven development writes the behavior and the check before an agent edits. How plan mode and goals support that in these four tools.

Spec-driven development means you write the behavior, the boundaries and the check before the agent edits. The spec can be a short prompt. It can be a file the repo already loads, such as AGENTS.md. No vendor documents a mode, a file name or a command by this phrase.

How spec-driven development works

An agent will fill gaps. If you say “add a field to the form” and stop, it picks the field name, the validation and the failure message. A spec says which of those are already decided.

You write three things. What the change must do. What it must not change. What you will run, or look at, to call it done. Then you ask for a plan against that text. You read the plan. Then it edits. Then you run the check you named, not a summary the agent wrote.

Plan mode is the control these tools document for the planning step. That entry has the per-tool limits, including where a shell command can still run while the agent explores. This entry does not restate the flags.

Spec-driven development in each tool

The practice is the same. The product support is plan mode, a goal with a verifiable end, and instruction files. There is no /spec command in the docs checked for this entry.

	Claude Code	Codex	Cursor	Grok Build
A mode named spec-driven	Not documented	Not documented	Not documented	Not documented
Documented planning step	Plan mode	Plan mode	Plan mode	Plan mode, and `/goal`
Where a standing spec can live	`CLAUDE.md`	`AGENTS.md`	A rules file	`AGENTS.md` or `.grok/rules/`
A check the tool runs for you	You name the command. `/verify` runs the app	You name the command	You name the command	`/goal` completes only when most reviewer subagents agree

Claude Code

Switch to plan mode, then paste the behavior, the boundaries and the check. /code-review is a later pass over a diff, not the spec. /verify runs the app to confirm a change works. Put a rule that every task must follow into CLAUDE.md. A rule that only this task cares about stays in the prompt. See Plan mode and the commands reference.

OpenAI Codex

Codex does not document spec-driven development. Plan mode is the documented pause before the edit. Codex reads AGENTS.md before it does work. Project instructions are concatenated from the repo root down to the current directory, and Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

Required team guidance belongs in that file. GitHub code review also looks there for repository-specific review rules. A one-off task does not belong in Codex memories. Memories are optional recall, and they are off until you enable them. See AGENTS.md and Plan mode.

Cursor

Cursor does not document spec-driven development. Plan mode is the documented planning step. A rule you want on every task belongs in a rules file. The rules entry covers where those files live.

For one task, put the behavior and the check in the prompt, and @ mention the files the change is allowed to touch. See Plan mode and @ mentions.

Grok Build

Grok Build does not document spec-driven development. Plan mode is one planning step. /goal is the other, and it is stricter about “done”.

The docs contrast a weak objective with a strong one. Weak: /goal Migrate the auth module to the new API. Strong: /goal Migrate the auth module to the new API, verified by the auth test suite passing, without changing public endpoints. You can add --budget and a token count. After the goal looks done, a panel of reviewer subagents checks the work, and the goal is complete only when most of them agree.

A standing rule still goes in AGENTS.md or in .grok/rules/. Those files load in full. See Modes and commands and Project rules.

Details checked against each vendor’s documentation in November 2026.

A real example

This is a spec for a real route on this site. The handler reads an email field and rejects an address that does not validate. The spec says that behavior stays, and it names the file the agent may read. Paste it after you switch to plan mode.

The newsletter form posts to /api/newsletter/subscribe.
The handler reads the email field and rejects an invalid email.

Do not add a second required field.
Do not change the list ids.

Done means an empty or invalid email is still rejected,
and a valid email still reaches the existing subscribe path.

Read functions/api/newsletter/subscribe.js.
Write the plan. Do not edit files until I approve it.

In Grok Build, the same constraints fit the strong /goal shape from the docs. Name the end state and what must stay true.

/goal Keep /api/newsletter/subscribe accepting only the email field, verified by an invalid email still being rejected, without adding a second required field.

When to use spec-driven development

Use it when the agent would otherwise invent a behavior you already decided. A form field, a status code, a file it must not touch, a test that must stay green.

Use plan mode for one change. Use AGENTS.md or CLAUDE.md when the same boundary applies to every later session. Use /goal in Grok Build when the task is long and you can say what “verified” means.

Skip the ceremony for a rename you can see in one file. A spec that is longer than the edit hides the change instead of bounding it.

Pitfalls

A plan is not a spec. If you approve a plan that invented the field name, you approved the invention. The behavior has to be in the prompt before the plan, or the plan becomes the spec by accident.

/goal without a check completes against a vague end state. The docs’ weak example is a migration with no test and no boundary. The strong example names the test suite and the public endpoints that must not change. Copy that shape.

Codex cuts project AGENTS.md instructions at 32 KiB by default. A spec you buried at the bottom of a long file can be past project_doc_max_bytes and never load. Put the standing rules near the start, or raise that limit.

Agent memory is the wrong place for a spec. It is per machine, it can be off, and a teammate’s session will not see it. A spec the next session must follow belongs in a file the tool loads from the repo.

Plan mode is not a guarantee that nothing runs. The plan-mode entry notes that Claude Code can run shell commands while it explores, and that Grok Build blocks edit tools while shell commands still follow your permission mode. Read the plan, and read the command, before you approve either.

How to document project decisions is the written reason a boundary exists, which is the part a spec should keep.
Give your coding agent a state machine puts the stop condition in code, so a retry limit does not depend on the model remembering it.
A deep dive into Grok Build shows a bounded task that names the behavior, the files and the verification command.
Architecture Dissector draws the map of an app. The architecture diagram tutorial puts an AGENTS.md snippet in the repo so a later session reads that map before it edits.

Plan mode: Plan mode makes a coding agent research and propose a plan before it edits code. How it works in Claude Code, Codex, Cursor and Grok Build, and when to use it.
Rules: Project rules are durable instructions a coding agent loads for a repo. How they work in Cursor, Claude Code, Codex and Grok Build, and when to skip them.
Agent memory: Agent memory is notes a coding agent keeps between sessions. How Claude Code, Codex and Grok Build store them, and what Cursor documents instead.

All AI glossary entries →

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.