Refacil SDD-AI: An AI-Assisted Practical Framework for Specification-Driven Development

The Refacil SDD-AI project deeply integrates the specification-driven development (SDD) methodology with AI-assisted programming. It provides structured development workflows for editors such as Claude Code, Cursor, and OpenCode through a CLI tool, and supports cross-repository agent communication. Its core goal is to solve the problem of specification consistency in AI-generated code, enabling AI to work under clear project constraints, thereby improving development efficiency and code quality.

Large language models have changed software development methods, but AI-generated code often has specification inconsistency issues, and manual prompting is inefficient. SDD-AI was initiated by Erikole21. Its core concept is to use project specifications as the contextual foundation for AI agents, enabling AI to work under constraints. Drawing on contract programming and design-first practices, it is upgraded to a dynamic specification system where specifications can be queried, understood, and executed by AI in real time.

1. CLI Tool Layer: Delivered as a command-line tool, providing commands like sdd init (initialization), sdd spec add (specification management), and sdd agent run (agent coordination);
2. Specification Storage System: Stores architecture specifications, coding standards, domain knowledge, and task templates in the refacil-sdd/ directory, with a format that balances human maintainability and AI parseability;
3. Editor Integration: Supports Claude Code (injecting specifications into context), Cursor (specification query), and OpenCode (structured workflow);
4. Agent Communication Bus: A local message bus supports cross-repository agent collaboration, such as pushing backend specification changes to frontend agents to remind updates.

1. Initialization Phase: sdd init creates a specification directory and guides users to fill in project information;
2. Specification Definition: The sdd spec command family adds/modifies versioned specifications (Markdown + YAML metadata);
3. Development Iteration: Create task specifications, and AI agents work according to the steps: understand requirements → consult specifications → generate code → verify compliance;
4. Review and Synchronization: Automatically check the consistency between code and specifications, and remind to update specifications or code.

Technical Advantages: Reproducibility (stable output under the same specifications), knowledge precipitation (specifications become long-term assets), gradual adoption (expand from single specification to multiple); Applicable Scenarios: Enterprise-level development (compliance and quality control), open-source projects (reduce contribution review costs), education and training (impart engineering discipline and architectural thinking).

Refacil SDD-AI represents an attempt to evolve AI-assisted programming towards structured and engineering-oriented approaches. In the future, it will expand to more editor integrations and a specification template library, forming a best practice community. Its significance lies in: in an era of enhanced AI capabilities, using specification-driven approaches to allow AI to exert creativity within boundaries while maintaining human control over key decisions.