spec-driven
Spec-driven development workflow. Use when implementing new features, skills, or game mechanics. Ensures specs exist before code.
When & Why to Use This Skill
This Spec-Driven Development (SDD) skill for Claude agents establishes a rigorous workflow that prioritizes technical documentation and architectural planning before code implementation. By enforcing a 'spec-first' mandate, it ensures that all new features, skills, and mechanics are built upon a foundation of validated Pydantic models, stateless logic, and comprehensive type hinting, significantly reducing technical debt and improving software maintainability.
Use Cases
- Feature Engineering: Designing complex system components by defining strict input/output schemas and logic flows in the /specs/ directory before writing any functional code.
- Standardizing Development Workflows: Aligning distributed teams or agentic workflows to follow consistent coding standards, such as mandatory Pydantic validation and 100% test coverage.
- Robust Skill Creation: Developing stateless and scalable agent skills that adhere to specific architectural constraints, ensuring they are easily testable and integration-ready.
- Edge Case Mitigation: Utilizing the structured spec format to identify and document potential failures and invalid inputs during the design phase rather than after deployment.
| name | spec-driven |
|---|---|
| description | Spec-driven development workflow. Use when implementing new features, skills, or game mechanics. Ensures specs exist before code. |
Spec-Driven Development
Workflow
Before writing ANY implementation code:
- Check for existing spec in
/specs/ - If no spec exists, create one first
- If spec exists, follow it exactly
Spec Structure
Every spec should define:
## Input
What data the skill/feature receives (use Pydantic models)
## Process
Step-by-step logic (reference SRD rules if applicable)
## Output
Structured result (use Pydantic models)
## Edge Cases
What happens on invalid input, failures, etc.
Implementation Rules
- Use
from __future__ import annotations - Use Pydantic for all input/output validation
- Skills MUST be stateless (no global variables)
- Skills MUST NOT call LLMs directly
- Use type hints:
str | NonenotOptional[str] - Follow existing patterns in
src/skills/
Testing
- Write tests BEFORE or alongside implementation
- Tests live in
tests/test_<module>.py - Use pytest with AAA pattern (Arrange-Act-Assert)
- Aim for 100% coverage