L12 · Spec · 5 min
How to write a good spec
In one sentence
A good spec (SPEC.md) is a short, plain-language agreement inside your project that defines what you are building, who it helps, what is included or left out, how you will verify it works, and which technical pieces your coding agent needs before writing any code.
Think of it like this
Think of an architect's sketch and room list before anyone pours concrete. Moving a wall on paper takes thirty seconds with an eraser; moving a brick wall after the roof is on takes a sledgehammer. Your spec is that sketch.
How it works
In Definitionspec-driven development (SDD)Agree on what to build (the spec) and a plan, then build one small, checked step at a time.Open in the glossary →, every project and every major feature starts with a Definitionspec`SPEC.md`: what you're building, who it's for, what's in and out, and how you'll know it works.Open in the glossary → saved in a file called SPEC.md at the root of your project folder. Instead of asking you to write a long document from scratch, your Definitioncoding agentAn AI that works in your project folder: it reads files, writes code and runs commands, with your permission.Open in the glossary → uses its interview-me DefinitionskillAn expert playbook your agent follows for a kind of task, like writing a spec or debugging.Open in the glossary → to ask you one question at a time, offering a sensible suggested answer for each.
Those questions are about people, problems and goals, never about code. Together you agree on five plain-language sections: what you are building, who it is for, the must-haves for the first version, what is out of scope for now, and how we will know it works when you test it yourself.
Below your plain-language summary, the agent adds the technical notes it needs: which stack pieces the app actually requires. Each app gets only what it needs: if nothing is saved between visits, there is no DefinitiondatabaseWhere your app remembers things between visits, like accounts or saved recipes.Open in the glossary →; if there are no accounts, there are no logins; if there are no AI features, there are no AI providers.
Your spec is a living document, not a contract carved in stone. Whenever you change your mind or discover a better idea while testing, tell your agent to update SPEC.md and the DefinitionplanThe spec split into small tasks, each finished and checkable on its own, in `tasks/plan.md`.Open in the glossary → first, and only then change the code. That keeps your project coherent from start to finish.
What it looks like in your project
When you start a project or ask for a new feature, your agent won't jump straight into generating files. It will ask its first question, wait for your reply, and after a few turns write SPEC.md in your language and show it to you for your OK before making a plan.
Copy for your agent
I want to define what we're building in SPEC.md. Interview me one question at a time, with a suggested answer for each, about who it's for, must-haves, what's out of scope, and how we'll know it works.
Quick check · 1 question