Install the pipeline
The open-source pipeline handles the entire workflow from finding to pull request. Install it in under a minute./plugin marketplace add cdeust/ai-architect-feedback-loop/plugin install ai-architect-feedback-loop
What Is Spec-Driven Development?
Spec-driven development is a methodology where you write a verified specification before you write a single line of code. The specification defines what the system should do, why it should do it, and how success is measured. Everything else — implementation, testing, documentation, deployment — follows from that specification.
This is not a new idea. Engineers have been writing specifications for decades. What is new is the ability to enforce those specifications automatically. When a specification is structured, verified, and machine-readable, it becomes more than a document. It becomes an executable contract that an autonomous pipeline can implement, test, and deliver.
The core principle of specification-driven development is simple: if you can describe what you want precisely enough, the implementation becomes mechanical. The intellectual work happens at the spec level — clarifying requirements, resolving ambiguities, defining edge cases, setting acceptance criteria. The coding work becomes a translation problem, and translation is exactly what AI excels at.
This stands in contrast to the "code first, document never" approach that dominates most software teams. In that model, developers jump straight into implementation, discover requirements as they go, and produce documentation (if any) as an afterthought. The result is code that works but is poorly understood, hard to verify, and expensive to change. Specification first development inverts this: you invest upfront in understanding the problem, and the implementation becomes the cheap part.
Why Spec-Driven Development Works
Specifications catch bugs before code exists
Every bug that reaches production started as an ambiguity in the requirements. When you write a specification and verify it — checking for contradictions, missing edge cases, and untestable claims — you eliminate entire categories of defects before any code is written. Verification at the spec level costs a fraction of what debugging costs at the code level. This is the foundation of requirements-driven development: fix the requirements, and the code fixes itself.
Specs are the best prompt for AI
An AI agent given a vague instruction produces vague code. An AI agent given a verified specification — with acceptance criteria, edge cases, API contracts, data schemas, and traceability requirements — produces code that matches what you actually need. The specification eliminates the guesswork. This is why spec to code automation works: the specification is the prompt, and a good prompt produces good output. The better the spec, the less iteration you need.
Specs create accountability
In a spec-driven workflow, every line of code traces back to a requirement. Every test traces back to an acceptance criterion. Every decision traces back to a design choice documented in the specification. When something breaks, you can follow the chain from the failure back to the requirement that was violated. When something changes, you can trace the impact from the requirement forward to every piece of code and every test affected. Executable specifications make this traceability automatic, not aspirational.
Specs survive team changes
Code is written once but read hundreds of times. Specifications are the highest-leverage documentation you can write because they capture intent, not just implementation. When a new developer joins the team, they can understand the system from the specifications alone — what it does, why each decision was made, and what the boundaries are. The spec is the institutional memory that survives when the original developer leaves.
The 5-Phase Spec-Driven Workflow
Spec-driven development is not waterfall. Specifications are living documents that evolve as you learn more about the problem. But the workflow follows a deliberate sequence: understand the problem before you solve it, verify the solution design before you implement it, and confirm the implementation before you ship it.
1
Discover
Gather the raw material: bug reports, feature requests, user research, performance data, competitive analysis, or research papers. The goal is to understand the problem space before prescribing a solution. In this phase, you collect findings — not requirements.
2
Specify
Transform findings into a verified specification. This is the core of the specification first workflow. You write a PRD that includes acceptance criteria, edge cases, API contracts, data schemas, security considerations, and performance targets. Critically, you verify the specification — checking for contradictions, ambiguities, untestable claims, and missing requirements. The spec is not done until it passes verification.
See how the PRD Generator handles this →3
Implement
Generate code from the specification. This can be fully automated (spec to code automation via an AI agent), partially assisted (AI generates a scaffold, human refines), or entirely manual. The key insight is that when the spec is precise, the implementation is a translation — and translation is where AI agents deliver the most value. Write spec, generate code — the spec is the source of truth.
See the implementation pipeline →4
Verify
Run quality gates against the implementation. This includes unit tests, integration tests, linting, type checking, semantic verification (does the code actually do what the spec says?), and benchmarking (does it meet the performance targets?). Verification is not just "do the tests pass" — it is "does the implementation satisfy the specification."
5
Deliver
Ship the verified implementation as a pull request with full traceability. Every requirement in the spec maps to code changes and test cases. The PR description links back to the specification. Reviewers can verify not just that the code works, but that it implements the right thing. This is the end-to-end specification to pull request workflow.
Specs are not rigid contracts. Unlike waterfall, the specification evolves. If you discover something during implementation that changes your understanding of the problem, you update the spec. The discipline is not "never change the spec" — it is "never change the code without updating the spec first." The specification stays in sync with reality.
Spec-Driven Development with AI Architect
AI Architect is a PoC that implements spec-driven development end to end. The open-source 14-stage pipeline maps to the 5 phases above: stages 1-4 handle discovery and analysis, stages 5-6 generate and review the specification, stages 7-11 implement and verify, stages 12-14 benchmark and deliver.
The PRD Generator powers the specification phase. It uses 15 thinking strategies to produce specifications with acceptance criteria, verified claims, and traceability. Not generic templates — specifications grounded in your codebase. It asks clarification questions until ambiguities are resolved, then produces the spec with a verification audit trail.
Once the specification exists, the pipeline takes over. Implements the spec, runs quality gates, verifies against the original requirements, benchmarks, creates a PR. Does it always produce merge-ready code? No. But the architecture is there — and the spec means every failure is traceable back to a specific requirement.
> /plugin marketplace add cdeust/ai-architect-feedback-loop
> /plugin install ai-architect-feedback-loop
> /plugin install ai-architect-feedback-loop
From specification to pull request
The pipeline is free and open source. The PRD Generator is free and open source.
Spec-Driven vs. TDD vs. Code-First
Spec-driven development is not opposed to test-driven development. It is a superset. TDD asks "does the code do what the tests say?" Spec-driven development asks "do the tests verify what the specification requires?" The spec layer sits above TDD and gives it direction.
| Spec-Driven | TDD | Code-First | |
|---|---|---|---|
| Starting point | Verified specification | Failing test | IDE and intuition |
| Verification timing | Before code exists | During implementation | After implementation (if ever) |
| Documentation | Spec is the documentation | Tests are partial documentation | Written retroactively or not at all |
| AI compatibility | Ideal — spec is the prompt | Partial — tests constrain but do not direct | Poor — AI guesses at intent |
| Traceability | Requirement to code to test | Test to code only | None |
| Rework cost | Low — caught at spec level | Medium — caught at test level | High — caught in production |
The practical difference is this: in a spec-first workflow, you know what to build and why before you write a single test. TDD tells you whether your implementation is correct. Spec-driven development tells you whether your implementation is right — that it solves the actual problem. The best teams use both: the spec defines what to build, TDD ensures it is built correctly.
Get Started
You do not have to adopt this all at once. Start with one feature. Write the spec before writing the code. Verify the spec. Then let the pipeline try to implement it. See what it gets right and what it misses.
1
2
Write your first spec
Describe the feature you want to build. The PRD Generator asks clarification questions, selects a thinking strategy, and produces a verified specification with acceptance criteria, edge cases, and a traceability matrix.
3
Let the pipeline implement it
Run /run-pipeline in Claude Code. The pipeline reads your spec, implements the code, runs quality gates, verifies against the original requirements, and creates a pull request. You review the result, not the process.
Try it on one feature
Write the spec. Let the pipeline try to implement it. See where it works and where it does not.