# Beyond the Hype: Practical Spec-Driven Development with AI Agents for Traceable Code Delivery > Source: > Published: 2026-09-19 12:02:03+00:00 *Originally published on [tamiz.pro](https://tamiz.pro/insights/spec-driven-development-ai-agents-practical-guide).* The era of "vibe coding"—where developers prompt an LLM, review the output, and push it to production without a structured rationale—is colliding with enterprise realities. Systems are too complex, security audits are too rigorous, and the cost of silent hallucinations in code generation is too high. To move from experimental AI assistance to reliable, production-grade software delivery, engineering teams must shift from an output-first mindset to an intent-first methodology: Spec-Driven Development (SDD). This deep-dive explores how to implement SDD using AI agents, transforming natural language requirements into executable, machine-readable specifications. We will dissect the architecture, the data contracts, and the deterministic validation loops required to build an evidence-backed pipeline that guarantees traceability from initial intent to the final deployed artifact. In traditional AI-assisted coding, the prompt is ephemeral; the context is limited to the model's memory window or the immediate conversation state. SDD replaces this fragility with a structured contract. Instead of asking an agent "write a function to handle user authentication," the system defines a JSON schema that explicitly dictates the input boundaries, error handling, and expected state mutations. The architecture rests on three core pillars: LLMs are non-deterministic. To achieve traceable code delivery, the agent loop must be wrapped in deterministic guardrails. The process flows as follows: The quality of SDD is entirely dependent on the quality of the specification. Vague specs produce vague code. We must use structured data formats that are easy for humans to review and precise enough for machines to enforce. Consider a payment processing feature. A natural language prompt might say: "Process a credit card payment and handle failures." A spec-driven contract for this feature must explicitly define the data flow. Below is a simplified example of a `FeatureSpec` object. This JSON serves as the single source of truth for both the human developer and the AI agent. ``` { "specId": "PAY-2023-001", "version": "1.0.0", "intent": "Process a credit card payment via Stripe", "inputs": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Amount in cents" }, "currency": { "type": "string", "pattern": "^[a-zA-Z]{3}$" }, "cardToken": { "type": "string" } }, "required": ["amount", "currency", "cardToken"] }, "constraints": [ "Amount must not exceed the user's verified limit." ], "expectedOutputs": { "type": "object", "properties": { "status": { "enum": ["success", "declined", "pending"] }, "transactionId": { "type": "string", "format": "uuid" } } }, "errorContract": { "failureModes": ["INSUFFICIENT_FUNDS", "CARD_EXPIRED", "NETWORK_TIMEOUT"] } } ``` In SDD, tests are not written after the code; they are derived *from* the specification. Before any code is generated, the system parses the `inputs` and `expectedOutputs` to generate a matrix of test scenarios. `minimum` and `maximum` values.`amount: -5`, `currency: "USD"`).` errorContract` failure modes. By treating the spec as a generator for tests, we ensure that the AI agent's success criteria are mathematically defined, removing human bias from the code review process. The agent is not just a text generator; it is an orchestrator of tools. We will outline a reference implementation using Python and an LLM capable of tool use. The agent operates in a sandboxed environment where it can read files, execute tests, and query the database schema, but cannot push code to production without human approval. The agent must maintain a "Working Memory" that contains the spec, the current state of the code, and the history of previous failures. This prevents the agent from entering a loop where it repeatedly tries the same failing code modification. ``` python class SpecDrivenAgent: def __init__(self, llm_client, spec_path, repo_context): self.llm = llm_client self.spec = load_json(spec_path) self.repo = repo_context self.history = [] # Keeps track of past attempts and errors def execute(self): # 1. Generate Test Cases based on Spec test_suite = self.derive_tests_from_spec(self.spec) # 2. Initial Plan Generation plan = self.llm.generate_code_plan(self.spec, self.repo) # 3. Static Validation of Plan if not self.validate_plan_against_constraints(plan): raise SpecViolationError("Proposed plan violates business constraints.") # 4. Code Generation & Execution Loop max_retries = 3 for attempt in range(max_retries): code = self.llm.generate_code(plan, test_suite, self.history) self.repo.apply_code(code) test_results = self.repo.run_tests(test_suite) if test_results.passed: self.generate_evidence_log(test_results, plan) return "SUCCESS" else: # Append the specific failure context to history # This forces the LLM to look at the exact failing assertion self.history.append({ "code_attempted": code, "failure_log": test_results.stderr, "attempt": attempt }) raise AgentExhaustedError("Failed to satisfy spec constraints.") ``` The `validate_plan_against_constraints` function is the critical safety net. Before the LLM writes code, it must prove that its plan aligns with the architectural rules. This validation is deterministic and does not rely on the LLM. `doNotTouch` array. If the LLM plans to modify `core/database.py` when the spec dictates changes to `services/payment.py`, the static validator rejects the plan. The core value proposition of SDD for enterprise engineering is traceability. When an audit asks, "Why was this database query written with a `LIMIT 100` instead of `LIMIT 50`?", the system must be able to provide the exact chain of evidence. Every time the agent generates code, it outputs an `EvidenceLog`. This is an immutable record that links the spec ID to the code commit. ``` { "specId": "PAY-2023-001", "commitHash": "a1b2c3d", "generationTimestamp": "2023-10-27T10:00:00Z", "modelVersion": "claude-3-opus", "testMatrix": [ { "testName": "test_payment_success", "status": "passed", "duration": "0.4s" }, { "testName": "test_card_declined", "status": "passed", "duration": "0.1s" } ], "reasoning_trace": [ "Step 1: Analyzed spec. Payment amount must be > 0.", "Step 2: Generated initial implementation.", "Step 3: Test 'test_insufficient_funds' failed due to missing status code 402.", "Step 4: Modified exception handler to return 402 as per spec.errorContract." ] } ``` By storing the `reasoning_trace`, you create a human-readable audit trail that mirrors the LLM's decision-making process. For deeper dives into how to manage LLM observability and audit logs at scale, see [tamiz.pro](https://tamiz.pro). In continuous integration (CI), the Evidence Log is attached to the Pull Request. If the tests pass, the PR is automatically tagged with the spec IDs that it satisfies. This creates a bidirectional link: While SDD is powerful for discrete, well-defined features, it faces challenges in complex, stateful systems. AI agents frequently fail when they need to understand the current state of a database. In SDD, the spec must include a `ContextState` section. Before code generation, the agent is provided with a read-only snapshot of the database schema (via migration files or DBML) and sample data. If the spec requires altering the database schema, the `evidence_log` must include the exact migration file generated by the agent. This migration is then reviewed by a human DBA before execution, maintaining the human-in-the-loop requirement for data integrity. For microservices, the spec must define the event contracts. The `expectedOutputs` in the spec should not just be HTTP responses, but also emitted domain events. `PaymentProcessed` event to the `payments` topic." Implementing SDD requires strict security boundaries. Agents must never run with production credentials. Each agent execution should happen in an ephemeral CI runner (e.g., GitHub Actions ephemeral container, or a disposable AWS Fargate task). `environment` configuration. The spec file is a critical data asset. It contains business rules that define the system's behavior. Therefore, spec files must be treated with the same security clearance as source code. Use version control (Git) with branch protection. Require human code review for spec changes, even if the spec is generated by another agent. Spec-Driven Development is not a one-time migration. It is an evolution of how we interact with software. As discussed in [Tamiz's Insights](https://tamiz.pro/insights), the transition to agentic workflows requires a fundamental shift in developer identity. We are no longer writing code; we are defining the constraints within which code is generated. The engineers who master this shift will define the next decade of software architecture. TDD dictates that you write the test *before* the code. SDD elevates this: you write the specification (intent, inputs, constraints, expected outputs) *before* the test. The test is an artifact generated from the spec. TDD is a practice; SDD is a comprehensive architectural workflow that includes test generation, code generation, and evidence logging. Agents can handle service implementations, but the *interface* and *domain model* must be highly refined in the spec. Attempting to generate a complex, novel domain model with an LLM without a detailed, pre-approved spec often leads to architectural drift. SDD works best when the domain logic is stable and the data contracts are clearly defined. Hallucinations are mitigated by the deterministic validation loop. The LLM might hallucinate a code structure, but the static validator and the execution of the spec-derived test matrix will catch the hallucination immediately. The evidence log then provides the exact point of failure, forcing the agent to correct itself within a bounded number of retries.