規格驅动开发指南

语言: English | 简体中文

版本: 1.0.0 最後更新: 2025-12-30 適用範圍: Claude Code Skills

目的

此技能引導您完成規格驅动开发 (SDD)，确保变更在实作前經過規划、记录和批准。

快速參考

SDD 工作流程

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│     提案     │───▶│     审查     │───▶│     实作     │
└──────────────┘    └──────────────┘    └──────────────┘
                                               │
                                               ▼
                    ┌──────────────┐    ┌──────────────┐
                    │     封存     │◀───│     验证     │
                    └──────────────┘    └──────────────┘

工作流程阶段

| 阶段 | 说明 | 产出 | |------|------|------| | 提案 | 定義变更内容与原因 | proposal.md | | 审查 | 利害关系人批准 | 批准记录 | | 实作 | 执行已批准的規格 | 程序码、测试、文件 | | 验证 | 确认实作符合規格 | 测试結果 | | 封存 | 关閉并封存 | 封存的規格及連結 |

核心原則

| 原則 | 说明 | |------|------| | 規格優先 | 没有批准的規格就不能进行功能变更 | | 工具優先 | 有 SDD 工具时優先使用工具指令 | | 方法論 > 工具 | SDD 可搭配任何工具或手动流程运作 |

「規格優先」的例外情况

緊急修復（先恢復服务，之後再補文件）
瑣碎变更（錯字、註解、格式調整）

提案範本

# [SPEC-ID] 功能標題

## 摘要
簡要描述提案的变更。

## 动机
为什麼需要这个变更？解决什麼問題？

## 详细设计
技術方案、受影響的元件、数据流程。

## 驗收标准
- [ ] 标准 1
- [ ] 标准 2

## 相依性
列出对其他規格或外部系统的相依性。

## 風險
潛在風險及緩解策略。

详细指南

完整标准請參考：

規格驅动开发标准

AI 優化格式（节省 Token）

AI 助手可使用 YAML 格式文件以減少 Token 使用量：

基礎标准：ai/standards/spec-driven-development.ai.yaml

与其他标准的集成

与提交消息集成

在提交消息中引用規格 ID：

feat(auth): implement login feature

Implements SPEC-001 login functionality with OAuth2 support.

Refs: SPEC-001

与 Check-in 标准集成

为規格提交程序码前：

[ ] 規格已批准
[ ] 实作符合規格
[ ] 测试涵蓋驗收标准
[ ] PR 中引用規格 ID

与程序码审查集成

审查者应验证：

[ ] 变更符合已批准的規格
[ ] 没有超出規格的範圍擴張
[ ] 規格驗收标准已达成

範例

✅ 良好做法

# SPEC-001 新增 OAuth2 登入

## 摘要
新增 Google OAuth2 登入，讓使用者可以用 Google 帳号登入。

## 动机
- 減少新使用者註冊的摩擦
- 不储存密码以提升安全性

## 驗收标准
- [ ] 使用者可以点擊「使用 Google 登入」按鈕
- [ ] 新使用者自动註冊
- [ ] 現有使用者可連結 Google 帳号

❌ 不良做法

# 新增登入

新增登入功能。

缺少規格 ID
没有动机说明
没有驗收标准

常見 SDD 工具

| 工具 | 说明 | 指令範例 | |------|------|----------| | OpenSpec | 規格管理 | /openspec proposal, /openspec approve | | Spec Kit | 輕量規格追蹤 | /spec create, /spec close | | 手动 | 無工具，文件式 | 手动建立 specs/SPEC-XXX.md |

最佳实踐

建议做法

✅ 保持規格專注且原子化（一个規格一个变更）
✅ 包含清晰的驗收标准
✅ 將規格連結到实作 PR
✅ 完成後封存規格

避免做法

❌ 在規格批准前開始写程序
❌ 实作期间修改範圍但不更新規格
❌ 讓規格处於懸置状态（务必关閉或封存）
❌ 跳過验证步骤

设置偵测

此技能支援项目特定设置。

偵测順序

检查工作區是否有 SDD 工具（OpenSpec、Spec Kit 等）
检查 CONTRIBUTING.md 中的規格工作流程文件
若無找到，预设使用手动文件式工作流程

首次设置

若未找到设置：

詢問使用者：「此项目尚未设置 SDD。您要设置 specs 目录嗎？」
建议在 CONTRIBUTING.md 中记录：

## 規格驅动开发

我們对所有非瑣碎的变更使用規格驅动开发。

### 流程
1. 在 `specs/` 目录建立提案
2. 取得团队負責人批准
3. 实作并在 PR 中引用規格
4. 合併後封存規格

### 規格範本
請參考 `specs/TEMPLATE.md`

版本历史

| 版本 | 日期 | 变更 | |------|------|------| | 1.0.0 | 2025-12-30 | 初始發布 |

授权

此技能採用 CC BY 4.0 授权。

來源: universal-dev-standards