---

name: spec-driven-dev description: | Guide Spec-Driven Development (SDD) workflow for planning changes before implementation. Use when: creating specs, proposals, planning features, using OpenSpec or similar tools. Keywords: spec, specification, SDD, proposal, openspec, design doc, 規格, 提案, 設計文件.

Spec-Driven Development Guide

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-30 Applicability: Claude Code Skills

---

Purpose

This skill guides you through Spec-Driven Development (SDD), ensuring changes are planned, documented, and approved before implementation.

Quick Reference

SDD Workflow

Copy┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Proposal   │───▶│    Review    │───▶│Implementation│
└──────────────┘    └──────────────┘    └──────────────┘
                                               │
                                               ▼
                    ┌──────────────┐    ┌──────────────┐
                    │   Archive    │◀───│ Verification │
                    └──────────────┘    └──────────────┘

Workflow Stages

Core Principles

Exceptions to "Spec First"

• Critical hotfixes (restore service immediately, document later)
• Trivial changes (typos, comments, formatting)

Proposal Template

Copy# [SPEC-ID] Feature Title

## Summary
Brief description of the proposed change.

## Motivation
Why is this change needed? What problem does it solve?

## Detailed Design
Technical approach, affected components, data flow.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies
List any dependencies on other specs or external systems.

## Risks
Potential risks and mitigation strategies.

Detailed Guidelines

For complete standards, see:

• Spec-Driven Development Standards

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

• Base standard: ai/standards/spec-driven-development.ai.yaml

Integration with Other Standards

With Commit Messages

Reference spec ID in commit messages:

Copyfeat(auth): implement login feature

Implements SPEC-001 login functionality with OAuth2 support.

Refs: SPEC-001

With Check-in Standards

Before checking in code for a spec:

• Spec is approved
• Implementation matches spec
• Tests cover acceptance criteria
• Spec ID referenced in PR

With Code Review

Reviewers should verify:

• Change matches approved spec
• No scope creep beyond spec
• Spec acceptance criteria met

Examples

✅ Good Practices

Copy# SPEC-001 Add OAuth2 Login

## Summary
Add Google OAuth2 login to allow users to sign in with their Google accounts.

## Motivation
- Reduce friction for new users
- Improve security by not storing passwords

## Acceptance Criteria
- [ ] Users can click "Sign in with Google" button
- [ ] New users are automatically registered
- [ ] Existing users are linked to Google account

❌ Bad Practices

Copy# Add login

Adding login.

• Missing spec ID
• No motivation
• No acceptance criteria

Common SDD Tools

Best Practices

Do's

• ✅ Keep specs focused and atomic (one change per spec)
• ✅ Include clear acceptance criteria
• ✅ Link specs to implementation PRs
• ✅ Archive specs after completion

Don'ts

• ❌ Start coding before spec approval
• ❌ Modify scope during implementation without updating spec
• ❌ Leave specs in limbo (always close or archive)
• ❌ Skip verification step

---

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check for SDD tool in workspace (OpenSpec, Spec Kit, etc.)
2. Check CONTRIBUTING.md for spec workflow documentation
3. If not found, default to manual file-based workflow

First-Time Setup

If no configuration found:

1. Ask the user: "This project hasn't configured SDD. Would you like to set up a specs directory?"
2. Suggest documenting in CONTRIBUTING.md:

Copy## Spec-Driven Development

We use Spec-Driven Development for all non-trivial changes.

### Process
1. Create proposal in `specs/` directory
2. Get approval from team lead
3. Implement and reference spec in PR
4. Archive spec after merge

### Spec Template
See `specs/TEMPLATE.md`

---

Related Standards

• Spec-Driven Development Standards
• Commit Message Guide
• Code Review Checklist

---

Version History

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards