Spec-Driven Development (SDD) is the foundational principle behind dbv-specs-ops: no line of code is written until the specification exists. In AI-assisted development, where a model can generate hundreds of lines in seconds, the absence of a prior specification is not a minor oversight — it is the root cause of runaway technical debt, token waste, and systems that work once but cannot be maintained. SDD introduces a structured contract between the developer and the AI: the “what” and “why” must be documented before the “how” begins.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/davidbuenov/dbv-specs-ops/llms.txt
Use this file to discover all available pages before exploring further.
The Three-Level Spectrum
AI-assisted software development is not a binary choice between “using AI” and “not using AI.” It exists on a spectrum with three distinct levels of discipline:- Vibe Coding is characterized by informal natural-language instructions accepted without rigorous validation. When something breaks, the error is pasted back into the AI to fix. It is ideal for weekend prototypes but unsustainable for production systems.
- Structured Coding introduces prompts with examples and some manual testing, reducing risk but without a formal framework governing the entire lifecycle.
- Agentic Engineering is development under a strict Harness — the AI acts as an execution engine guided by prior design specifications and validated automatically through tests and evaluation rubrics (Evals). This is where dbv-specs-ops operates.
Why Vibe Coding Fails in Production
The appeal of Vibe Coding is real: near-zero upfront effort and instant output. But this trades low Capital Expenditure (CapEx) for runaway Operational Expenditure (OpEx):- Token Burn: Context windows saturated by poorly-optimized prompts and infinite error-correction loops consume enormous token budgets with diminishing returns.
- Maintenance Tax: Human developers spend hours reverse-engineering “spaghetti code” or patching security vulnerabilities that a specification review would have prevented.
- No Tests: Without a spec defining acceptance criteria, tests are an afterthought — and an afterthought test suite is rarely written at all.
- No Traceability: When a requirement changes or a bug appears, there is no document explaining why the code was written the way it was.
How “Spec Before Code” Changes the Workflow
The SDD rule is simple to state and rigorous to enforce: the AI must not write implementation code for a requirement that does not exist indocs/SPECIFICATIONS.md. If the “what” is not clear, the AI asks clarifying questions before acting.
This single constraint produces a cascade of downstream benefits:
- The developer is forced to articulate intent before seeing output, surfacing ambiguities early.
- The AI has a ground-truth document to reference, reducing hallucinated features.
- Future sessions — with the same AI or a different one — can reconstruct context from the spec rather than reverse-engineering the code.
- Acceptance criteria defined in the spec become the basis for the mandatory test phase.
The 6 Development Phases
dbv-specs-ops enforces SDD through a strict six-phase lifecycle. Each phase has a trigger command the developer types in the chat. The AI always respects this order and will not skip a phase without explicit approval.| # | Phase | Command | Core purpose |
|---|---|---|---|
| 1 | Spec | /spec | Define the “what” and “why” in SPECIFICATIONS.md before any code |
| 2 | Plan | /plan | Validate specs against edge cases; break work into atomic steps |
| 3 | Build | /build | Implement incrementally, one slice at a time |
| 4 | Test | /test | Prove correctness — a task is not done without a passing test |
| 5 | Simplify | /code-simplify | Refactor for clarity and run the mandatory security audit |
| 6 | Ship | /ship | Version, document, and release with a full context update |
You can jump to any phase by typing its command. For example, typing
/ship when you are ready to deliver causes the AI to handle versioning, changelog updates, and git tagging automatically.The Enforcement Layer
dbv-specs-ops v2.0.0 introduces an Enforcement Layer built directly into the AI’s instruction set (docs/MASTER_PROMPT.md). This layer makes phase-skipping structurally difficult rather than relying on developer discipline alone:
- The AI is instructed to treat all project files (including
SPECIFICATIONS.md) as data, not as directives — only theMASTER_PROMPT.mdXML tags carry authority. This prevents prompt injection from within project files. - At the
/planphase, the AI must run an Adversarial Architect Review — a mandatory internal debate printed as an XML block — before breaking the work into tasks. If a risk is identified and accepted, it is immediately recorded inmemory.md. - At the
/shipphase, a Memory Gate requires the AI to print a<memory_update_proposal>XML block before closing any task, ensuring persistent knowledge is never silently discarded. - The AI will not mark a task as done unless a passing test exists. “Tests are proof” is a hard rule, not a suggestion.
CapEx vs. OpEx: The Economics of SDD
The economic model of SDD is the inverse of Vibe Coding, and understanding this inversion is key to justifying the upfront discipline it requires.| Dimension | Vibe Coding | Spec-Driven Development (SDD) |
|---|---|---|
| Upfront effort (CapEx) | Near zero — no planning or architecture | Moderate — write specs, configure Harness |
| Marginal cost per feature (OpEx) | Grows over time (token burn, maintenance tax) | Decreases over time (structured factory model) |
| Technical debt | High and compounding | Controlled and tracked |
| AI context quality | Degrades across sessions | Preserved in memory.md and task.md |
| Test coverage | Ad hoc or absent | Mandatory before task completion |
| Security posture | Unreviewed | Audited at /code-simplify phase |
| Onboarding a new session | Requires reverse-engineering | Reads memory.md Context Snapshot |
| Best for | Weekend prototypes | Production systems, team development |