Every coding tool ships a spec mode now, and the standard playbook has seven phases. We ran the full version for a month, then threw away everything except the spec. The spec survived because product took it over.
I was Lead AI Engineer at BuiltAI, where I championed spec-driven development for a team of 5 engineers, 2 product people and 3 analysts, and ran workshops on AI-assisted development for the wider company. This is what stuck, what we deleted, and what I’d tell an engineering manager deciding whether to roll it out today.
The 2026 playbook has seven phases. We kept one
The vendor version is sensible on paper. Microsoft’s guide to spec-driven development walks through Constitution, Specify, Clarify, Plan, Tasks, Implement and Validate, using GitHub’s Spec Kit. A DEV roundup of the 2026 tooling reviews 8 tools, from Spec Kit and Kiro to Cursor Plan Mode and BMAD, and describes much the same flow.
We started with Spec Kit. It got chunky very quickly. There was a learning curve, it produced a lot of content, and it was hard to tune to what we needed. It felt designed for large projects with big features. We needed something small that let us move faster.
The spec-kit phase lasted about a month. We wrote about 10 specs, then admitted it was too much work, too much to check and too much process. Engineers were very reluctant to pick it up.
So we stripped it to the bare minimum: a spec that encodes the business rules, a plan only for the big ones, then straight into implementation. The spec was the one artefact worth preserving.
The spec is a business document, and that’s the whole value
The moment it clicked was a complex recoveries feature. Lots of edge cases. We spent a long time discussing it with product and trying to write it down, and kept getting it wrong.
So I showed product the spec we’d written. They found a couple of misses and mistakes, edited the spec directly and sent it back to me. The feature landed.
The business had resisted at first. They saw specs as background engineering work that would block the real work. Once they had access, they were very pleasantly surprised that the specs matched the language they already talked in. They could review them, change them and share them with engineers.
Shifting from specs written by engineers to specs written and managed by product and analysts was probably the biggest change of the whole rollout. Bigger than any tool or template.
Once product owned the specs, engineering stopped being the bottleneck
Two things changed, for different reasons.
Throughput. Before, we developed 3-4 features a week. With AI coding working from product-owned specs, that became 3-4 features a day.
Lead time. Before, low testing confidence meant code sat in staging for 1-2 weeks while someone tested it. After we built a proper CI/CD pipeline and checks, features went straight to production. Releases went from roughly weekly to multiple times a day. These are the team’s numbers as I remember them, not a controlled measurement.
Specs drove the first. Gates drove the second.
Then the bottleneck moved. Product used to be ahead with planning and engineering was always behind. After the switch, the blocker was product, not engineering. If you roll this out, plan for that. Your product people become the constraint, and they need the time and the access to write specs, not just review them.
Engineers were slower to adopt than product. That was fine, because a spec can always be generated retrospectively from code that lacks one. Specs became the engineers’ default after we rewrote our cashflow engine in Rust. I argued against that rewrite at first. But because the logic was already in specs, it took weeks against an original estimate of about 6 months, and after that everyone saw the point.
Plans and task lists are dead weight now the models are good
The middle of the playbook died as the models improved. Plan, tasks, work breakdown: they became extra files that cost tokens and had to be maintained as additional sources of truth. The implementation changed several times after testing anyway, so the plan was out of date by the time the code worked.
It was easier to maintain two things: a business-language spec and the code. For bigger specs a reviewable plan was still useful. For everything else we skipped it.
I saw the same pattern on a personal project. I started it on the full Spec Kit flow, and across twenty-odd specs the tasks file was never produced once. When I cut the flow down to one spec per PR, I deleted far more than I added.
“But specs go stale.” Yes, and they inflate
Keeping spec and code in sync is still annoying. Skills and hooks help, but it’s still a bit of a pain. I don’t have a clean answer here.
The quieter problem is inflation. Left alone, specs grow: a bit more text, a bit more context that might not have been necessary, slowly growing files that don’t add anything. What fixed it was putting hard constraints in the spec skill itself:
- Business rules only.
- No implementation detail.
- A length cap.
- Required sections, so there’s nowhere to put filler.
On small projects I’ve stopped caring about staleness. I use specs as a planning tool: lots of them, worked through one by one and checked off. They drift, and that’s fine, because it’s so easy to rewrite one with AI.
“But what stops the slop?” Not specs
Gates are a separate question. Type checks, a TDD-style workflow and CI are what got our code right. They are necessary whenever AI writes code, with or without specs.
Specs tell the model what to build. Gates tell you whether it built it. A spec does not replace a test, and specs are not the only fix for AI slop.
Build your own spec skill instead of adopting a framework
Don’t adopt a framework. Tailor a spec skill to each project. AI makes that easy. Expect to throw it away later.
Here’s the structure of the template I use on a simple personal project. It’s just an example that has worked for me, not a standard:
# Spec: [feature name]
## Why
1-2 short paragraphs: what problem, for whom, why now. No implementation.
## Design
Links to mocks, plus key decisions only where a decision needs words.
## Requirements
- FR-001: System MUST [specific, testable capability]
Max 3 [NEEDS CLARIFICATION: question] markers.
## Key entities (only if data is involved)
## Success criteria (measurable, technology-agnostic)
## Out of scope
## Assumptions (one bullet per default chosen where the description was silent)The skill matters more than the template. It decides the scope (one spec, one PR), forces guesses into Assumptions instead of questions, and keeps requirements testable. A prompt to generate your own:
Write a Claude Code skill called /spec for this repository.
Context: who writes specs here is [product / analysts / engineers].
They should read like the language [that person] already uses.
The skill must:
- Create specs/NNN-slug/spec.md from a template you also write.
- Keep one spec to one PR's worth of work. If the request is bigger,
say so and propose a split.
- Contain business rules and testable MUST requirements only.
No implementation detail, no file names, no task lists.
- Use these required sections: Why, Requirements, Success criteria,
Out of scope, Assumptions. Add others only if this repo needs them.
- Cap the spec at [N] words and refuse to exceed it.
- Record guesses as Assumptions. Ask at most 3 clarifying questions.
Before writing, read the codebase and 2-3 recent PRs, and tell me
which parts of this template don't fit this project.Run it, read what comes out, and cut whatever your team won’t maintain.
Don’t over-invest: specs are probably temporary
What I’d say over a pint: don’t even try specs unless you’re ready to go down a hand-rolled, tailored route. Don’t try the frameworks. It’s all overkill.
And don’t try to build the perfect setup. As models improve, specs will probably become obsolete, the same way plans and task lists already did for us. Not every project needs a spec, and spending weeks on the optimal pipeline now probably won’t pay off in the long run.
For an engineering manager deciding on Monday: pick one feature with messy business rules. Have product write the spec with an AI-generated skill, get engineering to build from it, and make sure CI would catch it if the build were wrong. If product edits the spec and catches a mistake before any code is written, you have your answer.