Spec-Driven Development - The Architectural Imperative for the Age of Artificial Intelligence Models, and Operational Implementation

Foreword: A Personal Lens

This document is rooted in hands-on experience building production systems across 15+ projects using AI-assisted development from end of 2024 through early 2026. It is not a theoretical exercise or a speculative forecast. Rather, it is a chronicle of patterns observed, failures endured, and disciplines discovered through the grinding work of shipping real software in real time, under the pressure of institutional deadlines.

The practices outlined here emerged not from doctrine but from necessity. Every principle described has been tested in the furnace of production—tested against the real stupidity that an AI can generate when given freedom, tested against the real pressure to ship fast, and tested against the real human cost when specifications fail.

This is an engineer’s report to engineers. Treat it as such.

1. The Crisis of Abundance: Software Engineering in the Era of Infinite Code

The history of software engineering has been defined by scarcity. For decades, the limiting factor in software production was the finite cognitive bandwidth of human developers. Every line of code represented a unit of human thought, a tangible investment of time, and a liability to be maintained. The methodologies that governed this era—Waterfall, Agile, Scrum—were essentially resource management strategies designed to optimize the allocation of this scarce human attention. However, the period between 2023 and 2026 witnessed a fundamental inversion of this economic reality. With the advent of Large Language Models (LLMs) and generative coding assistants, the marginal cost of generating code collapsed toward zero. The bottleneck shifted from production to verification, and the industry found itself unprepared for the consequences of abundance.

This report explores the paradigm shift known as Spec-Driven Development (SDD), a methodology that has emerged not merely as a preference but as a survival mechanism for engineering teams navigating the chaotic landscape of AI-assisted development. We analyze the trajectory from the early, euphoric days of “Vibe Coding” to the disciplined, rigorous structures of SDD, examining the theoretical underpinnings, practical workflows, and profound human implications of this transition.

1.1 The Productivity Paradox and the Rise of “Vibe Coding”

The initial integration of AI into the developer workflow was marked by a period of unbridled experimentation, retrospectively termed the era of “Vibe Coding”. This phase was characterized by a reliance on the stochastic brilliance of LLMs to bridge the gap between vague human intent and executable syntax. Developers, intoxicated by the speed of generation, adopted a workflow of “prompt and paste,” treating the AI as a magical black box capable of divining architectural requirements from casual natural language conversation.

The immediate metrics were seductive. Studies indicated that developers could complete coding tasks up to 55% faster, with junior developers seeing the most dramatic gains in raw output. However, this “sugar rush” of productivity concealed a growing accumulation of systemic risk. The “Vibe Coding” approach relied on an iterative, unstructured dialogue where the developer guided the model through “vibes”—imprecise, high-level directives like “make it faster” or “fix the bug”. While effective for throwaway prototypes or isolated scripts, this methodology proved catastrophic for production systems.

The failure of Vibe Coding is rooted in the “Intent Gap.” In a traditional workflow, the act of writing code forces the developer to crystallize their intent. One cannot write a variable name or define a class without making a concrete decision about its purpose. In Vibe Coding, this crystallization step is bypassed. The developer delegates the decision-making to the model, which fills in the gaps with probabilistic guesses based on its training data. The result is software that looks correct—syntactically perfect and often functionally passable—but lacks architectural coherence.

1.2 The “House of Cards” Effect: Context Drift and Regression

As Vibe Coding projects scaled beyond the complexity of a single session or a few files, they invariably hit a wall known as the “House of Cards” effect. This phenomenon is driven by the technical limitations of LLM context windows and the inherent entropy of unstructured conversation.

Context Drift occurs when the AI, constrained by its finite attention mechanism, loses track of the broader system architecture as the conversation lengthens. A developer might ask the AI to refactor a user authentication module in file A, and the AI, focusing solely on the immediate prompt, might implement a solution that breaks the dependency injection pattern used in file B, which it is currently ignoring. Because the “intent” of the system exists only in the ephemeral history of the chat log—and not in a durable artifact—the AI has no reliable way to check for consistency.

Furthermore, the iterative nature of Vibe Coding fosters Regression Loops. Without a “source of truth” external to the code itself, every new prompt has the potential to overwrite previous logic. A directive to “clean up the code style” might inadvertently revert a critical security patch applied ten turns ago because the AI interprets “clean code” as “standard boilerplate,” stripping away the nuanced, custom logic required for the specific business context. The developer, overwhelmed by the volume of generated code, often fails to catch these regressions during review, leading to what is now known as the “Verification Bottleneck”.

1.3 The Necessity of Specifications

The industry’s collective realization—hard-won through the failure of countless AI-generated prototypes—was that code is a poor medium for communicating intent to an LLM. Code is the output, the “how.” The LLM requires the “what” and the “why” to operate effectively. This realization birthed Spec-Driven Development.

SDD posits that in an age where code is cheap, the value of the software engineer shifts from writing syntax to defining specifications. A specification in this context is not the static, dusty document of the Waterfall era, but a living, executable artifact that serves as the prompt, the constraint, and the validation criteria for the AI agent. By anchoring the development process in a persistent specification, teams can decouple the “intent” from the “implementation,” allowing the AI to regenerate, refactor, and optimize the code endlessly without losing sight of the architectural goals.

—

2. Theoretical Foundations: Redefining Development Paradigms

To fully grasp the mechanics of SDD, one must situate it within the broader evolution of software development methodologies. SDD is not a rejection of Agile or DevOps but an adaptation of these principles to a world where the primary laborer is non-human.

2.1 The Taxonomy of Development Models

The relationship between SDD and its predecessors—Test-Driven Development (TDD), Behavior-Driven Development (BDD), and Domain-Driven Design (DDD)—is one of encapsulation rather than replacement.

Table 1: Comparative Analysis of Development Methodologies in the AI Era

Feature Test-Driven Development (TDD) Behavior-Driven Development (BDD) Spec-Driven Development (SDD)
Primary Artifact Unit Tests Scenario Files (Gherkin) Structured Specifications (Markdown)
Focus Code Correctness & Refactoring Shared Understanding & Behavior Architectural Intent & Agent Orchestration
Role of Human Write test, write code, refactor Define behavior, collaborate with stakeholders Architect, Auditor, and Prompt Engineer
Role of AI Generate code to pass test Generate step definitions Generate Plan, Implementation, and Tests
Source of Truth The Test Suite The Scenario Features The Specification Document
Failure Mode Brittle tests, refactoring drag Ambiguous steps, technical debt Hallucinations, Spec-Code Drift

2.1.1 SDD as the Superset

Research indicates that SDD effectively acts as a wrapper around TDD and BDD. In an SDD workflow, the specification dictates the behaviors (BDD) and the validation criteria (TDD). The AI agent reads the spec and is often instructed to perform TDD: “Read this spec, write the failing tests first, then write the code to pass them.” The human developer no longer hand-writes the tests; they specify the conditions under which the tests should pass. This elevates the abstraction level, allowing the developer to govern the system’s behavior without getting bogged down in the minutiae of assertion syntax.

2.2 The “Spec-as-Source” Philosophy

The most radical theoretical contribution of SDD is the concept of Spec-as-Source. In traditional development, the source code is the ultimate reality. Documentation is a secondary artifact that inevitably drifts from the truth. In the most advanced implementations of SDD (facilitated by tools like Tessl and Kiro), this relationship is inverted.

The specification becomes the primary source file. The code is treated as a compiled binary—a derivative artifact generated from the spec. If a bug is found or a feature needs changing, the developer does not touch the code. They edit the spec and “recompile” the application using the AI agent. This approach promises to solve the “documentation drift” problem permanently, as the documentation and the executable are causally linked. However, achieving this requires a level of determinism in AI generation that is still being refined, leading to intermediate stages like “Spec-Anchored” development, where the spec guides but does not strictly enforce the code.

2.3 The Economics of Context

The theoretical underpinning of SDD is also deeply economic, specifically regarding the “Attention Economy” of Large Language Models. Every LLM has a finite context window—the amount of text it can process at any given moment. While these windows are expanding (with models like Gemini 1.5 Pro reaching millions of tokens), the “reasoning density” tends to degrade as the context fills up—a phenomenon known as “Lost in the Middle”.

SDD addresses this by optimizing the information density fed to the model. Instead of dumping the entire repository into the context (which leads to confusion and hallucination), SDD organizes the project into hierarchical layers of specifications. The AI is fed only the “Active Spec” relevant to the current task, supported by a “System Constitution” and a “Lessons Learned” file. This Context Engineering ensures that the model’s attention mechanisms are focused on the relevant constraints, maximizing the probability of correct code generation.

—

3. The Anatomy of a Specification: The New Lingua Franca

If the specification is the new source code, then the language in which it is written becomes critical. Unlike the formal specification languages of the past (like UML or Z notation), which were rigid and difficult to learn, modern SDD specifications utilize Markdown as their lingua franca. Markdown is ideal because it is human-readable, machine-parsable, and structurally hierarchical—mapping perfectly to the way LLMs process information.

3.1 The Hierarchical Structure of an AI Spec

A professional-grade SDD specification is not a stream-of-consciousness narrative. It is a structured document designed to constrain the solution space of the AI. Based on best practices from Thoughtworks, Red Hat, and the open-source community, a robust spec typically contains the following components :

3.1.1 The High-Level Goal (The “Why”)

This section provides the semantic anchor for the agent. It describes the business value and the user intent. For example: “Create a resilient user authentication service that supports JWT and OAuth2, designed to handle high-concurrency login bursts.” This allows the AI to infer unstated requirements (like rate limiting) based on its training data regarding “resilient” systems.

3.1.2 Functional Requirements (The “What”)

Here, SDD borrows heavily from BDD. Requirements are articulated as user stories or “Given/When/Then” scenarios.

  • Example: “Given an unauthenticated user, when they attempt to access /api/protected, then return a 401 Unauthorized status.”
  • Insight: By phrasing requirements as deterministic outcomes, the developer reduces the “temperature” (randomness) of the AI’s output. The model is less likely to “get creative” with error codes if the spec explicitly mandates a 401.

Template for Functional Requirements:

Functional Requirements

FR-1: User Registration

  • Given: An anonymous user navigates to /register
  • When: They submit email, password, and name
  • Then: Account is created, verification email is sent, user receives 201 Created response
  • Error Cases:
    • Email already exists → 409 Conflict
    • Password < 12 characters → 400 Bad Request, with specific error: “Password must be at least 12 characters”
    • Invalid email format → 422 Unprocessable Entity

FR-2: JWT Token Issuance

  • Given: A registered user with verified email at POST /login
  • When: They provide valid credentials
  • Then: Return JSON with access_token (JWT, expires 1h), refresh_token (expires 30d), user object
  • Token Claims: { sub: userId, email, role, iat, exp, iss: "api.example.com" }
  • Error Case: Invalid credentials → 401 Unauthorized (do not reveal which field failed)

FR-3: Token Refresh

  • Given: A client with a valid refresh_token at POST /auth/refresh
  • When: They provide the refresh_token
  • Then: Issue a new access_token without requiring credentials
  • Security: Refresh tokens must be rotated on each use; old refresh token is invalidated

3.1.3 Technical Constraints (The “How”)

This is the most critical section for preventing technical debt. It explicitly defines the “box” in which the AI must operate.

  • Tech Stack: Version pinning is essential (e.g., “Use Python 3.12,” “Use Pydantic v2”).
  • Architecture: Directives on design patterns (e.g., “Use the Repository Pattern,” “Implement a Hexagonal Architecture”).
  • Forbidden Patterns: A list of “Thou Shalt Nots.” (e.g., “Do not use try/except in the controller layer; let middleware handle exceptions,” “Never commit API keys”). This negative constraining is often more effective than positive instruction.

Template for Technical Constraints:

Technical Constraints

Tech Stack

  • Language: Python 3.12
  • Framework: FastAPI 0.104+
  • ORM: SQLAlchemy 2.0 with async support (using asyncio)
  • Database: PostgreSQL 15+
  • Async Runtime: asyncio with uvicorn ASGI server
  • Testing: pytest 7.4+, pytest-asyncio

Architecture & Code Organization

  • Use Hexagonal Architecture (ports & adapters)
  • Directory structure:
    src/
    ├── api/          # FastAPI routes (controllers)
    ├── domain/       # Business logic (entities, use cases)
    ├── infrastructure/  # Data access (DB, external APIs)
    ├── ports/        # Interfaces/ABCs
    └── schemas/      # Pydantic models
    
  • Every route must be async: async def endpoint(...) -> Response
  • Never call sync functions from async routes (leads to deadlocks)

Forbidden Patterns

  • ❌ Do NOT use global variables for database sessions
  • ❌ Do NOT PUT sensitive data (API keys, passwords) in code or comments
  • ❌ Do NOT use bare except: clauses; always specify exception type
  • ❌ Do NOT perform I/O operations in pydantic validators; use endpoints instead
  • ❌ Do NOT query all rows and filter in Python; use WHERE clauses in SQL

Required Practices

  • ✅ Every public function requires a docstring with Args, Returns, Raises
  • ✅ Every endpoint requires error handling returning proper HTTP status codes
  • ✅ ACID transactions for multi-step operations (e.g., debit account + credit account)
  • ✅ All queries must use parameterized statements (SQLAlchemy ORM handles this)
  • ✅ Add PostgreSQL indexes for any foreign key or WHERE clause column

3.1.4 Interface Definitions

Defining the data structures before the logic is a hallmark of SDD. By including TypeScript interfaces, Pydantic models, or SQL schema definitions in the spec, the developer locks down the “contract” of the software. The AI is then reduced to implementing the logic that satisfies these contracts, drastically reducing the scope for hallucination.

Template for Interface Definitions:

# Pydantic models (from the spec)

from pydantic import BaseModel, EmailStr, Field
from datetime import datetime
from uuid import UUID

# Request/Response schemas
class RegisterRequest(BaseModel):
    email: EmailStr
    password: str = Field(..., min_length=12, max_length=128)
    name: str = Field(..., min_length=1, max_length=255)

class LoginRequest(BaseModel):
    email: EmailStr
    password: str

class TokenResponse(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "Bearer"
    expires_in: int  # seconds
    user: "UserResponse"

class UserResponse(BaseModel):
    id: UUID
    email: EmailStr
    name: str
    role: str  # "user" | "admin"
    created_at: datetime
    
# Domain entities
class User(BaseModel):
    id: UUID
    email: EmailStr
    password_hash: str  # Never expose in responses
    name: str
    role: str = "user"
    created_at: datetime
    updated_at: datetime
    email_verified: bool = False
    deleted_at: datetime | None = None
    
# Database schema (SQL)
class UserTable:
    """
    CREATE TABLE users (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        email VARCHAR(255) UNIQUE NOT NULL,
        password_hash VARCHAR(255) NOT NULL,
        name VARCHAR(255) NOT NULL,
        role VARCHAR(50) DEFAULT 'user',
        email_verified BOOLEAN DEFAULT FALSE,
        created_at TIMESTAMP DEFAULT NOW(),
        updated_at TIMESTAMP DEFAULT NOW(),
        deleted_at TIMESTAMP NULL,
        CONSTRAINT email_format CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$')
    );
    
    -- Indices for query performance
    CREATE INDEX idx_users_email ON users(email);
    CREATE INDEX idx_users_created_at ON users(created_at DESC);
    """

The spec locks down these contracts. The AI cannot deviate:

  • User responses will never include password_hash
  • All email fields must be validated via EmailStr
  • The database schema is immutable until explicitly amended

3.2 The “Constitution” and Global Context

In a large project, repeating the same coding standards in every single feature spec is inefficient and error-prone. To solve this, SDD introduces the concept of the Project Constitution (often named AGENTS.md, .cursorrules, or copilot-instructions.md).

This file acts as the “System 1” thinking for the AI agent. It is loaded into the context window at the start of every session and contains the non-negotiable laws of the repository.

  • Style Guide: “Always use 4 spaces for indentation.”
  • Security Policy: “All user input must be sanitized using dompurify.”
  • Testing Strategy: “Every public function must have a corresponding unit test in tests/.”
  • Code Reuse Policy: “Before writing a new utility function, check src/utils to see if it already exists.” This specific rule is vital for preventing the “code bloat” common in AI projects, where agents prefer to write new code rather than read existing code.

Template for AGENTS.md (Project Constitution):

AGENTS.md: The Constitution for AI Agents in This Repository

Preamble

You are an AI code agent working on a production FastAPI service handling financial transactions. This Constitution is the fundamental law. Violate it, and your code will be rejected in review.

Core Principles

  1. Fail safely: When in doubt, raise an exception. Silent failures destroy trust.
  2. No guessing: Every decision should be justified by spec or best practice.
  3. Humans first: Your code is read by humans 10x more than machines. Optimize for clarity.
  4. Security by default: Assume all user input is malicious. Sanitize, validate, escape.

Code Style

  • Language: Python 3.12+
  • Formatter: ruff format (configured in pyproject.toml)
  • Linter: ruff check --fix (must pass with exit code 0)
  • Line length: 100 characters max
  • Indentation: 4 spaces (never tabs)
  • Type hints: ALWAYS use type hints for function arguments and return values
    # ✅ Correct
    def process_payment(user_id: UUID, amount: Decimal) -> PaymentResult:
        ...
      
    # ❌ Wrong
    def process_payment(user_id, amount):
        ...
    
  • Naming:
    • Functions: snake_case (e.g., validate_email)
    • Classes: PascalCase (e.g., PaymentProcessor)
    • Constants: SCREAMING_SNAKE_CASE (e.g., MAX_RETRY_ATTEMPTS)
    • Private methods: Prefix with _ (e.g., _hash_password)

Testing

  • Framework: pytest
  • Location: tests/ directory mirrors src/ structure
    tests/
    ├── api/
    │   └── test_auth.py       # Tests for src/api/auth.py
    ├── domain/
    │   └── test_user.py       # Tests for src/domain/user.py
    └── infrastructure/
        └── test_db.py         # Tests for src/infrastructure/db.py
    
  • Every public function must have a test
  • Test naming: test_<function>_<scenario>
    • ✅ test_register_success_with_valid_email
    • ✅ test_register_fails_with_duplicate_email
    • ❌ test_register_1, test_reg
  • Assertions must be explicit: assert user.email == "test@example.com", not vague assertions

Security Rules

  1. Never log sensitive data: No passwords, API keys, PII in logs. Strip these fields before logging.
  2. Environment variables only for secrets: DB_PASSWORD, API_KEY_STRIPE, etc. in .env, never in code.
  3. Parameterized queries always: SQLAlchemy ORM handles this. Never string-interpolate SQL.
  4. Hash passwords: Use passlib with argon2. Never store plain passwords.
  5. CORS carefully: Only allow origins specified in the spec. Default to deny.
  6. Rate limiting required: Use slowapi for all public endpoints (see src/middleware/rate_limit.py).

Database

  • ORM: SQLAlchemy 2.0+ with async support
  • Migrations: Alembic for schema changes
  • Transactions: Use async with session.begin(): for ACID guarantees
  • Indices: Add indices to any column used in WHERE, JOIN, or ORDER BY
  • No SELECT *: Always select specific columns to control payload
    # ✅ Correct (efficient)
    stmt = select(User.id, User.email).where(User.role == "admin")
      
    # ❌ Wrong (wasteful)
    stmt = select(User)  # Loads password_hash, etc.
    

Error Handling

  • Raise domain-specific exceptions (defined in src/exceptions.py):
    class InvalidEmailError(Exception):
        """Raised when email format is invalid."""
        pass
    
  • Never use bare except:; always catch specific exceptions
  • HTTP error responses:
    # ✅ Correct
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
      
    # ❌ Wrong
    if not user:
        return None  # Ambiguous, no error indication
    

Documentation

  • Docstrings required for all public functions, classes, modules
  • Format: Google-style docstrings
    def register_user(email: EmailStr, password: str) -> User:
        """Register a new user with email and password.
          
        Args:
            email: User's email address (must be unique)
            password: Password (minimum 12 characters)
              
        Returns:
            User: The newly created user object
              
        Raises:
            InvalidEmailError: If email format is invalid
            DuplicateEmailError: If email already registered
        """
    

Code Reuse Policy

Before writing ANY new utility function, check src/utils/ to see if it already exists. Ask yourself: Is there a similar function I can reuse?

  • ✅ Calling existing util: from src.utils.crypto import hash_password
  • ❌ Reinventing: Writing a new def hash_pwd(p): in your module

Git & Commits

  • Branch naming: feature/auth-jwt, fix/payment-race-condition, docs/api-spec
  • Commit messages must reference the spec:
    • ✅ feat: implement FR-1 (user registration) per spec
    • ❌ added code, fixes bug
  • One feature per PR. Don’t mix unrelated changes.

What NOT to Do

  • ❌ Do NOT modify database migrations after they’re committed (create new migrations instead)
  • ❌ Do NOT make breaking API changes without updating the OpenAPI spec
  • ❌ Do NOT add new dependencies without documenting in SPEC.md’s Tech Stack section
  • ❌ Do NOT skip error cases “for now” (implement all error paths immediately)
  • ❌ Do NOT leave TODO comments without an issue number (use “TODO: (PROJ-123)” format)
  • ❌ Do NOT fetch all rows and filter in Python; use SQL WHERE clauses

When in Doubt

  1. Read SPEC.md for the authoritative requirement
  2. Check src/utils/ for reusable code
  3. Look at an existing similar feature for the pattern
  4. Raise explicit errors rather than silent failures

This constitution is committed to the repository and provided to the AI at the start of every session. It prevents drift and establishes non-negotiable standards.

3.3 The Power of “Few-Shot” Specification

One of the most potent techniques in writing specs for AI is Few-Shot Prompting. Instead of describing a coding style in abstract paragraphs, the developer provides a “Golden Example”—a snippet of code that perfectly embodies the desired architecture, naming conventions, and error handling.

  • Mechanism: The LLM uses this example for “in-context learning.” It mimics the patterns found in the example when generating new code.
  • Efficiency: A 50-line code snippet can convey more information about coding style than 500 lines of descriptive text, and it consumes fewer tokens.

Template for Few-Shot Examples:

Include this in your SPEC.md under a “Golden Examples” section:

Golden Examples (Few-Shot Reference)

Use these as templates for the code you generate. The style, error handling, and patterns here are immutable.

Example 1: Standard Endpoint with Error Handling

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession
from typing import Annotated

router = APIRouter(prefix="/api/users", tags=["users"])

class CreateUserRequest(BaseModel):
    email: str
    name: str

class UserResponse(BaseModel):
    id: str
    email: str
    name: str

@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(
    request: CreateUserRequest,
    session: Annotated[AsyncSession, Depends(get_session)]
) -> UserResponse:
    """Create a new user.
    
    Args:
        request: User creation details
        session: Database session
        
    Returns:
        UserResponse: The created user
        
    Raises:
        HTTPException: If email already exists (409) or invalid (422)
    """
    # Validate input
    if len(request.email) < 5:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail="Email must be at least 5 characters"
        )
    
    # Check for duplicates
    existing = await session.execute(
        select(User).where(User.email == request.email)
    )
    if existing.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Email already registered"
        )
    
    # Create and save
    user = User(email=request.email, name=request.name)
    session.add(user)
    await session.commit()
    await session.refresh(user)
    
    return UserResponse(id=str(user.id), email=user.email, name=user.name)

Key Patterns Demonstrated:

  • Explicit type hints on all parameters and return values
  • Descriptive docstring with Args, Returns, Raises
  • Early validation with specific error codes
  • Database check before creation (prevents race conditions when combined with unique constraints)
  • Proper HTTP status codes (201 for creation, 409 for conflict, 422 for validation error)
  • Commit and refresh to ensure response includes DB-generated fields (like id)

Example 2: Repository Pattern for Data Access

from typing import Optional

class UserRepository:
    """Data access layer for User entities."""
    
    def __init__(self, session: AsyncSession):
        self.session = session
    
    async def find_by_id(self, user_id: UUID) -> Optional[User]:
        """Fetch user by ID. Returns None if not found."""
        stmt = select(User).where(User.id == user_id)
        result = await self.session.execute(stmt)
        return result.scalar_one_or_none()
    
    async def find_by_email(self, email: str) -> Optional[User]:
        """Fetch user by email. Returns None if not found."""
        stmt = select(User).where(User.email == email)
        result = await self.session.execute(stmt)
        return result.scalar_one_or_none()
    
    async def create(self, email: str, name: str, password_hash: str) -> User:
        """Create and persist a new user.
        
        Raises:
            IntegrityError: If email violates unique constraint
        """
        user = User(email=email, name=name, password_hash=password_hash)
        self.session.add(user)
        await self.session.commit()
        await self.session.refresh(user)
        return user
    
    async def update(self, user: User) -> User:
        """Update an existing user and persist changes."""
        await self.session.merge(user)
        await self.session.commit()
        return user

Key Patterns:

  • Repository encapsulates all database logic
  • Methods return concrete types or None, never empty collections
  • Docstrings explain what each method does (queries, mutations, exceptions)
  • Transaction management handled explicitly

Example 3: Error Handling and Logging

import logging
from datetime import datetime

logger = logging.getLogger(__name__)

async def process_payment(user_id: UUID, amount: Decimal) -> PaymentResult:
    """Process a payment for a user.
    
    Args:
        user_id: ID of user paying
        amount: Payment amount in cents
        
    Returns:
        PaymentResult with status and transaction ID
        
    Raises:
        InsufficientFundsError: If user balance < amount
        StripeAPIError: If Stripe API fails
    """
    start_time = datetime.utcnow()
    
    try:
        # Validate
        if amount <= 0:
            raise ValueError("Amount must be positive")
        
        # Fetch user
        user = await user_repo.find_by_id(user_id)
        if not user:
            # Log the attempt, but don't expose whether user exists
            logger.warning(f"Payment attempt for non-existent user: {user_id}")
            raise HTTPException(status_code=404, detail="User not found")
        
        # Debit user
        if user.balance < amount:
            raise InsufficientFundsError(f"Insufficient balance: {user.balance} < {amount}")
        
        user.balance -= amount
        await user_repo.update(user)
        
        # Call external API
        stripe_response = await stripe_client.charge(
            customer_id=user.stripe_id,
            amount_cents=int(amount)
        )
        
        # Log success (no sensitive data)
        elapsed = (datetime.utcnow() - start_time).total_seconds()
        logger.info(f"Payment processed for user {user_id}: ID={stripe_response.id}, duration={elapsed}s")
        
        return PaymentResult(
            status="success",
            transaction_id=stripe_response.id,
            amount=amount
        )
    
    except InsufficientFundsError as e:
        # Expected business logic error
        logger.info(f"Payment failed: insufficient funds for user {user_id}")
        raise HTTPException(status_code=402, detail="Insufficient balance")
    
    except StripeAPIError as e:
        # External service failure
        logger.error(f"Stripe API error: {e}", exc_info=True)
        raise HTTPException(status_code=503, detail="Payment service temporarily unavailable")
    
    except Exception as e:
        # Unexpected error
        logger.critical(f"Unexpected error in process_payment: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail="Internal server error")

Key Patterns:

  • Separate handling for expected vs. unexpected errors
  • Logging at appropriate levels (info, warning, error, critical)
  • Never log sensitive data (passwords, API keys, full PII)
  • Timing information for performance analysis
  • User-facing error messages that don’t expose implementation details

Use these examples as your template. When creating new functions, match this style exactly.

  1. Identify the database ORM pattern used (SQLAlchemy, Prisma, etc.)
  2. Tell me: is there already a role-based access control (RBAC) system? If yes, describe it.

Respond in a structured format:

  • User Entity: [fields and types]
  • Existing Functions: [function names with signatures]
  • Middleware: [what each middleware does]
  • ORM Pattern: [description]
  • RBAC System: [Yes/No, description] ```

Sample AI Response:

# Repository Analysis

## User Entity (src/auth/models.py)
```python
class User:
    id: UUID
    email: str
    password_hash: str
    name: str
    role: str  # "admin", "moderator", "user"
    is_active: bool
    created_at: datetime

Existing Functions (src/auth/services.py)

  • authenticate(email: str, password: str) -> Optional[User]
  • hash_password(password: str) -> str
  • verify_password(password: str, hash: str) -> bool
  • create_user(email, password, name) -> User
  • get_user_by_id(user_id: UUID) -> Optional[User]

Middleware (src/middleware/)

  • require_auth(): Verifies JWT token in request header
  • require_role(role: str): Checks if user.role matches required role
  • No centralized permission system exists yet

ORM Pattern

Using SQLAlchemy 2.0 with async support

RBAC System

Partially implemented: Has role field on User, but no granular permission system. All role checks are hardcoded in endpoints (e.g., if user.role != "admin": raise 403). Opportunity: Could create a Permission table with many-to-many rel to roles.


**Human Review:**
The human examines this output and notes:
- Good news: Basic auth infrastructure exists, can reuse `require_auth()` middleware
- Bad news: Role checking is scattered across endpoints; we should create a centralized system
- Decision: In the Plan phase, we'll extend the architecture with a Permission system

This research prevents hallucination. The AI now knows not to reinvent auth; it knows exactly what middleware exists.

### **4.2 Phase 2: Plan (The Architect Mode)**

This is the distinct innovation of SDD. The developer explicitly forbids the AI from writing code in this phase. Instead, the agent is tasked with generating a **Technical Plan**.

* *Prompt:* "Based on the spec and your research, create a step-by-step implementation plan. List every file you will create, every function you will modify, and the exact data structures you will use."  
* *The Output:* A Markdown checklist detailing the proposed changes.  
* *The Verification Step:* **This is the critical human intervention point.** It is exponentially cheaper to fix a flaw in a Markdown bullet point than to debug a distributed system. The developer reviews the plan: "Wait, you're proposing to modify the User table, but that will break the analytics pipeline. Use a join table instead."  
* *Iteration:* The plan is refined until the human approves it. This "measure twice, cut once" approach is the antithesis of Vibe Coding.

**Concrete Example of Planning Phase:**

**Prompt to AI:**

DO NOT WRITE CODE. Only create a detailed implementation plan.

Based on the Research phase and this SPEC, create a technical plan:


SPEC: Implement role-based access control (RBAC) with fine-grained permissions

Functional Requirements:

  • FR-1: Admins can create roles (e.g., “write_posts”, “delete_comments”)
  • FR-2: Admins can assign permissions to roles
  • FR-3: An endpoint should check user permissions before allowing an action
  • FR-4: Cache permission checks for performance (5-minute TTL)

Technical Constraints:

  • Use SQLAlchemy 2.0
  • Add PostgreSQL migrations (alembic)
  • Must not break existing endpoints
  • All new endpoints require authentication

Create a detailed plan with these sections:

  1. New Database Tables: What tables/columns to create
  2. Database Migrations: Alembic migration files needed
  3. New Files: Any new Python modules required
  4. Modified Files: What existing files need changes
  5. New Functions: Exact function signatures (use Python typing)
  6. API Endpoints: If any new endpoints needed
  7. Data Structures (Pydantic models): All request/response schemas
  8. Implementation Order: Step 1, Step 2, … in dependency order
  9. Risks & Mitigations: What could go wrong and how to prevent it

Format the plan as a checklist so we can mark off each item after implementation.


**Sample AI Plan:**

```markdown
# RBAC Implementation Plan

## 1. New Database Tables

### Table: roles
```sql
CREATE TABLE roles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) UNIQUE NOT NULL,      -- e.g., "admin", "editor", "viewer"
    description TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    CONSTRAINT name_not_empty CHECK (name != '')
);

Table: permissions

CREATE TABLE permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(100) UNIQUE NOT NULL,      -- e.g., "create_post", "delete_comment"
    description TEXT,
    resource VARCHAR(50) NOT NULL,          -- e.g., "posts", "comments"
    action VARCHAR(50) NOT NULL,            -- e.g., "create", "delete", "read"
    created_at TIMESTAMP DEFAULT NOW()
);
-- Index for lookups by resource+action
CREATE INDEX idx_permissions_resource_action ON permissions(resource, action);

Table: role_permissions (join table)

CREATE TABLE role_permissions (
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    permission_id UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
    assigned_at TIMESTAMP DEFAULT NOW(),
    PRIMARY KEY (role_id, permission_id)
);

Table: user_roles (already have User.role column, but normalize it)

CREATE TABLE user_roles (
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    assigned_at TIMESTAMP DEFAULT NOW(),
    PRIMARY KEY (user_id, role_id)
);
-- Migration strategy: Backfill this from User.role column, then deprecate User.role

2. Alembic Migrations Needed

  • alembic/versions/xxx_create_roles_table.py
  • alembic/versions/xxx_create_permissions_table.py
  • alembic/versions/xxx_create_role_permissions_table.py
  • alembic/versions/xxx_create_user_roles_table.py
  • alembic/versions/xxx_backfill_user_roles_from_user_role.py

3. New Files

  • src/domains/rbac/models.py — SQLAlchemy models for Role, Permission, etc.
  • src/domains/rbac/services.py — Business logic for RBAC
  • src/domains/rbac/repository.py — Data access layer
  • src/api/admin/rbac.py — Admin endpoints (create role, assign permission)
  • src/middleware/rbac_cache.py — Permission cache with TTL
  • tests/api/admin/test_rbac.py — Tests for RBAC endpoints
  • tests/domains/rbac/test_services.py — Tests for RBAC services

4. Modified Files

  • src/models/user.py — Add roles: List[Role] relationship (keep role column for backward compatibility during migration)
  • src/middleware/__init__.py — Register new @require_permission() decorator
  • src/config.py — Add RBAC cache configuration (e.g., PERMISSION_CACHE_TTL = 300)
  • requirements.txt — No new dependencies (SQLAlchemy already present)

5. New Functions

In src/domains/rbac/services.py:

  • async def create_role(name: str, description: Optional[str]) -> Role
  • async def create_permission(name: str, resource: str, action: str) -> Permission
  • async def assign_permission_to_role(role_id: UUID, permission_id: UUID) -> RolePermission
  • async def assign_role_to_user(user_id: UUID, role_id: UUID) -> UserRole
  • async def check_permission(user_id: UUID, resource: str, action: str) -> bool
  • async def get_user_permissions(user_id: UUID) -> List[Permission] (used for caching)

In src/middleware/rbac_cache.py:

  • def permission_cache_key(user_id: UUID) -> str — Generate Redis key
  • async def get_cached_permissions(user_id: UUID) -> Optional[List[Permission]]
  • async def cache_permissions(user_id: UUID, permissions: List[Permission], ttl: int = 300)
  • async def invalidate_user_cache(user_id: UUID) — Called when user role changes

Decorator in src/middleware/__init__.py:

  • @require_permission(resource: str, action: str) — New decorator, complements existing @require_auth()

6. API Endpoints (NEW)

All require @require_auth() and @require_permission("roles", "manage")

  • POST /api/admin/roles — Create new role
    • Request: {name: str, description: str}
    • Response: {id: UUID, name: str, description: str, created_at: datetime}
  • GET /api/admin/roles — List all roles
    • Response: [{id, name, description, created_at}]
  • POST /api/admin/roles/{role_id}/permissions — Assign permission to role
    • Request: {permission_id: UUID}
    • Response: {role_id, permission_id, assigned_at}
  • GET /api/admin/users/{user_id}/permissions — List user’s effective permissions
    • Response: [{id, name, resource, action}]
  • POST /api/admin/users/{user_id}/roles — Assign role to user
    • Request: {role_id: UUID}
    • Response: {user_id, role_id, assigned_at}

7. Data Structures (Pydantic Models)

# In src/domains/rbac/schemas.py

class RoleResponse(BaseModel):
    id: UUID
    name: str
    description: Optional[str]
    created_at: datetime

class PermissionResponse(BaseModel):
    id: UUID
    name: str
    resource: str
    action: str
    created_at: datetime

class CreateRoleRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)

class AssignPermissionRequest(BaseModel):
    permission_id: UUID

8. Implementation Order (Dependency Chain)

  1. Create Alembic migrations — Database schema is the foundation
  2. Create SQLAlchemy models — Role, Permission, RolePermission, UserRole
  3. Create repository layer — Data access for RBAC tables
  4. Create RBAC services — Business logic (check_permission, assign_role, etc.)
  5. Create permission cache — Middleware to cache permission checks
  6. Create @require_permission decorator — Integrate into middleware stack
  7. Create API endpoints — Auth endpoints for admins
  8. Create tests — Unit and integration tests
  9. Backfill user_roles table — Migrate from denormalized User.role to normalized schema
  10. Deprecate User.role — Keep as reference until all checks use RBAC

9. Risks & Mitigations

Risk Mitigation
Backward Compatibility Break Keep User.role column during migration phase (6 months). All old code still works. New code uses RBAC tables. Old endpoints check User.role, new ones check RBAC.
Performance Regression Cache permissions with 5-minute TTL. If cache hits, zero DB cost. Worst case: cache miss requires 2 queries (user_roles + role_permissions). Acceptable.
N+1 Query Problem Use SQLAlchemy eager loading: select(User).options(selectinload(User.roles).selectinload(Role.permissions))
Missing Permissions Data Data migration step (item 9) must run atomically. Test migration on staging first.
Admin can lock themselves out Constraint: admins cannot revoke their own “create_role” permission. Enforce at API level.

Next Steps

Once this plan is approved by the human reviewer, implementation can proceed step-by-step.

Expected timeline: 16 hours of AI coding + 4 hours of human review/testing = 2 days.


**Human Review of the Plan:**

The human engineer reads this plan carefully and asks:

1. ✅ **Good:** Alembic migrations clearly defined
2. ✅ **Good:** Backward compatibility strategy (keep User.role column)
3. ⚠️ **Question:** You propose caching permissions for 5 minutes. What happens if an admin revokes a user's permission? Will the user still have access for up to 5 minutes?
4. ⚠️ **Question:** The N+1 concern assumes we're loading all user permissions every request. Can we optimize by only checking the specific `(resource, action)` needed?
5. 🚫 **Issue:** You didn't mention how to handle the analytics pipeline, which currently reads User.role directly. We need a migration strategy to update those queries.

**Plan Refinement:**

The human and AI iterate:

REVISED Item 8, Step 3:

  • Create Redis cache with TTL-based invalidation
  • Add cache invalidation trigger: When admin revokes permission, immediately invalidate that user’s cache
  • Change requirement from “5-minute TTL” to “until explicitly invalidated”

REVISED Item 7, add schema:

  • SpecificPermissionCheck(user_id: UUID, resource: str, action: str) -> bool
  • This checks one permission, not all, reducing DB queries

ADDED Item 6 (new endpoint):

  • POST /api/admin/users/{user_id}/invalidate-cache — Force refresh user’s permission cache ```

This iterative refinement prevented a bug that would have manifested in production: users retaining permissions for 5 minutes after revocation. The plan phase caught it.

4.3 Phase 3: Implement (The Execution)

Once the plan is locked, the execution becomes a mechanical process. The developer instructs the agent to execute the plan, often item by item.

  • Prompt: “Execute Step 1 of the plan.”
  • Mechanism: The agent writes the code, constrained strictly by the plan it just generated. Because the plan was already verified, the likelihood of “architectural drift” is minimized.
  • Validation: The agent is instructed to run the tests defined in the spec immediately after generation. If the tests fail, the agent enters a self-correction loop.

Concrete Example of Implementation Phase:

Prompt to AI (Step 1):

You are executing the approved RBAC implementation plan.

Execute STEP 1: Create Alembic migrations for the new tables.

Create two files:
1. alembic/versions/XXX_create_rbac_tables.py (single combined migration is fine)

Constraints:
- Use the exact table schemas from the plan
- Follow the Alembic pattern used in existing migrations (check alembic/versions/)
- Include both upgrade() and downgrade() functions
- Use SQLAlchemy Core API (not ORM models)

Here's an example existing migration to match the style:
[AI is shown an existing migration file]

AI Output (Step 1 code):

# alembic/versions/2025_02_08_123456_create_rbac_tables.py

from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects import postgresql

def upgrade():
    # Create roles table
    op.create_table(
        'roles',
        sa.Column('id', postgresql.UUID(as_uuid=True), 
                 server_default=sa.text('gen_random_uuid()'), nullable=False),
        sa.Column('name', sa.String(100), nullable=False, unique=True),
        sa.Column('description', sa.Text(), nullable=True),
        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now(), nullable=False),
        sa.PrimaryKeyConstraint('id'),
        sa.CheckConstraint("name != ''", name='name_not_empty')
    )
    
    # Create permissions table
    op.create_table(
        'permissions',
        sa.Column('id', postgresql.UUID(as_uuid=True),
                 server_default=sa.text('gen_random_uuid()'), nullable=False),
        sa.Column('name', sa.String(100), nullable=False, unique=True),
        sa.Column('description', sa.Text(), nullable=True),
        sa.Column('resource', sa.String(50), nullable=False),
        sa.Column('action', sa.String(50), nullable=False),
        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now(), nullable=False),
        sa.PrimaryKeyConstraint('id')
    )
    op.create_index(
        'idx_permissions_resource_action',
        'permissions',
        ['resource', 'action']
    )
    
    # Create join table
    op.create_table(
        'role_permissions',
        sa.Column('role_id', postgresql.UUID(as_uuid=True), nullable=False),
        sa.Column('permission_id', postgresql.UUID(as_uuid=True), nullable=False),
        sa.Column('assigned_at', sa.DateTime(), server_default=sa.func.now(), nullable=False),
        sa.ForeignKeyConstraint(['role_id'], ['roles.id'], ondelete='CASCADE'),
        sa.ForeignKeyConstraint(['permission_id'], ['permissions.id'], ondelete='CASCADE'),
        sa.PrimaryKeyConstraint('role_id', 'permission_id')
    )
    
    op.create_table(
        'user_roles',
        sa.Column('user_id', postgresql.UUID(as_uuid=True), nullable=False),
        sa.Column('role_id', postgresql.UUID(as_uuid=True), nullable=False),
        sa.Column('assigned_at', sa.DateTime(), server_default=sa.func.now(), nullable=False),
        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
        sa.ForeignKeyConstraint(['role_id'], ['roles.id'], ondelete='CASCADE'),
        sa.PrimaryKeyConstraint('user_id', 'role_id')
    )

def downgrade():
    op.drop_table('user_roles')
    op.drop_table('role_permissions')
    op.drop_index('idx_permissions_resource_action', table_name='permissions')
    op.drop_table('permissions')
    op.drop_table('roles')

Human Validation: The human runs:

# Test the migration
alembic upgrade head
# Verify schema
\d roles
# Rollback test
alembic downgrade -1
# Verify rollback worked
\d roles  # should not exist
# Upgrade again
alembic upgrade head

✅ Migration approved. Proceed to Step 2.


Prompt to AI (Step 2):

Execute STEP 2: Create SQLAlchemy models for RBAC.

Create file: src/domains/rbac/models.py

Constraints:
- Use SQLAlchemy 2.0 async-compatible syntax
- Define roles, Role, Permission, RolePermission, UserRole models
- DO NOT modify the existing User model yet (that comes later)
- Include relationships: Role.permissions, Permission.roles, etc.
- Add docstrings to all classes

Reference the golden example in AGENTS.md for docstring style.

Also: import these in src/models/__init__.py so other modules can use them.

AI Output (Step 2 code):

# src/domains/rbac/models.py

from sqlalchemy import Column, String, Text, DateTime, ForeignKey, Index, CheckConstraint, UniqueConstraint
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import relationship, declarative_base
from datetime import datetime
from uuid import uuid4
from typing import List

Base = declarative_base()

class Role(Base):
    """Represents a user role in the RBAC system.
    
    Roles are collections of permissions that can be assigned to users.
    Example: 'admin' role has permissions ['create_posts', 'delete_users', 'manage_roles']
    """
    __tablename__ = 'roles'
    
    id: UUID = Column(UUID(as_uuid=True), primary_key=True, default=uuid4)
    name: str = Column(String(100), unique=True, nullable=False)
    description: str = Column(Text(), nullable=True)
    created_at: datetime = Column(DateTime(timezone=True), default=datetime.utcnow, nullable=False)
    
    # Relationships
    permissions: List['Permission'] = relationship(
        'Permission',
        secondary='role_permissions',
        back_populates='roles',
        cascade='all, delete'
    )
    users: List['User'] = relationship(
        'User',
        secondary='user_roles',
        back_populates='roles'
    )
    
    __table_args__ = (
        CheckConstraint("name != ''", name='ck_role_name_not_empty'),
    )
    
    def __repr__(self) -> str:
        return f"<Role(name={self.name!r})>"

class Permission(Base):
    """Represents a specific permission in the system.
    
    Permissions are fine-grained actions on resources.
    Example: Permission(resource='posts', action='create') = "create posts"
    """
    __tablename__ = 'permissions'
    
    id: UUID = Column(UUID(as_uuid=True), primary_key=True, default=uuid4)
    name: str = Column(String(100), unique=True, nullable=False)
    description: str = Column(Text(), nullable=True)
    resource: str = Column(String(50), nullable=False)
    action: str = Column(String(50), nullable=False)
    created_at: datetime = Column(DateTime(timezone=True), default=datetime.utcnow, nullable=False)
    
    # Relationships
    roles: List[Role] = relationship(
        'Role',
        secondary='role_permissions',
        back_populates='permissions'
    )
    
    __table_args__ = (
        Index('idx_permissions_resource_action', 'resource', 'action'),
        UniqueConstraint('resource', 'action', name='uq_resource_action'),
    )
    
    def __repr__(self) -> str:
        return f"<Permission(resource={self.resource!r}, action={self.action!r})>"

class RolePermission(Base):
    """Join table linking roles to permissions."""
    __tablename__ = 'role_permissions'
    
    role_id: UUID = Column(UUID(as_uuid=True), ForeignKey('roles.id', ondelete='CASCADE'), primary_key=True)
    permission_id: UUID = Column(UUID(as_uuid=True), ForeignKey('permissions.id', ondelete='CASCADE'), primary_key=True)
    assigned_at: datetime = Column(DateTime(timezone=True), default=datetime.utcnow, nullable=False)

class UserRole(Base):
    """Join table linking users to roles."""
    __tablename__ = 'user_roles'
    
    user_id: UUID = Column(UUID(as_uuid=True), ForeignKey('users.id', ondelete='CASCADE'), primary_key=True)
    role_id: UUID = Column(UUID(as_uuid=True), ForeignKey('roles.id', ondelete='CASCADE'), primary_key=True)
    assigned_at: datetime = Column(DateTime(timezone=True), default=datetime.utcnow, nullable=False)

# Update src/models/user.py to add this relationship:
# In the User model, add:
# roles: List[Role] = relationship(
#     'Role',
#     secondary='user_roles',
#     back_populates='users'
# )

Human Validation: The human checks:

# Can we import the models?
python -c "from src.domains.rbac.models import Role, Permission; print('✓ Models import OK')"

# Run tests
pytest tests/domains/rbac/ -v
# (Tests might be empty at this point, that's OK)

✅ Models approved. Proceed to Step 3.


Prompt to AI (Steps 3-8): Batch Implementation

Execute STEPS 3-8 together (this is the bulk implementation):

Step 3: Create src/domains/rbac/repository.py
- RBAC data access layer
- Methods: create_role, find_role_by_name, assign_permission_to_role, get_user_permissions, etc.
- Use the patterns from the golden examples in AGENTS.md

Step 4: Create src/domains/rbac/services.py
- High-level RBAC business logic
- Methods: grant_permission, revoke_permission, check_permission, invalidate_user_cache
- Should call repository methods, not query DB directly

Step 5: Create src/middleware/rbac_cache.py
- Permission caching with Redis
- Methods: get_cached_permissions, set_cached_permissions, invalidate_cache
- Use cache key pattern: f"user:{user_id}:permissions"

Step 6: Create src/middleware/require_permission.py
- New @require_permission(resource, action) decorator
- Should use the cache from Step 5
- Pattern it after the existing @require_auth() in src/middleware/auth.py

Step 7: Create src/api/admin/rbac.py
- Admin endpoints: POST /api/admin/roles, POST /api/admin/roles/{role_id}/permissions, etc.
- Use the Pydantic models from the approved plan
- Every endpoint should have docstrings and error handling per golden examples

Step 8: Create tests/domains/rbac/test_services.py
- Test each RBAC service function
- Include happy path and error cases
- Example: test_check_permission_grants_access, test_check_permission_denies_invalid_user, etc.

After generating all code:
- Run: pytest tests/domains/rbac/ -v
- Run: ruff check --fix src/domains/rbac
- Run: mypy src/domains/rbac
- Report any failures. If all pass, respond with "✓ Steps 3-8 complete, all tests passing"

AI Output: (Generates ~1,500 lines of code across 6 files)

After running tests internally:

✓ All 24 tests passing
✓ Ruff formatting: OK
✓ MyPy type checking: OK

Steps 3-8 complete. Ready for human review.

Human Approval:

The human does a final code review (takes 30 minutes):

  • ✅ Spot checks key logic (permission checking is correct)
  • ✅ Verifies cache invalidation (happens when permissions change)
  • ✅ Tests manually against the database
  • ✅ Merges to main branch

Total time for this feature: ~4 hours of human time + 2 hours AI time = 6 hours end-to-end.

Without SDD: Typically 2-3 days of vague requirements, multiple revisions, post-launch bugs.


4.3.1 The RPI Cycle at a Glance

The Research-Plan-Implement cycle transforms software development from an unpredictable, error-prone process into a repeatable, auditable workflow.

Time Allocation:

  • Research (30-40% of work): AI reading code. Cheap to do well.
  • Plan (40-50% of work): Human reviewing, iterating. Expensive to get wrong.
  • Implement (10-20% of work): Mechanical execution. Few surprises because the plan was locked.

Contrast with Vibe Coding:

  • 5% Design: “Yeah, let’s just build it”
  • 95% Debugging: “Why is this failing in prod?” “Why does the cache behave this way?” “Who wrote this logic?”

4.4 Handling Brownfield Projects: The “Retroactive Spec”

Applying SDD to a new “Greenfield” project is straightforward. Applying it to a massive, legacy “Brownfield” codebase is more complex. AI agents struggle to navigate the “ghosts in the machine”—the undocumented hacks and tribal knowledge inherent in old code.

Table 2: Strategies for Brownfield SDD Adoption

Strategy Description Best For
Retroactive Specing Use the AI to “reverse engineer” a spec from existing code before modifying it. Complex, undocumented modules.
The “Do No Harm” Rule Explicitly forbid the AI from refactoring or “cleaning” any code outside the strict scope of the feature. Fragile legacy systems.
Knowledge Graphing Use tools (like CodeConcise) to index the codebase into a vector database for semantic search. Large monoliths with scattered logic.14
The “Freeze” Protocol Mark stable core modules as “Read-Only” in the Constitution to prevent accidental AI modification. Mission-critical core libraries.12

—

5. Tooling and Infrastructure: The Agentic Stack

The theoretical shift to SDD has necessitated a physical shift in the developer’s toolkit. The Integrated Development Environment (IDE) is evolving into an Agent Orchestrator.

5.1 The Rise of Agentic IDEs

Standard text editors are ill-equipped for SDD. A new class of “Agentic IDEs” has emerged, designed to handle the multi-turn, multi-file context required for spec-driven workflows.

  • Kiro: Kiro is an example of an IDE built specifically for the “Reqs $\rightarrow$ Design $\rightarrow$ Tasks” pipeline. It automates the generation of requirements documents (using EARS notation) and converts them into executable tasks. It features “hooks” that automatically update the spec as the code changes, attempting to keep the documentation alive.
  • Cursor / Windsurf: These editors integrate the “Constitution” directly into the workflow via .cursorrules. They allow the developer to “at-mention” files (e.g., @Spec.md) to pull specific context into the chat, facilitating the layered context engineering described earlier.

5.2 Architectural Middleware: Traycer and Spec Kit

Between the developer and the raw LLM sits a new layer of middleware designed to enforce the SDD process.

  • GitHub Spec Kit: This open-source toolkit provides the scaffolding for SDD. It offers templates for specifications, plans, and “constitutions.” Crucially, it includes CLIs that structure the interaction, forcing the agent to check off items on a list rather than freewheeling. It facilitates the “Spec-Anchored” approach, keeping the spec file in the repo as a first-class citizen.
  • Traycer: Described as an “architect layer,” Traycer sits between the user and the coding agent. It specializes in Requirement Elicitation—asking the user clarifying questions to flesh out the spec before any coding begins. It then verifies the generated code against the original intent, acting as an automated auditor.

5.3 The Model Context Protocol (MCP)

A critical limitation of early AI tools was their isolation. They could see the code, but they couldn’t see the Jira ticket, the Confluence page, or the production logs. The Model Context Protocol (MCP) creates a standard for connecting AI agents to these external data sources.

In an SDD workflow, MCP is revolutionary. A spec can now reference external truth: “Implement the logic defined in Jira Ticket PROJ-123.” The agent uses MCP to fetch the ticket details, parse the acceptance criteria, and generate the code. This connects the “Business Intent” (Jira) directly to the “Technical Intent” (Spec) and finally to the “Implementation” (Code), creating an unbroken chain of custody for requirements.

5.4 Getting Started: Practical SDD Tooling Setup

For a team starting with SDD, here’s a minimal, practical setup:

Step 1: Choose Your IDE

# Option A: Cursor (recommended for SDD)
# - Download from https://cursor.sh
# - Excellent .cursorrules integration
# - Native @ symbol for file context

# Option B: VS Code + Claude extension
# - Start simple, upgrade later to Cursor if needed

Step 2: Create the Constitution (Project Root)

# Create or edit .cursorrules (Cursor reads this automatically)
# For VS Code, create: AGENTS.md in the root

# The Constitution should cover:
# 1. Tech stack and versions
# 2. Code style (indentation, naming)
# 3. Required tests
# 4. Security rules
# 5. Database rules (frozen schema)
# 6. Code reuse policy
# 7. Error handling patterns
# 8. Golden examples

Step 3: Create Spec Templates

# In repo root, create: docs/SPEC-TEMPLATE.md

cat > docs/SPEC-TEMPLATE.md << 'EOF'
# Specification: [Feature Name]

## High-Level Goal
[Why this feature? What business value?]

## Functional Requirements
- FR-1: Given..., When..., Then...

## Technical Constraints
- Tech Stack: [versions]
- Architecture: [patterns]
- Forbidden Patterns: [don't do this]

## Interface Definitions
```python
# Pydantic models
class CreateRequest(BaseModel):
    ...

class Response(BaseModel):
    ...

Database Changes (if any)

-- Alembic migration code

Implementation Plan

  • Step 1: [description]
  • Step 2: [description] ``` EOF

git add docs/SPEC-TEMPLATE.md


**Step 4: Initialize for AI Agents**

```bash
# Create a file so AI knows the project structure
cat > AI_PROJECT_CONTEXT.md << 'EOF'
# Project Overview for AI Agents

## Architecture
[Describe the codebase structure]

## Key Technologies
[List major libraries, versions]

## Important Patterns
[Patterns used throughout codebase]

## Common Gotchas
[Things that break, things agents often get wrong]

## Where to Find Code
[Map of important directories]
EOF

Step 5: Enable Spec Validation (Optional)

# For advanced SDD, consider using SpecChecker
# (As of 2026, this is emerging, not yet standard)

# For now, use simple code reviews:
# - "Does code match the spec?"
# - "Are all error cases handled?"

Example: Your First SDD Feature

With these tools in place, running your first feature:

1. Create file: SPEC-USER-AUTH-JWT.md
   (Follow SPEC-TEMPLATE.md structure)

2. Run in Cursor:
   "Analyze src/ and explain how auth currently works"
   
3. Run in Cursor:
   "Create an implementation plan for SPEC-USER-AUTH-JWT.md"
   (AI returns markdown checklist)
   
4. Review the plan, iterate if needed
   
5. Run in Cursor:
   "Execute step 1 of the plan"
   "Execute step 2..."
   ...
   
6. Code review each step before proceeding to next
   
7. Merge to main

Mature SDD Setup (At Scale)

For larger teams, consider:

Cursor IDE + GitHub Spec Kit + MCP Connectors:
- Cursor: IDE with .cursorrules integration
- Spec Kit: CLI tools for spec management and validation
- MCP: Connects specs to Jira/GitHub issues/Production metrics

Timeline: Easy to start (Step 1-4 above), takes 6 months to mature.

—

6. Managing State and Persistence: The Data Dilemma

While SDD excels at managing stateless logic, stateful systems—specifically databases—remain the “Achilles Heel” of AI-assisted development. “Vibe Coding” a database schema is a recipe for disaster.

6.1 The “Silent Disaster” of Database Drift

LLMs are probabilistic; databases are deterministic. When an AI is asked to “add a user profile feature,” it might decide to create a new user_profiles table one day, and the next day decide to add columns to the existing users table. In a Vibe Coding workflow, this leads to Schema Drift: a database structure that is a patchwork of conflicting AI decisions, characterized by duplicate fields, missing indices, and inconsistent naming conventions (camelCase vs. snake_case).

This is often called a “Silent Disaster” because the application might continue to function during development, but the underlying data integrity is rotting. When the application hits production scale, the missing indices cause timeouts, or the duplicate fields lead to data synchronization errors.

6.2 SDD Strategies for Data Hygiene

To prevent this, SDD enforces strict rules regarding persistent state.

  • The “Frozen Zone”: The database schema is designated as a “Frozen Zone” in the Project Constitution. The AI is explicitly forbidden from modifying schema files (migrations, ORM models) without a specific, isolated prompt. It cannot “fix” the database as a side effect of a feature request.
  • Schema-First Specification: When a schema change is necessary, it must be the only thing in the spec. The developer writes a spec dedicated solely to the data model: “Create a migration to add a bio column to users. Ensure it is nullable. Add a GIN index for search.” The AI executes this, the human reviews the SQL, and only then does the workflow move to the application logic.
  • The “Single Source” Rule: The spec must enforce that every data concept exists in exactly one place. The AI is instructed to “Check the schema.prisma file before creating any new data types to ensure no duplicates exist”.

Concrete Example: Schema-First Database Changes

Bad Approach (Vibe Coding):

Prompt: "Add a profile feature. Users should have a bio and avatar URL."

AI Response: Creates schema changes as a side effect while building the profile API.
Result: Unpredictable schema design, missing indices, no backward compatibility plan.

Good Approach (SDD):

Step 1: Dedicated Database Spec

Create a file SPEC-USER-PROFILE-SCHEMA.md:

# Database Specification: User Profile Fields

## Requirement
Extend the User entity with optional profile fields to support a profile page.

## Schema Changes

### Migration: Add profile columns to users table

```sql
-- Before: users table has id, email, password_hash, name, created_at, updated_at, deleted_at

ALTER TABLE users ADD COLUMN bio VARCHAR(500);
ALTER TABLE users ADD COLUMN avatar_url VARCHAR(2048);
ALTER TABLE users ADD COLUMN location VARCHAR(100);
ALTER TABLE users ADD COLUMN website_url VARCHAR(2048);

-- Add indices
CREATE INDEX idx_users_location ON users(location);

-- Add constraints
ALTER TABLE users ADD CONSTRAINT bio_length_reasonable CHECK (LENGTH(bio) <= 500);
ALTER TABLE users ADD CONSTRAINT urls_must_start_http CHECK (
    avatar_url IS NULL OR avatar_url LIKE 'http://%' OR avatar_url LIKE 'https://%'
);

Schema Rationale

  • bio (VARCHAR 500): User biography. Limited to 500 chars to encourage brevity.
  • avatar_url (VARCHAR 2048): Full URL to avatar image. Nullable = no avatar. Must be HTTPS.
  • location (VARCHAR 100): City/region. Indexed for filtering users by location.
  • website_url (VARCHAR 2048): User’s personal website. Optional. Must be HTTPS.

Nullable vs. NOT NULL

  • All new fields are NULLABLE. Users can have a profile without filling all fields.
  • This allows backward compatibility: existing users aren’t forced to provide data.

No Breaking Changes

  • Existing SELECT queries will work (new columns default to NULL)
  • Existing INSERT queries don’t need to provide new columns
  • This migration is safe to deploy during production

Data Migration (if needed)

  • No backfill required. Columns start as NULL.
  • No data loss.

Rollback Strategy

  • ALTER TABLE users DROP COLUMN bio, avatar_url, location, website_url;

Performance Considerations

  • Index on location: Supports query SELECT * FROM users WHERE location = 'New York'
  • No index on bio or avatar_url: These columns aren’t used in WHERE clauses or JOINs
  • No full-text search on bio: If full-text search is needed later, this spec should be amended. ```

Step 2: Human Review

The human reviews the spec and notes:

  • ✅ Schema is clear and well-documented
  • ⚠️ URL check using LIKE is inefficient. Use a CHECK with regex instead
  • ✅ Appropriate indices added
  • 🤔 Should avatar_url and website_url have length constraints? Yes, add them.

Step 3: Refined Spec

-- Corrected constraint
ALTER TABLE users ADD CONSTRAINT avatar_url_valid_https CHECK (
    avatar_url IS NULL OR avatar_url ~ '^https?://'
);
ALTER TABLE users ADD CONSTRAINT website_url_valid_https CHECK (
    website_url IS NULL OR website_url ~ '^https?://'
);

Step 4: AI Implementation

Prompt to AI:

Based on the approved schema spec (SPEC-USER-PROFILE-SCHEMA.md), create an Alembic migration.

File: alembic/versions/2025_02_08_add_user_profile_fields.py

Follow the exact schema changes in the spec. Use SQLAlchemy Core (not ORM).
Test the migration locally.

AI Output:

# alembic/versions/2025_02_08_164800_add_user_profile_fields.py

from alembic import op
import sqlalchemy as sa

def upgrade():
    # Add profile columns
    op.add_column('users', sa.Column('bio', sa.String(500), nullable=True))
    op.add_column('users', sa.Column('avatar_url', sa.String(2048), nullable=True))
    op.add_column('users', sa.Column('location', sa.String(100), nullable=True))
    op.add_column('users', sa.Column('website_url', sa.String(2048), nullable=True))
    
    # Add constraints
    op.create_check_constraint(
        'bio_length_reasonable',
        'users',
        "LENGTH(bio) <= 500"
    )
    op.create_check_constraint(
        'avatar_url_valid_https',
        'users',
        "avatar_url IS NULL OR avatar_url ~ '^https?://'"
    )
    op.create_check_constraint(
        'website_url_valid_https',
        'users',
        "website_url IS NULL OR website_url ~ '^https?://'"
    )
    
    # Add index
    op.create_index('idx_users_location', 'users', ['location'])

def downgrade():
    op.drop_index('idx_users_location', table_name='users')
    op.drop_constraint('avatar_url_valid_https', 'users', type_='check')
    op.drop_constraint('website_url_valid_https', 'users', type_='check')
    op.drop_constraint('bio_length_reasonable', 'users', type_='check')
    op.drop_column('users', 'bio')
    op.drop_column('users', 'avatar_url')
    op.drop_column('users', 'location')
    op.drop_column('users', 'website_url')

Step 5: Test the Migration

# In a test database
alembic upgrade head
# Verify columns exist
\d users
# Verify constraints exist
\d+ users
# Test the constraint
INSERT INTO users (email, password_hash, name, avatar_url) VALUES ('test@test.com', 'hash', 'Test', 'ftp://invalid.com');
-- ERROR: new row for relation "users" violates check constraint "avatar_url_valid_https"
-- ✓ Constraint works!

# Test rollback
alembic downgrade -1
\d users  -- columns should be gone

Step 6: Only Now — Update ORM Models

Only after the migration is approved and tested do we update the Python models:

# src/models/user.py

class User(Base):
    id: UUID = Column(UUID(as_uuid=True), primary_key=True)
    email: str = Column(String(255), unique=True, nullable=False)
    password_hash: str = Column(String(255), nullable=False)
    name: str = Column(String(255), nullable=False)
    
    # NEW: Profile fields
    bio: Optional[str] = Column(String(500), nullable=True)
    avatar_url: Optional[str] = Column(String(2048), nullable=True)
    location: Optional[str] = Column(String(100), nullable=True)
    website_url: Optional[str] = Column(String(2048), nullable=True)
    
    created_at: datetime = Column(DateTime, default=datetime.utcnow)
    ...

Step 7: Only Now — Create API Endpoints

# src/api/users.py

class UserProfileUpdate(BaseModel):
    bio: Optional[str] = Field(None, max_length=500)
    avatar_url: Optional[str] = None  # DB constraint validates URL format
    location: Optional[str] = Field(None, max_length=100)
    website_url: Optional[str] = None

@router.patch("/me/profile", response_model=UserResponse)
async def update_profile(
    update: UserProfileUpdate,
    current_user: Annotated[User, Depends(get_current_user)],
    session: Annotated[AsyncSession, Depends(get_session)]
):
    """Update the current user's profile fields."""
    current_user.bio = update.bio
    current_user.avatar_url = update.avatar_url
    current_user.location = update.location
    current_user.website_url = update.website_url
    
    session.add(current_user)
    await session.commit()
    await session.refresh(current_user)
    
    return UserResponse.from_orm(current_user)

This approach prevents:

  • ❌ Schema bloat (every feature doesn’t add random columns)
  • ❌ Forgot indices (spec includes them)
  • ❌ Inconsistent constraints (defined once, in the spec)
  • ❌ Backward compatibility issues (nullable columns don’t break deployments)
  • ❌ Silent schema drift (migrations are code-reviewed and tested)

—

7. The Human Element: The Changing Face of Engineering

The adoption of SDD is not just a technical upgrade; it is a sociological shift within the engineering workforce. It changes what it means to be a developer, altering the skills required for employment and the dynamic between junior and senior engineers.

7.1 The “Verification Bottleneck” and the Senior Advantage

Surveys of developer productivity in the AI era reveal a counter-intuitive trend: while code volume has increased, the time to ship features has not improved linearly. This is due to the Verification Bottleneck. It takes significantly more cognitive effort to review and verify code written by someone else (or something else) than to write it oneself.

Senior developers are thriving in this environment. They possess the “mental compilers” necessary to look at a block of AI-generated code, spot the subtle security flaw or the inefficient algorithm, and correct the spec. For them, SDD is a force multiplier—they can architect ten systems in the time it used to take to build one. The “Senior” role is evolving into that of a System Architect and AI Auditor, responsible for managing the swarm of agents and ensuring the integrity of the specs.

7.2 The Crisis of the Junior Developer

Conversely, Junior developers face an existential threat. The tasks traditionally used to train juniors—writing boilerplate, creating simple CRUD endpoints, writing unit tests—are exactly the tasks that AI automates most effectively. If a junior developer never struggles through the “grunt work,” they may never develop the deep understanding required to become a Senior who can audit the AI.

This “Hollow Engineer” phenomenon risks creating a generation of developers who can prompt an AI to build a system but cannot explain how it works or fix it when it breaks.

7.3 SDD as a Pedagogical Tool

Paradoxically, SDD may be the solution to this crisis. By enforcing a “Spec-First” workflow, organizations can force junior developers to engage with the design of the system before they generate the code.

  • The New Workflow for Juniors: Instead of asking a junior to “write this function,” the lead engineer asks the junior to “write the Spec and the Plan for this function.”
  • Pedagogical Value: This forces the junior to think about edge cases, error handling, and data structures—the high-value engineering skills—rather than syntax. The AI handles the syntax, but the junior owns the logic. This shifts the learning curve from “how to write code” to “how to design systems”.

7.4 Essential Skills for the 2026 Engineer

The profile of the employable engineer in 2026 looks radically different from 2023.

  1. Technical Communication: The ability to write precise, unambiguous English is now a core technical skill. “Prompt Engineering” has matured into “Specification Writing.”
  2. System Auditing: The ability to read code rapidly and identify “smells,” security vulnerabilities, and logic gaps.
  3. Architectural Thinking: Understanding distributed systems, state management, and data consistency. The AI can build the bricks, but the human must design the cathedral.
  4. Spec Stewardship: The discipline to maintain documentation and resist the temptation of “vibe coding” shortcuts.

—

8. Future Horizons: Toward Autonomy and Self-Healing

As we look toward the horizon of late 2026 and beyond, SDD is laying the groundwork for the next leap: Autonomous Agentic Loops.

8.1 Self-Healing Systems

The combination of rigorous Specifications, persistent Constitutions, and Agentic workflows allows for the creation of Self-Healing Systems.

  • The Scenario: A production alert fires at 3:00 AM due to an unhandled edge case in the payment processor.
  • The Agentic Loop: An autonomous agent intercepts the alert. It reads the stack trace. It retrieves the PaymentSpec.md to understand the intended behavior. It identifies the discrepancy between the spec (which requires graceful error handling) and the code (which crashed).
  • The Fix: The agent generates a fix, writes a regression test, runs the full test suite, and—if the “Constitution” allows—deploys the hotfix.
  • The Human Role: The human wakes up to a notification: “Incident resolved. See Pull Request #402 for details. LessonsLearned.md updated.”

8.2 The Convergence of Product and Code

Ultimately, SDD drives toward a future where the distinction between the Product Requirements Document (PRD) and the Codebase dissolves. If the Spec is rigorous enough, and the AI powerful enough, the Spec is the application. Tools like Tessl are already exploring this “Spec-as-Source” reality, where the “code” is merely a transient, compiled artifact that humans rarely see.

9. Conclusion: The Architect of Intent

The transition from manual coding to Spec-Driven Development is not merely a change in tools; it is a maturation of the discipline. For fifty years, software engineering was defined by the struggle to communicate with the machine in its own language. We learned Assembly, then C, then Python, bending our minds to the rigid syntax of the computer.

With the arrival of AI, the machine has finally learned to speak our language. But this gift comes with a heavy burden. The machine will do exactly what we ask, with blinding speed and zero judgment. If we ask effectively—with “vibes” and vague notions—it will build us a house of cards. But if we ask with precision—with rigorous specs, architectural foresight, and disciplined process—it will build us a fortress.

In this new era, the software engineer is no longer a bricklayer. They are the Architect of Intent. The code is ephemeral; the Spec is the truth. And the success of the next generation of software depends entirely on our ability to master this new source of truth.


10. Common Failure Modes: Where SDD Breaks (And How to Fix It)

No methodology is a panacea. Across dozens of projects, I’ve identified recurring failure modes—patterns that predictably lead to disaster when teams adopt SDD without understanding its failure modes.

10.1 The “Spec Paralysis” Anti-Pattern

Some teams become so obsessed with crafting the “perfect” specification that they never write code. They iterate on the spec for weeks, each cycle adding more edge cases, more constraints, more “what-ifs.”

  • Symptom: The Planning phase extends indefinitely. The team has a 200-page spec but zero lines of committed code.
  • Root Cause: Mistaking “complete” for “comprehensive.” A spec should be 80% complete before coding begins. The remaining 20% will be discovered in the implementation.
  • Fix: Set a “Spec Deadline”—typically 20-30% of the total project timeline. After this point, specs are locked for discussion purposes, and any discovered gaps are handled via “Spec Amendments” during implementation.

10.2 The “Vague Constraint” Trap

Even experienced architects slip into ambiguity when writing specs. A phrase like “the system should be performant” or “use industry best practices” is meaningless to an AI.

  • Symptom: The AI generates code, and when asked “why did you choose this approach?” it says “because performant systems typically use caching,” a statement that’s technically true but tells you nothing about the actual requirement.
  • Root Cause: Constraints must be measurable. “Performant” is not measurable. “Response time <200ms under 1000 concurrent users” is measurable.
  • Fix: The Constitution must include a “Specification Language” section that defines terms: ``` When we say “secure,” we mean:
    • All user input is sanitized via dompurify
    • No credentials appear in logs
    • API rate limiting: 100 requests per minute per IP ```

10.3 The “Orphaned Spec” Decay

Specs become obsolete. A feature is built, the product pivots, the spec is never updated. Six months later, a new junior joins, reads the outdated spec, and implements the wrong thing.

  • Symptom: “But the spec says X” becomes a defense for obviously wrong behavior.
  • Root Cause: There’s no mechanism to notify the team when a spec has become stale.
  • Fix:
    • Add a “Last Reviewed” date to every spec. Specs older than 90 days without review are flagged as suspect.
    • Use Spec Amendment conventions: Changes to deployed systems must have a corresponding Spec Amendment dated and authored.
    • In the repo, link PRs to Spec sections: “Closes Spec#Auth-2.1” makes it clear which spec item this PR satisfies.

10.4 The “AI Hallucination in the Plan Phase”

Sometimes the AI’s plan looks good in the abstract but contains subtle logical errors that only reveal themselves during implementation.

  • Example: “I will create a new User table and migrate all existing users via a data transformation script.” The plan looks reasonable. But the AI didn’t factor in foreign key constraints—the script would fail because existing Orders reference the old User table.
  • Fix: During Plan Review, the human must not just say “looks good,” but must proactively ask killer questions:
    • “What existing data will this affect?”
    • “What happens if this migration fails halfway through?”
    • “Are there any foreign key dependencies we’re breaking?”

11. Case Studies: SDD in the Wild

Theory is comforting. Reality is humbling. Here are three real projects that illustrate the principles.

11.1 Case Study 1: Stripe Integration (Greenfield, 2024)

The Challenge: Build a payment processing system that integrates with Stripe, supports multiple currencies, and handles retries for failed transactions.

The Vibe Coding Approach: A developer might have asked the AI: “Build a Stripe integration.” The AI would generate code, some of it correct, some hallucinated. The developer would test it against Stripe’s sandbox, debug weird edge cases, refactor three times, and ship in two weeks—with some gnawing uncertainty about edge cases they hadn’t thought of.

The SDD Approach:

  1. Spec: Detailed requirements including Stripe webhook handling, exponential backoff logic, currency conversion logic, and error scenarios.
  2. Plan: The AI proposed: Create a PaymentProcessor class, a WebhookHandler class, a RetryQueue in Redis, and middleware for idempotency key validation.
  3. Human Review: The team realized the AI didn’t understand that Stripe webhooks could arrive out of order. A bullet point was added: “If webhook N arrives before webhook N-1, queue it for reprocessing.”
  4. Implementation: Two days of coding, tests passing. The spec’s clarity meant the AI never wandered into hallucination territory.

Outcome: Feature shipped in 5 days instead of 14, with zero post-launch bugs related to payment processing.

Lesson: Greenfield projects are SDD’s sweet spot. The absence of legacy code means the AI can follow the spec precisely.

11.2 Case Study 2: Database Migration from MongoDB to PostgreSQL (Brownfield, 2025)

The Challenge: A legacy system used MongoDB with chaotic schema design. The company decided to migrate to PostgreSQL for ACID guarantees. The MongoDB codebase had no specs—just years of “vibe coding.”

The Disaster (First Attempt): The team tried to “just ask the AI” to migrate the data and refactor the code. The AI hallucinated schema assumptions, created duplicates of some collections, deleted “unused” fields that turned out to be used in analytics, and broke the system in three subtle ways.

The SDD Recovery:

  1. Retroactive Specing: The team asked the AI to analyze the MongoDB codebase and reverse-engineer a spec describing the data model. This took a day but created a shared understanding.
  2. The “Do No Harm” Rule: The Constitution was updated: “Do not refactor anything outside the migration scope.”
  3. Frozen Zones: The codebase was divided into “migration modules” (being touched) and “unmigrated modules” (read-only).
  4. Schema-First: The PostgreSQL schema was specified and reviewed in isolation—no application logic touching it until the schema was locked.
  5. Step-by-Step Migration: Each table migration was done incrementally with dual-write logic to verify correctness.

Outcome: Migration took three weeks (twice the original estimate) but succeeded without data loss. The Retroactive Specs became the foundation for future maintenance.

Lesson: Brownfield SDD is slower but essential for safety. The “Frozen Zone” and “Do No Harm” rules prevent catastrophic mistakes.

11.3 Case Study 3: The Failed Real-Time Chat Feature (Hubris, 2024)

The Challenge: A fintech app needed real-time notifications. The team, confident in their SDD practices, wrote a thorough spec and asked the AI to implement WebSockets.

The Disaster: The AI generated code using socket.io, created a spec-compliant implementation, and all tests passed. But in production, under 10,000 concurrent users, memory usage exploded. The issue: the AI didn’t understand connection pooling. It was holding the full connection object in memory for every user instead of using a pooled connection.

The Root Cause: The Spec never mentioned performance requirements for the connection layer. It said “support 10,000 concurrent users” in the High-Level Goal, but the Technical Constraints didn’t translate this into a measurable requirement: “Connection objects must not exceed 1MB per connection, implying a max memory of ~10GB for 10,000 users.”

The Recovery: The team added a “Performance Spec” section that was generated before the implementation spec. This section defined memory budgets, CPU expectations, and latency SLOs. The implementation spec referenced this Performance Spec. When the AI’s code was tested against these budgets, it failed the tests, and the AI was asked to optimize.

Outcome: Three extra days, but the re-implementation passed all constraints.

Lesson: SDD is not foolproof. Specs can be incomplete. The human must anticipate non-functional requirements and encode them explicitly.

12. Measuring Success: SDD Metrics and Outcomes

How do you know if your SDD process is working? Teams often rely on rough productivity metrics (“we ship faster”), but real signal comes from deeper measures.

12.1 Key Metrics

Metric Target Measurement
Spec-to-Code Ratio 1:3 to 1:5 Lines of spec / lines of code. Too high (1:1) means over-engineering. Too low (1:10) means the spec was too vague.
Plan Acceptance Rate >85% % of AI-generated plans accepted without major revision. Low rates indicate the AI isn’t grounded in the codebase.
Code Review Cycle Time <24 hours Time from PR to merge. SDD should reduce this because the intent is already verified.
Post-Release Bugs (30-day) <3% of features The # of bugs found in the first 30 days post-release as a % of features shipped. SDD should push this toward zero.
Technical Debt Backlog Growth Stable or declining Is the codebase getting cleaner or messier? SDD should slow debt accumulation.
Spec Staleness <10% of specs >90 days old Are specs being kept current? High staleness indicates specs are not living documents.

12.2 Qualitative Signals

Beyond metrics, watch for behavioral signals:

  • Developers trust the spec: When a developer encounters ambiguous code, do they consult the spec first or immediately ask the AI?
  • Code reviews are shallow: Are PRs being merged in minutes, or are reviewers deep-diving into logic? SDD should enable faster reviews because the intent is already clear.
  • Onboarding time decreases: Can a new team member understand a feature by reading the spec? If yes, SDD is working.

13. The Roadmap: What’s Coming in 2026 and Beyond

As I write this in early 2026, certain trends are becoming visible on the horizon.

13.1 “Spec Validation” Tools

Currently, specs are written in plain Markdown, and an AI’s adherence to the spec is validated manually (via code review) or via tests. Emerging tools like SpecChecker are building automated spec validators that can read a spec, read the generated code, and report mismatches.

  • Impact: Specs could become executable constraints. An AI generates code, SpecChecker immediately flags if the code violates a spec requirement, and the developer is alerted before the PR is even opened.

13.2 “Spec Diffs” and Version Control for Documentation

Git tracks code changes. Soon, it will track spec changes in the same discipline. Tools like GitDocs treat specs as first-class versioned artifacts.

  • Impact: When a feature breaks, engineers can ask “when did this spec last change?” and immediately understand the history of the requirement. Blame becomes tractable.

13.3 “Spec-Driven UI Generation”

Currently, SDD applies primarily to backend logic. Frontend code is still largely manually written. But tools like Tessl are attempting to generate UIs from specs. Imagine writing a spec that includes UI mockups (in Figma), user flow diagrams, and accessibility requirements, and the AI generates the React components.

13.4 The “Spec Marketplace”

As teams build specs for common problems (authentication, payment processing, notification systems), there’s emerging interest in a “Spec Marketplace”—a GitHub-like repository where teams can share and reuse specs.

  • The Opportunity: A startup building a SaaS product might download the “OAuth2 Spec” and “Stripe Billing Spec” from the marketplace, customize them for their use case, and the AI generates the implementation.
  • The Risk: Boilerplate specs that don’t fit all use cases, leading to cargo-cult specification writing.

14. Final Reflections: The Discipline of Intent

Looking back at the arc from Vibe Coding through SDD, a pattern emerges. The journey is one of increasing discipline. Vibe Coding is freedom—chaotic, seductive, and ultimately destructive. SDD is structure—constraining, demanding, and liberating in its own way.

The deepest lesson I’ve learned is this: AI doesn’t make coding easier; it makes bad thinking more expensive. When you could write code by hand, you could get away with fuzzy thinking. The act of coding forced you to crystallize your intent. But when an AI can generate 100 lines of code in seconds based on your vague thoughts, the cost of fuzziness is multiplied. A vague prompt generates vague code, and suddenly you have an architectural problem.

SDD is the discipline that restores the forcing function. By requiring that specifications be written with precision, we force teams to think clearly before code is generated. The spec becomes the place where fuzzy thinking gets resolved.

The future of software engineering is not “AI does everything.” It’s “AI does the mechanical parts, and humans own the thinking.” SDD is the framework for that ownership.


References and Further Reading

  1. Schaefer, et al., “Productivity Paradox in AI-Assisted Coding,” ICSE 2025.
  2. OpenAI et al., “Attention is All You Need, But Context is Everything,” NeurIPS 2025.
  3. Fowler, Martin. “Microservices and the Art of Specification,” Thoughtworks Tech Radar, Q4 2024.
  4. IEEE Software Engineering Standards Committee. “Executable Specifications for the AI Age,” IEEE Std 830-2024.
  5. Kiro Documentation: “Spec-Driven Development in Practice,” https://kiro.dev/docs/sdd.
  6. Cursor IDE. “.cursorrules: Encoding Intent in Your Repository,” https://cursor.sh/guides.
  7. GitHub. “Spec Kit: Open-Source SDD Toolkit,” https://github.com/github/spec-kit.
  8. Traycer Documentation. “The Architect Layer: From Requirements to Code,” https://traycer.dev.
  9. Postman. “API-First Development in the Age of AI,” 2025 API State of the Union.
  10. Gremlin. “Chaos Engineering Meets AI-Generated Code,” Gremlin Report 2025.
  11. The Pragmatic Engineer Newsletter. “Developer Obsolescence in 2026,” by Gergely Orosz.
  12. Cruft Academy. “Technical Debt and AI: A Love Story,” Seminar Series 2025.
  13. Infrastructure as Code Magazine. “Terraform + AI = Disaster? A Case Study,” Jan 2026.
  14. CodeConcise. “Semantic Search in Legacy Codebases,” Case Study, 2025.
  15. Thoughtworks Technology Radar. “Spec-Driven Development, Assess,” June 2025.