Plan mode vs spec-driven development: when a plan is enough

Published 23 October 2026

Plan mode is enough when one person makes the change in one session and nobody else has to agree to it. A spec earns its place when the work outlives the session, when several sessions or agents build against it, or when someone else has to say yes. The difference is less about detail than about where the document lives: Claude Code, Cursor, GitHub Copilot and Kiro all keep a plan outside the repository unless you save it there, and in public repositories few people do. A spec is a file next to the code, with a history. Below is what each one keeps, what the tools themselves advise, what the research shows about plans, the case against writing either down, and a rule for when a plan should become a spec.

I think the biggest mistake I made was turning the plan into an artifact instead of designing a process for improved human understanding.

— Ayman Nadeem, who built a planning-first coding app, in Plan mode is dead, September 2026

Plan or spec: what each one keeps

• A plan says how. Which files change, in what order, and which checks prove it. The agent writes it after reading the code; you read it, correct it and approve it; the same session builds it. Then the session ends, and the plan with it.
• A spec says what and why. The behaviour, the cases that pass or fail, what is out of scope and what must not change. It is a file in the repository. The people who have to agree read it, and every session or agent that builds the change starts from it.

The same change, both ways. The plan, as plan mode might produce it:

PLAN
1. In the nightly job, select invoices
   not paid in full, seven days past
   the due date.
2. Keep the reminder record; skip
   invoices already reminded.
3. Add a test for a partly paid
   invoice; run the reminder tests.

The part of the spec it came from:

FR-016  The portal must send one
        reminder, seven days after the
        due date, for every invoice not
        paid in full, to the company's
        billing contact.

4. Partly paid by 8 March: one
   reminder.

Decided by the finance lead,
16 June (D-7).

The plan is enough to build the change. It does not say that a partly paid invoice now gets a reminder because the finance lead decided so on 16 June — and that is what someone will need to know when the reminder is questioned next year. The whole spec, from version 1 to version 2, is in the spec-driven development example.

What the tools themselves advise

Four tools’ plan modes come with the same advice: skip the plan for a small change, plan when the approach is unclear or the change spreads across files.

• Claude Code: “Plan mode is useful, but also adds overhead.” Planning is most useful when you are uncertain about the approach, when the change touches several files, or when you do not know the code. The threshold: “If you could describe the diff in one sentence, skip the plan” (Claude Code documentation).
• Cursor: “For quick changes or tasks you’ve done many times before, jumping straight to Agent mode is fine” (Cursor documentation).
• GitHub Copilot in VS Code: “Use a separate planning step when the approach is uncertain or a change spans multiple parts of your project. For a small, well-defined edit, you can ask an agent to implement it directly” (VS Code documentation).
• Kiro has both a plan mode and specs, and its documentation draws the line between them. Plan mode is for “tasks that need 15–60 minutes of implementation - long enough to benefit from planning, short enough that formal specs would be overkill.” Specs are for “High complexity, team collaboration, audit trail” (Kiro documentation).

Put together, that is three levels, not two:

Where the plan goes when the session ends

So a plan reaches the repository only when someone decides it should, and in public repositories few do. A 2026 study screened 36,710 GitHub repositories of engineered software projects for plan files in their .claude/plans, .cursor/plans and .gemini/plans folders, and “identified 85 Markdown plan files from 10 repositories.” One repository held 66 of them. Most plans appeared in a single commit and only seven were ever revised, so the authors conclude that “most committed plan files are therefore better characterized as ephemeral task records than as intentionally maintained project artifacts” (Abubakar et al., ESEM 2026). The study searched only those folders, so plans saved under other names were not counted.

Spec files turn up far more often: a separate study of spec-driven development collected 470,795 of them from 73,030 public repositories (Agarwal et al., 2026, preprint). The searches differ, so the numbers do not compare directly, but the pattern is plain enough: a plan is treated as a step in a session, a spec as a document someone means to keep.

What the research says about plans

A plan helps the agent, and a bad one hurts it. The largest study of how agents follow plans ran 21,120 attempts at real GitHub issues, giving the agent the standard plan for fixing an issue — find the code, reproduce the bug, patch it, check the patch — a changed one, or none. “Providing the standard plan improves issue resolution, and we observe that periodic plan reminders can mitigate plan violations and improve task success. A subpar plan hurts performance even more than no plan at all” (Liu et al., ASE 2026). Its plans were workflows, not plans for a particular change, but two lessons carry over: read the plan before you approve it, and in a long build, point the agent back to the plan or the spec.

The thinking may matter more than the document. In the practice study, one explanation the authors offer for why specs help is “that the benefit relative to vibe coding comes less from the agent having a spec than from the developer having articulated goals before delegation.” If so, “the same benefit should appear with any practice that leads a developer to plan before acting, including plan modes present in AI coding agents like Cursor and Claude Code.” Nobody has tested that yet.

Practitioners already choose by size and risk. The same study found that “Most practitioners used SDD selectively, and only a few used it for every task”, and skipped it for small tasks, bugs and one-off scripts. One Reddit post it quotes: “If you’re using [an SDD framework] for smaller changes, you’re going to have a bad time. It’s too verbose and produces too much overhead and documentation.” Those who decided by risk advocated it when the stakes were high and the intent was clear.

The case against writing it down

The strongest version comes from Ayman Nadeem, who built and launched a coding app around persistent plans and specs. Its users “had surprisingly little appetite for that spec”, and “The spec contained more information without creating more clarity.” As models improved, the need to spell everything out shrank, and the loop changed from plan, approve, execute to “understand → act → inspect → clarify → adjust → act again”, with the planning inside it.

The same question came up on Hacker News in August 2026: “Did we all just collectively decide that /plan mode was enough?” (Hacker News). In the discussion of Nadeem’s post, one answer was “Plan mode is not dead, it just moved to OpenSpec and other similar tools” (Hacker News), and another: “Unless you’re working on a super crucial piece of engineering, you can probably get away with going straight to building it” (Hacker News).

Neither side argues against thinking before building. The disagreement is about whether the thinking has to become a document. It does when someone other than the current session needs it: a reviewer, a later session, another agent, the person who has to agree. Nadeem’s own conclusion leaves that open: “keeping that understanding up to date as the system changes is still an open problem.”

Using both: plan mode against a spec

The two are not rivals. The spec says what; plan mode turns it into how, with the code in front of it.

1. Write the spec, then plan from it. Start a fresh session, in plan mode, with the spec named in the prompt. Anthropic’s course on an AI-native development process makes this the default: engineers “give Claude the approved spec.md” and iterate on the plan “until an engineer who has never seen the conversation could implement the change from the plan alone” (Claude Academy).
2. Have the plan cite the spec. When each step names the requirement or case it serves, “a reviewer can check the plan against the spec line by line” (the same course).
3. Use plan mode to find holes in the spec. One commenter, about Codex: “plan mode is very useful for finding serious issues with one’s spec. I use it to improve my spec. I keep rerunning plan mode over my updated spec until it stops finding issues” (Hacker News).
4. If the plan changes the what, change the spec. A plan that adds a case, drops a rule or picks a number the spec did not give is a decision. Stop, put it in the spec with who made it, and plan again.

The course goes one step further and commits the approved plan as plan.md, updated in the same commit whenever the build departs from it. That is worth doing when a reviewer will check the code against the plan; otherwise the plan can go when the session does, as long as the spec stays.

When a plan should become a spec

Turn the plan into a spec when any of these is true:

1. The work will not finish in this session.
2. Someone else has to agree with what will be built: a client, a product manager, another team.
3. More than one session or agent builds against it.
4. The plan has started to hold decisions about behaviour — what the user sees, a rule, a limit, a number — not only files and steps.
5. Someone will need to know later why the system works this way.
6. A reviewer will check the code against something other than the code.

And a spec is too much when the change fits in one sentence, when a failing test already says what “fixed” means, for a prototype or a one-off script, and for a production hotfix, where in one participant’s words “there is no time for spec-driven development and the whole flow” (Agarwal et al.).

To turn a plan into a spec, do not save the step list. Ask the agent to write down the behaviour you agreed — what and why, the cases that pass or fail, what is out of scope, the open questions — and edit it until you would sign it. How to write it is in how to write a spec for AI agents; the files and the loop in Claude Code, in spec-driven development with Claude Code.

Where Specroot fits

This is the problem Specroot works on: the decisions that come up while planning — which behaviour, which rule, who agreed — kept in a spec that the people who have to agree can read, after the session that produced them has ended. Specroot for teams using AI coding agents.