For decades, the spec was the document nobody read after week two. The code was the truth; the spec was a formality. AI coding agents have inverted that relationship. When an agent implements a feature, the spec you hand it is the highest-leverage artifact in the whole process — the implementation is now downstream of the words. Teams that write precise specs get precise software from their agents. Teams that write vague ones get confident, plausible, wrong software.
Why specs are the new source code
An AI agent will fill every gap in your spec with the most statistically likely interpretation — which is often reasonable and occasionally catastrophic. A human engineer fills the same gap by walking over and asking. The agent's version of asking is only as good as the context you gave it. So the discipline that used to live in code review has moved upstream: the quality bar is now applied to the specification, before a line is generated.
In our experience, an hour spent tightening a spec routinely saves a day of reviewing and redirecting generated code. That trade only gets better as agents get faster.
What a build-ready spec contains
A spec an agent can build from reliably has five parts. None of them is long — the whole document is often two pages — but all five must be present:
- Behavior. What the system does, described as observable outcomes: "when a user submits an expired card, the payment is rejected and the saved card is flagged for re-entry."
- Constraints. The rules the implementation must respect: performance budgets, security requirements, which existing modules to reuse, which patterns this codebase follows.
- Non-goals. Explicitly what not to build. This is the section most teams skip and the one agents need most — it's the only fence against helpful over-engineering.
- Acceptance criteria. Checkable statements that define done. If a criterion can't be turned into a test, rewrite it until it can.
- Examples. Concrete input/output pairs, including edge cases. Three good examples disambiguate more than three paragraphs of prose.
A useful test: could a competent engineer who has never met you build the right thing from this spec alone? If not, an agent can't either — it just won't tell you.
The spec-first workflow in practice
Here is the loop our teams run with AI coding tools like Claude Code:
- Draft with the model. Describe the feature conversationally; have the LLM draft the spec and interrogate it — "what's ambiguous here? what edge cases am I missing?" The model is a superb spec reviewer.
- Review the spec, not the vibe. A human — ideally the tech lead plus a product owner — approves the spec the way code used to be approved. This is the highest-value review of the whole cycle.
- Agent plans before it codes. Hand the spec to the agent and review its implementation plan first. Redirecting a plan costs minutes; redirecting a diff costs hours.
- Acceptance criteria become tests. The agent turns each criterion into an automated test before or alongside the implementation, so "done" is machine-checked.
- Deviations flow back into the spec. If reality forced a change, the spec is updated in the same pull request. Otherwise it starts lying immediately.
Specs as living documentation and review artifact
Kept in the repository next to the code — versioned, diffed, and reviewed like code — specs quietly solve two old problems. Documentation stops rotting, because the spec is a working input to development rather than an afterthought. And review gets a second, more strategic surface: reviewers can evaluate what we decided to build separately from whether the code does it, which is a far better use of senior attention than line-by-line nitpicking. New teammates — including new augmented engineers joining your team — onboard from specs in days rather than reverse-engineering intent from code for weeks.
This discipline compounds across the whole lifecycle — see our companion piece on the AI-native SDLC for where spec quality pays off in each phase. And if you'd rather hand us the spec and receive working software, that's exactly what our outsourcing model is built for.
Key takeaways
- When agents implement, spec quality determines code quality — the review bar has moved upstream.
- A build-ready spec has five parts: behavior, constraints, non-goals, acceptance criteria, and concrete examples.
- Non-goals are the most neglected and most valuable section — they fence in helpful over-engineering.
- Review the agent's plan before its code, and turn every acceptance criterion into an automated test.
- Keep specs in the repo and update them in the same PR as the code — that's what makes them living documentation.
Want help setting up a spec-first workflow — or a team that already works this way? Get in touch.