Spec-first development means writing a specification — scope, acceptance criteria, edge cases, and non-goals — before an AI coding agent writes any code, so the agent executes against defined intent instead of inferring it from a prompt. It’s the entry point to the broader discipline of spec-driven development, which also includes spec-anchored development (the spec is maintained and re-used after the feature ships) and spec-as-source development (the spec becomes the only artifact humans edit directly). Spec-first alone answers what to build; it doesn’t answer how much scrutiny a given change deserves, who independently confirms the agent actually followed the spec, or what happens to that spec six months later. Those three gaps are where most spec-driven development attempts break down in production, and where a spec-anchored delivery method — proportional ceremony, independent verification, and a maintained spec — picks up the difference.
Engineering teams usually encounter spec-first development when ad-hoc prompting hits an invisible wall. A team writes lightweight specifications or adopts a spec kit, sees immediate speed gains on an isolated feature, and then encounters structural friction on the next release. Small bug fixes end up bogged down in heavy administrative ceremony, complex changes drift from architectural intent, and initial specifications sit unmaintained in repository folders after code merges. Structure scales, vibes don’t.
Evaluating human-refined specifications highlights why structured inputs matter for generative tooling. Research published in a February 2026 arXiv paper by Deepak Babu Piskala, titled “Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants”, demonstrates that human-refined specifications reduce LLM code-generation errors by up to roughly 50%. The same research confirms that passing spec-derived automated tests confirms compliance with written assertions rather than the overall correctness of the underlying software architecture. Bridging that gap requires moving past basic prompt structuring into a complete governance layer.
Spec-First, Spec-Anchored, and Spec-as-Source: What the Terms Actually Mean
The software industry has established clear terminology around spec-driven development (SDD) as an overarching discipline for AI-assisted engineering. Rather than treating all specification practices as identical, practitioners separate workflows into three distinct maturity levels based on how persistent and authoritative the written specification remains throughout the software lifecycle.
Level | What Happens to the Spec | Best Fit |
|---|---|---|
Spec-first | Written before code, guides the initial build, maintenance afterward is optional | Teams starting with spec-driven development; small, well-scoped features |
Spec-anchored | Persists and evolves alongside the code, often with governance checkpoints and audit requirements | Teams needing durable specs across a feature’s life, regulated or multi-team work |
Spec-as-source | The only artifact a human edits directly; code becomes a generated, non-hand-edited output | Narrow, API-first, or highly mature-tooling domains — still early in practice |
Level
Spec-first
Spec-anchored
Spec-as-source
What Happens to the Spec
Written before code, guides the initial build, maintenance afterward is optional
Persists and evolves alongside the code, often with governance checkpoints and audit requirements
The only artifact a human edits directly; code becomes a generated, non-hand-edited output
Best Fit
Teams starting with spec-driven development; small, well-scoped features
Teams needing durable specs across a feature’s life, regulated or multi-team work
Narrow, API-first, or highly mature-tooling domains — still early in practice
This taxonomy was independently established across the industry by IBM Think, Thoughtworks, and Augment Code to create standard definitions for engineering teams. In “What is Spec-Driven Development?“, IBM Think identifies spec-anchored development as the pragmatic target for most production engineering organizations, reserving spec-as-source for specialized environments with deterministic code generation pipelines.
SPD Technology’s Spec-First Delivery method originates every feature at the spec-first level while operating under spec-anchored rules by default. Specifications, architecture decision records (ADRs), and test plans exist as versioned assets inside the client’s source control repository rather than temporary prompt artifacts.
Engineers frequently confuse task-scoped specifications with project-level context engineering assets. This is the static vs. dynamic context distinction in practice: a specification defines a single, dynamic unit of work with clear boundaries and acceptance criteria, while context engineering assets — static rules files, AGENTS.md files, or project memory banks — supply persistent domain rules and architectural constraints that persist across multiple task runs.
Why Spec-First Alone Breaks Down Once Teams Move Past the First Feature
Adopting a spec-first approach delivers immediate clarity for isolated tasks, but applying uniform specification templates across an entire codebase exposes clear operational limits. Without a framework that adjusts overhead relative to risk, teams spend excessive time defining trivial code changes or watching agents bypass written instructions on complex architectural tasks.
Birgitta Böckeler at Thoughtworks watched this play out directly with real engineering teams, and wrote it up in Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl. One bug fix — a two-line change — went through a standard spec-kit workflow and came out the other side as four user stories and sixteen acceptance criteria. The mismatch alone tells most of the story.
What she found on larger tasks is more concerning: agents that failed to execute specific written directives even with a large context window and an explicit constitution file sitting right there in the repository. Böckeler’s own term for trusting that setup without checking it is “a false sense of control”.
Skip the enforcement gates and a maintenance tax starts accumulating — specialized AI technical debt that compounds with every cycle. IBM Think traces the outcome to three things: context drift, architectural fragmentation, and token costs that stop being sustainable once the pattern repeats. All three tend to surface at exactly the point a team tries to move from vibe coding to agentic engineering. A specification with no enforcement behind it doesn’t do much — it sits as documentation while the actual architecture drifts wherever the next prompt takes it, which is a fair description of why AI-generated code breaks in production once it’s running across a dozen engineering pods.
A better toolkit release doesn’t fix any of this. What actually closes the gap is proportional ceremony, independent verification, and a real plan for what happens to the spec long after the code has already merged.
The Governance Layer, Part One: Not Every Ambiguity Deserves the Same Scrutiny
Unmanaged specifications slow down engineering velocity by treating minor implementation details with the same administrative weight as core system changes. Establishing a functional governance layer starts by matching review intensity directly to the risk profile of each individual task.
Classify by Reversibility, Not by Presence
Open questions identified during specification drafting are classified strictly by the cost of reversing a wrong decision. Reversible choices, such as internal UI spacing or non-critical default values, receive automated defaults to keep work moving forward. Irreversible decisions involving database schemas, public API contracts, payment processing workflows, or regulatory compliance boundaries halt execution until an engineer records an explicit approval.
Three Depths, Not One Ceremony
Specification depth operates as an explicit setting configured at the project or feature level. Light depth automatically resolves reversible choices using repository standards, standard depth applies balanced review to feature additions, and deep depth enforces full trade-off analysis across system dependencies. This structure prevents early-stage prototypes and regulated financial services features from navigating identical approval workflows.
Defaults Are Never Silent
Nothing here happens silently. Every default the tooling takes during a task gets written into a structured log the moment it’s made, and none of it locks in until an engineer sees it — all of it lands in one summary batch, ready for a quick review or a veto before code generation proceeds. Speed and visibility aren’t a trade-off under this model; the batch is what lets both hold at once.
The Governance Layer, Part Two: How Much Autonomy Should the Agent Get, Task by Task
Granting a coding agent full system access across every task introduces severe operational risk, while restricting agents to line-by-line autocomplete eliminates their productivity benefits. Teams need a dynamic execution strategy that scales agent permission boundaries based on measurable safety controls.
SPD Technology’s calibrated autonomy framework ties an agent’s operational freedom directly to two things: how strong the verification around it is, and how bad the blast radius would be if it got something wrong. Permission is set per task type — a repository doesn’t get one blanket setting applied across everything in it. At the top tier, once verification has earned it, agents run parallel task streams inside isolated environments and merge everything back through the same standard integration gates.
Zone | Typical Task Type | Governing Rule |
|---|---|---|
Zone 1 — Always human-led | Architecture, security, payments, personal data, public API contracts | AI advises; a human decides and reviews — no exceptions, regardless of how confident the spec seems |
Zone 2 — AI-assisted, human-verified | Features, refactoring, bug fixes, integrations | The agent builds against the spec and its tests; an accountable engineer reviews the evidence on every change |
Zone 3 — Automated, machine-verified | Test generation, documentation, routine maintenance | Runs at full speed inside strict, automated checks — earned by being cheap to verify and easy to undo |
Zone
Zone 1 — Always human-led
Zone 2 — AI-assisted, human-verified
Zone 3 — Automated, machine-verified
Typical Task Type
Architecture, security, payments, personal data, public API contracts
Features, refactoring, bug fixes, integrations
Test generation, documentation, routine maintenance
Governing Rule
AI advises; a human decides and reviews — no exceptions, regardless of how confident the spec seems
The agent builds against the spec and its tests; an accountable engineer reviews the evidence on every change
Runs at full speed inside strict, automated checks — earned by being cheap to verify and easy to undo
Who Verifies That the Agent Actually Followed the Spec
Assigning the same coding agent to both write software and verify its own compliance creates a fundamental conflict of interest. An agent checking its own output re-evaluates code using the identical context, assumptions, and implicit biases that introduced the original defect.
To resolve this self-review failure mode, SPD Technology’s governance framework introduces an explicit verifier and challenger split. The verifier role inspects code changes directly against the written specification to confirm complete feature coverage. The challenger role operates under an adversarial posture, actively attempting to break the implementation by probing unstated assumptions, edge cases, and hallucinated dependencies. Augment Code details a related concept in “What Is Spec-Driven Development? A Complete Guide“, where a single dedicated verifier checks output from an implementor role before integration. SPD Technology extends this concept by separating verification into two distinct postures — confirmation and active attack — rather than relying on a single checking pass.
Serhii Leleko
AI & ML Engineer at SPD Technology
“The reason a single reviewing agent doesn’t catch what a verifier and challenger split does is structural, not a matter of trying harder. A verifier confirming its own implementation against the spec starts from the same assumptions that produced the code — the check is correlated with the mistake, not independent of it. Splitting confirmation from active attack is what actually breaks that correlation.”
This is zero-trust development applied to AI-generated output: the author of a change — whether human engineer or autonomous agent — is strictly prohibited from approving their own work, and independent review remains mandatory across all task zones.
Tests Are The Contract, Not The Proof
Writing test requirements before any code exists changes what testing actually does inside the workflow. A test suite drafted this early becomes the boundary the agent has to build inside of, present from the very first line of implementation. Drafting it early also earns its place for a plainer reason: it forces someone to name the expected behaviors, the boundary conditions, and the error states before the implementation quietly decides them on its own.
Every task specification requires a corresponding test suite drafted prior to implementation, following a strict red-green-refactor cycle where initial tests fail explicitly for the expected reasons. Passing automated test suites demonstrates that generated code satisfies specific assertion statements, but passing tests alone do not prove full specification compliance — this is the tests vs. evals distinction in practice: tests verify deterministic outputs, while the verifier and challenger roles above are effectively running the evals that verify non-deterministic agent judgment.
The Piskala arXiv paper underscores this limit, proving that green test runs validate assertion logic rather than underlying system health. Verifying true compliance requires pairing deterministic unit and integration tests with independent verifier and challenger reviews that assess code design, security implications, and spec alignment.
A passing test log is not the same thing as watching the software actually run. Verification means observing real behavior inside a live execution environment, not just reading assertions that came back green. Sometimes that direct observation isn’t possible yet — the environment isn’t ready, or the dependency is still mocked. In that case, the execution record has to say so plainly: which functional areas were actually watched running, and which ones are still waiting on staging to confirm.
Making Spec Compliance Auditable: The Evidence Package
Engineering leaders and compliance reviewers require verifiable proof that generated code satisfies technical and regulatory standards. Claims of spec compliance carry little weight during audits or security assessments unless backed by concrete artifacts produced during execution.
SPD Technology’s evidence package framework solves this by automatically aggregating execution artifacts directly from the CI/CD pipeline into a permanent audit trail:
- Plain-language change summaries linked directly to the full source diff
- Automated unit, integration, and regression test execution logs
- Static code quality metrics and dependency security scan outputs
- Independent review sign-offs recorded by designated verifiers and challengers
- Documented rollback procedures and environment contingency plans.
Attach an evidence package to every pull request, and a specification stops being a temporary planning draft — it becomes an audit record nobody can quietly edit after the fact. Versioning those packages alongside the codebase commits themselves, and the project as a whole shifts from basic spec-first mechanics into something that actually behaves like spec-anchored development. Technical founders and compliance leads get the same thing out of it either way: full visibility into why a system looks the way it does today, not just what changed.
Adopting Spec-First Development: A Phased Path
Most rollouts fail for the same reason: someone tries to overhaul the entire delivery pipeline at once. A governed specification workflow only actually sticks when it’s adopted in stages, each one building enough team capability to absorb the next without the whole operation stalling out.
Microsoft’s own developer guidance lays out a tool-centric version of this using GitHub Spec Kit — constitution files, then specification drafting, then a plan, then task execution, moved through in sequence. SPD Technology takes that same shape and adapts it into something built around risk management and team capability instead of tool installation.
Order | Phase | Timeline | Relative Effort |
|---|---|---|---|
1 | Pilot on one real feature with visible ceremony or verification friction | 1–2 weeks | Low — scoped to a single team and feature |
2 | Formalize a lightweight spec template and the reversible/irreversible classification | 2–3 weeks | Medium — mostly team agreement, not new tooling |
3 | Wire in independent verification (verifier + challenger) and a minimal evidence package | 3–5 weeks | Medium-High — depends on existing review culture and CI maturity |
4 | Expand autonomy zones and spec-anchoring based on pilot evidence | Ongoing | High — this is where the practice becomes durable, not a one-time rollout |
Order
1
2
3
4
Phase
Pilot on one real feature with visible ceremony or verification friction
Formalize a lightweight spec template and the reversible/irreversible classification
Wire in independent verification (verifier + challenger) and a minimal evidence package
Expand autonomy zones and spec-anchoring based on pilot evidence
Timeline
1–2 weeks
2–3 weeks
3–5 weeks
Ongoing
Relative Effort
Low — scoped to a single team and feature
Medium — mostly team agreement, not new tooling
Medium-High — depends on existing review culture and CI maturity
High — this is where the practice becomes durable, not a one-time rollout
Starting with an isolated feature pilot exposes where current processes introduce unnecessary friction or lack adequate controls. Mapping out the initial path from vibe-coded MVP to production system helps teams calibrate autonomy settings before expanding the methodology across broader engineering pods scaling from MVP to platform.
Spec-First Development Readiness Checklist
Evaluating an organization’s readiness for agentic engineering requires assessing governance controls, verification protocols, and specification maintenance practices. Teams can use this checklist to identify critical gaps in their current workflow:
-
Open questions in a spec are classified by reversibility, not treated uniformly — otherwise small changes carry the same ceremony as irreversible ones, or worse, irreversible ones carry too little.
-
Autonomy level is set per task type, not once for the whole project — otherwise high-risk work gets the same freedom as routine maintenance, by default rather than by decision.
-
A verifier confirms spec compliance independently of the change’s author — otherwise “the agent checked its own work” gets treated as verification when it isn’t.
-
A separate adversarial pass actively tries to break each change — otherwise edge cases and hallucinated dependencies that a confirming review misses ship anyway.
-
Every task’s test plan exists before implementation starts — otherwise “tests pass” becomes the only signal, standing in for spec compliance it doesn’t actually confirm.
-
Releases carry an evidence package, not just a merged PR — otherwise a claim that the spec was followed can’t be checked by anyone who wasn’t in the room.
-
Specs are versioned in the repository and revisited after ship, not archived — otherwise the spec goes stale within a quarter and the next change starts from a prompt again.
-
Legacy code gets a characterization-test safety net before a spec-first workflow touches it — otherwise AI-assisted changes to undocumented systems have no way to prove they preserved existing behavior.
The full AI Production-Ready Checklist goes further into what that looks like for an enterprise deployment.
Our Expertise: Running Spec-First Delivery in Production, Not Just in a Toolkit
SPD Technology’s Spec-First Delivery method — the engineering machinery behind our zero-to-one service offering and verified velocity framework — executes the governance layer described throughout this article as a standard delivery discipline. Our teams integrate decision protocols, calibrated autonomy zones, and independent verification directly into daily development workflows to maintain high delivery velocity without sacrificing system quality.
- Every feature specified through SPD Technology’s decision protocol travels a gated pipeline — baseline, frame, design, plan, build, assure — where the spec is a required artifact at every stage, not a one-time planning document.
- Reversible and irreversible decisions are classified explicitly during specification, with irreversible calls signed off by a named human before implementation starts, regardless of how fast the rest of the task moves.
- Every AI-generated change is judged independently of its author — a verifier confirms the change matches the specification, and a separate challenger’s only job is to attack it, before it can merge.
- Legacy systems are brought into a spec-first workflow behind a characterization-test safety net that pins down current behavior before any AI-assisted change is made, so modernization doesn’t risk silently breaking what already works.
- Specs, decision records, and test suites are versioned in the client’s own repository from day one and remain the client’s asset — built to behave like spec-anchored development by default, not spec-first-and-forgotten.
Governance is the whole difference between an experimental spec-first attempt and a practice that actually holds at spec-anchored maturity. An engineering lead doesn’t need to guess where that gap sits, either — a targeted pilot on one production feature will show exactly where the current delivery pipeline needs stronger verification controls.
Conclusion
Spec-first development is a genuine entry point on the path from vibe coding to agentic engineering. Getting it to hold at production scale is a different problem, and it’s solved by governance, not by a better prompt. Proportional ceremony, independent verification, specs kept as versioned assets through the whole software lifecycle — sustaining velocity past the first release depends on all three holding at once.
Generation is solved. Verification, judgment, and direction are the new craft. The fastest way to find out which of the three a team is actually missing is to run one real feature through a governed pilot and see exactly where the process resists on the way to durable, spec-anchored delivery controls.
Key Takeaways
- Spec-first, spec-anchored, and spec-as-source are three different levels of commitment, not synonyms — a spec written once and never revisited is spec-first by definition, however rigorous it was on day one.
- Applying the same specification ceremony to a one-line change and an irreversible architectural decision isn’t thoroughness — it’s the documented cause of teams abandoning spec-driven development as too heavy for daily use.
- An agent reviewing its own output inherits the same blind spots that produced it in the first place. That’s the whole case for independent verification: it has to be a role the author never holds, full stop — running the same agent through a second prompt doesn’t change who’s doing the looking.
- Green tests confirm the deterministic slice of a task; they don’t confirm the agent’s approach matches the spec’s intent, which is why “tests passed” and “verified” are different claims.
- A spec without an evidence package is a claim a reviewer has to trust; the same spec with test results, scan outcomes, and an independent sign-off attached is something they can check without being in the room.
- Legacy code has no spec-to-anchor a spec-first workflow to, which is why AI-assisted changes to undocumented systems need a characterization-test safety net before the workflow can apply at all.
- A spec that isn’t versioned and revisited after a feature ships reverts to a prompt by the next change — which is the mechanism by which “we tried spec-driven development” quietly becomes “we used to.”
In short: spec-first gets a team started; proportional ceremony, independent verification, and a maintained spec are what make it survive contact with production.
Frequently Asked Questions
What’s the difference between spec-first and spec-driven development?
Spec-driven development (SDD) is the umbrella term for building software where a specification, not a prompt, is the primary source of truth for an AI coding agent. Spec-first is the entry-level pattern within that umbrella: a spec is written before code, guides the initial implementation, and may or may not be maintained afterward. The two more advanced patterns — spec-anchored (the spec persists and evolves with the code) and spec-as-source (the spec becomes the only artifact a human edits directly) — are also forms of SDD, so “spec-first” describes a starting point, not the full discipline.
How much specification does a task actually need before an AI agent should start?
The amount of specification should scale with how expensive a wrong assumption would be to undo, not with the size of the feature. A reversible decision — a default value, a UI copy choice — can take a sensible default and move on; an irreversible one — a data model, a public API contract, anything touching payments or personal data — needs an explicit decision before implementation starts. Teams that apply the same depth of specification to every task regardless of risk tend to abandon the practice as too slow for routine work, a documented failure mode in independent reviews of spec-driven toolkits.
Can an AI agent verify its own compliance with a spec?
Not reliably. An agent asked to implement a task and then confirm it followed the spec is checking its own work with the same assumptions and blind spots that produced the implementation in the first place. Independent verification requires a role the implementing agent never holds — ideally two distinct postures, one confirming the change matches the specification and a separate one actively trying to find what the confirming review would miss, such as skipped edge cases or dependencies that don’t actually exist.
Does spec-driven development work for legacy codebases with no existing specs?
Yes, but not by writing a spec for the whole system retroactively, which is rarely practical. The safer approach is to first capture what the existing system actually does today in a characterization test suite — automated tests that pin down current behavior without judging whether it’s correct — and then apply spec-first development to new changes inside that safety net. This lets AI-assisted modernization proceed at speed while the characterization suite proves that existing behavior wasn’t silently broken along the way.
Is spec-driven development the same as test-driven development (TDD)?
No, though they’re complementary and often used together. TDD defines a unit’s correctness through a failing-then-passing test, written before the implementation, at the level of a single function or component. Spec-driven development defines a broader unit of intent — scope, acceptance criteria, edge cases, non-goals — before an AI agent generates any code at all, and the resulting tests are typically one output of that specification rather than the specification itself. A green test suite confirms the deterministic behavior it covers; it doesn’t confirm the implementation matches the spec’s broader intent, which is why independent review still matters alongside tests.
What happens to a spec after the feature it describes ships?
That depends entirely on which level of spec-driven development a team is practicing. In spec-first development, nothing happens to the spec by default — it served its purpose and may go stale as the code evolves. In spec-anchored development, the spec is versioned in the repository, treated as a living artifact, and updated as the feature changes, which is what lets it keep catching drift long after the first release. Teams that expect spec-driven development to keep paying off past the first feature need to deliberately choose spec-anchored practice — it doesn’t happen automatically just because a spec existed once.
How much does a spec-first pilot cost, and how long does it take?
Cost and timeline scale with scope: a pilot is deliberately tied to one real feature, not a full-platform re-architecture, which is what keeps the first phase to roughly 1–2 weeks. That scoped pilot is the mechanism that calibrates everything after it — a team can’t seize the cost of full governance (verifier/challenger roles, an evidence package, autonomy zones) until one real feature shows where the existing process is over- or under-invested. SPD Technology’s engineering team scopes this as a pilot engagement precisely so cost and timeline are set against a concrete feature, not a generic estimate.