Plans are worthless, but planning is everything

I have a folder with eighteen plans in it. My coding agent wrote every one of them. I approved every one of them. Thirteen were never executed.

The five that were executed did not age well either. A plan was three to five times longer than the spec it came from. It named fifty to a hundred files, classes and test methods. By the time the agent started building, some of those files had moved. The plan described, with great confidence, a codebase that no longer existed.

A year ago those plans were worth the tokens. Today they are long text files I do nothing with.

Three steps, one too many

My workflow had three steps: spec, plan, implementation. The spec said what I wanted. The plan said how the agent would build it, file by file. Then the agent built it. In April I called the plan one of three pillars.

Back then the middle step earned its place. Models started coding before they understood the question. A plan was the only way to see what they were about to do. Plan mode in Claude Code existed for exactly that reason.

So I asked myself a simple question. Is the middle step still doing anything?

For me the answer was no. The model reads the code better at build time than at plan time, because at build time the code is current. The plan was a snapshot of decisions that should have been taken later.

I was not the only one

In September, Ayman Nadeem published an article called "Plan mode is dead". It reached Hacker News and collected more than five hundred comments. He had built a coding tool around a separate planning step. His diagnosis of why it failed is one sentence long: "we had conflated planning with a plan".

One of those comments came from Boris Cherny, who works on Claude Code and built plan mode himself.

I broadly agree with the author's point: plan mode was useful, and is no longer useful.

He also explained what plan mode is under the hood: "a little reminder to every user message along the lines of 'you're in plan mode, please don't code yet'". It never changed what the model could do. He stopped using it when he noticed that "the model just got it", and that for complex work "planning had become interactive and iterative".

To be fair to the feature, it is not being removed. In the same thread he wrote that "plan mode isn't going away". It is just no longer where a session starts. Recent versions of Claude Code start in auto mode.

Not everybody agreed. The best objection in that thread is worth keeping: "The model is smarter now but that doesn't solve for underspecification if it guesses my intent wrong."

That is true. It is also the whole point of the title, which I borrowed from Eisenhower. The plan as a document is worthless. The planning, the thinking about what you actually want, is everything. It just has to happen somewhere else.

Where the planning went

I read what Anthropic now recommends in its own best practices for Claude Code. Plan files are not in it. This is.

• Let the agent interview you. The documentation gives the prompt literally: "Interview me until you could write the spec, then write it to SPEC.md."
• Build in a fresh session. Start a new session from the spec, so the build begins "with a clean context and a written definition of done".
• Give it a check that can fail. "Give Claude something it can run that comes back pass or fail." Then it can work on its own and you do not have to watch.
• Ask for evidence. The command it ran and the output. Not a sentence saying it works.
• Use a second agent as a fresh pair of eyes. Not because it is smarter. Because it has not seen how the code was written.

So the underspecification problem is real, and the answer is not a longer plan. The answer is a better spec, written after an interview, with a test attached to every promise.

The real problem is my existing projects

Knowing this is the easy part. I have several projects, each with its own instructions, its own skills and its own habits. Some still tell the agent to write a plan first.

Changing the way of working in one project takes an afternoon. Changing it everywhere, the same way, without breaking what already works, is the kind of job that never gets done.

That is why I built the spec-driven kit.

The spec-driven kit replaces the plan with six phases

The kit is a set of rules, skills, agents and hooks for Claude Code. It replaces "spec, plan, implement" with six phases.

Phase	What happens	Who decides
Investigate	The agent reads the code first and records what it verified	The agent
Interview	It asks me questions, round by round, until nothing has to be assumed	I answer
Specify	Behaviour, two diagrams, acceptance criteria, vertical slices	I approve
Build	One slice per fresh session, the test first	The agent
Verify and approve	A second agent tries to break the checks, then I get a one-screen recap	I commit
Review	After the last slice, a reviewer checks every criterion against the diff	I push

Six choices in it matter more than the rest.

The spec is the only planning document. It says what must be true and how that is checked. No file lists, no class names, no line numbers. So it cannot go stale. The agent works those out from the current code when it builds.

Work is cut in vertical slices. A slice is one piece of behaviour I can see working, never one layer. A page comes first on fake data. I can try it and change my mind while that is still cheap. The next slice wires it to the real backend.

Every slice starts with a test that fails. An integration test first, then a unit test before each piece of logic. A test that never failed proves nothing.

Nobody grades their own work. In my trial run, a reviewer without context found a test that passed on any 401 response. It was green, and it proved nothing. So the kit has three agents that never see the conversation. One reads the spec before I do. One breaks the behaviour on purpose to see whether each check notices. One reviews the finished feature.

Rules without exceptions are hooks. An instruction can be skipped under pressure. A hook cannot. No edits on a protected branch. No recap while verification fails. Commit and push ask for my confirmation.

My commit is the acceptance. The agent stops after every slice. I read the recap, try the slice, review the diff and commit. A clean working tree tells the next session that the previous slice was accepted.

The review by slice is the part I will not give up

If I had to keep one thing from the whole kit, it is this one. I review the code slice by slice.

An agent builds faster than I can read. Give it a whole feature and it comes back with two thousand lines. I can approve that. I cannot understand it. And after three features like that, I no longer know my own codebase.

A small slice is different. One piece of behaviour, one diff I can read in a few minutes. After every slice the map in my head is up to date again. I know what was built, where it lives and why.

That is also why I ask for pictures. The spec carries two diagrams, so I see what will be built before a line of code exists. A diagram shows me in ten seconds what a page of text hides.

The model can write the code without me. It cannot keep me in the loop without my help. The diagrams and the small reviews are how I keep up with the AI. The day I skip them, I am no longer the developer. I am the person who presses approve.

How to use it

The kit is never copied into a project by hand. It stays in its own folder next to the project, and a setup session installs it from there. That way it can look at what the project already has before it touches anything.

work/
  spec-driven-kit/     the kit
  my-project/          the project to set up

1. Clone the kit next to your project. You need git and Node.js.
2. Start Claude Code in the kit folder: claude --add-dir ../my-project
3. Run /setup ../my-project and stay in the conversation. It surveys the project, shows what it would add and asks what the kit should take over. It commits nothing.
4. Review the diff in your project and commit it.
5. Start Claude Code in the project and run /new-feature with a name and a sentence of context.

For a project that already has a harness, the setup asks one question per concern: planning, test-first, review, verification, commit policy. For each one you decide. Your existing piece stays, the kit takes over, or the kit plugs into it. Your own verification command, for example, simply becomes the kit's.

You do not have to take everything at once either. The kit installs by level: the review agents only, then the guards, then the full workflow.

The kit is here: github.com/geobarteam/spec-driven-kit

What I kept

I did not stop planning. I plan more than before. The investigation, the interview and the spec are all planning.

I did not stop reviewing either. I still read every slice, because that is what keeps the picture of the system in my head.

What I stopped doing is asking an agent to write down, in great detail, how it will build something in a codebase that will have changed by the time it starts.

The eighteen plans are still in their folder. I keep them as a reminder.

Sources

• Ayman Nadeem, "Plan mode is dead", 24 September 2026
• The Hacker News discussion of that article
• Boris Cherny's comment in that discussion
• Anthropic, Best practices for Claude Code
• Anthropic, Permission modes (Claude Code documentation)
• spec-driven-kit on GitHub