- An AI assistant fills every gap in your request with a guess. A written specification removes the guesses before any code exists, when mistakes are cheapest to fix.
- A good spec is short and concrete: the goal, who it is for, the rules, the cases that must work, what is out of scope and what must never happen.
- The process is a loop: write the spec, plan, build in small steps, check each step against the spec, and update the spec when you learn something.
- It is not worth the effort for throwaway experiments. The test is simple: would building the wrong interpretation cost real rework? If yes, write the spec.
The short answer
If you ask an AI assistant for "a customer portal with invoices", it will build something. It will decide for itself who can see what, what happens when a payment fails, what the screens look like and what to do with old data. Every one of those decisions is a guess, and some of the guesses will be wrong in ways you only discover later.
Spec-driven development means writing those decisions down first, in a document that both people and AI assistants can read, and treating that document as the source of truth for what gets built. The assistant then works from a shared description instead of from a hunch. It is not a new idea, because good teams have always written requirements, but AI changes the economics: the assistant can turn a clear specification into working code in minutes, which makes the specification the part worth getting right.
How it differs from "just prompting"
Working from short prompts is fast and feels productive, and for small, disposable things it is the right choice. Its weakness is that the intent lives in a long conversation that nobody can easily re-read. Two weeks later, nobody remembers why a rule exists, and the next person who asks the assistant for a change may unknowingly undo it.
Working from a specification flips that. The intent lives in a file that is kept alongside the code and changes with it. When something is unclear, you fix the file, not the chat. When a new person joins, or a new assistant session starts, the file tells them what the software is meant to do and why.
Compare how each approach handles a simple request: "Let customers download their invoices".
- Prompt only: the assistant adds a download button. It works for the developer's test account. Whether other customers can download each other's invoices was never asked, so it was never decided.
- With a spec: the spec says that a customer may download only their own invoices, that a missing or foreign invoice returns a plain "not found", that the file is named with the invoice number, and that each download is recorded. The assistant builds that, and the tests check exactly those rules.
What goes into a good specification
A spec does not have to be long or formal. For a feature, a page or two is plenty. What matters is that it answers the questions an assistant would otherwise guess at. A practical structure:
- Purpose. One or two sentences on the problem and for whom. "Office managers need to see which invoices are overdue without asking us."
- Users and permissions. Who uses it, and who may do what. This is the section that prevents the most expensive mistakes.
- Behaviour in plain rules. The things that must be true, written as short statements anyone can check. "An invoice is overdue when unpaid thirty days after its date."
- Examples and edge cases. A few concrete cases, including the awkward ones: no invoices yet, a part-payment, two customers with the same name, a very long list.
- Acceptance criteria. The checks that will tell you it is done. "Given a customer with two overdue invoices, the page lists both, newest first."
- Out of scope. What this deliberately does not do. Saying "no reminders by email yet" prevents the assistant from helpfully inventing them.
- Data and privacy. What is stored, for how long, and what must never appear in logs or screens.
- Security needs. The rules the code must not break: every query limited to the signed-in customer, nothing sensitive in error messages.
- Open questions. What you do not know yet. An honest list is far better than a confident guess.
The workflow, step by step
The details vary between teams and tools, but the shape is almost always the same.
1. Specify
Write the spec with the people who understand the business, and let an assistant help by interviewing you, spotting gaps and proposing edge cases. The aim is not to produce a document but to find the missing decisions. A short session of "what happens if…?" questions usually surfaces several.
2. Review the spec
Before any code exists, someone other than the author reads it and tries to break it. Is anything ambiguous? Does it contradict another feature? Is a permission missing? A misunderstanding corrected here costs a conversation. Found after the build, it costs a rewrite.
3. Plan
Turn the spec into a short technical plan: which parts of the system change, in what order, and what could go wrong. Ask the assistant to propose it, and have an engineer approve or amend it. This is where architectural judgement matters, and it remains a human responsibility.
4. Break into small tasks
Split the plan into pieces small enough to build and read in one sitting, each with its own checks. Small pieces keep the review realistic and make it easy to see which step introduced a problem.
5. Build
The assistant generates the code for one task at a time from the spec and the plan. Because the intent is on the page, you spend far less time re-explaining, and the result is more consistent from one session to the next.
6. Verify against the spec
Run the acceptance checks, ideally as automated tests written from the spec's own examples. A person reads the change, with particular care around permissions, money and personal data. If the result is wrong, first ask whether the spec was unclear before blaming the assistant.
7. Update the spec
Reality always teaches something. When you learn that a rule was wrong or incomplete, fix the spec first and then the code. A spec that is not kept up to date is worse than none, because it misleads.
A small example
Imagine a request from a client: "Customers should be able to see what they owe us." Here is how the spec turns that sentence into something buildable. It is shortened for the page.
Purpose. Let a customer see all their unpaid invoices and the total owed, so they can pay without contacting us.
Who and what they may do. A signed-in customer sees only the invoices of their own company. Staff can see any customer. A customer can never see another customer's invoices, even by typing an address.
Rules. An invoice is "unpaid" until fully paid. The total is shown per currency and is never added across currencies. Overdue means unpaid for more than thirty days after the invoice date, and is marked clearly.
Cases. No invoices: show a friendly message. A part-payment: show the remaining balance. More than fifty invoices: show them in pages.
Acceptance. A customer with three unpaid invoices sees three rows and the correct total. Another customer's invoice number, typed into the address, returns "not found".
Out of scope. Online payment and email reminders will come later.
That took ten minutes to write. It settled who can see what, how money is totalled, what "overdue" means and what is not part of the job. Every one of those points would otherwise have been a guess in the assistant's code, and the permission rule in particular is exactly the kind of thing that goes missing silently.
Why this matters more now: the review bottleneck
AI changes where the effort goes. Writing code has become cheap and quick. Understanding, reviewing and trusting that code has not. Teams that adopt assistants often find that the number of changes grows faster than anyone's ability to review them, so review becomes the bottleneck, and quality slips quietly when reviewers skim.
A specification helps in two ways. It catches misunderstandings early, when they are small, and it gives the reviewer a standard to review against: not "does this look reasonable?" but "does this do what the spec says, and nothing else?". That second question is far easier to answer, and far more reliable.
Tests are the other half of the same idea. Acceptance criteria written in the spec can become automated checks, so that the specification is not only read but executed. A change that breaks a rule fails immediately, whoever or whatever wrote it.
Isn't this just the old way of working?
It is a fair question. Writing requirements before building was the heart of the slow, document-heavy methods that many teams moved away from, and nobody wants to go back to months of paperwork. There are real differences, though.
- The loop is short. The distance from spec to working code is minutes or hours, not months, so you learn from the result immediately and adjust the spec.
- The spec is alive. It lives in the same place as the code, changes with it and is small enough to maintain.
- It is proportional. A small change gets a few lines. A risky change gets a page or two. Nobody writes a hundred-page document.
The criticisms deserve respect too. Specs can grow bloated, and assistants do not always follow a long document faithfully, particularly when it is vague. The remedy is to keep specs concrete and modest, to split big features into small specs, and to check the result against the spec rather than assuming it was followed.
When it is not worth it
Specification has a cost, and sometimes the cost is higher than the benefit.
- Throwaway experiments. If you are exploring an idea and expect to discard the result, prompt freely. A spec would slow down exactly the learning you want.
- Tiny, reversible changes. Fixing a typo or adjusting a colour does not need a document.
- Work done alone with no lasting consequences. A personal script needs only a clear idea in your head.
The test we use is straightforward: if building the wrong interpretation would mean serious rework, or would touch permissions, money or personal data, write the spec. If not, keep it light. The depth of the spec should follow the cost of a misunderstanding.
How to start in a small company
You do not need a new tool or a new department. A sensible first step is a small pilot.
- Pick one real feature, medium in size and not business-critical, and write its spec in a plain text file kept with the code.
- Agree a simple template. The headings listed above are a good start. Resist adding more until you feel the need.
- Have the spec reviewed by someone who did not write it, before building.
- Turn the acceptance criteria into tests, and let the assistant build against them in small steps.
- Measure honestly. Note how long it took, how much rework there was, how long the review took and what the assistant got wrong. Compare with how you worked before. If there are no numbers yet, say so and collect them.
- Adjust, then extend to the next feature. Let the template grow only where it proves useful.
Several tools now support the practice: some help structure the specification, others carry out the implementation from it. The tools matter less than the habit, and the habit can start with a text file and a review.
What it means if you are the client
If you commission software, spec-driven working is good news, because it makes the project easier to understand and to control. You can read the specification, in your own language, and say "yes, that is what I meant" or "no, that is not right" before any money is spent on building the wrong thing. It makes scope clear, so it is easier to agree what is included and what is not, and to judge whether a quote is realistic. And it gives you a standard of acceptance: the checks in the spec are how you decide the work is finished.
It also makes the software easier to maintain years later. The reasoning behind decisions survives in the document, instead of in the memory of whoever happened to be there.
How we use it
We build our software with AI assistants and we write specifications for anything that touches permissions, money or personal data. For small changes we keep it light: a few lines in the task itself. We review the spec before the build, check the result against it, and update it when we learn something. We have not measured how much faster or slower this makes us compared with other ways of working, and we would rather say that than quote a number we cannot support. What we can tell you is that it has made our reviews calmer and our hand-overs clearer.
If you have an idea for an application and would like to see what a first specification looks like before committing to anything, we are happy to write one with you. It is often the most useful hour of the whole project.
Common questions
Is spec-driven development the same as writing requirements?
It is a close relative. The difference is that the document is short, kept with the code, updated as you learn, and used directly by AI assistants to build and by tests to check, so it stays useful instead of gathering dust.
Does it replace developers?
No. People still own the design decisions, review the plan and the result, and take responsibility for what is released. The assistant speeds up the typing, not the judgement.
How long should a spec be?
As short as it can be while still answering the questions an assistant would otherwise guess at. A page or two for a feature is typical. If it is growing past that, split the feature.
What if the assistant ignores the spec?
It happens, especially when the spec is vague or very long. Make the rules concrete, work in small steps, and verify the output against the acceptance checks instead of trusting that it complied.
Can I use it for an existing application?
Yes, and it is a good way to start. Write the spec for the next change, and for the parts that carry the most risk, such as permissions. Over time the specs describe the parts of the system that matter most.
Photo: Lucas Kepner on Unsplash
