How to do spec-driven development with AI coding agents

"Add authentication to the app."

Ten minutes later you have six hundred lines: a dependency you didn't want, a migration you didn't ask for, and a password reset flow on an email service you don't use. None of it is wrong, exactly. It's just not the thing in your head, and the only way to find that out is to read all of it.

The failure wasn't the model. It was the brief. You gave an agent five words and it made a hundred decisions to fill the gap.

What spec-driven development actually means

Write down what "done" looks like before any code exists, then let the agent build against that.

Not a requirements document. Not a ceremony. Half a page of plain text that answers the questions the agent would otherwise answer for you. The whole idea rests on one asymmetry: a wrong spec costs a paragraph to fix, and wrong code costs a review, a revert and an afternoon.

This isn't the opposite of vibe coding; it's what makes vibe coding survive a real codebase. You still describe intent in plain language. You just do it once, carefully, instead of eleven times in a chat thread while the diff grows underneath you.

Why agents need this more than people do

Hand a vague ticket to a human contractor and they come back with questions. Hand it to an agent and it comes back with a pull request.

Agents don't stall on ambiguity, they resolve it: silently, plausibly, in whatever direction the training data leans. Every unstated assumption becomes a decision you didn't make and won't notice until review. A spec is making those decisions yourself, in advance, where they're cheap.

What belongs in one

Five things. More than half a page and you're writing documentation, not a brief.

• The outcome in one sentence. What is true afterwards that isn't true now.
• The boundaries. Which files are in scope, and explicitly which are not. This one line prevents most runaway diffs.
• Acceptance criteria. The command that should pass, the behavior you can observe. Something checkable, not "works correctly."
• The shape. Point at the file to copy from. "Follow the pattern in PasswordResetController" beats three paragraphs describing that pattern.
• Non-goals. The tempting adjacent work you don't want touched. Agents are helpful; say no in advance.

And if you can't write the acceptance criteria, you don't know what you want yet. That's not the process failing; you just found the real problem before it cost you a diff.

Write the spec with the agent, not for it

Two phases, and the first one produces no code.

Ask the agent to read the relevant code and draft the spec: what the change involves, which files it would touch, what it's unsure about. Then make it list its assumptions and open questions explicitly. That list is gold: it's every place your idea was underspecified, surfaced before a line got written.

Edit the draft: correct the wrong assumptions, answer the questions, delete the scope creep. Now the brief is grounded in your codebase rather than in what the agent imagines it looks like.

Then implement it in a fresh session. One that just spent thirty messages exploring carries a lot of dead context; a clean one reading a tight spec does better work. Plan and build are different jobs. Claude Code even ships the split as a feature: plan mode keeps a session read-only until you approve its proposal.

Where the specs should live

In a chat window, a spec is a message that scrolls away. That's the practical reason this discipline dies: there's nowhere for the brief to live except the conversation that consumes it.

It's the workflow SanuDesk is built around: a desktop app where your Claude Code and Codex sessions tile into one grid, with a Kanban board the agents take their work from, and the card is the spec. You write the brief on the card, deploy it to a session, and the agent starts with the outcome, the boundaries and the acceptance criteria in hand. When the work comes back, the card is still sitting there to check it against.

The two briefs stack, too. An AGENTS.md file is the standing spec for the repo (how to run the tests, what never to touch), and the card is the spec for this one task. That's the whole context an agent needs, and neither one gets retyped.

For work that repeats, Loops run the same brief on a schedule, which only works because the brief is written down. It drives the agent accounts you already pay for, so nothing is metered by us, and the free tier is enough to try it.

It quietly fixes review, too

Reviewing an unbriefed diff means asking "what is this?" and "should it be this?" at once, which is why reviewing AI-generated code gets so draining at volume. With a spec, review collapses into one question: does this do what the card said, and nothing else? That scales to a fleet of agents in a way reading everything never will.

The honest limits

Don't spec a typo fix. Under ten lines the brief costs more than the change, and pretending otherwise is how good practices turn into theater.

Specs also rot. If you rewrite the plan mid-task, update the card or throw it away: a stale brief is worse than none, because you'll review against it and approve the wrong thing.

Try it on your next task

Take the next thing you were about to hand an agent and spend three minutes writing the outcome, the boundaries, the check, and one non-goal. Paste that in instead of the sentence you were going to type.

Most people notice on the first try, not because the agent got smarter, but because it finally knew what you wanted.

Download SanuDesk free and turn your next task into a card, or see how the grid, the board and Loops fit together on the features page.