Spec-Kit — Spec-Driven Development (SDD)#

GitHub 官方開源工具包 (v0.4.3)，將規格驅動開發引入 AI Agent 工作流程。 Repo: https://github.com/github/spec-kit | License: MIT

What is Spec-Driven Development?#

Spec-Kit reverses traditional AI coding: specifications are first-class citizens, code is a derived output. Instead of "vibe coding" where you prompt AI directly, SDD follows a structured pipeline:

text

Constitution → Specify → Clarify → Plan → Tasks → Implement

Each phase has explicit inputs, outputs, and quality gates.

Prerequisites#

CLI Installation#

bash

# Install Specify CLI (requires uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.4.3

# Verify
specify check

System requirements: Python 3.11+, uv, Git, a supported AI agent.

Agent Support#

Spec-Kit supports 30+ AI agents. Key ones for our stack:

AgentIntegrationNotesClaude Code/speckit.* slash commands.claude/commands/speckit.*.mdGemini CLI.gemini/commands/speckit.*.tomlStandardopencode/speckit.* slash commandsStandardCodex CLI--ai-skills flagSkills in .agents/skills/GitHub Copilot/speckit.* slash commandsVS Code native

Workflow Commands#

Core Pipeline#

StepCommandOutputWhen0. Initspecify init <project> --ai <agent>``.specify/ + commandsNew project1. Constitution/speckit.constitution <description>``memory/constitution.mdNew project / principles2. Specify/speckit.specify <feature description>``specs/<NNN-feature>/spec.mdStarting a new feature3. Clarify/speckit.clarifyUpdates spec.md clarificationsBefore planning4. Plan/speckit.plan <tech stack description>``specs/<NNN-feature>/plan.md + researchAfter spec approved5. Tasks/speckit.tasks``specs/<NNN-feature>/tasks.mdAfter plan validated6. Implement/speckit.implementCode changesTasks defined

Optional Commands#

CommandPurposeWhen/speckit.analyzeCross-artifact consistency & coverage analysisBefore final review/speckit.checklistQuality checklists (unit tests for specs)Validate completeness/speckit.taskstoissuesConvert tasks to GitHub IssuesNeed project board sync

CLI Reference#

specify init#

bash

# New project
specify init my-project --ai claude

# Existing directory
specify init . --ai claude --force

# With Codex skills
specify init my-project --ai codex --ai-skills

# Skip git init
specify init my-project --ai claude --no-git

# Timestamp-based branch numbering
specify init my-project --ai claude --branch-numbering timestamp

specify check#

Verifies: git + all CLI agents configured in AGENT_CONFIG.

Extension & Preset Management#

bash

# Extensions
specify extension search                    # Browse available
specify extension add <name>                # Install

# Presets
specify preset search                       # Browse available
specify preset add <name>                   # Install

Project Structure#

After specify init:

text

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Project principles (Step 1)
│   ├── scripts/
│   │   ├── check-prerequisites.sh
│   │   ├── common.sh
│   │   ├── create-new-feature.sh    # Creates feature branch + spec dir
│   │   ├── setup-plan.sh
│   │   └── update-claude-md.sh
│   ├── templates/
│   │   ├── constitution-template.md
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   ├── extensions/
│   │   ├── catalog.json
│   │   └── <ext-id>/templates/
│   └── presets/
│       └── <preset-id>/templates/
├── specs/
│   └── 001-feature-name/
│       ├── spec.md                   # Feature specification (Step 2)
│       ├── plan.md                   # Technical plan (Step 4)
│       ├── research.md               # Phase 0 research output
│       ├── data-model.md             # Data model design
│       ├── quickstart.md             # Getting started guide
│       ├── contracts/                # API contracts
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       └── tasks.md                  # Task breakdown (Step 5)
├── .claude/commands/
│   ├── speckit.constitution.md
│   ├── speckit.specify.md
│   ├── speckit.plan.md
│   ├── speckit.tasks.md
│   └── speckit.implement.md
└── [source code]

Template Details#

Constitution ( memory/constitution.md)#

Defines non-negotiable project principles. All specs must comply.

Structure:

• Core Principles (I, II, III, ...) — Each with clear description
• Additional Constraints — Tech stack, compliance, security
• Development Workflow — Code review, testing gates
• Governance — Amendment rules, compliance verification

Only CEO/CTO may amend. Version: X.Y.Z | Ratified: YYYY-MM-DD

Spec ( spec.md)#

Key sections:

• Feature Branch: NNN-feature-name
• User Scenarios & Testing — Prioritized user stories (P1, P2, P3), each independently testable
• Edge Cases — Boundary conditions, error scenarios
• Requirements — Functional + non-functional
• Review & Acceptance Checklist — Validation gates

Plan ( plan.md)#

• Summary — Primary requirement + technical approach
• Technical Context — Language, dependencies, storage, testing, platform
• Constitution Check — Must pass before Phase 0
• Project Structure — File tree
• Implementation Details — Phase-by-phase breakdown

Tasks ( tasks.md)#

Format: [ID] [P?] [Story] Description

• [P] = can run in parallel
• [Story] = which user story (US1, US2, ...)
• Organized by user story for independent implementation

Extensions & Presets#

Template Resolution Priority (highest → lowest)#

text

Project-local overrides (.specify/templates/overrides/)
    ↓
Presets (.specify/presets/<preset-id>/templates/)
    ↓
Extensions (.specify/extensions/<ext-id>/templates/)
    ↓
Core (.specify/templates/)

Notable Community Extensions#

ExtensionPurposeTypespec-kit-jiraSync specs to Jira Epics/Storiesintegrationspec-kit-verifyValidate code vs spec artifactscode (read-only)spec-kit-cleanupPost-implementation quality gatecode (read+write)spec-kit-reviewComprehensive code reviewcode (read-only)spec-kit-archiveArchive merged featuresdocs (read+write)spec-kit-syncDetect/resolve spec vs code driftdocs (read+write)spec-kit-doctorProject health diagnosticsvisibility (read-only)spec-kit-maqa-extMulti-agent QA coordinatorprocess

Notable Presets#

PresetPurposepirate-speakFun localization demoaide-in-placeIn-place technology migrations

Paperclip Integration#

Reassign via API (use this, NOT shell scripts)#

bash

PAPERCLIP_API="http://localhost:3100/api"

# Reassign by agent ID
curl -s -X PATCH "$PAPERCLIP_API/issues/$ISSUE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"assigneeAgentId\": \"$TARGET_AGENT_ID\"}"

# Comment on issue
curl -s -X POST "$PAPERCLIP_API/issues/$ISSUE_ID/comments" \
  -H "Content-Type: application/json" \
  -d "{\"body\": \"Description of work done\"}"

Issue Lifecycle#

text

Dev → implement → reassign code-reviewer → CTO review → reassign qa → PM confirms → done
Bug: Dev → fix → reassign cto → reassign qa → done

Best Practices#

1. Spec before code — Resist "write code first, document later"
2. Constitution is law — All PRs must verify compliance
3. Prioritize user stories — P1 is the MVP, each story independently testable
4. Keep specs alive — Update specs when implementation drifts, don't pretend
5. Task granularity — Each task 2-4 hours max, split large ones
6. Use extensions — Install verify + cleanup for automated quality gates
7. Validate before implement — Run /speckit.analyze + /speckit.checklist
8. Clarify before planning — /speckit.clarify reduces rework

Common Pitfalls#

• Skipping constitution → Agent makes inconsistent decisions
• Overly vague specs → AI hallucinates features or misses edge cases
• No clarify step → Plan includes wrong assumptions
• Tasks too large → AI loses context, produces buggy code
• Not updating specs after changes → Drift between spec and code
• Ignoring constitution during plan → Architecture violations

Upgrade#

bash

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v0.4.3

References#

• Official repo: https://github.com/github/spec-kit
• Methodology deep-dive: spec-driven.md in repo
• GitHub blog: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• Extension catalog: extensions/catalog.community.json
• Preset catalog: presets/catalog.community.json
• Addy Osmani's spec writing guide: https://addyosmani.com/blog/good-spec/