Spec-Driven Development: From Vibe-Coding to AI Engineering

The objective of this phase is to translate a high-level vision into a structured functional specification that defines what is being built and why, while explicitly avoiding technical "how" decisions.

• Goal-Oriented Documentation: The specification serves as a contract between the human and the AI agent, focusing on user journeys and measurable success criteria.

• Key Components of a Spec:

  • User Stories: Structured as "As a [user type], I want [capability], so that [benefit]".

  • Success Criteria: Measurable outcomes, such as "95% of notifications delivered within 60 seconds".

  • Explicit Constraints: A "DO NOT" list that defines boundaries, such as "Do NOT implement push notifications" or "Do NOT modify the existing User model".

• The Clarification Gate: AI agents are instructed to identify and mark ambiguities with [NEEDS CLARIFICATION] tags rather than making guesses. This phase often involves an iterative dialogue where the agent asks targeted questions to resolve uncertainty before any planning begins.

• Automation: Tools like the GitHub Spec Kit (/specify command) or Agent OS (shape-spec command) automate the creation of these SPEC.md or requirements.md files.

Once the functional requirements are stable, the workflow moves into the technical design phase, where the AI agent "groks" the existing codebase to propose an architecture that fits local patterns.

• Technical Translation: Business requirements are converted into technical decisions, including data models, API contracts, and technology stacks.

• Constitutional Compliance: The plan must align with the Project Constitution, ensuring that new features use standard libraries, follow security protocols, and respect naming conventions.

• Research-Driven Planning: Agents can be tasked with researching library compatibility or comparing different implementation approaches (e.g., Rust vs. Go) to inform the final architectural choice.

• Artifact Generation: This phase typically produces a plan.md along with supporting documents for database schemas and integration points with existing services.

In this phase, the comprehensive technical plan is decomposed into atomic, independently testable units of work.

• Forced Decomposition: Complexity is managed by ensuring each task touches only 1–2 files and is small enough to be reviewed as a single Pull Request.

• Task Derivation: The agent converts API contracts and data models into specific, verifiable steps, such as "create a user registration endpoint that validates email format".

• Logical Sequencing: Tasks are grouped into phases (e.g., Setup → Database → Implementation → Polish) to maintain a logical development order.

• Parallelization: Independent tasks are marked with a [P] tag, allowing multiple agents to work on different components simultaneously without conflicting.

The implementation phase involves the AI execution of individual tasks while the human developer shifts from "writer" to "architect and validator".

• Task Execution: Agents use the context from the specification, plan, and current task to generate implementation code. Advanced setups may orchestrate multiple specialized sub-agents (e.g., a Database Engineer and a UI Designer) to handle different task groups.

• Test-Driven Guardrails: Each acceptance criterion from the specification is translated into a test case. The agent must write and pass these tests before a task is considered complete.

• Human-in-the-Loop Review: Instead of reviewing massive "code dumps," the developer evaluates focused, specific changes that address a single task.

• Drift Detection: Continuous validation gates catch deviations from the original specification early, ensuring that the running system does not silently diverge from intended behavior.

• Verification: At the end of the feature build, Agent OS or Spec Kit runs a full verification process to confirm that all technical and functional requirements defined in Phases 1 and 2 are satisfied.

The Project Constitution (constitution.md) is a central, version-controlled document that establishes non-negotiable principles for a project. It acts as the system's "architectural DNA," ensuring that every AI-generated implementation remains consistent and high-quality.

• Core Purpose: It prevents AI assistants from building a "house of cards" by forcing them to follow local patterns instead of generic training data.

• Essential Contents:

  • Architectural Principles: Mandatory patterns like "library-first" (every feature begins as a standalone library) or "CLI-first" (functionality must be exposed via command-line).

  • Coding Standards: Explicit naming conventions (e.g., PascalCase for React components) and directory structures.

  • Non-Negotiable Workflow: Article III of the constitution often mandates strict Test-Driven Development (TDD), barring any implementation code until tests are written and confirmed to fail.

• Senior Oversight: A strong constitution requires the judgment of senior engineers to encode real architectural intent and rationale.

While a README.md explains a project to humans, Agent Instruction files (e.g., CLAUDE.md, AGENTS.md, or .cursorrules) explain how an AI should operate within specific project constraints.

• Separation of Concerns: This separation is critical for predictability; it provides the agent with facts that would otherwise clutter human documentation.

• Operational Details: These files should include:

  • Development environment commands: Exact commands for building, testing, and linting (e.g., npm run build, pytest -v).

  • Navigation Maps: Route tables mapping feature names to specific URLs or file locations.

  • Tool Usage: Precise instructions on which specialized tools (e.g., MCP servers for browser navigation vs. performance traces) to use for specific tasks.

• Persistence: The file acts as a persistent anchor that mitigates context loss when a developer restarts an agent session.

GitHub’s analysis of over 2,500 agent configuration files revealed that the most effective governance uses a three-tier boundary system to manage AI risk.

• ✅ Always Do (Autonomous Actions): Actions the agent should take without asking, such as running tests before every commit or following the project's specific style guide.

• ⚠️ Ask First (Approval Gates): High-impact actions that require human intervention, such as modifying database schemas, adding new dependencies, or changing CI/CD configurations.

• ? Never Do (Hard Stops): Categorically off-limits behaviors, most importantly "Never commit secrets or API keys" and "Never remove a failing test without approval".

• Reflective Verification: Developers should instruct agents to compare their final output against these boundaries and list any items not addressed, forcing the model to self-audit.

Organizations use the Project Constitution to establish "opinionated stacks," which democratize senior-level productivity across the entire team.

• Eliminating Implicit Guesswork: By front-loading context about approved libraries and patterns, SDD ensures that AI-generated code "feels native" to the project.

• Version Control for Thinking: Governance via the constitution ensures that even if three developers use different AI tools (e.g., Cursor, Claude Code, and Copilot), they are all implementing against the same contract and standards.

• Cross-Skilling and Onboarding: Standardized governance allows junior developers to follow the same "Spec → Plan → Tasks → Implement" flow as senior architects, as the organizational knowledge is embedded in the specifications and tests.

• Compliance Alignment: For regulated industries, specs and constitutions map directly to audit chains (e.g., SOC 2 or ISO 42001), turning compliance into an automated byproduct of the development process.

To bridge the gap between natural language and executable code, SDD utilizes the Easy Approach to Requirements Syntax (EARS). This structured format provides a universal language that both humans and AI agents can process with high deterministic accuracy.

• The Logic of Invariants: Requirements are expressed through a specific logic: WHEN [condition] THEN the system SHALL [expected behavior].

• Behavioral Scenarios: In testing contexts, this is often expanded into a GIVEN... WHEN... THEN... format to define specific state transitions and acceptance criteria.

• Property-Based Testing: Utilizing EARS allows requirements to be translated directly into system properties or invariants. These can then be used by the AI to run property-based testing, where the agent attempts to find any test case that falsifies the invariant, providing a high degree of confidence in the final code.

• Goal: The spec should be specific, testable, and precise enough that another developer or a literal-minded agent could implement it without further explanation.

A major cause of failure in AI-assisted coding is "blindness to context," where agents make plausible but incorrect assumptions about unstated requirements.

• The Clarification Gate: Effective SDD workflows mandate that agents identify uncertainties before planning begins. Agents are instructed to mark all ambiguities using [NEEDS CLARIFICATION] tags.

• Preventing Hallucinations: By forcing the agent to stop and ask targeted questions rather than guessing, you prevent the creation of "house of cards" code that collapses during integration.

• Validation Checklists: High-quality specs include a Requirement Completeness checklist. If markers like [NEEDS CLARIFICATION] still remain in the document, the "gate" is closed, and the implementation phase cannot proceed.

• Interactive Dialogue: Strategic planning commands (e.g., /specify or shape-spec) initiate a rounds-of-questions phase where the agent interviews the developer to course-correct the requirements document.

AI agents are increasingly multi-modal and perform significantly better when they have access to an actual visual reference for the user interface they are expected to build.

• Visual Context Layers: Developers can provide mockups, wireframes, and screenshots directly to the planning agent.

• Visual Analysis: Advanced agents (like the Spec Researcher sub-agent in Agent OS) analyze these images to generate visual insights and functional requirements, documenting them directly in the spec folder.

• ASCII Mockups: For text-based environments, agents can even generate ASCII diagrams to represent UI screens, allowing developers to rationalize the layout and "add-user" button placement before implementation begins.

• Figma Integration: Some workflows allow agents to reference Figma mocks directly via specialized MCP servers to ensure the generated CSS and component structure match the design system exactly.

In SDD, specifications are not static documentation; they are living, executable artifacts that serve as the project’s shared source of truth.

• Code-Spec Alignment: Specifications are version-controlled Markdown files that live in the repository alongside code and tests. When behavior changes, the specification is updated first, and the subsequent implementation is derived from that updated truth.

• Anchoring Context: Specs mitigate "context loss" or memory drift in AI sessions. Because the specification persists between chat windows, it provides a durable anchor whenever work resumes, preventing the agent from "forgetting" earlier architectural decisions.

• Intent as the System of Record: As software evolves, the unit of delivery shifts from a codebase to the specification itself. Maintaining the software means evolving the specifications, while implementation code becomes an "ambient," disposable artifact that can be regenerated in different languages (e.g., Rust vs. Go) from the same spec.

• Historical Traceability: Every change to the specification should be committed, creating a historical record of implementation decisions that assists in auditing and onboarding new team members.

Agent OS is a free, tool-agnostic system designed to align AI agents with a team’s specific coding style and standards while driving consistency across large features.

• plan product: A command used at project start to establish the product mission, roadmap, and tech stack as a persistent reminder for both humans and agents.

• shape-spec: Initiates strategic planning for a new feature. The agent asks a series of targeted clarifying questions (e.g., using "sensible assumptions" to speed up the process) and analyzes visual assets like mockups or wireframes to define user interface requirements.

• create-tasks: Analyzes the finalized spec and plan to generate an implementation roadmap in tasks.md. It groups tasks logically and can suggest specialized agents (e.g., Database Engineer or UI Designer) to handle specific task groups.

• orchestrate tasks: An advanced implementation workflow that delegates task groups to specialized sub-agents, particularly when used with tools like Claude Code.

Amazon Kiro is an enterprise agentic IDE built to improve control over AI agents and increase code quality through formal verification.

• EARS Syntax Integration: Kiro represents acceptance criteria using the Easy Approach to Requirements Syntax (EARS). This provides a structured natural language format (e.g., WHEN [condition] THEN the system SHALL [behavior]) that is machine-interpretable.

• Property-Based Testing (PBT): Kiro translates EARS requirements directly into system invariants (properties). It then uses automated reasoning to find test cases that falsify these invariants, providing a high degree of confidence that the implementation exactly matches the spec.

• Requirement Verification: Kiro scans requirements for over-ambiguity or invalid constraints (such as conflicting rules), helping developers resolve architectural gaps before implementaton begins.

The Model Context Protocol (MCP) allows AI agents to move beyond reasoning from static code by providing controlled, auditable access to live runtimes.

• Observation vs. Speculation: Instead of "guessing" why a system is slow or broken, MCP-enabled agents use live tools to diagnose real behavior.

• Specialized MCP Servers:

  • Playwright MCP: Enables agents to navigate browsers, trigger interactions, and capture screenshots for UI/UX verification.

  • Chrome DevTools MCP: Grants agents access to performance traces, network analysis, and console logs to troubleshoot bottlenecks like Slow LCP or Layout Thrashing.

• The Diagnostic Feedback Loop: SDD uses MCP to compare observed runtime behavior directly to the intended behavior defined in the spec, allowing for precise, evidence-based refactoring.

In SDD, testing is shifted to the earliest possible stage. Instead of writing tests after the code is generated, the specification itself contains the scenarios and acceptance criteria that will drive the implementation.

• Scenarios as Specification Artifacts: Effective specs include structured test scenarios for three critical paths:

  • The Happy Path: Success scenarios where all conditions are met (e.g., "GIVEN user has enabled channels, WHEN order status changes, THEN notifications are sent within 60 seconds").

  • Edge Cases: Handling boundary conditions like "Quiet Hours" for SMS delivery.

  • Error Cases: Explicit logic for system failures, such as retries with exponential backoff if a provider returns a 500 error.

• The Non-Negotiable TDD Workflow: Many projects include an "Article III: Test-First Imperative" in their project constitution. This mandates that no implementation code is written until unit tests are authored, approved by the user, and confirmed to fail (Red phase).

• Test-Driven Guardrails: Every acceptance criterion in the specification becomes a specific test case. This ensures that the agent cannot consider a task "done" until the code passes the specific checks derived from the spec.

SDD prevents "house of cards" code- fragile AI outputs that collapse under scrutiny by establishing mandatory review checkpoints at every stage of the lifecycle. You do not proceed to implementation until the upstream artifacts are fully validated.

• Specification Review Gate: A human review to remove hallucinations, correct misinterpretations, and resolve [NEEDS CLARIFICATION] tags before planning begins.

• Plan Review Gate: A technical checkpoint to ensure the proposed architecture, data models, and API contracts fit the Project Constitution and follow organizational standards.

• Atomic Task Verification: Breaking large features into small, reviewable chunks (typically 1–2 files each) allows humans to review focused Pull Requests rather than massive code dumps.

• Drift Detection: SDD introduces a self-policing feedback control loop that continuously compares observed runtime behavior against the intended behavior in the spec. If the code deviates (e.g., an API returns an undeclared field), the system fails fast.

To achieve high-rigor architectural determinism, SDD utilizes the Easy Approach to Requirements Syntax (EARS) to translate natural language into machine-interpretable system invariants.

• Structured Requirement Syntax: Acceptance criteria are written in the EARS format: WHEN [condition] THEN the system SHALL [behavior].

• Translating EARS into Invariants: These requirements are translated into system properties or invariants—fundamental truths the software must always satisfy.

• Falsification-Driven Testing: Using tools like Amazon Kiro, the system attempts to find a single test case that falsifies the invariant. If no contrapositive is found, the developer has a high degree of confidence that the implementation aligns 1:1 with the specification.

For complex features, SDD evolves from single-agent prompting to multi-agent orchestration, where specialized sub-agents are deployed for specific task groups.

• Specialized Personas: Tasks are routed to agents based on their core competencies:

  • Database Engineer Agent: Handles migrations, schema updates, and persistence logic.

  • API Architect Agent: Focuses on endpoint implementation and contract enforcement.

  • UI Designer Agent: Implements frontend components following visual mockups provided in the spec.

• Context Efficiency: Using sub-agents keeps individual context windows small and focused, which prevents logic degradation and "instruction drift" that often happens in monolithic chat sessions.

• The Orchestration Layer: Frameworks like Agent OS use the tasks.md roadmap to coordinate these agents. The human developer acts as the high-level "architect and validator," approving the output of each specialized agent before it is merged into the main project branch.

Traditional AI-assisted development often ends once the code is generated, but SDD extends this into troubleshooting and diagnosis. By treating the SPEC.md as the source of truth, developers can use AI agents to observe and verify that the running system actually matches the original intent.

• Evidence-Based Observation: Instead of asking an AI to "guess" why a system is failing based on static code, developers use Model Context Protocol (MCP) servers to give agents controlled access to live runtimes.

• Specialized Diagnostic Tools:

  • Playwright MCP: Used for automated browser navigation and user interactions to trigger specific flows defined in the spec.

  • Chrome DevTools MCP: Grants agents access to performance traces, network analysis, and browser-level insights.

• Repeatable Diagnostic Workflows: Agents follow a structured flow: navigate to a route defined in the spec, trigger a specific interaction, record a performance trace, and summarize findings with direct references to the source code.

• Real-World Examples: Agents can be prompted to analyze Largest Contentful Paint (LCP) breakdowns or identify Layout Thrashing by triggering reflows and analyzing the resulting trace data.

Once specifications become authoritative, drift detection becomes a mandatory architectural capability. Drift is defined as any divergence between declared system intent (the spec) and observed system behavior (the implementation).

• Architecture as a Runtime Invariant: SDD transforms architecture from an advisory design-time artifact into a self-policing control system.

• Continuous Validation: Validation layers compare observed behavior to the specification through continuous schema validation, contract testing, and payload inspection.

• Detecting Deviations: Common forms of drift include APIs returning undeclared fields, required fields being omitted during refactors, or security scopes degrading relative to the original policy intent.

• Failing Fast: When the system detects a violation of the specification, it is designed to fail fast, preventing architectural violations from propagating into production.

Legacy modernization is often hampered because the original intent of a system is lost to time. SDD provides a structured path to rebuild these systems by separating the stable "what" from the flexible "how".

• Intent Capture: The first step is to capture the essential business logic from the legacy system into a modern, structured specification.

• Clean-Slate Design: Developers can then design a fresh architecture in the technical plan such as refactoring a monolith to microservices or upgrading frameworks (e.g., Java 8 to 17) while ensuring the core business logic remains consistent.

• Eliminating Technical Debt: Because the AI rebuilds the system from the ground up based on the new plan and old intent, the project can be modernized without carrying forward years of accumulated technical debt.

Because SDD detaches specifications from implementation code, it becomes the primary engineering artifact, allowing for the generation of multiple implementation variations from a single source of truth.

• Language Exploration: Developers can ask AI agents to produce different implementations—such as comparing a component written in Rust vs. Go—to evaluate performance differences based on the same functional spec.

• Optimization Targets: Shared specifications can be used to generate multiple approaches to explore different optimization targets, such as performance, maintainability, or cost.

• UI/UX Parity: Multi-variant implementations can also extend to design. Agents can create several UI versions that rely on different Figma mocks (exposed via MCP) while all adhering to the same functional requirements.

• Target Agnosticism: A high-quality spec-native system guarantees that identical specifications yield identical artifacts, regardless of the target language or platform.

The core value proposition of SDD is the amplification of human effectiveness by automating the mechanical translation from specification to implementation.

• Accelerated Task Completion: Industry benchmarks and GitHub research indicate that developers using AI-assisted tools complete tasks 55% faster. High-performing users often realize 6+ hours of weekly savings.

• Massive Reductions in Migration Time: SDD excels in code migration and legacy modernization by separating stable intent from flexible implementation.

  • Google: Successfully generated character changes where 80% of landing modifications were AI-authored, leading to a 50% reduction in total migration time.

  • Airbnb: Migrated 3,500 test files in six weeks using AI automation, a task originally estimated to take 1.5 years.

• Cost vs. Benefit: Upfront specification effort typically takes hours, whereas manual implementation takes days or weeks. While specification adds 20-40% extra time upfront per feature, it results in 50-80% implementation time savings.

Adopting SDD requires a deliberate, phased approach to manage the significant cognitive shift required for engineers to move from implementation-first thinking to contract-first reasoning.

• Phase 1: Pilot (Weeks 1-4):

  • Objective: Validate value with minimal risk.

  • Scope: 1–2 developers working on a non-critical greenfield feature using low-friction tools like GitHub Copilot or Cursor.

• Phase 2: Team Expansion (Weeks 5-12):

  • Objective: Scale established patterns across the full development team.

  • Milestone: Establish team templates and formal specification review processes, aiming for 50%+ feature adoption.

• Phase 3: Organization-Wide Rollout (Weeks 13-24):

  • Objective: Establish SDD as the default workflow.

  • Scale: Governance policies for spec review and quality gates are integrated into CI/CD pipelines, targeting 80%+ adoption.

• Full Maturity: Research indicates that while many install extensions immediately, it takes roughly 11 weeks to fully realize productivity gains.

Successful SDD requires disciplined adherence to the workflow to prevent the creation of "house of cards" code fragile AI outputs that collapse under scrutiny.

• Vague Prompts: Treating AI like a search engine instead of a literal-minded pair programmer leads to failure. Vague prompts like "build something cool" produce wrong results because models are exceptional at pattern completion but cannot perform "mind reading".

• Spec Drift: Treating specs as "dusty artifacts" that are written once and forgotten leads to misalignment. Specs must be living documents that evolve alongside the code; if they are not updated when requirements change, governance collapses.

• The "Lethal Trifecta": AI agents can be dangerous due to the combination of speed (working faster than humans can review), non-determinism (same input yielding different outputs), and cost (encouraging corner-cutting on verification).

• Jumping to Code: Negating SDD by skipping the planning phase and jumping straight to "write the code" removes the ability to verify intent and architectural constraints.

To maximize ROI, organizations must track specific metrics that differentiate between "vibe coding" and rigorous engineering.

• Productivity Metrics:

  • Developer Velocity: Story points per sprint and feature cycle time.

  • Time Allocation: Monitoring the ratio of time spent on specification vs. implementation vs. debugging.

• Quality Metrics:

  • Defect Density: Bugs per 1,000 lines of code.

  • Validation Pass Rates: Tracking how often code passes mandatory verification gates on the first attempt.

• Operational Metrics:

  • Migration Accuracy: The percentage of AI-generated changes that successfully land in a repository without manual refactoring.

  • ROI Breakthrough: The point at which AI generates code 50-80% faster than manual coding, justifying the 20-40% specification overhead.