This document introduces the Specification-Driven Development (SDD) workflow—a structured methodology for building software using agentic tools such as Claude Code, AWS Kiro, and Roo Code. SDD organizes development into four clear phases: Steering Architect, Planning, Execution, and Debugger. This separation of concerns accelerates high-quality code generation, improves clarity, and ensures maintainability and traceability.
- 🚀 SDD Workflow Overview
- 🤖 Setting up the SDD Agents
- ✅ Best Practices for SDD
- 🔬 Applying SDD to Scientific Data Analysis
- Conclusion
- References
The SDD workflow consists of three main phases, with a dedicated mode for debugging.
- 🧭 Steering Architect Mode: Define the project's high-level rules, product vision, technology stack, and overall structure.
- 🗂️ Planning Mode: Collaboratively create detailed feature specifications, including requirements, design documents, and actionable tasks.
- ⚡ Execution Mode: A powerful, test-driven engine that implements tasks, verifies correctness with a self-healing mechanism, and incrementally updates the codebase.
- 🐞 Debugger Mode: A structured workflow to identify, replicate, and fix bugs, often initiated by the Execution mode.
Each phase is supported by specialized agentic tools and context files, which enforce coding discipline and minimize ambiguity throughout the development lifecycle.
graph LR
A[🧭 Steering Architect] --> B[🗂️ Planning];
B --> C[⚡ Execution];
C -- Tests Fail --> D[🐞 Debugger];
D -- Fix Verified --> C;
Responsibilities:
- Analyze the existing codebase (if any) to establish a baseline.
- Generate or update foundational rule files (e.g., in an
.ai-rules/directory). - Document the product vision, technology stack, folder structure, and project-level architectural rules, including conventions for unit testing and a unified development sandbox.
Artifacts:
.ai-rules/product.md: Describes the product's purpose, features, and target audience..ai-rules/tech.md: Specifies the programming languages, frameworks, libraries, and testing strategies to be used..ai-rules/structure.md: Defines the project's directory layout, file organization, and the unified sandbox environment conventions.
To ensure a clean and isolated development environment, the Steering Architect establishes conventions for a unified sandbox—a temporary, isolated space for developing new features or fixing bugs without impacting the main codebase.
All isolated work, whether for new features or bug fixes, takes place in the .sandbox/ directory or through a temporary Git branch. The method for creating this sandbox can be configured:
- Git Checkout: A lightweight approach that uses a temporary branch for isolated changes.
- Directory Copy: A minimal copy of only the necessary files for the task.
- Git Worktree: A more advanced approach where the sandbox is a linked Git worktree, ideal for seamless version control and parallel development.
These choices are documented in .ai-rules/structure.md. For a detailed explanation of each strategy, see the Sandbox Development Guide.
Steps:
- Define Requirements: Elicit and document requirements using methods like user stories, scenarios, or EARS (Event-Action-Response-State).
- Design Solution: Create high-level designs for modules, APIs, and interaction sequences.
- Break Down Tasks: Decompose the design into small, manageable tasks and analyze their dependencies.
Spec Folder Structure: A dedicated folder is created for each feature to hold its specifications:
specs/
└── feature-name/
├── requirements.md
├── design.md
└── tasks.md
Collaborative Refinement: Engage in dialogue with the AI agent to refine and clarify ideas. The agent should ask targeted questions (typically 3–5 per feature) to move from broad concepts to precise specifications, ensuring spec files are comprehensive and clear.
The Execution Mode is the core engine of the SDD workflow. It is a highly autonomous agent that takes a task from the planning phase and sees it through to completion. It incorporates a flexible, test-driven approach with a powerful self-healing mechanism.
Key features include:
- Flexible Testing Strategies: It can operate in TDD (Test-First), Classic (Code-First), or No-Tests mode, depending on the feature's configuration.
- Self-Healing Loop: If tests fail, it automatically attempts to fix the code multiple times before asking for help.
- Seamless Debugger Handoff: When it can't fix a problem, it packages up all the context into a handoff file and provides a smooth transition to the Debugger Mode.
For a complete breakdown of its internal workings and a detailed diagram, see the Execution Workflow Documentation.
Features can be developed in parallel, while tasks within each feature are executed sequentially. This enables efficient collaboration and faster delivery. For details on asynchronous local coding workflows, see Asynchronous Coding on Local with Git Worktree.
When a bug is identified during the Execution Mode, the SDD workflow provides a seamless transition to the Debugger Mode. This mode is designed to provide a safe and structured environment for bug resolution, ensuring that fixes are tested in isolation before being merged into the main codebase.
- Isolation: Bugs are replicated in a minimal, sandboxed environment within the unified
.sandbox/directory to prevent any impact on the main development work. - Two-Tiered Strategy: Offers both Atomic Function Testing (using TDD) for isolated bugs and System Integration Debugging for more complex issues.
- User-Centric Verification: The agent collaborates with the user to verify that the fix resolves the original bug without introducing new ones.
- Seamless Workflow Integration: After a bug is fixed and merged, the agent prompts to switch back to the Execution Mode to continue with the next task, ensuring a smooth development cycle.
Our SDD workflow introduces a "pendulum" or "boomerang" development cycle between the Execution and Debugger modes, designed for rapid and stable feature development in progressive mode.
The cycle works as follows:
- Execute: The
task-executoragent implements a significant, planned task from thetasks.mdfile. - Verify: Upon completion, the agent presents the changes to the user for verification.
- Debug (if needed): If the user identifies a bug, the workflow seamlessly transitions to the
debuggeragent. The bug is then isolated, replicated, and fixed in the unified sandbox environment. - Return: Once the bug is resolved and the fix is merged, the
debuggeragent offers to switch back to thetask-executor. - Continue: The
task-executorpicks up the next task, continuing the development momentum.
This iterative process ensures that each piece of implemented functionality is validated before moving on, creating a tight feedback loop that builds robust and reliable features quickly.
This section provides instructions for configuring agentic tools like Claude Code and Roo Code to use the SDD methodology with sub-agents or modes.
The prompts for each mode are essential for guiding the AI.
- Use the
/agentscommand in Claude Code and selectCreate new agent. - Choose
Personal (~/.claude/agents/)for global use orProject (.claude/agents)for project-specific use. - Select
Manual configuration. - Set the Agent type (identifier) to
steering-architect,planning-mode, orexecution-mode. - Copy the corresponding system prompt from the links above.
- Copy the description for the sub-agent from the prompt file's header.
- Allow the agent to use
All tools. - Set a color for the agent or leave it as automatic.
- Save the new agent.
- Use the agent with a prompt like:
Use @steering-architect to create project guidance for a Python library.
- Go to
Modes->Mode Settings->Create New Mode. - Provide a mode name, such as
🧭 Steering Architect,🗂️ Planning, or⚡ Execution. - Choose
Globalfor the save location orProject-specificfor local use. - For
Role Definition, copy the corresponding prompts from the links above. - For
Short description (for humans), copy the description from the header of the prompt files. - For
When to Use, copy thewhen_to_useguidance from the header of the prompt files. LeaveAvailable ToolsandCustom Instructionsunchanged. - Save the new mode.
- Switch to the corresponding mode and use a prompt like:
Create project guidance for a Python library project.
- Maintain Separation of Concerns: Strictly adhere to the responsibilities of each phase.
- Create Atomic Tasks: Ensure tasks are small, self-contained, and testable.
- Use Context Files: Always reference spec files for every change to maintain alignment.
- Include Verification Steps: Every task should have clear acceptance criteria.
- Iterate on Specs: Refine specifications based on learnings from implementation.
- Keep Documentation Current: Regularly update rules and documentation to reflect project evolution.
For guidance on adapting the SDD methodology for scientific data analysis and research, please see the detailed guide here: Applying SDD to Scientific Data Analysis
This guide provides a robust framework for structured, traceable, and maintainable software development. By leveraging agentic tools within the SDD methodology, teams can build complex systems with greater speed, discipline, and quality.