一、SDD 誕生的背景：AI 時代軟件工程的範式變革

2.1、傳統開發範式的痛點

在 AI 編碼助手（如 GitHub Copilot、Claude Code、Cursor）普及之前，軟件開發遵循 "代碼優先、文檔次之" 的模式，面臨三大核心痛點：

痛點	具體表現	影響
意圖與實現鴻溝	需求文檔模糊、變更頻繁，代碼與文檔長期脫節	溝通成本高，重構風險大，維護困難
協作效率低下	團隊成員對需求理解不一致，缺乏統一 "事實來源"	重複工作多，衝突頻繁，交付週期長
質量保障滯後	測試在編碼後進行，缺陷發現晚，修復成本高	產品穩定性差，用戶體驗受損

隨著 AI 編碼工具的普及，這些問題被進一步放大：AI 能快速生成代碼，但缺乏對整體系統架構和業務邏輯的理解，容易產生 "局部正確但全局錯誤" 的代碼；同時，開發者過度依賴 AI 提示詞，導致代碼質量參差不齊，可維護性急劇下降。

2.2、SDD 的核心定義與價值

規範驅動開發 (Spec-Driven Development, SDD) 是生成式 AI 時代下適配工程化開發的新型軟件開發方法論，核心是先由技術人員定義簡潔、可測試、形式化的系統規格說明 (Spec)，將其作為人、團隊與 AI 之間的 "動態契約" 和開發過程的唯一事實來源。

SDD 帶來三大革命性轉變：

• 權力反轉：將軟件開發的 "單一事實來源" 從易變的代碼轉移到人類意圖的直接表達 —— 規範本身
• 流程重構：從 "編碼→測試→修復→文檔" 轉變為 "規範→設計→實現→驗證" 的線性流程
• 人機協同：規範成為 AI 的 "操作手冊"，消除 AI 猜測意圖的成本，提升代碼生成質量

2.3、SDD 的發展歷程

SDD 並非全新概念，而是在傳統軟件工程理論基礎上的進化：

• 早期起源：可追溯至 20 世紀 80 年代的 "契約式設計"(Design by Contract) 和 "測試驅動開發"(TDD) 理念
• 現代演進：2025 年，GitHub 發佈 Spec-Kit 工具，正式將 SDD 從理論推向實踐
• 生態成熟：2026 年，OpenSpec、Superpowers 等工具相繼出現，形成完整的 SDD 工具生態
• 行業認可：微軟、亞馬遜等科技巨頭開始在內部推廣 SDD 方法論，將其納入官方培訓課程

二、SDD 工具對比分析：Spec-Kit、OpenSpec 與 Superpowers

2.1 核心定位與設計理念對比

對比維度	Spec-Kit (GitHub)	OpenSpec	Superpowers
核心定位	"藍圖派"：從零開始的完整規劃，適合 0-1 項目	"園丁派"：現有系統的增量改造，適合 1-n 項目	"全流程管家"：從需求到交付的完整開發流程管理
設計理念	"規格即法律"(固定規則體系)，強調門控流程和詳盡文檔	"OPSX 靈活工作流"(動作而非階段)，圍繞變更提案，流程簡潔	"測試優先，證據驅動"，系統化降低複雜度
哲學基礎	深度規範驅動，追求流程完整性和可控性	輕量級規範驅動，追求快速迭代和極簡主義	方法論驅動 (技能系統)，強調心理學引導 AI 行為
適用團隊	組織完善、有嚴格流程合規的大型團隊	敏捷團隊、初創企業、需要快速迭代的項目	獨立開發者、質量導向團隊、AI 代理密集型項目

2.2 技術架構與功能特性對比

對比維度	Spec-Kit (GitHub)	OpenSpec	Superpowers
技術棧	Python (uv 包管理器)，CLI 驅動，支持多平臺	TypeScript (npm)，Web UI+CLI 雙模式，輕量級	Markdown+JavaScript 插件，編輯器集成，跨平臺
核心流程	7 步線性流程：spec→plan→tasks→implement→verify→document→evolve	3 步增量流程：propose→apply→archive，管理規範增量	5 步閉環流程：brainstorm→isolate→plan→TDD→review
規範形式	結構化 Markdown，支持複雜場景和約束條件	極簡 YAML，聚焦變更點，最小化文檔量	自然語言 + 測試用例，強調可執行性和證據驗證
AI 集成	內置支持 15+AI 編碼助手，統一接口管理	專注 Claude 和 Copilot，強調輕量級集成	深度集成 GitHub Copilot，支持蘇格拉底式對話
變更管理	動態憲法機制，規範版本化，完整審計追蹤	變更隔離，共識驅動，風險控制優先	微任務隔離，自動衝突解決，快速回滾機制
學習曲線	陡峭，適合有流程意識的團隊	平緩，適合快速上手的場景	中等，需要理解測試驅動理念

2.3 選型建議：根據場景選擇合適的 SDD 工具

針對不同場景，建議結合項目類型、團隊規模、規範複雜度等多維度因素，綜合評估選擇最適合的 SDD 工具：

• 選擇Spec-Kit：適合新項目、企業級項目，強調流程規範和架構控制的團隊，尤其是企業級項目和跨團隊協作場景。
• 選擇OpenSpec：適合遺留系統改造、兼容性要求高的項目，強調快速迭代和風險控制的敏捷團隊。
• 選擇Superpowers：適合質量優先的團隊，強調自動化和測試驅動開發的項目，尤其適合原型開發和AI密集型項目。

決策因素	選擇 Spec-Kit	選擇 OpenSpec	選擇 Superpowers
項目類型	全新項目、企業級項目	增量變更、遺留系統	原型開發、AI 密集型
團隊規模	10 人以上、跨團隊	3-10 人、敏捷團隊	1-3 人、獨立開發者
規範複雜度	高 (需要詳細約束)	低 (聚焦變更點)	中 (強調測試用例)
流程要求	嚴格 (門控機制)	靈活 (增量流程)	自動化 (全流程)
學習成本	高 (需要培訓)	低 (快速上手)	中 (理解測試驅動)

三、Spec-Kit 架構深度解讀：規範驅動的工程化基石

3.1 核心特性：規範驅動的全流程管控

3.1.1 可執行規範 (Executable Specifications)

Spec-Kit 的核心創新在於將規範從靜態文檔轉變為可執行的開發指令：

• 規範採用結構化 Markdown 格式，包含需求、場景、約束、驗收標準等要素
• 規範可直接驅動 AI 生成代碼、測試用例和文檔，無需人工翻譯
• 規範變更自動觸發代碼和測試的更新，確保一致性

3.1.2 門控流程 (Gated Workflow)

Spec-Kit 的核心是‌七階段門控開發流程‌，每一階段均對應可驗證的工程產出，形成從需求到實現的強約束鏈。各環節嚴格順序執行，未經前一階段驗收，不得進入下一階段。

階段編號	階段名稱	核心目標	產出文件	關鍵約束
1	Constitution	建立項目憲法與技術紅線	constitution.md	定義禁止項、審批項、允許範圍；需團隊共識簽署
2	Specify	將自然語言需求轉化為形式化規範	spec.md	必須使用結構化語義模板，禁止模糊表述
3	Clarify	消除歧義，確認邊界與例外	clarification.md	所有模糊點必須由產品/架構師簽字確認
4	Plan	設計技術實現路徑與架構選型	plan.md	必須包含技術棧、數據流、依賴圖、風險評估
5	Tasks	拆解為可執行、可追蹤的開發任務	tasks.md	每項任務需綁定負責人、預估工時、驗收標準
6	Analyze	驗證規範一致性與變更影響	自動化分析報告	形式化驗證通過率 ≥95%，影響範圍必須可視化
7	Implement	由AI生成代碼並提交審查	生成代碼 + 測試用例	代碼必須與 spec.md 保持雙向追溯，禁止手動覆蓋

所有階段均通過 specify CLI 工具驅動，每個環節的交付物自動納入版本控制，形成‌可審計、可回溯、可驗證‌的工程契約鏈。
任意環節未通過門控檢查，系統將阻斷後續流程，確保“規範即權威”。

3.1.3 動態憲法機制 (Dynamic Constitution)

Spec-Kit 引入項目憲法 (Project Constitution) 概念，作為項目的 "最高法律"：

• 憲法定義項目的架構原則、編碼標準、安全規範、測試策略等核心規則
• 所有規範和代碼必須符合憲法要求，憲法合規檢查器自動驗證
• 憲法支持版本化管理，變更需要團隊共識，確保項目方向的一致性

3.2 核心概念：構建規範驅動的思維模型

3.2.1 單一事實來源 (Single Source of Truth)

Spec-Kit 的核心哲學是規範即唯一事實來源，所有開發活動都圍繞規範展開：

• 規範是需求、設計、實現、測試、文檔的唯一依據
• 消除代碼與文檔、設計與實現之間的不一致性
• 團隊成員通過規範達成共識，減少溝通成本

3.2.2 意圖優先 (Intent-First)

Spec-Kit 強調先明確意圖，再考慮實現，與傳統 "實現優先" 模式形成鮮明對比：

• 規範階段專注於業務需求和用戶價值，不涉及技術細節
• 計劃階段才將業務意圖轉換為技術實現方案
• 避免過早陷入技術選型，確保解決方案符合業務目標

3.2.3 人機協同 (Human-AI Collaboration)

Spec-Kit 重新定義了開發者與 AI 的協作模式，從 "AI 輔助編碼" 升級為 "規範驅動 AI 開發"：

• 開發者負責定義清晰、精確的規範，AI 負責執行實現細節
• 規範成為開發者控制 AI 行為的 "護欄"，確保代碼質量和一致性
• 開發者從繁瑣的編碼工作中解放出來，專注於架構設計和業務邏輯

3.3 技術架構：分層設計與組件化實現

Spec-Kit 採用模塊化、可擴展的架構設計，核心分為四層，從底層到上層依次為：

3.3.1 核心引擎層 (Core Engine)

• 規範解析器 (Spec Parser)：解析結構化 Markdown 規範，提取需求、約束、場景等關鍵信息
• 憲法合規檢查器 (Constitutional Compliance Checker)：確保所有規範符合項目憲法 (Constitution) 定義的架構原則和編碼標準
• 任務生成器 (Task Generator)：將規範和計劃轉換為 AI 可執行的原子任務，支持任務依賴和優先級管理
• 驗證引擎 (Validation Engine)：執行自動化測試，驗證代碼實現是否符合規範要求

3.3.2 工具集成層 (Tool Integration Layer)

• AI 代理適配器 (AI Agent Adapter)：提供統一接口，支持 15 + 主流 AI 編碼助手，如 Claude Code、GitHub Copilot、Amazon Q 等
• 版本控制集成器 (VCS Integrator)：與 Git 無縫集成，自動管理規範和代碼的版本歷史，支持分支策略和合並衝突解決
• IDE 插件 (IDE Plugins)：提供 VS Code、IntelliJ 等主流編輯器的集成支持，實時規範檢查和提示

3.3.3 命令行界面層 (CLI Layer)

• specify CLI：核心命令行工具，提供 init、spec、plan、tasks、implement 等 7 個核心命令，引導開發流程
• 交互式終端 (Interactive Terminal)：支持自然語言交互，簡化規範編寫和任務執行流程
• 報告生成器 (Report Generator)：生成規範合規報告、測試覆蓋率報告、代碼質量報告等

3.3.4 擴展層 (Extension Layer)

• 模板系統 (Template System)：提供規範模板、計劃模板、任務模板，支持自定義擴展
• 插件框架 (Plugin Framework)：允許開發者編寫自定義插件，擴展 Spec-Kit 功能，如集成特定測試工具、部署流程等
• 自定義規則引擎 (Custom Rule Engine)：支持添加項目特定的合規規則，如安全標準、性能指標等

四、Spec-Kit安裝

Spec-Kit 是 GitHub 官方開源的‌規格驅動開發（Spec-Driven Development, SDD）‌工具包。 它通過標準化的工作流（Specify → Plan → Tasks → Implement），幫助開發者利用 AI 編碼助手（如 claude、opencode 等）構建高質量軟件，解決“氛圍編碼”（Vibe Coding）導致的代碼質量不一和流程缺失問題。

• 官網：https://github.github.com/spec-kit/
• Github：https://github.com/github/spec-kit

Step1：安裝核心依賴 uv

Spec-Kit 基於Python 開發，依賴 uv 作為包管理器和工具運行器，因為它比傳統的 pip/venv 更快且更易於管理。

# 安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 驗證安裝
uv --version

Step2：安裝 Spec-Kit (Specify CLI)

# 使用 uv 安裝 Spec-Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 驗證安裝
specify --version

Step3：初始化項目

初始化現有項目：

# 在當前目錄初始化
specify init .

# 指定特定的 AI 助手
specify init . --ai opencode

創建並初始化新項目:

# 基本初始化
specify init project01

# 指定特定的 AI 助手
specify init project01 --ai claude

# 指定腳本類型 (Mac/Linux默認sh，Windows默認ps，也可強制指定)
specify init project01 --script sh

‌初始化過程中的交互提示：‌

• ‌選擇 AI Agent‌：如果你未在命令行指定 --ai，它會提示你選擇已檢測到的 AI 工具。
• ‌選擇腳本類型‌：Mac/Linux 用戶通常選擇 sh (Bash)；Windows 用戶通常選擇 ps (PowerShell)。
• ‌文件合併‌：如果目錄下已有文件，Spec-Kit 會嘗試合併或提示覆蓋，請根據提示操作。
• 安全配置（重要）：初始化後，AI 助手可能會在項目根目錄生成包含 API Key 或敏感信息的文件夾（例如 .opencode/, .claude/ 等）。務必將這些文件夾加入 .gitignore 防止敏感信息洩露：

# 編輯 .gitignore 文件，添加以下內容（根據你使用的 AI 工具調整）
.opencode
.omo
.claude
.specify
specs

Step4：驗證與開始使用

初始化完成後，打開你的 AI 編碼助手（如在終端輸入 opencode、claude 啟動對應編程工具，或在 VS Code/Cursor 中打開項目）。

檢查是否可用以下 Slash Commands（斜槓命令）：

命令	功能描述	階段
/speckit.constitution [必須]	建立項目原則和非談判性準則	0. 準備
/speckit.specify [必須]	定義“做什麼”和“為什麼”，生成規格文檔	1. 規格化
/speckit.clarify	在規劃前通過提問澄清模糊需求	1.5 澄清
/speckit.plan [必須]	基於規格和技術棧生成技術實施計劃	2. 規劃
/speckit.tasks [必須]	將計劃分解為可執行的、有序的任務列表	3. 任務分解
/speckit.analyze	分析任務一致性和覆蓋率	3.5 分析
/speckit.implement [必須]	執行任務，生成代碼和測試	4. 實現

‌典型工作流示例：‌

• /speckit.constitution - 設定項目原則（例如：代碼質量、測試標準）
• /speckit.specify - 描述你的需求（例如：“創建一個用戶註冊系統...”）
• /speckit.plan - 制定實施計劃
• /speckit.tasks - 生成待辦任務
• /speckit.implement - AI編寫代碼

問題：如何指定Spec文檔的語言和風格 ？

• 打開 .specify/memory/constitution.md。在文件中添加或修改以下規則（建議放在文件頂部或 "Communication" 部分）

## Communication Guidelines
- **Language**: All specifications, plans, tasks, code comments, and commit messages MUST be written in **Simplified Chinese (zh-CN); unless explicitly requested otherwise.
- **Tone**: Professional, concise, and direct.

五、Spec-Kit案例實踐

我們以 "XXL-API 項目代碼重構" 為例，展示 Spec-Kit 的完整實踐流程。

本次改造項目為正式開源項目，對代碼規範性與質量存在要求；另外，該重構需求涉及 “9個功能模塊”、“前後端代碼邏輯修改”，累計需要修改 130+ 項目文件，為中型顆粒度需求。本次改造需求存在一定複雜度。

Step1：Spec-Kit 初始化

進入項目根目錄，執行如下命令生成 Spec-Kit 工程契約鏈：

specify init .

執行後，會生成 .specify 契約鏈文件目錄：

Step2：Constitution - 生成項目憲法

執行如下命令生成 “項目憲法”（例如：項目約定、技術棧與約束、開發工作流等），確保後續規範和代碼實現的一致性和可控性。

# 創建項目憲法
/speckit.constitution 
 
# 創建項目憲法，補充指定中文約束（否則默認生成 英文 內容）
/speckit.constitution 補充1條規則：所有規範文檔使用中文描述

執行後將會生成 .specify/memory/constitution.md 文件，內容如下：

Step3：Specify - 生成功能規格

執行如下命令 + 填寫功能需求描述，生成 “功能規格（Spec）”：

/speckit.specify  針對XXL-API項目按照如下要求重構：

1、按照下面項目規範結構，重構重構項目目錄結構：

xxl-api-admin/src/main/java/com/xxl/api/admin
- /framework: 基礎框架代碼，包含公共的 登錄、util、過濾器等組件。
- /business：業務代碼，包含具體業務模塊的 controller、service、model、mapper 子分層代碼。
  xxl-api-admin/src/main/resources/templates
- /framework：基礎模板，基礎框架實體 對應的。
- /business：業務模板，業務領域實體對應的。
  xxl-api-admin/src/main/resources/mapper
- /framework：基礎Mapper文件，基礎框架實體 對應的。
- /business：業務Mapper文件，業務領域實體對應的。


2、業務代碼分類判斷邏輯：Java代碼部分，當前 com/xxl/api/admin/controller/biz 下除了 UserController 都是 業務領域，保留User相關Java代碼不變，其他按照規範調整。模板部分，當前 help.ftl、index.ftl、login.ftl 屬於基礎框架，其他屬於業務領域；Mapper部分，當前 XxlApiUserMapper.xml 屬於基礎框架，其他屬於業務部分。

執行後將會生成 .specify/specs/001-project-structure-refactor/spec.md 文件，內容如下：

Step4：Plan - 生成技術規劃

執行如下命令，生成 “技術規劃”：

/speckit.plan

執行後將會生成 .specify/plans/001-project-structure-refactor/plan.md 文件，內容如下：

Step4：Tasks - 拆解任務

執行如下命令，生成 “任務清單”：

/speckit.tasks

執行後將會生成 .specify/tasks/001-project-structure-refactor/tasks.md 文件，內容如下：

Step5：Implement - 生成代碼實現

執行如下命令，將會按照拆解任務（tasks.md）進行 “代碼生成”：

/speckit.implement

Agent會按照任務清單（tasks.md）逐個實現，每個任務完成後自動對照requirements.md檢查。

所有任務完成後，人工進行Review驗收，確認符合要求後合併代碼（當前該PR已合入 XXL-API master分支，交付符合預期）。

Spec-Kit經驗總結

• 項目憲法要保持穩定：constitution.md一旦確定不要頻繁修改，確保所有參與者都遵循統一規則
• 規格只寫做什麼不寫怎麼做：SPEC.md避免過度約束實現細節，給AI留出技術優化空間
• 不要跳過澄清和檢查階段：這兩個階段是減少返工的關鍵，提前發現模糊點和偏差比後期修改成本低很多

---

原文地址：https://www.xuxueli.com/blog/?blog=ai/speckit