A coding agent fills every gap in your request with its best guess, drawn from average code on the internet. A good spec closes the gaps that matter: the goal, what done looks like, the constraints and what's out of scope. Here's how to write one, without writing it yourself.
Key takeaways
- Whatever your spec leaves blank, the model fills in with average patterns from its training data.
- Spec the goal, acceptance criteria, constraints and out-of-scope. Leave low-level decisions to the agent.
- Make 'done' checkable: concrete steps and a pass or fail for each feature.
- Don't hand-write specs. Let the agent interview you, generate the spec, then edit it.
- Keep specs small and current. Prototype to discover what you want, then spec what you'll keep.
Try it with your agent
For your next feature:
I want to build [feature]. Interview me one question at a time (with your recommended answer) to write a one-page spec: goal and who it's for, acceptance criteria I can check, constraints (stack, dependencies, performance), out of scope, and existing code to reuse. Save it to specs/[name].md.
Transcript
Intro
Every request you give an agent has gaps. The agent will fill every one of them. The question is whether you choose what goes there, or the internet does.
Gaps get filled
Mario Zechner, who builds the Pi coding agent, puts it like this. You know what we call a sufficiently detailed spec? It's a program. So if you leave blanks in your spec, the model fills them with the patterns it learned from average code on the internet.
OpenAI's Ryan Lopopolo estimates a good patch involves around five hundred small decisions that nobody wrote down. Naming, error handling, logging, performance. The model has seen every possible choice. Your job is to write down what good looks like here.
The intern problem
Brendan O'Leary learned this before agents existed. As a new manager, he gave interns a rough wireframe with placeholder emoji and Comic Sans. They built exactly that, Comic Sans and all. It wasn't their fault, he says. He never told them what mattered. Agents work the same way.
Anatomy of a spec
So what goes in a spec? Start with the goal and who it's for. Then what done looks like, as criteria you can check. Then the constraints: the stack, which dependencies are allowed, any performance limits. What's out of scope. And existing code the agent should reuse instead of reinventing.
The right altitude
Notice what's missing: function names, file layouts, how to write the loop. The JetBrains course on spec-driven development calls it the architect and the builder. Give lots of context about goals and constraints, and leave the low-level decisions to the agent.
Constraints matter
Constraints are the gaps that bite hardest. When Cursor's Wilson Lin pointed thousands of agents at building a web browser, they pulled in existing parsers and a JavaScript engine. That wasn't misbehavior. His instructions never said what to build from scratch.
Checkable done
The best specs make done machine-checkable. In Anthropic's long-running agent experiments, every feature gets concrete steps and a passes flag that starts as false. The agent only flips it to true after it has actually verified the behavior.
Don't write it yourself
Here's the good news: you don't have to write specs by hand. Geoffrey Huntley's workflow: I don't create my specs, I generate them. Have the agent interview you, let it write the spec, then review and edit it yourself before any code gets written.
Small and current
Two cautions. Martin Fowler warns against recreating waterfall: write the smallest spec that makes forward progress, then build in thin slices. And specs drift. Dex Horthy's team throws away plans after each task. The code is the source of truth. Even Boris Cherny's team often skips documents and prototypes instead. Prototype to learn what you want, then spec what you'll keep.
Quick check
Quick check. Your agent added three new dependencies to build a CSV parser you expected it to write itself. What went wrong? Tap your answer.
Try it
Try it on your next feature. This prompt makes the agent interview you and produce a one-page spec with a goal, checkable criteria, constraints, scope and code to reuse. Edit it, then build from it.
Recap
Recap. Every gap gets filled, so close the ones that matter. Spec the goal, checkable done, constraints and scope, at the right altitude. Let the agent interview you and write it. And keep specs small and disposable. Next: how to talk to agents, prompt by prompt.