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

Stage	Description	Output
Proposal	Define what to change and why	`proposal.md`
Review	Stakeholder approval	Approval record
Implementation	Execute approved spec	Code, tests, docs
Verification	Confirm implementation matches spec	Test results
Archive	Close and archive	Archived spec with links

Core Principles

Principle	Description
Evaluate First	Assess scope and sync needs before creating spec
Spec First	No functional changes without approved spec
Tool Priority	Use SDD tool commands when available
Methodology > Tooling	SDD works with any tool or manual process
Bidirectional Sync	Changes propagate to all related artifacts

Pre-Spec Evaluation

Before creating a specification, answer these questions:

Question	Options	Result
Scope?	Project-specific / Universal	Determines if Core Standard needed
Interactive?	Yes / No	Determines if Skill needed
User-triggered?	Yes / No	Determines if Command needed

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

Tool	Description	Command Examples
OpenSpec	Specification management	`/openspec proposal`, `/openspec approve`
Spec Kit	Lightweight spec tracking	`/spec create`, `/spec close`
Manual	No tool, file-based	Create `specs/SPEC-XXX.md` manually

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

Change Origin	Sync To
Core Standard	→ Skills, Commands, Translations
Skill	→ Core Standard, Commands, Translations
Command	→ Skill, Translations

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

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

First-Time Setup

If no configuration found:

Ask the user: "This project hasn't configured SDD. Would you like to set up a specs directory?"
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

Version History

Version	Date	Changes
1.1.0	2026-01-26	Added: Pre-Spec Evaluation, Sync Verification, Sync Matrix, enhanced best practices
1.0.0	2025-12-30	Initial release

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards