【规范驱动开发】OpenSpec简介

SDDSpec-Driven Development规范驱动开发是一套研发思想先定规范、再写代码。开发前把需求、接口、架构、校验规则写成结构化文档以此约束人工与 AI 编码避免理解偏差所有变更可追溯、可校验解决 AI 写代码 脑补跑偏、需求无留存的问题。OpenSpec是落地 SDD 的轻量开源工具框架专为 AI 编程助手Cursor、Claude Code 等打造。它在项目里统一存放提案、设计、任务三类规范文档配套 CLI 命令驱动标准化流程强制 AI 编码前读取本地规范沉淀全流程变更记录适配团队协作与存量项目迭代。是一款轻量化、高灵活度的开源工具能够高效助力开发者完成项目规范定义、流程梳理、内容归档等全链路开发工作。项目路径https://github.com/Fission-AI/OpenSpec为什么需要它用 AI 写代码最大的毛病是 跑偏需求只存在聊天记录里对话一长AI 就会忘掉原始需求、被无关代码干扰甚至自己编功能。OpenSpec 的思路是在写任何代码前先把意图锁死成一份人可审、机可读的规范文件AI 每次开工都从这份规范出发而不是从你的口头描述出发。AI 强了人也更容易偷懒不审。能力越强人越倾向 它说的都对把验收责任丢给 AI。SDD 强制你在写代码前先审一遍方案 —— 这个 人审 环节恰恰是 AI 替代不了的。SDD 对于小任务会更消耗token但对与大任务通常算总账是省的把 token 从 AI 跑偏后反复返工、重读长上下文 这些打水漂的开销变成 写一份规范一次性锁定方向 的投资。一、OpenSpec 安装教程OpenSpec 支持全局安装安装后可在任意目录调用全局命令快速完成项目配置与流程操作。推荐使用 npm 安装最新稳定版本确保功能完整、兼容性最佳。npm install -g fission-ai/openspeclatest执行以上命令即可完成全局安装安装成功后终端可识别openspec全局指令无需重复配置环境变量。二、项目初始化流程安装完成后即可在自有项目中初始化 OpenSpec 配置具体步骤如下cd your-project openspec init三、OpenSpec 两大核心工作流为适配不同项目的开发需求OpenSpec 内置两套差异化工作流开箱即用的默认快速路径Core Profile以及支持精细化自定义的扩展工作流Expanded Workflow开发者可根据项目复杂度自由选择。3.1 默认快速路径 (Core Profile)这是开箱即用的基础命令集覆盖了从探索到归档的核心流程。/opsx:explore探索模式。想法模糊时先用它跟 AI 自由对话AI 会研究代码库、对比方案帮你把想法变具体全程不生成任何代码或文档。/opsx:propose提出变更方案。思路明确后让 AI 一次性生成四件套规划文档——proposal.md为什么做、specs/行为规范、design.md技术方案、tasks.md任务清单。人审关键一步也是 AI 替代不了的一环。AI 只是起草者你要花几分钟审查规范和方案错了直接改——此时纠错最便宜审完才进入实施。/opsx:apply开始执行。AI 严格按 tasks.md 的任务清单逐一实现代码并勾选完成不自由发挥。/opsx:verify校验一致性复杂改动建议做。检查实现是否与规范相符发现偏差及时修正通过后再归档。/opsx:archive归档变更。代码完成并验证通过后把本次增量规范合并回 openspec/specs/成为项目新的真相源供任何后续会话和队友引用。3.2 扩展工作流命令 (Expanded Workflow)以下命令提供更精细的控制默认未启用。开启方式在项目终端执行 openspec config profile 选择 workflows再运行 openspec update。/opsx:new change-name建立新的变更。只创建变更文件夹骨架不生成任何文档为后续逐步规划做准备。/opsx:continue逐步生成文档。与 new 搭配使用每次只生成下一个文档如先 proposal.md适合想分阶段审核、每步都过目的场景。/opsx:ff快速推进 (Fast-Forward)。跳过逐步生成一次性产出全部规划文档proposal.md、specs/、design.md、tasks.md适合需求已经很明确的场景。/opsx:verify验证实现。对照规范文档检查已写的代码是否符合预期归档前的最后一道检查。/opsx:bulk-archive批量归档。一次性归档多个已完成变更适合攒了一批一起收尾。/opsx:onboard引导式入门。通过交互式引导带你完整走一遍工作流适合刚上手时熟悉节奏。四、驱动开发闭环五、人工审核技巧5.1 各文件审核优先级文件优先级审什么specs/行为规范必审这是 AI 的验收标准错了代码全错。看场景是否 GIVEN/WHEN/THEN 式、可不可测、有没有歧义、符不符合你的原始意图proposal.md为什么做必审10 秒扫一眼它要解决的问题是不是你想解决的问题范围有没有悄悄变大 / 变小design.md技术方案重点审只看关键决策技术选型合不合理、有没有引入你没同意的依赖、新增风险项你认不认、被标记解决的 Open Question 是否真的解决了tasks.md执行清单快速扫不逐条看只检查任务和 specs 对得上吗关键步骤测试、实测漏没漏有没有把不该改的文件写进去docs / 实施方案.md等说明文档可不审给人看的说明错个字不影响代码5.2 审核的 5 个技巧只审 delta不审全文。OpenSpec 的优势就是每次变更只有 这次改了什么。你这次就直接审那三个修订点而不是重读所有文档。用 5 个问题代替通读范围对不对proposal验收标准清不清楚、可不可测specs 场景有没有引入意外design 新决策、新依赖风险认不认新增风险项你同意吗该解决的悬而未决问题都标了吗Open Question重点盯 specs 的场景。它是 AI 实现的靶子也是以后回归测试的靶子 —— 写得准实现就八九不离十。修订类变更看 前后差异。比如你这次说话人方案从 服务端归一 改成了 本地聚类合并—— 你就确认这一个改动写对了、且相关处specs 场景、tasks 任务、docs 注记都同步改了没有。格式交给工具人只管语义。openspec validate帮你查结构、格式、依赖缺失openspec status看进度。机器能查的别用眼睛查你的几分钟全花在 判断对不对 上。一句话审 契约specs proposal 关键决策不审 过程tasks 文档—— 每次变更省下 80% 的审核时间还不会漏掉真正要命的东西。六、openspec/ 目录关系6.1specs/ 和 changes/openspec/ 下只有两类东西「已生效的真相」specs/和「进行中的草稿」changes/。归档 把草稿里的增量规范合并进真相然后把草稿收进档案柜。文件流永远是单向的changes/ → specs/。6.2 两个 specs 的区别openspec/specs/openspec/changes/xxx/specs/角色主规格现状 / 真相增量规范这次想改什么状态已生效归档过的共识待审未生效的提案谁读每个 AI 会话开工前只有做这个变更的会话内容项目完整的行为契约只写 相对现状变了什么deltaproposal.md→为什么做design.md→怎么实现tasks.md→做什么AI 的执行清单specs/→改什么契约增量规范一句话总结主specs/是 已定稿的答案changes/是 待审批的修改意见archive是 审批通过后收进档案柜—— 文件从草稿流向真相单向、不乱。七、实战落地建议新手入门建议从核心工作流开始使用/opsx:explore→/opsx:propose→/opsx:apply→/opsx:archive这个标准流程能帮你快速建立规范驱动的开发习惯。复杂需求如果需求复杂或需要团队评审可以启用扩展工作流使用/opsx:new和/opsx:continue来精细控制每个文档的产出。需求明确如果对要做的功能非常确定想快速推进可以直接使用/opsx:ff一次性生成所有规划文档。