level 01
Spec-First
most common
You write a spec, the AI builds it, you move on. The spec is thrown away after. Fine for one-off tasks and quick fixes. Useless six months later when you need to change something and the intent is gone.
// the ai productivity paradox
You bought the AI coding tools.
Your delivery didn't get faster.
Here's why — and what fixes it.
Individual developers really are coding faster with AI. But across nearly 45,000 professionals tracked in the industry's largest delivery study, the numbers that actually matter to a business — how fast features reach customers, how often releases break — barely moved. Specdr closes that gap by changing one thing: writing the specification first, and keeping it as the source of truth.
Faster typing isn't faster shipping.
Here's the uncomfortable finding the industry spent 2025 absorbing.
In a randomized controlled trial — the same gold-standard method used to test new medicines — researchers at METR watched 16 seasoned developers work through 246 real tasks on large, mature codebases. The expectation was a clear speed-up. The result was the opposite: with AI tools, the developers took 19% longer. More striking still, they believed AI had sped them up by about 20%. They were wrong about their own work, in the same direction as the hype.
In fairness, METR later cautioned that this single study shouldn't be read as the last word — selection effects may have shaped who participated. We agree. So we don't rest the argument there.
The durable evidence is bigger and harder to wave away. The State of DevOps research, drawing on roughly 45,000 professionals, and a separate analysis of around 10,000 developers both found the same pattern: AI tools lift individual output, while organization-level delivery — lead time, release frequency, failure rate — stays flat or even slips.
So the money got spent. The typing got faster. The business outcomes didn't follow.
AI is brilliant at building. It's terrible at guessing what you meant.
When you hand an AI assistant a vague request, it fills the gaps with assumptions. Some are right. Some aren't. The wrong ones don't announce themselves — they surface later as rework, as features that technically work but solve the wrong problem, as the slow grind of cleaning up code nobody fully specified.
The fix is old-fashioned and almost boring: decide what you want, precisely, before anything gets built. Write it down as a specification. Have the AI build against that specification. Keep the specification current as the source of truth — not a document that rots in a folder.
That discipline has a name. It's called spec-driven development, and the level that works for real teams is called spec-anchored.
Not all specs are created equal.
Spec-driven development comes in three maturity levels. Knowing the difference is the whole game.
// specdr operates here
level 02
Spec-Anchored
the team standard
Both the spec and the code are living, maintained artifacts. The spec is updated before the code changes, every time. New people read the spec to understand the system instead of reverse-engineering it. This is where teams building real products for the long haul belong.
level 03
Spec-as-Source
experimental
The spec is the only thing you maintain; code is regenerated on demand. Promising, but not yet reliable for production — the same spec doesn't reliably produce the same code twice, which breaks debugging and version control.
Specdr lives squarely at spec-anchored — the level the research backs and serious teams actually use.
A disciplined way to build software with AI — open source, and built on Claude Code.
Specdr is a free, open-source framework that turns spec-anchored development from a good idea into a repeatable process. It gives your team a structured path from "here's what we want" to working, maintained, production-ready software — with the specification anchoring every step so the AI never has to guess.
It's designed so that less-experienced engineers can run it confidently, with the AI as a genuine collaborator instead of an unpredictable autocomplete. The result is fewer wrong turns, less rework, and a system that stays understandable as it grows.
Under the hood it's a thirteen-step pipeline — from first feature spec through to production and the changes that come after — where every step produces a checked, signed-off artifact before the next one begins.
// 01
Spec first, always.
Every change starts with the specification, so intent is never lost.
// 02
Built on Claude Code.
Uses the most capable AI coding setup available, governed by structure instead of vibes.
// 03
Open source.
No lock-in, no license fee. Adopt it, read it, shape it.
// the loop, in full
Thirteen steps. Idea to production, and everything after.
Each step produces one validated artifact and hands it to the next. The specification anchors the whole chain, so nothing downstream has to guess.
specify
01 feature spec
02 requirements
design
03 architecture
04 data model
05 interface design
06 infrastructure
build
07 test contracts
08 implementation
09 ci / cd
ship
10 environments
11 qa + sign-off
12 production
sustain
13 maintenance
A gate on every step.
Nothing moves forward until an automated check, an AI consistency pass, and a human sign-off all clear. No step skips its review.
Decisions that can't quietly rot.
Every architectural call becomes a dated record with its own history. You supersede decisions in the open — you never silently rewrite them.
A specialist reviews the work.
Each step closes with a domain-expert pass — architect, database engineer, reliability engineer — that hunts for drift before it reaches the next step.
Open source, and built on Claude Code. Want a closer look?
The numbers behind the discipline.
~50%
fewer errors
when human-refined specs guide AI-generated code
— controlled studies, 2026
75%
cycle-time reduction
for API changes — caught at spec review, not in production
— documented case study
2 days
to ship a 2-week feature
spec mode used at enterprise scale
— AWS, Amazon Kiro
45,000+
professionals tracked
whose data exposed the paradox spec-anchoring solves
— State of DevOps
None of these come from us marking our own homework. They come from independent research and named companies. Spec-anchored development is now tracked on the Thoughtworks Technology Radar, and AWS, Red Hat, and Microsoft have all published enterprise guides for it. The question across the industry has shifted from "should we do this?" to "how do we do this at scale?"
This is how a smaller team out-ships a bigger one.
Follow the chain. AI makes building cheap. What it doesn't make cheap is clarity about what to build — and that's exactly the gap a specification closes. When the spec is doing the heavy lifting, your engineers stop burning hours decoding vague requests, cleaning up misread intent, and reworking features that missed. Most of the waste that quietly inflates a team's size simply stops happening.
That's the real payoff, and it's the honest one. Spec-anchored teams don't ship more because they hired more people or bought a faster tool. They ship more because far less work gets thrown away. The same output that used to require a larger group becomes reachable by a focused few — and the work that remains is the high-judgment work people actually want to do: deciding what's worth building, and confirming it was built right.
Smaller team. More shipped. Less rework.
That's not a slogan — it's what falls out of the math once clarity stops being the bottleneck.
The discipline travels.
Spec-anchored development isn't tied to one language, one industry, or one size of project. The research base spans API development, enterprise systems, and embedded software. Specdr itself supports the full range of modern stacks — web front-ends, mobile apps, back-end services, and cloud infrastructure across the major providers — at project complexity from a first MVP to a maturing product.
The reason it generalizes is simple: every kind of software benefits from someone deciding, clearly, what it should do before it gets built. That's true whether you're a two-person startup or a team onboarding contractors next quarter.
Where spec-anchored isn't the answer.
We'd rather you trust us than oversell you.
If you're building a weekend prototype, a throwaway script, or a one-time experiment, full spec-anchored discipline is overkill — the lighter spec-first approach is the right call, and we'll tell you so. The maintenance habit that makes spec-anchoring powerful only pays off when something will live and change over time, usually past the six-month mark, with more than one person touching it.
And the discipline is exactly that: a discipline. Specs have to be updated before code, every time, or they rot and mislead. Specdr is built to make that habit easy to hold — but no framework can want it for you. If your team will commit to that, the leverage is real and durable.
The framework is free. Help installing it isn't.
Adopting spec-anchored development is half framework, half habit. The framework is open source — you can read it, run it, adopt it on your own. But the habit is what makes or breaks the leverage, and that part isn't in the docs.
If your team wants help building the muscle — establishing the review cadence, getting the first three specs right, deciding what not to include — Peter works directly with engineering leaders to install spec-anchored practice end-to-end. Smaller team. Larger throughput. Less rework.
Engagements range from a handful of working sessions up to a full-quarter implementation. Honest scope, honest pricing.
Reach out to PeterBuild clearly. Ship more with less.
Specdr is open source and ready to read. Join the build list for new releases, field notes, and practical guidance on adopting spec-anchored development — written for teams, not for hype.
// newsletter
Join the build list
New releases, field notes, and practical guidance on adopting spec-anchored development.
// contact
Contact Peter
Want hands-on help adopting Specdr? Or a question we should answer in a future field note? Send a message.