尧图网站建设 
规范驱动开发落地实战用 OpenSpec 给 AI 编码助手装上需求版本管理的完整指南【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpecOpenSpec 是面向 AI 编码助手的规范驱动开发Spec-driven Development工具它把散落在聊天记录里的需求变成可审查、可合并、可追溯的规范文件让人与 AI 在写代码前先达成一致。这篇文章用一次完整的落地演示讲透它的工作机制、常见坑与推广节奏照着做你就能在现有项目里跑通第一轮先定规范、再写代码的闭环。一、当 AI 助手开始自信地犯错团队到底缺什么先看一个真实场景。某团队 8 个人其中 3 个重度使用 AI 编码助手。周一后端让 AI 实现登录会话过期AI 顺手把超时设成了 15 分钟周三前端要对接同一个功能因为两段对话互相看不见AI 凭记忆写出了 30 分钟的版本。周五联调时两端行为不一致排查了半天才定位到根因需求只存在于两段互相隔离的聊天记录里没有任何一方能说清系统当前应该怎样。更麻烦的是这种问题会滚雪球。产品经理要求加一个开关AI 改了 A 处的行为B 处的另一个功能悄悄坏掉新人接手项目时问现在系统到底有哪些行为契约答案只能靠读代码反推。问题不在 AI 不够强而在于需求放在上下文窗口里等于没有需求。团队缺的不是更强的模型而是一个人与机器都能读、都能改、且有单一事实来源的契约层——这正是规范驱动开发要解决的问题也是 OpenSpec 存在的理由。二、核心机制拆解需求也能像代码一样做版本管理理解 OpenSpec 最省力的方式是一个类比Git 对代码做版本管理OpenSpec 对需求做版本管理。它把项目里所有已确认的行为收进openspec/specs/目录主干每个新功能在openspec/changes/名称/下开一个独立文件夹分支完成后归档merge 回主干。每个变更文件夹里有四份工件各司其职proposal.md为什么做、做什么、影响哪些能力specs/增量规范delta描述行为将如何变化design.md怎么做技术方案与决策tasks.md可勾选的实施清单其中最值得理解的是增量规范delta spec。它像 git diff 一样只记录变化用三个段落表达三种操作ADDED新增行为、MODIFIED修改行为、REMOVED废弃行为。# Delta for Auth ## ADDED Requirements ### Requirement: Two-Factor Authentication The system MUST support TOTP-based two-factor authentication. #### Scenario: 2FA login - GIVEN a user with 2FA enabled - WHEN the user submits valid credentials - THEN an OTP challenge is presented为什么用 delta 而不是重写整份规范因为大多数开发发生在存量系统上只写变化评审者一眼看到改动点两个变更同时改同一份 spec 的不同需求也不会冲突归档时 ADDED 追加、MODIFIED 替换、REMOVED 删除合并干净利落。这四份工件的依赖关系由 schema 声明式定义配置文件在schemas/spec-driven/schema.yamlartifacts: - id: proposal generates: proposal.md requires: [] - id: specs generates: specs/**/*.md requires: [proposal] - id: design generates: design.md requires: [proposal] - id: tasks generates: tasks.md requires: [specs, design]注意一个反直觉的点依赖是使能而不是门禁。它告诉 AI 可以按什么顺序生成工件但从不强制你按部就班——你可以跳过 design也可以在实现中途回改 proposal。这正是它区别于瀑布式规格框架的地方fluid not rigid流程服务于人而不是人服务于流程。三、实战演示从安装到第一个变更落地前提是 Node.js 20.19.0 或更高版本。整个流程只有两条命令进终端其余全在 AI 对话里完成。步骤 1安装npm install -g fission-ai/openspeclatest步骤 2初始化cd your-project openspec initinit 会探测你使用的编码工具并打印出正确的命令形式——同一个功能在不同工具里写法不同Cursor、GitHub Copilot 里是/opsx-proposeAmazon Q 里是opsx-proposeCodex 里是$openspec-propose。项目会生成openspec/目录骨架和给 AI 的指令文件。步骤 3在 AI 对话里提出需求/opsx:propose add-dark-modeAI 会在openspec/changes/add-dark-mode/下生成四件套。这一步的关键是AI 只写方案一行代码都不会动。你要做的第一件事是审查specs/ui/spec.md检查需求是否用 SHALL/MUST 表达、每个场景是否可测试、有没有把实现细节混进规范。步骤 4确认方案后实施/opsx:applyAI 会逐条勾选 tasks.md 中的任务边实现边汇报进度。如果中途发现设计有问题直接回改 design.md 再继续不需要重启流程。步骤 5归档/opsx:archivedelta 合并进主规范openspec/specs/ui/spec.md变更文件夹归档到openspec/changes/archive/2025-01-24-add-dark-mode/留存审计历史。步骤 6打开全局视图openspec view仪表盘把规范覆盖了多少需求、哪些变更卡在 0%、任务完成率多少一次性摊开是团队做数据决策的入口。示例图中 10 个规范、64 条需求、3 个进行中变更、任务完成率 73%——每个数字背后都是一个可追踪的契约。这套流程的完整说明见docs/getting-started.md命令的分工规则见docs/how-commands-work.md。四、不同团队怎么用场景适配矩阵OpenSpec 的设计哲学是从个人项目可扩展到企业但不同规模团队的用法和取舍并不一样对号入座更重要。场景推荐路径关键取舍个人开发者 / 单仓库core 配置explore → propose → apply → archive开销最小一人即可闭环主要价值是管住自己的 AI小团队3-10 人上述流程 openspec list/show做周度评审规范要有明确 owner否则没人维护中大型团队启用扩展配置new/continue/verify/ff多了验证环节周转略慢但质量更稳多仓库 / 跨团队协作Storesbeta独立规划仓库共享 specs单一事实来源跨仓库但 beta 功能需先评估存量老项目直接从 delta 改起不必先写全量规范brownfield 优先见效最快新手和资深的差别不在命令而在审查习惯新手容易跳过 proposal 审查直接让 AI 写代码资深使用者会把最多时间花在 spec 上——因为改 spec 的成本是分钟级改已实现代码的成本是小时级。五、避坑指南新手最容易踩的 6 个坑把斜杠命令敲进终端。/opsx:开头的命令运行在 AI 聊天框里openspec开头的命令才在终端跑。这是最高频的起步错误init 的输出里其实写明了别跳过那几行提示。在 spec 里写实现细节。类名、函数名、库选型属于 design.md。判断标准很简单如果换一种实现方式对外行为不变它就不该出现在 spec 里。MODIFIED 只贴修改片段。归档时 MODIFIED 是整段替换只贴一行新描述会把原有细节全部冲掉。正确做法是整块复制原需求含全部场景再修改。场景标题用了 3 个井号。delta spec 里场景必须用####4 个井号3 个井号会静默失败——校验不报错但归档时场景悄悄丢失。这是最隐蔽的坑建议归档前用openspec validate兜底。新能力不写 Purpose。新建能力的 delta 需要写 50 字以上的## Purpose段落否则归档后主 spec 会留下一个 TBD 占位符得手工补。顺手写上省得回头收拾。用 skip_specs 逃避规范。纯重构、文档、工具链变更可以声明skip_specs: true但行为明明变了却不想写 spec是反模式。校验会拒绝零 delta 的变更也别为了过检硬造一条需求——那比不写更糟。还有两条团队级建议保持上下文卫生实现开始前清空会话别让旧的讨论污染新的决策涉及文件路径的变更主动写 Windows 场景——项目强制使用 path.join() 保证跨平台你的规范也应声明跨平台行为否则在 Linux 上验证通过的路径逻辑到了 Windows 就翻车。六、行动清单一周内把它用起来第 1-2 天挑一个非关键模块做试点完整跑一轮 explore → propose → apply → archive先体验先对齐再动手的节奏差异。第 3-5 天拉上 2-3 人做第一个变更的同行评审重点检查 delta 的 ADDED/MODIFIED 是否真实覆盖了行为变化借此统一团队的 spec 写作标准。次周把openspec validate接进 CI设成合并门禁让规范问题在提交前暴露。持续盯四个量化指标——规范覆盖率关键功能有无对应 spec、变更周转时间propose 到 archive 的时长、验证通过率、归档后返工率。前两个看效率后两个看质量。七、写在最后OpenSpec 的价值主张可以压缩成一句话在 AI 编码时代把口头需求变成可版本管理的契约。它不要求你重写流程只要求你在让 AI 动手前花十分钟把话说清楚而这十分钟换来的是可审查、可追溯、可合并的增量规范库——AI 每写一行代码都有据可依。它的演进方向也清晰可见Storesbeta把规范从单仓库扩展到跨仓库协作让平台团队在独立仓库里维护 specs、产品团队只读引用自定义 schema 让团队定义自己的工件流比如 research-first 这类先调研后提案的流程社区 schema 目录则把沉淀下来的最佳实践变成可复用资产。对于正在把 AI 助手从玩具升级为生产力的团队这可能是成本最低、收益最确定的切入点。【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 规范驱动开发落地实战：用 OpenSpec 给 AI 编码助手装上“需求版本管理“的完整指南
规范驱动开发落地实战用 OpenSpec 给 AI 编码助手装上需求版本管理的完整指南【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpecOpenSpec 是面向 AI 编码助手的规范驱动开发Spec-driven Development工具它把散落在聊天记录里的需求变成可审查、可合并、可追溯的规范文件让人与 AI 在写代码前先达成一致。这篇文章用一次完整的落地演示讲透它的工作机制、常见坑与推广节奏照着做你就能在现有项目里跑通第一轮先定规范、再写代码的闭环。一、当 AI 助手开始自信地犯错团队到底缺什么先看一个真实场景。某团队 8 个人其中 3 个重度使用 AI 编码助手。周一后端让 AI 实现登录会话过期AI 顺手把超时设成了 15 分钟周三前端要对接同一个功能因为两段对话互相看不见AI 凭记忆写出了 30 分钟的版本。周五联调时两端行为不一致排查了半天才定位到根因需求只存在于两段互相隔离的聊天记录里没有任何一方能说清系统当前应该怎样。更麻烦的是这种问题会滚雪球。产品经理要求加一个开关AI 改了 A 处的行为B 处的另一个功能悄悄坏掉新人接手项目时问现在系统到底有哪些行为契约答案只能靠读代码反推。问题不在 AI 不够强而在于需求放在上下文窗口里等于没有需求。团队缺的不是更强的模型而是一个人与机器都能读、都能改、且有单一事实来源的契约层——这正是规范驱动开发要解决的问题也是 OpenSpec 存在的理由。二、核心机制拆解需求也能像代码一样做版本管理理解 OpenSpec 最省力的方式是一个类比Git 对代码做版本管理OpenSpec 对需求做版本管理。它把项目里所有已确认的行为收进openspec/specs/目录主干每个新功能在openspec/changes/名称/下开一个独立文件夹分支完成后归档merge 回主干。每个变更文件夹里有四份工件各司其职proposal.md为什么做、做什么、影响哪些能力specs/增量规范delta描述行为将如何变化design.md怎么做技术方案与决策tasks.md可勾选的实施清单其中最值得理解的是增量规范delta spec。它像 git diff 一样只记录变化用三个段落表达三种操作ADDED新增行为、MODIFIED修改行为、REMOVED废弃行为。# Delta for Auth ## ADDED Requirements ### Requirement: Two-Factor Authentication The system MUST support TOTP-based two-factor authentication. #### Scenario: 2FA login - GIVEN a user with 2FA enabled - WHEN the user submits valid credentials - THEN an OTP challenge is presented为什么用 delta 而不是重写整份规范因为大多数开发发生在存量系统上只写变化评审者一眼看到改动点两个变更同时改同一份 spec 的不同需求也不会冲突归档时 ADDED 追加、MODIFIED 替换、REMOVED 删除合并干净利落。这四份工件的依赖关系由 schema 声明式定义配置文件在schemas/spec-driven/schema.yamlartifacts: - id: proposal generates: proposal.md requires: [] - id: specs generates: specs/**/*.md requires: [proposal] - id: design generates: design.md requires: [proposal] - id: tasks generates: tasks.md requires: [specs, design]注意一个反直觉的点依赖是使能而不是门禁。它告诉 AI 可以按什么顺序生成工件但从不强制你按部就班——你可以跳过 design也可以在实现中途回改 proposal。这正是它区别于瀑布式规格框架的地方fluid not rigid流程服务于人而不是人服务于流程。三、实战演示从安装到第一个变更落地前提是 Node.js 20.19.0 或更高版本。整个流程只有两条命令进终端其余全在 AI 对话里完成。步骤 1安装npm install -g fission-ai/openspeclatest步骤 2初始化cd your-project openspec initinit 会探测你使用的编码工具并打印出正确的命令形式——同一个功能在不同工具里写法不同Cursor、GitHub Copilot 里是/opsx-proposeAmazon Q 里是opsx-proposeCodex 里是$openspec-propose。项目会生成openspec/目录骨架和给 AI 的指令文件。步骤 3在 AI 对话里提出需求/opsx:propose add-dark-modeAI 会在openspec/changes/add-dark-mode/下生成四件套。这一步的关键是AI 只写方案一行代码都不会动。你要做的第一件事是审查specs/ui/spec.md检查需求是否用 SHALL/MUST 表达、每个场景是否可测试、有没有把实现细节混进规范。步骤 4确认方案后实施/opsx:applyAI 会逐条勾选 tasks.md 中的任务边实现边汇报进度。如果中途发现设计有问题直接回改 design.md 再继续不需要重启流程。步骤 5归档/opsx:archivedelta 合并进主规范openspec/specs/ui/spec.md变更文件夹归档到openspec/changes/archive/2025-01-24-add-dark-mode/留存审计历史。步骤 6打开全局视图openspec view仪表盘把规范覆盖了多少需求、哪些变更卡在 0%、任务完成率多少一次性摊开是团队做数据决策的入口。示例图中 10 个规范、64 条需求、3 个进行中变更、任务完成率 73%——每个数字背后都是一个可追踪的契约。这套流程的完整说明见docs/getting-started.md命令的分工规则见docs/how-commands-work.md。四、不同团队怎么用场景适配矩阵OpenSpec 的设计哲学是从个人项目可扩展到企业但不同规模团队的用法和取舍并不一样对号入座更重要。场景推荐路径关键取舍个人开发者 / 单仓库core 配置explore → propose → apply → archive开销最小一人即可闭环主要价值是管住自己的 AI小团队3-10 人上述流程 openspec list/show做周度评审规范要有明确 owner否则没人维护中大型团队启用扩展配置new/continue/verify/ff多了验证环节周转略慢但质量更稳多仓库 / 跨团队协作Storesbeta独立规划仓库共享 specs单一事实来源跨仓库但 beta 功能需先评估存量老项目直接从 delta 改起不必先写全量规范brownfield 优先见效最快新手和资深的差别不在命令而在审查习惯新手容易跳过 proposal 审查直接让 AI 写代码资深使用者会把最多时间花在 spec 上——因为改 spec 的成本是分钟级改已实现代码的成本是小时级。五、避坑指南新手最容易踩的 6 个坑把斜杠命令敲进终端。/opsx:开头的命令运行在 AI 聊天框里openspec开头的命令才在终端跑。这是最高频的起步错误init 的输出里其实写明了别跳过那几行提示。在 spec 里写实现细节。类名、函数名、库选型属于 design.md。判断标准很简单如果换一种实现方式对外行为不变它就不该出现在 spec 里。MODIFIED 只贴修改片段。归档时 MODIFIED 是整段替换只贴一行新描述会把原有细节全部冲掉。正确做法是整块复制原需求含全部场景再修改。场景标题用了 3 个井号。delta spec 里场景必须用####4 个井号3 个井号会静默失败——校验不报错但归档时场景悄悄丢失。这是最隐蔽的坑建议归档前用openspec validate兜底。新能力不写 Purpose。新建能力的 delta 需要写 50 字以上的## Purpose段落否则归档后主 spec 会留下一个 TBD 占位符得手工补。顺手写上省得回头收拾。用 skip_specs 逃避规范。纯重构、文档、工具链变更可以声明skip_specs: true但行为明明变了却不想写 spec是反模式。校验会拒绝零 delta 的变更也别为了过检硬造一条需求——那比不写更糟。还有两条团队级建议保持上下文卫生实现开始前清空会话别让旧的讨论污染新的决策涉及文件路径的变更主动写 Windows 场景——项目强制使用 path.join() 保证跨平台你的规范也应声明跨平台行为否则在 Linux 上验证通过的路径逻辑到了 Windows 就翻车。六、行动清单一周内把它用起来第 1-2 天挑一个非关键模块做试点完整跑一轮 explore → propose → apply → archive先体验先对齐再动手的节奏差异。第 3-5 天拉上 2-3 人做第一个变更的同行评审重点检查 delta 的 ADDED/MODIFIED 是否真实覆盖了行为变化借此统一团队的 spec 写作标准。次周把openspec validate接进 CI设成合并门禁让规范问题在提交前暴露。持续盯四个量化指标——规范覆盖率关键功能有无对应 spec、变更周转时间propose 到 archive 的时长、验证通过率、归档后返工率。前两个看效率后两个看质量。七、写在最后OpenSpec 的价值主张可以压缩成一句话在 AI 编码时代把口头需求变成可版本管理的契约。它不要求你重写流程只要求你在让 AI 动手前花十分钟把话说清楚而这十分钟换来的是可审查、可追溯、可合并的增量规范库——AI 每写一行代码都有据可依。它的演进方向也清晰可见Storesbeta把规范从单仓库扩展到跨仓库协作让平台团队在独立仓库里维护 specs、产品团队只读引用自定义 schema 让团队定义自己的工件流比如 research-first 这类先调研后提案的流程社区 schema 目录则把沉淀下来的最佳实践变成可复用资产。对于正在把 AI 助手从玩具升级为生产力的团队这可能是成本最低、收益最确定的切入点。【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考