You ask an AI coding agent to add team invitations. Twenty minutes later the screen works. The agent picked its own rule for who may invite whom, though the project already had one. A week later a fresh session changes the screen and breaks the reminder email.
Rules written down first give you something to check every result against. You agree the premises and review the specs in plain words; the agent and developers write the code and the automated tests.
What is spec-driven development?
Spec-driven development means you write down what the software must do before any code is written. The code is then built from that and checked against it, so the written description, not the person or agent typing the code, decides what counts as done.
With AI agents it works best in three layers, in this order:
- Premises. Short plain sentences that are true about the whole project, grouped by area where possible. “Only team admins can invite or remove people” is a premise. They are what you talk over and agree with the client, and they act as guardrails: no spec and no line of code may break them. Everything starts here.
- Specs. A spec describes one feature in detail: what the user sees, the rules, the odd cases and what is left out. Specs are already managed with the AI. The agent helps write and update them, and people review every spec before it is built.
- Tests. Each spec comes with tests, automatic checks that must stay true whenever a feature is added or changed. Their job is to catch regressions, meaning something that worked before and stops working after a change.
Writing requirements before building is not new. What has changed is who reads them. More of the code is now written by AI agents, and an agent builds from the text it is given.
GitHub’s Spec Kit is one tool built around this. Its workflow also starts with rules for the whole project, which it calls a constitution: “Create a constitution once per project and repeat the remaining steps for each feature.”
Why do premises, specs and tests matter more with AI agents?
A developer on your team remembers last week’s meeting. An agent starting a new task has only what it is given to read. Four things follow from that:
- An agent starts each session without your earlier conversations. Whatever you agreed is missing unless it is written down somewhere the agent reads. Matt Pocock puts it in one line on AI Hero: “The spec exists because context windows end.” A context window is the amount of text an agent can hold in one session.
- An agent works fast on whatever it is told. It will build a full feature from one sentence. If the sentence was vague, you get a full feature built on guesses.
- An agent may fill gaps with guesses. Pocock describes the result of typing “build this” at a fresh agent on his implement skill page: it “often redesigns the work while it builds it.”
- An agent changing one feature can break another. It sees the task in front of it, not everything else that depends on the code it touches. In one project, an agent working on another feature removed a working feature: copying entries for collection societies. A test that tries to copy an entry catches its removal the next time the tests run, and a failing test stops the change from going live.
Premises tell the agent what is always true. The spec tells it what to build now. Tests check whether the behaviours they cover still work after a change.
How does spec-driven development work, step by step?
Matt Pocock publishes a set of skills for AI coding agents on AI Hero. A skill is a saved set of instructions an agent follows when you type its name, such as /to-spec. His documented workflow takes an agreed idea through a written spec, smaller tasks, building and review. Before using these skills, agree the project’s premises with the client.
| Step | What happens | Who or which skill |
|---|---|---|
| 1. Premises | You and the client agree the sentences that are always true | People, no skill |
| 2. Interview | The agent asks you questions until the feature’s design is clear | /grill-with-docs |
| 3. Spec | The agreed design is written down as one spec, then reviewed | /to-spec |
| 4. Tickets | The spec is split into small pieces of work | /to-tickets |
| 5. Build | An agent builds one ticket, writes its tests and runs all tests | /implement |
| 6. Check | The change is reviewed against the spec and the coding rules | /code-review |
1. The premises. Before any feature work, sit down with the client and write the premises. Talk each sentence over until both sides agree it is true, group them by area and keep them where every agent and every person on the project reads them. They change rarely. When a new request conflicts with a premise, either the request changes or you agree a new premise with the client.
2. The interview. According to its AI Hero page, the grill-with-docs skill “interviews you about a plan or design until you and the agent share one understanding of it”. It asks a round of questions, waits for your answers, then asks the next round. Give the agent your premises first, so its questions start from what is already agreed. Agreed terms go into a glossary, a list of the project’s words and what they mean. When a decision would be hard to undo, its reason would not be obvious later, and choosing it means giving something else up, it gets a short written record.
3. The spec. The /to-spec skill “turns the conversation you have just had into a spec, and publishes it to your issue tracker as a single issue.” An issue tracker is the team’s shared list of work, and an issue is one item on it. In Pocock’s words, “The spec records decisions you already made. It is not a place to make new ones.” Before writing, it agrees with you where the feature will be tested. Then read the spec yourself: check it against the premises and against what you meant. Pocock also says when to use it: “Reach for it when the build is too big for one agent session and must be split across several.”
4. The tickets. The /to-tickets skill splits the spec into tickets and “sizes each ticket to fit in a single fresh context window”. Each ticket delivers a small piece of working behaviour you can try. Nothing reaches the tracker until you approve the proposed tickets.
5. The build. The /implement skill “builds work that has already been decided.” His page adds: “It never reopens the plan.” The agent takes one ticket and writes the tests and the code together. Its last step before saving is this: “Run the full test suite once, at the end.” The full test suite means every test in the project, including the ones for features built months ago.
6. The check. The /code-review skill reviews the change along two separate lines. One asks whether the code follows how the project writes code. The other, in his words, “asks whether the code does what the originating issue or spec asked for.” Someone still reads the review and decides what to fix, because the build step “does not act on the findings code-review produced”.
After the work ships, Pocock’s advice for the spec is “Treat it as disposable after the work ships.” The premises stay, and so do the tests: they run again whenever the code changes.
What does a premise look like?
A premise is one sentence. It is true for the whole project, uses no technical words, and a client can answer it with yes or no. Some examples for a team tool, grouped under two areas:
Teams
- Every person belongs to exactly one team.
- Only team admins can invite or remove people.
Billing
- A team that has not paid can still read its data but cannot add new work.
- Invoices are never deleted; a wrong invoice is cancelled and replaced with a new one.
A spec for team invitations must fit both team premises. If a client later asks for people in two teams, that is a new premise to agree first, not a detail to slip into a spec.
What should a good spec contain?
A spec does not need to be long. It needs to answer the questions an agent would otherwise guess. Using team invitations as the example:
| Part | What to write | Example |
|---|---|---|
| Premises it relies on | The premises this feature must respect | Only team admins can invite or remove people |
| The problem | What the user cannot do today and why it matters | Teams cannot add colleagues without contacting support |
| What the user sees | The screens and steps, in plain words | An “Invite” button on the team page opens a form with an email field |
| Rules | What the feature itself decides | An invitation expires after 7 days |
| Edge cases | Odd inputs and what happens | The email already belongs to a team member: show a message, send nothing |
| Out of scope | What this change deliberately leaves out | Inviting several people at once |
| Tests | Checks that must stay true from now on | An admin invites a new address and the colleague can join from the email |
What are the common mistakes?
- No premises, so the spec has no guardrails. Each spec then sets its own rules, and two specs can contradict each other without anyone noticing.
- Tests are missing, so an agent quietly removes a working feature. Without a test for the affected behaviour, its removal may go unnoticed. Write tests for the behaviours that must keep working and run them before each release.
- The spec is too vague. “Make invitations work” leaves every rule to the agent. Write the rule you want, even when it seems obvious.
- The spec is written after the code. Then it describes what the agent guessed, not what you decided.
- New decisions get made inside the spec. Settle them in the interview first, or with the client as a premise.
- Nobody reviews the spec. The agent wrote it from your answers, so read it before the work is split into tasks.
- One ticket holds the whole feature. It will not fit in one session. Split it so each ticket can be built and checked on its own.
Where does Essential Code fit?
We build our current project this way. If you want your team to build with AI agents like this, we set up premises, specs and tests with you as part of our web app and SaaS development work.