一、为什么需要规范驱动开发最近市场也是越来越卷了在项目中也是要求用AI开发我相信用过AI开发的小伙伴都遇到了AI越写越乱越写越成屎山。用 AI 写代码最让人头疼的不是工具不好用而是你想要的和 AI 做出来的根本不是一回事。你让它加个登录功能它给你整了一套 OAuth2 JWT 微服务架构你让它改个按钮颜色它把整个样式系统重构了。其根源在于需求没说清楚AI 就开始自由发挥。规范驱动开发的核心思路很简单先说清楚要做什么再让 AI 动手。 官方说法叫 “Agree before you build”但我觉得更叫提示词优化/提示词工程最近也一直有一个名词叫 SDD 驱动开发那么什么是SDDSDD 全称 Spec-Driven Development (规范驱动开发)它指的是一种开发方法先把“要做什么、为什么做、做到什么程度算完成”写成结构化、可审查、可验证的规范再让 AI 或人按规范去实现和验收。这里通常都是围绕着一个Spec。那Spec 是什么Spec是“需求文档”“目标与背景”“验收标准”“接口契约”“边界条件”“技术方案”“任务清单”“验证方式” 等等可以理解为一个目录下包含上述的文档。而目前开源的SDD开发框架最火热的就是OpenSpec 和 Spec-kit两大AI驱动框架.在 OpenSpec 里则落在了proposal.mddesign.mdtasks.md在 Spec-Kit 里则落在了constitution.mdspec.mdplan.mdtasks.md二、OpenSpec轻量级规范驱动开发2.1 核心结构openspec/ ├── specs/# 已实现的功能真相之源└── changes/# 待实现的提案└──[变更名]/ ├── proposal.md# 为什么要做、做什么├── design.md# 技术方案├── tasks.md# 实施清单└── specs/# 规范增量补丁两个文件夹的分离是关键设计specs/ 存放当前系统的真实状态changes/ 存放提议的更新。这种设计让状态和变更分开管理在修改现有功能或跨多个规范时尤其有效。其次就是config.yml 的作用一次性告诉 AI 这些项目级上下文之后每次生成规范、设计或任务时AI 都会自动带上这些信息不需要你反复在对话中强调OpenSpec 的配置文件位于 openspec/config.yaml。它扮演着整个项目的“世界观”和“全局标准层”角色AI 编码助手在执行任何具体任务前都会先读取这个文件以确保编写的代码符合团队规范。如何使用你可以告诉AI让它编写config.yaml加入你项目的架构编码风格规范等。config.yaml 中核心字段解析字段作用schema设置默认工作流 schema免去每次命令都输入 --schema spec-drivencontext注入项目上下文AI 在所有制品生成时都会看到你的技术栈和约定rules按制品类型添加规则比如 proposal 必须包含回滚方案specs 必须用 Given/When/Then 格式operations为 apply 和 archive 操作提供建议性指引不约束制品内容只影响 AI 执行这些操作时的行为githubCopilot控制是否生成 GitHub Copilot 云端 Agent 相关文件2.2 安装前置要求Node.js ≥ 20.19.0# 全局安装npminstall-gfission-ai/openspeclatest#AI安装-前提是手动安装好Node.js ≥ 20.19.0请你帮我安装好OpenSpec以下是OpenSpec的项目连接地址https://github.com/Fission-AI/OpenSpec# 验证安装openspec--version2.3 项目初始化# 切换到你的项目下cdyour-project#执行就会生成2.1 核心结构文件openspec init初始化是交互式的会询问你要配置哪些 AI 工具Claude Code、Cursor、GitHub Copilot 等。也可以用 --tools 参数跳过交互# 指定配置 Claude Code 和 Cursoropenspec init--toolsclaude,cursor# 配置所有支持的工具openspec init--toolsall# 跳过工具配置openspec init--toolsnone# 执行openspec initOpenSpec 会自动检测项目中已有的工具目录如 .claude/、.cursor/并预选2.4 核心工作流OpenSpec 的核心工作流非常简洁三阶段即可跑通阶段命令功能规划/opsx:propose创建变更提案一次性生成全部规划文档实施/opsx:apply按任务清单实现代码归档/opsx:archive归档已完成变更更新主规范除了核心三命令还有几个实用命令命令用途/opsx:explore探索想法、调研问题只读你可以和AI讨论你的需求看下AI的想法/opsx:new创建新变更逐个生成工件只是一个空的changs一般搭配/opsx:continue 命令一起使用可以让你逐步审核每个文件/opsx:ff一次性生成所有规划文档/opsx:verify验证实现与规范的一致性只读加上以上命令就可以实现Expanded模式的流程开发new - continue -apply -verify-archive五步实现更精准的控制CLI 终端命令方面openspec list 列出进行中的变更openspec show [item] 查看详情openspec validate [item] 验证格式openspec archive --yes 非交互式归档2.5 在项目中的实际使用命令流程以下是我正常开发迭代写需求的流程使用/opsx:explore 探索想法跟需求使用/opsx:propose 创建变更提案一次性生成全部规划文档简单查看以下提按的内容proposal.mddesign.md task.md使用/opsx:apply 按任务清单实现代码使用/opsx:verify 验证实现与规范的一致性最后/opsx:archive 归档已完成变更更新主规范当然如果不放心怕AI编写代码有偏差想多看几眼把控细节。可以使用/opsx:new 跟 /opsx:continue 一起使用具体流程如下2.6 在项目中的实际使用场景场景一存量项目添加新功能。 这是 OpenSpec 最擅长的场景。在现有代码库中执行 openspec initOpenSpec 会扫描现有代码和规范理解当前系统能力然后生成增量变更提案。不需要重构现有代码可以逐步引入。场景二修复 Bug。 先用 /opsx:propose 描述 Bug 现象和预期行为AI 会读取现有 specs 理解系统然后生成修复方案和任务清单再用 /opsx:apply 实施。场景三新项目从零开始。 虽然 OpenSpec 更擅长存量项目但也支持全新项目。从第一个功能开始就用 /opsx:propose 建立规范体系以及config.yml 文件后后续所有开发都基于不断更新的 specs/ 展开。OpenSpec 兼顾存量项目Brownfield和新建项目Greenfield但它的设计哲学更偏向“流动而非僵化、迭代而非瀑布三、Spec-Kit团队级规范驱动开发3.1 Spec-Kit的核心Spec-Kit 的核心工作流是Specify → Plan → Tasks → Implement → Converge。每个阶段生成一个 Markdown 工件文件作为下一个阶段的输入给 AI 提供结构化的上下文而不是零散的 promptSpec-Kit 的实现包含三个核心组件specify CLI初始化和管理以规范驱动的项目Markdown 工件文件constitution.md、spec.md、plan.md、tasks.md斜杠命令/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement3.2 Spec-Kit的安装Spec-Kit 的安装依赖 uvPython 包管理器# 先安装 uv如果还没有curl-LsSfhttps://astral.sh/uv/install.sh|sh# 安装 Specify CLI替换 vX.Y.Z 为最新版本号uv toolinstallspecify-cli--fromgithttps://github.com/github/spec-kit.gitvX.Y.Z# 也可以从 PyPI 安装uv toolinstallspecify-cli# AI安装请帮我群居安装spec-kitgithub地址为https://github.com/github/spec-kit验证安装specify checkspecify check 会检查系统中已安装的工具包括 git、claude、cursor-agent 等3.3 项目初始化# 创建新项目并指定 AI 集成specify init my-project--integrationcopilot# 在当前目录初始化specify init.--integrationclaude# 非交互模式适合 CI 环境specify init my-project --non-interactive--integrationclaude3.4 AI工作流程的使用Spec-Kit 采用严格的七步工作流每一步生成一个文件共同构成功能的“完整规范体系”。阶段命令用途项目原则/speckit:constitution创建项目治理原则每个项目一次规范/speckit:specify描述要构建什么关注 what 和 why盲点/speckit:clarcify需求有疑问时澄清规划/speckit:plan制定技术实现方案提供技术栈和架构选择任务分解/speckit:tasks将技术方案分解为可执行任务清单实施/speckit:implement按任务清单逐步实现代码收敛/speckit:converge对照规范验证实现是否一致此外还有辅助命令: /speckit:analyze检查遗漏、/speckit:checklist生成质量检查清单3.5 扩展可以通过CMD或者PowerShell 输入列出可安装的扩展命令specify extension search “”安装扩展 specify extension add卸载扩展: specify extension remove列出已安装的扩展specify extension list查看扩展详情 specify extension info更新扩展 specify extension update []启用扩展的 hooks specify extension enable禁用扩展的 hooks specify extension disable主题皮肤等列出可安装的Presets / 主题命令specify preset search “”安装预设specify preset add [preset_id]列出已安装的预设specify preset list移除预设specify preset remove查看预设详情 specify preset info对此我们可以通过specify preset add Lean来安装精简版的五命令模式。Spec-Kit 其实默认是Full的九命令模式如下图五命令模式流程为 /speckit:constitution - /speckit:specify - /speckit:plan - /speckit:tasks - /speckit:implement九命令模式流程为/speckit:constitution - /speckit:specify - /speckit:clarcify - /speckit:plan - /speckit:tasks-/speckit:taskstoissues - /speckit:analyze - /speckit:implement - /speckit:checklist3.6 constitution其实在使用 Spec-Kit 使用得好不好好不好用其关键在于constitution宪法/规约写得好不好OpenSpec 其实也是一样的道理 config.yml 写得好那么返工就少问题也就少。那么如何写好constitution宪法/规约呢 我总结提出了几个点标明 行为边界/职责领域等不让AI越界操作禁止项写死每次执行都参考宪法约束每步可纠错可控误差不累计不雪崩代码复用强制写明必须要复用的情况避免给重复造轮子好的 constitution宪法/规约或者 OpenSpec的 config.yml 应该遵循六大写作原则禁止项 允许项 限制比授权更有约束力具体 抽象函数Function 60 而非一直写下去同时需要复用开篇定义范围禁止AI擅自扩展每条附加根本原因让AI知道为什么这样才会真正遵守例如代码示例/逻辑依据有版本才能有迭代有需求才会有验收规则限制等最好控制在2000字以下避免上下文过长导致AI遗忘。四类核心规则代码复用策略AI天生喜欢写而不是度 写读项目实际架构不明确的禁止防止AI擅自引入特别是Router-Service模式禁止的代码模式/规则不让AI怎么写方法函数必须控制在多少。术语精确性确保AI理解词汇不产生歧义误解3.7 项目中的实际使用场景场景一大型新项目从零开始Spec-Kit 的完整工作流保证了从项目原则到最终实现的完整覆盖。每一步的产出都是持久化的 Markdown 文件存储在 Git 仓库中可以像代码一样进行版本管理和代码审查。场景二团队协作与代码审查规范文件spec.md、plan.md、tasks.md可以随代码一起提交到功能分支。审查者可以同时看到“你要构建什么”和“你是怎么构建的”。Spec-Kit 还支持通过环境变量 SPECIFY_FEATURE 跟踪当前开发的功能在 Git 工作流中会根据分支名自动推断。场景三多 Agent 自由切换Spec-Kit 支持 38 种 AI 编码代理集成Copilot、Claude、Cursor、Gemini、Windsurf 等同一个项目可以在不同 Agent 之间自由切换底层的工件文件是共享的场景四存量项目逐步引入对于已有代码库使用 specify init . --here 就地初始化然后从下一个新功能开始使用 SDD 流程。不需要重构现有代码可以逐步引入。四、Spec-Kit 与 OpenSpec 的选型对比4.1 全方位对比维度Spec-KitOpenSpec定位重型、流程严谨、GitHub 官方轻量、灵活、社区驱动安装uv tool install 需要python环境npm install -g前置依赖Python 3.11 / uvNode.js ≥ 20.19.0核心工作流6-7 步完整流水线3 步propose → apply → archive适用场景新项目、大型团队、强规范需求存量项目迭代、小团队、敏捷开发规范增量以完整规范为主Delta Spec 增量变更学习成本中高低4.2 工作流程对比如下图总结选型建议新项目、大型项目、需要完整开发流程 → Spec-Kit小项目、存量项目迭代 → OpenSpec
