AI规范编程：从SDD理念到Spec-Kit落地实践

文章目录一、SDD 诞生的背景AI 时代软件工程的范式变革2.1、传统开发范式的痛点2.2、SDD 的核心定义与价值2.3、SDD 的发展历程二、SDD 工具对比分析Spec-Kit、OpenSpec 与 Superpowers2.1 核心定位与设计理念对比2.2 技术架构与功能特性对比2.3 选型建议根据场景选择合适的 SDD 工具三、Spec-Kit 架构深度解读规范驱动的工程化基石3.1 核心特性规范驱动的全流程管控3.1.1 可执行规范 (Executable Specifications)3.1.2 门控流程 (Gated Workflow)3.1.3 动态宪法机制 (Dynamic Constitution)3.2 核心概念构建规范驱动的思维模型3.2.1 单一事实来源 (Single Source of Truth)3.2.2 意图优先 (Intent-First)3.2.3 人机协同 (Human-AI Collaboration)3.3 技术架构分层设计与组件化实现3.3.1 核心引擎层 (Core Engine)3.3.2 工具集成层 (Tool Integration Layer)3.3.3 命令行界面层 (CLI Layer)3.3.4 扩展层 (Extension Layer)四、Spec-Kit安装Step1安装核心依赖 uvStep2安装 Spec-Kit (Specify CLI)Step3初始化项目Step4验证与开始使用五、Spec-Kit案例实践Step1Spec-Kit 初始化Step2Constitution - 生成项目宪法Step3Specify - 生成功能规格Step4Plan - 生成技术规划Step4Tasks - 拆解任务Step5Implement - 生成代码实现Spec-Kit经验总结一、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 与 Superpowers2.1 核心定位与设计理念对比对比维度Spec-Kit (GitHub)OpenSpecSuperpowers核心定位“蓝图派”从零开始的完整规划适合 0-1 项目“园丁派”现有系统的增量改造适合 1-n 项目“全流程管家”从需求到交付的完整开发流程管理设计理念“规格即法律”(固定规则体系)强调门控流程和详尽文档“OPSX 灵活工作流”(动作而非阶段)围绕变更提案流程简洁“测试优先证据驱动”系统化降低复杂度哲学基础深度规范驱动追求流程完整性和可控性轻量级规范驱动追求快速迭代和极简主义方法论驱动 (技能系统)强调心理学引导 AI 行为适用团队组织完善、有严格流程合规的大型团队敏捷团队、初创企业、需要快速迭代的项目独立开发者、质量导向团队、AI 代理密集型项目2.2 技术架构与功能特性对比对比维度Spec-Kit (GitHub)OpenSpecSuperpowers技术栈Python (uv 包管理器)CLI 驱动支持多平台TypeScript (npm)Web UICLI 双模式轻量级MarkdownJavaScript 插件编辑器集成跨平台核心流程7 步线性流程spec→plan→tasks→implement→verify→document→evolve3 步增量流程propose→apply→archive管理规范增量5 步闭环流程brainstorm→isolate→plan→TDD→review规范形式结构化 Markdown支持复杂场景和约束条件极简 YAML聚焦变更点最小化文档量自然语言 测试用例强调可执行性和证据验证AI 集成内置支持 15AI 编码助手统一接口管理专注 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 的核心是‌七阶段门控开发流程‌每一阶段均对应可验证的工程产出形成从需求到实现的强约束链。各环节严格顺序执行未经前一阶段验收不得进入下一阶段。阶段编号阶段名称核心目标产出文件关键约束1Constitution建立项目宪法与技术红线constitution.md定义禁止项、审批项、允许范围需团队共识签署2Specify将自然语言需求转化为形式化规范spec.md必须使用结构化语义模板禁止模糊表述3Clarify消除歧义确认边界与例外clarification.md所有模糊点必须由产品/架构师签字确认4Plan设计技术实现路径与架构选型plan.md必须包含技术栈、数据流、依赖图、风险评估5Tasks拆解为可执行、可追踪的开发任务tasks.md每项任务需绑定负责人、预估工时、验收标准6Analyze验证规范一致性与变更影响自动化分析报告形式化验证通过率 ≥95%影响范围必须可视化7Implement由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/Githubhttps://github.com/github/spec-kitStep1安装核心依赖 uvSpec-Kit 基于Python 开发依赖 uv 作为包管理器和工具运行器因为它比传统的 pip/venv 更快且更易于管理。# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 验证安装 uv --versionStep2安装 Spec-Kit (Specify CLI)# 使用 uv 安装 Spec-Kit uv tool install specify-cli --from githttps://github.com/github/spec-kit.git # 验证安装 specify --versionStep3初始化项目初始化现有项目# 在当前目录初始化 specify init . # 指定特定的 AI 助手 specify init . --ai opencode创建并初始化新项目:# 基本初始化 specify init project01 # 指定特定的 AI 助手 specify init project01 --ai claude # 指定脚本类型 (Mac/Linux默认shWindows默认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 specsStep4验证与开始使用初始化完成后打开你的 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 项目文件为中型颗粒度需求。本次改造需求存在一定复杂度。Step1Spec-Kit 初始化进入项目根目录执行如下命令生成 Spec-Kit 工程契约链specify init .执行后会生成.specify契约链文件目录Step2Constitution - 生成项目宪法执行如下命令生成 “项目宪法”例如项目约定、技术栈与约束、开发工作流等确保后续规范和代码实现的一致性和可控性。# 创建项目宪法 /speckit.constitution # 创建项目宪法补充指定中文约束否则默认生成 英文 内容 /speckit.constitution 补充1条规则所有规范文档使用中文描述执行后将会生成.specify/memory/constitution.md文件内容如下Step3Specify - 生成功能规格执行如下命令 填写功能需求描述生成 “功能规格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文件内容如下Step4Plan - 生成技术规划执行如下命令生成 “技术规划”/speckit.plan执行后将会生成.specify/plans/001-project-structure-refactor/plan.md文件内容如下Step4Tasks - 拆解任务执行如下命令生成 “任务清单”/speckit.tasks执行后将会生成.specify/tasks/001-project-structure-refactor/tasks.md文件内容如下Step5Implement - 生成代码实现执行如下命令将会按照拆解任务tasks.md进行 “代码生成”/speckit.implementAgent会按照任务清单tasks.md逐个实现每个任务完成后自动对照requirements.md检查。所有任务完成后人工进行Review验收确认符合要求后合并代码当前该PR已合入 XXL-API master分支交付符合预期。Spec-Kit经验总结项目宪法要保持稳定constitution.md一旦确定不要频繁修改确保所有参与者都遵循统一规则规格只写做什么不写怎么做SPEC.md避免过度约束实现细节给AI留出技术优化空间不要跳过澄清和检查阶段这两个阶段是减少返工的关键提前发现模糊点和偏差比后期修改成本低很多原文地址https://www.xuxueli.com/blog/?blogai/speckit