spec-writing

Sprint specs document goals, scope, requirements, and testing criteria in a structured .claude/sprint/[N]/specs.md file. This artifact eliminates ambiguity by defining what's in scope, what's out of scope, acceptance criteria, and edge cases upfront, enabling agents to execute with precision and reduce rework.

A specs.md file includes mandatory sections: Sprint Goal, Scope (In Scope and Out of Scope), Requirements, Testing criteria, and QA settings. The template supports minimal or detailed patterns depending on project needs, with clear boundaries on deliverables and testable acceptance criteria.

Yes, specs.md supports both minimal and detailed spec patterns. Start with a concise sprint title, Goal, and Scope, then add Requirements and Testing sections as needed. The flexible structure adapts to project complexity while maintaining the core structure that prevents miscommunication.

Specs.md sections explicitly separate functional requirements (what the system does) from technical requirements (how it's built) and testing criteria. This dual documentation ensures architects and agents align on both the user-facing behavior and implementation constraints within the sprint scope.

In Scope lists deliverables and features the sprint commits to building; Out of Scope documents related work excluded from the current sprint. This boundary prevents scope creep and clarifies what agents should not attempt, keeping focus and preventing wasted effort on secondary tasks.

Specs provide agents with precise, machine-readable goals and testable criteria in a standard location and format. This structure enables automated sprint execution, reducing iteration cycles by eliminating ambiguity and ensuring agents understand acceptance criteria before implementation begins.