Specification-Driven Development // SDD
Don’t Just Prompt, Prescribe: The Power of Spec-Driven AI
Spec-Driven Development (SDD) is a modern software development methodology that inverts the traditional workflow by establishing the specification as the central, authoritative artifact. Instead of code being the primary source of truth, SDD treats the specification as an executable contract that drives the entire engineering process, from design and planning to implementation, testing, and documentation. This approach aims to close the gap between intent and implementation, ensuring that the final product precisely matches the defined requirements and aligns all stakeholders, from developers to project managers, around a single, unambiguous vision.
The core of SDD is a collaborative and iterative process between developers and AI agents. It begins not with code, but with a high-level description of the feature’s purpose and requirements. An AI agent then expands this into a detailed, structured specification, which is refined through collaboration. Once the specification is validated, it is used to generate a technical implementation plan that outlines the architecture and technology stack. From this plan, the AI breaks down the work into small, isolated, and testable tasks. Only after these clear, actionable tasks are defined does the AI proceed to write the code, ensuring a methodical and validated progression from concept to completion.
This methodology solves several persistent problems in software development. By formalizing the requirements into a detailed contract before any code is written, SDD minimizes ambiguity, reduces last-minute surprises, and shortens feedback loops. This leads to greater consistency in design and higher code quality. The resulting specification does not become obsolete after coding begins; instead, it serves as a living document and a historical artifact that details what the feature is, how it works, and why it was built. This creates better alignment across teams and ensures the software being built directly addresses user needs.
While related to other methodologies like Test-Driven Development (TDD) and Behavior-Driven Development (BDD), SDD is distinct in its starting point and focus. TDD begins with writing tests, and BDD focuses on describing behavior in natural language. SDD precedes both, starting with the foundational “what” and “why” captured in a clear, structured specification. This makes it an intent-driven approach where the primary role of the developer is to steer the process and validate the outputs, while AI handles the bulk of the code generation and implementation details.
Real-World Spec-Driven Development: From Blueprints to AI Collaboration with AGENTS.md, CLAUDE.md, and GEMINI.md
Spec-Driven Development (SDD) has evolved from a formal methodology of writing detailed specifications before coding into a dynamic, collaborative practice essential for leveraging the full potential of AI coding agents. Instead of static documents, modern SDD relies on living, version-controlled markdown files that act as a “single source of truth” for both human developers and their AI partners.
This shift is best understood through real-world examples like AGENTS.md, CLAUDE.md, and GEMINI.md. These aren’t just documentation; they are executable instructions, project constitutions, and context guides that transform general-purpose AI models into specialized members of your development team.
The Rise of the Spec File: Beyond “Vibe-Coding”
In the initial wave of AI-assisted coding, developers often engaged in “vibe-coding”: giving a vague prompt to an AI, getting a block of code back, and iterating until it “felt” right. This approach, while useful for simple prototypes, struggles with the complexity of real-world applications. The AI lacks crucial context about the project’s architecture, coding standards, and overall intent, leading to code that might look correct but fails to integrate properly or misses key requirements.
Spec-driven development addresses this by making the project’s context and requirements explicit in dedicated markdown files. This ensures that the AI isn’t guessing your intent, it’s following a clear blueprint.
CLAUDE.md: The AI’s Project-Specific Brain
The CLAUDE.md file is a prime example of a spec file designed to deeply embed an AI agent, like Anthropic’s Claude, into a specific project. It functions as the AI’s memory and rulebook, containing guidelines that shape its behavior and output to match the team’s standards.
What a CLAUDE.md file contains in practice:
- Implementation Best Practices: Rules that dictate the AI’s process. For example, it might instruct the AI to always ask clarifying questions before starting complex work, follow Test-Driven Development (TDD), or list pros and cons if multiple approaches exist.
- Project-Specific Conventions: Details about the codebase that a new developer would need to know. This includes coding styles (e.g., using Lombok to reduce boilerplate in Java), error handling patterns, and architectural designs like Domain-Driven Design (DDD).
- Domain Vocabulary: A guide to the specific language and naming conventions used within the project to ensure consistency in the code generated by the AI.
- Dynamic Mode Adaptation: Sophisticated configurations can instruct the AI to switch its behavior based on the context. For instance, it might operate in an “Exploration Mode” when requirements are unclear and switch to a direct “Implementation Mode” once a clear specification is defined.
By reading the CLAUDE.md file at the start of a session, the AI transforms from a generic assistant into a junior developer that understands the project’s unique landscape, producing code that is more maintainable and consistent.
GEMINI.md: Guiding Google’s AI with Project Context
In the same vein as CLAUDE.md, the GEMINI.md file provides instructional context for Google’s Gemini models, particularly when used with tools like the Gemini CLI. It serves as a configuration file that sets the rules of engagement and tailors the AI’s responses to a project’s specific needs.
A real-world GEMINI.md might include:
- High-Level Project Goals: A clear description of what the application does and why.
- Key Folders and Files: Pointers to important parts of the codebase, helping the AI focus its analysis.
- Coding Standards and Libraries: Explicit instructions on preferred libraries, frameworks, and coding patterns to use.
- Mode-Specific Instructions: Defining different operational modes for the AI. A powerful example is creating a “Plan Mode,” where the GEMINI.md instructs the AI to act strictly as a senior engineer. In this mode, the AI is forbidden from writing implementation code and must instead research the codebase and produce a detailed, step-by-step plan for approval before any code is written.
This approach ensures that the powerful reasoning capabilities of models like Gemini are harnessed effectively, aligning their output with established project architecture and conventions.
AGENTS.md: A Standardized Language for AI-Human Workflows
While CLAUDE.md and GEMINI.md are often specific to the AI agent being used, AGENTS.md is an emerging open specification designed to standardize how AI agents interact with software development workflows, regardless of the underlying model. It bridges the communication gap between humans and AI by providing a machine-readable format for defining development procedures that is still easily understood by developers.
The core purpose of AGENTS.md is to eliminate ambiguity in common development tasks:
- Executable Commands: It defines operations as atomic, predictable commands. Instead of a natural language description like “run the tests,” it would specify the exact command-line instruction.
- Standardized Workflow: It provides a clear, unambiguous sequence for building, testing, linting, and deploying the application. This is crucial for autonomous agents that need precise instructions.
- Dependency and Execution Order: It formally documents dependencies and the correct order of operations, something often left as “tribal knowledge” in a README.md.
GitHub’s Copilot coding agent now supports AGENTS.md, allowing developers to create a single file in their repository root to guide the AI on how to build, test, and validate its changes.
The Spec-Driven Workflow in Action: A Practical Example
Modern SDD with AI tools follows a structured, multi-phase process, often facilitated by toolkits like GitHub’s Spec Kit.
- Specify: A developer starts by creating a high-level requirements document (e.g., spec.md or architecture.md). This file describes the “what” and “why” of a new feature, focusing on user stories and goals, not the technical stack. For example: “Develop a feature that allows users to save articles to a ‘read later’ list.”
- Plan: The developer then asks the AI agent (guided by its CLAUDE.md or GEMINI.md) to analyze the specification and create a detailed technical plan. This plan outlines the proposed architecture, API endpoints, data models, and choice of technologies. The developer reviews and refines this plan.
- Tasks: Once the plan is approved, the agent breaks it down into a list of small, actionable, and testable tasks, often in a tasks.md file. Instead of a vague goal like “build the feature,” the tasks are concrete, such as “Create a /posts/{id}/save API endpoint” or “Add a ‘Save’ button to the article view UI component.”
- Implement: The AI agent, now fully equipped with context from the various spec files, implements each task one by one. Throughout this process, AGENTS.md can be used to define the commands the agent uses to run tests and validate its own work, creating a tight feedback loop.
By externalizing the intent, plan, and rules into these structured markdown files, spec-driven development transforms the development process into a more predictable, transparent, and collaborative partnership between human and artificial intelligence.
Developing with specs keeps the fun of vibe coding, but fixes some of its limitations: vibe coding can require too much guidance on complex tasks or when building on top of large codebases, and it can misinterpret context. When implementing a task with vibe coding, it’s difficult to keep track of all the decisions that were made along the way, and document them for your team. By using specs, Kiro works alongside you to define requirements, system design, and tasks to be implemented before writing any code. This approach explicitly documents the reasoning and implementation decisions, so Kiro can implement more complex tasks in fewer shots.
