An AI coding agent will build whatever you give it, quickly and with confidence. The quality of the result is capped by the quality of the spec. Here is what we have learned about writing one an agent can build to.
The short answer
A spec an AI agent can build to states the problem, lists requirements in plain language, gives acceptance criteria that a test can pass or fail, names what is out of scope, and is approved by a named person before work starts.
Start with the problem, not the feature
Most tickets name a feature: “add export to CSV”. An agent can build that in minutes, and it will probably build the wrong thing. Who needs the export? What do they do with it next? Which columns matter, and which must never leave the system?
Write two or three sentences on the problem first, in the words of the person who has it. An agent that knows why can make sensible small decisions. An agent that only knows what will guess.
Write requirements a person can read in one pass
Requirements are for two readers: the agent that builds and the person who approves. If the person cannot read them in one pass, they will approve something they did not understand. Keep each requirement to one sentence, one behavior and one actor.
- One behavior per line. “The system exports open invoices” and “The export excludes card numbers” are two requirements, not one.
- Name the actor. “The finance user can…” is clearer than “It should be possible to…”.
- Use the business’s nouns. If the team says “remittance”, do not write “payment record”.
Make every acceptance criterion able to fail
Acceptance criteria are where most specs go soft. “The export is fast” and “The export works for large accounts” cannot fail, so they cannot be checked. Rewrite each one until a test could pass or fail it.
| Weak and testable acceptance criteria | Weak | Testable |
|---|---|---|
| Speed | The export is fast | An export of 50,000 invoices completes in under 30 seconds |
| Scope | Works for large accounts | Accounts with more than 10,000 open invoices export in one file |
| Safety | Sensitive data is protected | No exported column contains a card number or bank account number |
| Errors | Handles errors gracefully | If the export fails, the user sees the reason and no partial file is saved |
A good test of a criterion: could two people disagree about whether it passed? If yes, it needs another rewrite.
Say what you are not building
Agents are generous. Ask for an export and you may also get a scheduling screen, a new settings page and a refactor of the reports module. A short “out of scope” list stops that, and it gives reviewers a quick way to reject work nobody asked for.
The out-of-scope list is the cheapest code review you will ever do.
Name every repository it touches
A spec written for one repository often turns out to need changes in three. Write the acceptance criteria per repository, so each agent run has a clear finish line, and so the person approving can see the whole blast radius before anything starts.
Have a named person lock it
Finally, a spec needs an owner. Not a channel, not “the team”: one person who reads it and says this is what we will build. Once it is locked, changes go through them. That is what stops the spec from drifting while three agents build to it.
In CrewPE
The Thread Analyst drafts requirements and acceptance criteria for every repository the change touches, scores its own draft for readiness, and waits for you to lock it.
See how CrewPE worksQuestions teams ask
- What should a spec for an AI coding agent include?
- The problem in plain words, requirements with one behavior each, acceptance criteria that a test can pass or fail, an out-of-scope list, the repositories it touches, and the name of the person who approved it.
- How detailed should acceptance criteria be?
- Detailed enough that two people could not disagree about whether a criterion passed. Include numbers, limits and error behavior where they matter, and leave out implementation details the agent can decide.
- Should the agent write the spec?
- An agent can draft it, and often drafts it well. A person who owns the outcome should still read, correct and approve it before any code is written.
Maathavan Vinayak
Co-founder of EnWithAI, working on CrewPE and on how teams and AI agents agree what to build before they build it.