Spec-Driven Development
Synthesis
The spec-driven pattern treats a Markdown document as a maintained description of intent that an agent can compile into code. In the GitHub Brain MCP example, user-facing documentation, requirements, models, logic, queries, and a compilation prompt live in related Markdown files; the agent updates the implementation, which is then built and tested. [src]
Its real value is not that Markdown is magical. A versioned, reviewable specification gives humans and agents a shared interface for asking what changed, what must remain true, and what tests should demonstrate. The source reports a functioning workflow but cautions that regeneration slowed as the generated codebase grew; it had not yet established a mature test strategy. [src]
Guardrails
Keep specifications concrete enough to test, make generated changes inspectable, and preserve a feedback loop between specification defects and implementation defects. A document that merely restates vague wishes is not a reliable programming interface.