Spec-Driven Development Guide

Language: English | 繁體中文

Version: 1.1.1 Last Updated: 2026-01-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

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

Workflow Stages

Core Principles

Pre-Spec Evaluation

Before creating a specification, answer these questions:

Exceptions to "Spec First"

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

Proposal Template

# [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:

feat(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

# 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

# Add login

Adding login.

• •Missing spec ID
• •No motivation
• •No acceptance criteria

Common SDD Tools

Sync Verification

After completing a spec, verify synchronization:

Sync Checklist

## Sync Status

### Scope: [Universal|Project|Utility]

- [ ] Core Standard: [Created|Updated|N/A]
- [ ] Skill: [Created|Updated|N/A]
- [ ] Command: [Created|Updated|N/A]
- [ ] Translations: [Synced|Pending|N/A]

Sync Matrix

Best Practices

Do's

• •✅ Evaluate scope before creating spec
• •✅ Keep specs focused and atomic (one change per spec)
• •✅ Include clear acceptance criteria
• •✅ Link specs to implementation PRs
• •✅ Archive specs after completion
• •✅ Verify sync status before closing

Don'ts

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

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:

## 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