Spec-first development means the written specification is the thing people argue over and sign, and coding agents build to it: humans decide, agents type, and every change still arrives as a pull request a named engineer reviews before it merges. In the 2025 Stack Overflow Developer Survey, 84% of developers said they use or plan to use AI tools, and their single biggest frustration, at 66%, was AI output that is almost right but not quite, which is exactly the failure a specification exists to prevent.
Picture a CTO of a forty-engineer product company. She is our invention, but her month is not unusual. Her team adopts coding agents in March, and by the end of the month the pull-request queue has doubled. Nothing is shipping faster. Two senior engineers now spend most of their day reading diffs and asking, in review comments, what the change was supposed to do. Her throughput went up and her delivery went down, and she cannot tell whether the tools are the problem.
Every US dollar figure below converts at LKR 328.75, the Central Bank of Sri Lanka’s indicative USD/LKR spot rate for 10 September 2026.
What spec-first development actually means
A specification here is not a requirements document that nobody reads. It is a decision-grade artefact: scope, the data it touches, the states it can be in, the edge cases, and acceptance criteria written so that a reviewer can say yes or no without a meeting. It lives in the repository, it goes through review, and it is versioned like code.
GitHub’s spec-kit README, published in 2025, describes the same inversion: spec-driven development “flips the script on traditional software development”, so that “specifications become executable, directly generating working implementations rather than just guiding them”. The tooling is new. The idea is not, which is the argument we made in The Spec Was Always the Product.
The vendors have quietly agreed. Anthropic’s Claude Code documentation on project memory says a project CLAUDE.md should hold “instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows”, and that “these instructions are shared with your team through version control”. Read that as a governance statement rather than a configuration tip. The instructions your agents obey are now a reviewable file in your repository, owned by whoever owns the codebase.
The loop, step by step
The AI coding agents workflow has six stages, and only two of them are typing.
| Stage | Who does it | Artefact | How it is checked |
|---|---|---|---|
| Intent | Person, usually a product lead | One page: the problem, the decision it changes, what happens if nobody builds it | A named owner signs it, or the work does not start |
| Specification | Person, drafted with an agent | Scope, data touched, states, edge cases, acceptance criteria | Reviewed by an engineer who did not write it, until every “what happens when” is answered |
| Repository instructions | Person | Committed agent instructions: build commands, conventions, architectural decisions | Ordinary code review, because it is an ordinary file |
| Build | Agent | A branch and a pull request | Continuous integration, tests, and the diff read against the spec, not against taste |
| Review and merge | Person, one of your engineers | Merged commit, or a correction with a written reason | Approved untouched, or sent back with the reason recorded |
| Maintenance | Person, then agent | The spec is edited first, then the code | The change is refused if the spec was not updated |
Two things in that table do the work. The first is that the specification is reviewed by somebody who did not write it, before an agent sees it, because an ambiguity found at this stage costs a comment and an ambiguity found after the build costs a rewrite. The second is that the maintenance row is the one teams skip, and skipping it is how a spec-first codebase quietly becomes a normal one within four months.
What it is not: vibe coding and prompt libraries
Vibe coding is prompting your way to something that runs, then keeping it. It is genuinely useful, and we have argued that it killed the MVP as a category in The MVP Is Dead. Vibe Coding Killed It. The correct use of a vibe-coded prototype is as a question, not an answer: it surfaces the assumptions nobody wrote down, and then you throw it away and write the spec it revealed. The failure is keeping it, because you now own code whose intent exists only in a chat log somebody has closed.
A prompt library is not spec-first development either. A shared folder of clever prompts optimises the instruction to the model. A spec constrains the outcome regardless of which model reads it. The test is simple: if you swapped your agent for a different vendor’s agent tomorrow, would the artefact still be valid? A prompt would not be. A specification would.
There is a third legitimate method, eval-first, where you write the tests and let the agent satisfy them. It is excellent where correctness is fully expressible as assertions. Most business software is not, because the interesting requirements are policy and exception handling rather than arithmetic.
What changes for a CTO: review replaces typing as the bottleneck
This is the one structural change, and everything else follows from it. When typing was the constraint, you managed capacity by hiring people who type. When agents type, the queue moves to review, and review capacity is your senior engineers, who are the people you have least of.
The evidence points the same way. DORA’s 2024 Accelerate State of DevOps Report concluded that “AI adoption significantly increases individual productivity, flow, and job satisfaction. However, it also negatively impacts software delivery stability and throughput.” The report’s model estimated that a 25% increase in AI adoption was associated with a 7.2% decrease in delivery stability and a 1.5% decrease in throughput. Individual speed and system speed came apart, which is our CTO’s doubled queue in one sentence.
Three practical consequences. Batches must get smaller, not larger, because a reviewer can hold about four hundred lines in their head and an agent will happily produce four thousand. Reviewers need something to review against, which is the spec, or they fall back to reviewing style. And the review decision itself becomes a measurable signal, the same one we use for agents elsewhere in the business, described in what an AI agent’s approval rate means: the share of pull requests merged untouched, and the reason attached to every one that is not.
We set out which stages compressed and which did not in The SDLC Didn’t Get Faster. It Got Restructured. Coding and testing collapsed. Planning, design and maintenance did not, and now dominate.
Where spec-first development fails
Honesty first, because the method has a real failure envelope.
It fails on genuine exploration. If you do not know what you are building, writing a spec is a way of inventing certainty you do not have. Prototype first, then specify what you learned.
It fails where the domain is undocumented. A tax rule, a clinical pathway, a customs classification: if the rule has never been written down, spec-first surfaces that on day one, which feels like the method failing when it is the method working. Picture a four-partner audit practice in Colombo 2: it cannot hand over a compliance workflow to any agent until somebody writes down the three exceptions that live in one partner’s head.
It fails when nobody owns the spec. An unsigned specification is a wish list, and agents build wish lists confidently.
It fails on very small teams under real time pressure. Below roughly five engineers, the coordination cost the spec removes was not being paid anyway, and the ceremony can be net negative for a fortnight of work.
And it fails if the spec becomes a gate rather than an artefact. If updating it requires a committee, engineers will route around it, and you are back to intent living in a chat log.
How we install it, and what that costs
specshop.dev is an AI consultancy and AI agency in Colombo, Sri Lanka, led by Janaka Ediriweera, Principal AI and Product Management Consultant. There are two routes, and most teams need both.
The first is teaching your engineers the loop. Our AI training programme runs across two consecutive weekends, four live sessions plus about three hours of work in between, eighteen hours in total, at US$500 to US$2,000 per seat depending on the track, which is about LKR 164,375 to LKR 657,500. It is application-gated: two years of professional experience and at least one feature already shipped with Claude Code, Cursor, Devin or Aider. It covers all four of those tools, and it teaches spec-first against eval-first and vibe-then-verify rather than pretending only one method exists.
The second is a worked example inside your repository. Our delivery engineer is the senior post on the roster when you hire an AI agent, at US$3,000 a month, about LKR 986,250, with a one-off recruitment fee of US$9,500, about LKR 3,123,125, that covers deployment, tool connection, the 30-day probation with weekly scorecards and the first month’s salary. It builds to a signed spec, opens the pull request, and your engineers review and merge. The spec is the contract, and your team keeps the merge button.
What to do this week
Take the last three pull requests your team argued about. For each one, write the specification that would have prevented the argument, in one page, after the fact. That exercise costs an afternoon and tells you honestly whether your disagreements were about intent or about taste.
Then commit an instructions file to one repository, review it like code, and measure one number for a fortnight: the share of agent-authored pull requests merged untouched. If it is low, your spec is thin. If it is high and nobody is reading, you have a different problem, and it is worse.
Questions people actually ask.
What is spec-first development?
Spec-first development is a way of building software in which a written, decision-grade specification is agreed and signed before any code is generated, coding agents build to that specification, and a named human engineer reviews and merges every resulting pull request. The specification lives in the repository and is versioned and reviewed like source code, so intent survives after the chat session ends.
How is spec-first different from vibe coding?
Vibe coding produces working software from conversational prompts and keeps the result, so the intent behind the code exists only in a chat log. Spec-first treats a prototype as a question rather than an answer: you use it to surface hidden assumptions, write those assumptions into a specification, and then have the agent build against that document.
Do AI coding agents replace developers?
No, they move the bottleneck from typing to reviewing, which increases rather than reduces the value of experienced engineers. In the 2025 Stack Overflow Developer Survey, 45.7% of developers said they distrust the accuracy of AI output against 32.7% who trust it, and DORA’s 2024 report found AI adoption raising individual productivity while lowering delivery stability, both of which argue for more human review, not less.
How long does it take to move a team to spec-first?
Teaching the loop takes eighteen hours across two weekends, but a team habit takes about one delivery cycle, typically six to ten weeks, before the specification is genuinely written first rather than reconstructed afterwards. The signal that it has taken hold is when someone refuses to merge because the spec was not updated.
What size team is spec-first for?
It pays off from roughly five engineers upwards, and pays off most between twenty and fifty, where review capacity is scarce and coordination costs are already visible. Below five engineers on short pieces of work, the ceremony can cost more than the ambiguity it removes, so prototype and write the spec only for the parts you intend to keep.
Sources
- How Claude remembers your project, Claude Code documentation, Anthropic, 2026 — project instruction files hold “build and test commands, coding standards, architectural decisions, naming conventions, and common workflows”, and “these instructions are shared with your team through version control”. Fetched 10 September 2026.
- spec-kit README, GitHub, 2025 — spec-driven development “flips the script on traditional software development” so that “specifications become executable, directly generating working implementations rather than just guiding them”, with a six-step flow of establish, specify, plan, break down, implement and converge. Fetched 10 September 2026.
- AI, 2025 Stack Overflow Developer Survey — 84% of respondents using or planning to use AI tools in their development process; 66% citing “AI solutions that are almost right, but not quite” as their biggest frustration; 45.7% distrusting the accuracy of AI output (26.1% somewhat, 19.6% highly) against 32.7% trusting it. Fetched 10 September 2026.
- Accelerate State of DevOps Report 2024, DORA, 2024 — “AI adoption significantly increases individual productivity, flow, and job satisfaction. However, it also negatively impacts software delivery stability and throughput”, with the report’s model estimating a 25% increase in AI adoption associated with a 7.2% decrease in delivery stability and a 1.5% decrease in throughput. Fetched 10 September 2026.
- Daily Indicative USD/LKR Spot Exchange Rates, Central Bank of Sri Lanka, 2026 — the indicative rate of LKR 328.75 per US$1 on 10 September 2026, used for every conversion in this post.