一、SDD 诞之由：AI 世中软件工之范式更迭

2.1、旧式开之苦痛

于 AI 编助未普之先，软件之开循"码先文后"之式，有三大苦痛：

苦痛	显于	所及
意实之距	需文不明、易变，码文久离	沟通费，重构险，维难
协效低	众员于需解不一，无统"实源"	劳作繁复，龃龉频仍，期程绵长
质保迟滞	測試行於編碼後，缺陥發現晚，修復成本高	產品穩定性劣，用戶體驗受損

夫 AI 编码之器渐行于世，是故前弊益彰：AI 虽能速生代码，然于全系统之构架、业务之脉络，茫昧难明，易生"局部之是而全局之非"之码；复有开发者过恃 AI 之提示，致代码优劣参差，可持守者骤降。

二、二、SDD之核心定义与价值

規範驅動開發 (驱动规格开发，SDD) 乃生成之智械时世，适于工化之新法也。其要，先由技士立简明、可试、形式之系统规约 (Spec)，为人与众、智械间之"变契"，亦为开程唯一之实本。

SDD 带来三变：

• 权转：将软件开发之"一实本"自易迁之码移至人意直表——规约自体。
• 程重构：自"编→试→修→文"转为"规→设→实→验"之线性。
• 人机协：规约成智械之"操典"，除智械测意之费，升码生之质。

2.3、SDD 之演进轨迹

SDD 非为创见，实乃传统软件工程之根基而进：

• 其源可溯至廿世纪八十之"契约式设计"(Design by Contract) 与 "测试驱动开发"(TDD) 之理念
• 其演进于二零二五年，GitHub 发 Spec-Kit 之器，始将 SDD 由理入实
• 其生态渐熟于二零二六年，OpenSpec、Superpowers 等器相继出，成 SDD 之完整器用生态
• 其得行业之认，微软、亚马逊等科技巨擘始在其内推 SDD 之法，纳于官方之训

二、SDD 之器较析：Spec-Kit、OpenSpec 与 Superpowers

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

對比維度	Spec-Kit (GitHub)	OpenSpec	Superpowers
核心定位	"藍圖派"：從零開始之完整規劃，適合 0-1 项目	"園丁派"：現有系統之增量改造，適合 1-n 项目	"全流程管家"：從需求至交付之完整開發流程管理
設計理念	"規格即法律"(固定規則體系)，強調門控流程與詳盡文檔	"OPSX 灵活工作流"(動作而非階段)，圍繞變更提案，流程簡潔	"以测为先，据证而行"，化繁为简，系统其术
哲思之基	深究规范之理，求流程之全，控其可驭。	轻量之规，驱动迅疾之变，崇极简之旨。	方法之理为纲（Skill System），重心理之导以行 AI
适于众人之所共事者	组织周密，流程严谨，合规之巨擘	灵动机队、新创之业、须速更迭之项目	独行之士、质重之众、智械繁集之务

2.2 技术架构与功能特性之比较

较之维度	规格之套 (GitHub)	开篇	超能
技艺之系	Python（uv为包之理），CLI为驱，通于多域	TypeScript（npm为用），Web之UI与CLI为双式，轻而便之	Markdown与JavaScript为插，集于编辑，跨域而通
中核之序	七步之序：spec→plan→tasks→实作→验之→载文→进化	三步之增：propose→apply→archive，理增之规	五步闭环之序：发想→析异→谋策→TDD→察核
規範形制	结构化Markdown，兼支繁复境况与制约之条	至简 YAML，专攻变易，减文至微	自然之语，兼测其例，重其可施，明其验之。
智物相融	内置支持十五以上AI编码助手，统摄接口管理	专攻Claude与Copilot，力倡轻量级集成	深融 GitHub Copilot，具苏格拉底式对谈之能
更变之理	动态宪法机制，规范版本化，完整审计追踪	隔离更迭，共识为纲，控险为先	微任隔离，自解纷争，速退之制
习道之坡	峻峭，宜于有程之众	平缓，适于速成之境	中庸，需明试驱之理

2.3 择器之议：因境选适SDD之具

异境异宜，当合项目之型、众之广、规之繁，综而择至适之SDD器：

• 择Spec-Kit：宜于新构、企级之务，重程范与构控之众，尤宜企级与跨众协之境。
• 择OpenSpec：宜于旧系统改造、兼容性所求甚高之项目，重速迭与风险控制之敏捷团队。
• 择Superpowers：宜于质量为先之团队，重自动化与测试驱动开发之项目，尤宜原型开发与AI密集型项目。

决断之因	择 Spec-Kit	择 OpenSpec	择 Superpowers
项目之属	全新项目、企业级项目	增量变更、旧系统	原型开发、AI密集型
团队之规	十人以上、跨团队	3-10 人、敏捷团队	1-3 人、独立开发者
规范复杂度	高（需详尽约束）	低（专注变易处）	中（重测试之例）
流程要求	严（设门以控）	灵（增积为序）	自（全程自动化）
学成本	高（需训导）	低（速易习）	中（明测试之导）

三、深析Spec-Kit之架构：以规为纲，筑工程之基

3.1 核心之要：以规统之全流程

3.1.1 可行之规 (Executable Specifications)

Spec-Kit之创，在于化规为动：

• 规采结构Markdown，含需、境、制、验诸要
• 规可直驱AI生码、试例与文，无需人译
• 规变自触码与试之更，保其同

3.1.2 门限之序 (Gated Workflow)

Spec-Kit之核在七阶门控开发展程每一阶段皆对应可验之工成，遂成自需至实之强制链。诸节必依序严行，未验前阶，不得入后阶。

阶段编号	阶段名	中心之旨	生產文件	要害之约
一	宪法	立项目宪章，定技术之界	《宪法.md》	定禁项、审项、许范；需众议共署
二	指陈	将自然之语转化为形式之则	spec.md	必用结构之语义模板，禁用模糊之表述
3	阐明	消弭歧义，确认边界与例外	clarification.md	所有模糊之点必由产品/架构师签署确认
4	规划	设计技术之实现路径与架构之选型	plan.md	必具技术栈、数据流、依存图、风险评量
五	任務	分解为可执行、可追踪之开发任务	任事之文也	每项任務必須繫屬於主事者、預計所需時日、以及審定之準則。
六	剖析	验规一意，察变所系	自動化分析報告	形式化验证通过率逾九五，影响之域必可显见
七	施为	由人工智能生成代码并提交审查	生成代码并辅以测试用例	代码须与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)。

《规器之要》重明意旨，而后谋其实现，与旧时"技先于道"者迥异：

• 规范之期，专究事理与用者之益，未涉技之细末
• 及至谋篇，方将意转为技之方略
• 杜早陷于技择，务使术合于事之纲

3.2.3 人机相协（Human-AI Collaboration）

《规器之要》更定人机合契之道，自"技辅于码"进为"规范导技"：

• 术者立明约，AI行其细务
• 约若人御之栏，以保码之质与同
• 使开发者脱于繁冗之码，专攻构架之设与事理之思

3.3 技术构架：分阶设制，组件化以成

Spec-Kit循模块化、可延展之构架，其核分四阶，自下而上为：

3.3.1 核心引擎层 (Core Engine)

• 规范解析器 (Spec Parser)：析结构化 Markdown 规范，擷需求、约束、场景等要义
• 宪法合规检核器 (Constitutional Compliance Checker)：保诸规范合乎项目宪法 (Constitution) 所定之构架原则与码制标准
• 任务生成器 (Task Generator)：将规范与计画化为此AI可施之单元任务，助任务相系与序级之管
• 验核引擎：行自动化之试，察码之实合乎规范之求

3.3.2 工具融会之层

• 智代适接器：设一统之口，容十五以上之主流智编助，若 Claude Code、GitHub Copilot、Amazon Q 等
• 版控融会器：与 Git 无隙相合，自理规范与码之版史，助分支之策与合冲之解
• 编器插件：供 VS Code、IntelliJ 等主流编器之合，实时规检与示

3.3.3 命行界层

• CLI：核要之命行器，具七要令——初立、立规、立计、立务、实之，导开之序
• 交互之终（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）之器也。其以标准化之程（指定→规划→任务→实作），助开发者御AI编码助（如claude、opencode等），构高质软件，解“氛编码”（Vibe Coding）致代码不一、程缺之弊。

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

初，安核心之依，曰 uv

。Spec-Kit 乃以 Python 为基，其依于 uv，为包之管器，亦为器之行器，盖较于旧式之 pip/venv，速且易理也。

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

# 验证安装
uv --version

次，安 Spec-Kit (Specify CLI)

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

# 验证安装
specify --version

三，启项目之始

既启旧有之项目：

# 在当前目录初始化
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 之器：若于命令行未指 --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 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 之全然实践。

是次改造，乃正式开源之项目，于代码之规范与质量，有所求焉；复有重构之需，涉“九个功能模块”、“前后端代码逻辑之变”，累计须改项目文件百三十余，为中等之细粒需求。此改造之需，颇涉繁复。

步骤一：初始化 Spec-Kit

入于项目根目录，行如下之命，以成 Spec-Kit 工程契链：

specify init .

命既行，则生 .specify 契链文件之目录：

步骤二：Constitution - 生成项目宪法

，行此令以成“项目宪法”（若“项目约定”、“技术之栈与约束”、“开发之工作流”等），务使后之规范与代码之实，皆合且可御。

# 创建项目宪法
/speckit.constitution 
 
# 创建项目宪法，补充指定中文约束（否则默认生成 英文 内容）
/speckit.constitution 补充1条规则：所有规范文档使用中文描述

，既行，则生 .specify/memory/constitution.md 文，其文如下：

Step3：指定 - 成功能之规

，行此令，并填功能之需，以成“功能之规（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：规划 - 成技术之规

，行此令，以成“技术之规”：

/speckit.plan

，既行，则生 .specify/plans/001-project-structure-refactor/plan.md 文，其文如下：

第四步：任务拆解

执行下列指令，生成“任务清单”：

/speckit.tasks

执行后当生.specify/tasks/001-project-structure-refactor/tasks.md文件，其内容如下：

第五步：实现——代码生成

执行下列指令，将依循任务拆解（tasks.md）进行“代码生成”：

/speckit.implement

Agent将依循任务清单（tasks.md）逐一实现，每成任务即自对照requirements.md检视。

诸任务毕，人工验之，合乎要求则合代码（今该PR已合入XXL-API master分支，交付无违预期）。

Spec-Kit经验之总结

• 项目宪法宜固：constitution.md一旦既定，勿频更易，务使众皆循一规。
• 规格惟言其用，不述其法。：SPEC.md勿过拘于细，以留机于AI之进。
• 勿越澄察之阶：此二阶段乃减返工之要，早察模糊与偏差，较后期改之费，其廉甚矣。

---

原文出处：https://www.xuxueli.com/blog/?blog=ai/speckit