Using Spec-Driven Development for Production Workflows - Erik Hanchett, AWS

Key Concepts

• Spec-Driven Development (SDD): A methodology where structured requirements and design documents are created in Markdown before any code is written.
• AI Interns: A metaphor for Large Language Models (LLMs) that require clear, structured guidance to prevent them from "going off the rails."
• Steering Docs: Configuration files (e.g., agents.md, claud.md) that provide rules and guidelines to AI agents.
• Model Context Protocol (MCP): A standard for connecting AI models to external data sources (e.g., Jira, Asana) to provide relevant project context.
• Property-Based Testing: A testing methodology where code is validated against requirements using randomized inputs to ensure robustness.
• Human-in-the-Loop: The principle that a human developer must review and validate all AI-generated specifications and code.

---

1. The Philosophy of Spec-Driven Development

Eric Hanchett argues that SDD is essential for moving beyond "vibe coding" (writing code without a plan). By forcing the AI to generate documentation first, developers provide the necessary context to ensure the output aligns with project goals.

• The "Why": LLMs are prone to hallucination or drifting from requirements. SDD acts as a guardrail, ensuring the AI acts as a guided assistant rather than an autonomous agent making arbitrary decisions.
• The "Human-in-the-Loop": Hanchett emphasizes that the developer remains responsible for the final output. The AI is a tool, not a replacement for architectural oversight.

2. The SDD Workflow

The process follows a structured, iterative path:

1. Requirements Phase: The AI generates user stories and requirements (often in EARS format—Easy Approach to Requirements Syntax).
2. Design Phase: The AI creates high-level design documents, including architecture diagrams (Mermaid, ASCII art).
3. Implementation Phase: The AI breaks the design into a granular task list.
4. Refinement: The developer reviews and edits these documents to inject personal expertise and ensure accuracy.
5. Execution: The AI implements the tasks, often starting with an MVP (Minimum Viable Product) subset of the task list.

3. Tools and Implementation

• Kiro: An AI-powered IDE and CLI tool developed by AWS to facilitate SDD. It features a dedicated "Spec Mode" that automates the creation of requirements, design docs, and task lists.
• Manual SDD: Developers can replicate this process by manually prompting any LLM to generate the three-part documentation (Requirements -> Design -> Tasks) before coding begins.
• Spec It: An open-source project by GitHub that integrates similar specification-driven workflows into existing coding assistants.
• Skills: Instruction files that can be triggered on-demand (e.g., via /skillname) to perform specific tasks within the coding environment.

4. Advanced Techniques

• Property-Based Testing: Using libraries like fast-check (in the Node/TypeScript ecosystem) to run hundreds of tests against the requirements document. This ensures that the logic holds up under various data inputs.
• MCP Integration: By using the Model Context Protocol, developers can pull live data from project management tools (Jira, Asana) directly into the AI’s context window, ensuring the specs are always synced with the latest business requirements.

5. Best Practices and Warnings

• The Goldilocks Zone: Avoid providing too much or too little information in steering documents. Provide enough rules to guide the AI without overwhelming its context window.
• Review Everything: Never blindly trust the generated code. Always perform manual code reviews and use automated testing tools to verify the AI's output.
• Not Just for Greenfield: While SDD is excellent for new projects, it is equally effective for legacy codebases when implementing complex new features.
• MVP Strategy: When the AI generates a task list, instruct it to prioritize the first few tasks to create a functional MVP, allowing for early validation of the architecture.

Synthesis

Spec-Driven Development is a strategic shift from reactive coding to proactive planning. By leveraging AI to generate and maintain documentation, developers can manage complex projects more effectively. The core takeaway is that context is king: the quality of the code produced by an AI is directly proportional to the quality of the specifications provided to it. By maintaining a "human-in-the-loop" approach and utilizing tools like Kiro or manual documentation workflows, developers can achieve higher-quality, more maintainable software.