spec-driven-dev

Spec-Driven Development Guide

Language: English | 繁體中文

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