barcelosvinicius Skill: Spec-Driven Development (SDD)
SDD replaces ad-hoc prompting with a structured hierarchy of executable artifacts — specs, plans, and tasks — that give the AI precise, minimal, and verifiable context for every unit of work.
The core difference from vibe coding: vibe coding generates code from intent; SDD generates code from an executable spec. This becomes critical when the project grows beyond a single sprint, because context drift and implicit decisions are the main causes of AI-generated bugs in long-running systems.
Reference: engineering-principles.md §A and §Appendix C.
When to use SDD
| Scenario | Recommendation |
|---|---|
| Project spans more than 2 weeks | Use SDD from the start |
| Multiple features in parallel | Use SDD — prevents cross-feature context bleed |
| AI contradicts earlier decisions | Adopt SDD immediately — signals context drift |
| One-off script or prototype | Skip SDD — overhead exceeds benefit |
| Rapid exploration / learning phase | Skip SDD — decisions are still fluid |
| Team without discipline to maintain specs | Skip SDD — stale specs are worse than none |
The maturity test: if you find yourself re-explaining architecture decisions made in a previous session, SDD is overdue.
The .specify/ structure
.specify/
specs/ ← one spec per feature — WHAT the system does
plans/ ← execution plan derived from the spec — IN WHAT ORDER
tasks/ ← atomic task breakdown — EACH UNIT OF WORK
Each artifact is generated from the previous one, but can be edited by hand if the AI decomposes incorrectly.
Writing specs — EARS syntax
Use EARS (Easy Approach to Requirements Syntax) for requirements:
WHEN [trigger condition]
THE SYSTEM SHALL [action]
AND [additional constraint or output]
The format has zero ambiguity: trigger, condition, action, payload. An AI can generate testable code directly from it; a human can verify it against production behavior without interpretation. Every spec must also declare Non-goals (explicit boundaries prevent scope creep and hallucination), Constraints, and binary Acceptance criteria.
Full spec/plan templates and worked good-vs-bad examples: ears-reference.md.
Writing tasks — the atomic unit
Tasks are the direct input to AI implementation sessions. A task is well-formed when it satisfies all three properties:
- Single session — implementable without refreshing context mid-task.
- Binary verification — passes or fails a concrete test, no ambiguity.
- Explicit dependencies — lists predecessor tasks by ID, or "none".
Each task isolates one technical decision and declares what is out of scope. When the AI makes an error, the error is small and localized.
Worked decomposition example (entity → endpoints → auth): ears-reference.md.
Context as graph — depth and breadth
- Depth-first (default): ai-context file → task spec → task file. Minimal token cost; use for any session with a defined task.
- Breadth-first: ai-context file →
docs/INDEX.md→docs/structural-analysis.md. Use when starting a new feature, planning, or diagnosing cross-cutting issues.
The authority hierarchy doubles as a loading sequence — each layer narrower than the previous:
engineering-principles → ai-context file → agent → skill → spec → task
Without SDD, the same hierarchy is simply the authority model ending at the
docs layer (engineering-principles → ai-context → agent → skill → docs): no
.specify/ is required, and the "graph" is just that load order plus the
"most specific layer wins" rule — nothing more. Add .specify/ only when the
"When to use SDD" table above says so.
Golden rule: default to the deepest (narrowest) layer that contains the needed context. Move up only when the current layer is insufficient.
Compliance verification
SDD changes what is reviewed, it does not eliminate review:
- Tests derived from the spec — each
WHEN/SHALLrequirement maps to one or more test cases (AI + CI). - Human review focused on spec alignment — "does this code implement this spec?" is narrower and more objective than "is this code good?".
Integration with session continuity
With .specify/ in use, the depth-first flow replaces the full
HISTORY.md load for implementation sessions; at session end, mark the task
✅, update docs/HISTORY.md, and commit task file + code + docs together.
See the proc-session-continuity skill for the full protocol.
Common mistakes
| Mistake | Solution |
|---|---|
| Task scope too large | Decompose until each task fits one session |
| Spec without non-goals | Always add a Non-goals section |
| Outdated spec after code changes | Add spec update to the Definition of Done |
| Using SDD for one-off scripts | Apply the "When to use SDD" table |
| Skipping the plan layer | The plan makes ordering explicit and reviewable |