Beyond the Hype: Practical Spec-Driven Development with AI Agents for Traceable Code Delivery

Originally published on tamiz.pro.

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.

1. The Architecture of Spec-Driven Development

1.1 From Prompts to Contracts

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:

1. Intent: The raw requirement expressed by the human, or a higher-level specification.
2. Contract: The machine-readable JSON specification (JSONSchema, OpenAPI, or proprietary formats) that translates intent into constraints.
3. Evidence: The deterministic logs, test execution traces, and LLM reasoning paths generated during the code generation process.

1.2 The Deterministic Agent Loop

LLMs are non-deterministic. To achieve traceable code delivery, the agent loop must be wrapped in deterministic guardrails. The process flows as follows:

• Specification Parsing: The agent ingests the spec and the current codebase context.
• Plan Generation: The agent generates a step-by-step execution plan.
• Validation Checkpoint 1: The plan is evaluated against the spec using static rules. If a proposed action violates a constraint (e.g., touching a protected database schema), the plan is rejected.
• Code Generation: The agent writes the code based on the validated plan.
• Execution & Testing: The code is compiled and executed against a suite of predefined, spec-derived tests.
• Validation Checkpoint 2: The test results are compared against the expected outcomes defined in the spec.
• Evidence Generation: Every step is logged. If a failure occurs, the agent is forced to read the exact test failure output and the spec constraint that was violated, preventing it from blindly guessing a fix.

2. Data Contracts: Defining the Specification

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.

2.1 Structuring the Spec

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"]
  }
}

2.2 Deriving Test Cases from the Spec

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.

• Happy Path: Valid inputs matching the JSONSchema types.
• Boundary Conditions: Inputs exactly at minimum and maximum values.
• Negative Cases: Inputs explicitly violating the schema (e.g., amount: -5, currency: "USD").
• Error Injection: Simulating the 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.

3. Implementing the AI Agent with Tooling

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.

3.1 The Agent Loop Logic

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.

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.")

3.2 Static Validation Guardrails

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.

• File Protection: The spec can include a 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.
• Dependency Graph Analysis: The validator checks if the proposed code introduces forbidden dependencies (e.g., a web server depending on a database driver directly, violating the architecture layer).

4. Evidence-Backed Traceability

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.

4.1 The Evidence Log

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.

4.2 Linking Intent to Artifact

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:

• Forward: Spec -> Tests -> Code -> PR -> Deployment.
• Reverse: If a bug is found in production, you trace the commit back to the Evidence Log, which points to the specific spec constraint. If the spec was wrong, you update the spec. If the spec was right but the LLM hallucinated, you update the agent's context or guardrails.

5. Handling Complexity and Edge Cases

While SDD is powerful for discrete, well-defined features, it faces challenges in complex, stateful systems.

5.1 State Mutation and Database Schemas

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.

5.2 Asynchronous Systems and Event Sourcing

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.

• Spec Constraint: "When payment is successful, emit a PaymentProcessed event to the payments topic."
• Agent Execution: The agent generates the code and, crucially, the test suite includes a mock message broker to verify that the event is emitted with the correct payload schema.

6. Production Best Practices and Security

Implementing SDD requires strict security boundaries.

6.1 Sandboxing and Ephemeral Environments

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).

• The runner is provisioned with a read-only clone of the repository.
• The agent executes tests in an isolated database container (Docker) that is destroyed after the job completes.
• No direct network access to external payment gateways; all external calls are intercepted by a mock server defined in the spec's environment configuration.

6.2 Securing the Spec

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.

7. The Future of SDD

Spec-Driven Development is not a one-time migration. It is an evolution of how we interact with software.

• Self-Healing Systems: In the near future, SDD will enable systems that monitor production errors, automatically generate a spec for the fix, propose the code, and self-heal. The human role shifts from coder to spec architect.
• Cross-Stack Agents: Today, agents are often language-specific. Tomorrow, a single spec will drive a Python backend, a TypeScript frontend, and a Rust system service, all validated by a unified test matrix.

As discussed in Tamiz's 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.

Frequently Asked Questions

How does Spec-Driven Development differ from Test-Driven Development (TDD)?

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.

Can AI agents handle entire microservices in Spec-Driven Development?

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.

How do we manage the hallucinations in the generated code?

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.