Spec-Driven Development
DesignSpec-Driven Development is an Agent Skill for design published in the winstonkoh87/Athena-Public repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Interrogates the user to build a complete design specification before writing any code. Prevents "vibe coding" failures.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/winstonkoh87/Athena-Public/blob/HEAD/examples/skills/coding/spec-driven-dev/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/spec-driven-development-639e9c86, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
📋 Spec-Driven Development
Philosophy: 55 minutes defining the problem, 5 minutes solving it.
1. The Problem
Most AI coding failures happen because the agent starts coding before understanding:
- What the user actually wants (vs. what they said)
- Edge cases and constraints
- Integration points and dependencies
- Success criteria
2. Execution Workflow
PHASE 1: INTERROGATION (No Code Allowed)
├─ "What is the ONE thing this must do?"
├─ "What does success look like? Be specific."
├─ "What are 3 things this must NOT do?"
├─ "Who/what does this interact with?"
└─ "What's the simplest version that would be useful?"
PHASE 2: SPEC DOCUMENT
└─ Write a design.md with:
├─ Goal (1 sentence)
├─ Requirements (numbered list)
├─ Non-Requirements (explicit exclusions)
├─ Architecture (how components connect)
├─ Edge Cases (what could go wrong)
└─ Acceptance Criteria (how to verify)
PHASE 3: USER APPROVAL
└─ Present spec for review
└─ DO NOT proceed to code until approved
PHASE 4: IMPLEMENTATION
└─ Code against the approved spec
└─ Reference spec line items in commits
3. The Spec Template
# Design Spec: [Feature Name]
## Goal
[One sentence describing what this does]
## Requirements
1. [Must do X]
2. [Must handle Y]
3. [Must integrate with Z]
## Non-Requirements (Out of Scope)
- [Will NOT do A]
- [Will NOT support B]
## Architecture
[How the components connect — diagram or description]
## Edge Cases
- [What if input is empty?]
- [What if API is down?]
- [What if user does X instead of Y?]
## Acceptance Criteria
- [ ] [Testable condition 1]
- [ ] [Testable condition 2]
4. When to Use
- Any feature that touches >3 files
- Any task that takes >30 minutes
- Any time you catch yourself thinking "I'll figure it out as I go"