一、OpenSpec 简介AI 编程常陷于“氛围编程”的困境大模型缺乏长期记忆易导致上下文丢失与需求漂移最终引发架构混乱与技术债。为此规范驱动开发SDD应运而生。它颠覆传统惯性确立“先定规范再写代码”的新秩序将规范作为项目的“单一事实来源”确保开发意图与最终实现高度一致。作为 SDD 的最佳落地载体OpenSpec 是一款轻量级开源框架。它通过标准化工作流与结构化目录将抽象理念具象化让开发者与 AI 在编码前精准对齐目标确保 AI 严格按规范“照单执行”。简言之SDD 确立了以规范为核心的开发秩序而 OpenSpec 则是保障这一秩序高效贯彻的工程化基础设施。附OpenSpec githubhttps://github.com/Fission-AI/OpenSpec二、OpenSpec 常用命令openspec init --tools claude # 初始化及绑定claude code工具 openspec new change add-logging --description 这是变更描述 # 创建新变更 openspec apply add-logging # 实现add-logging功能 openspec validate add-logging # 验证add-logging变更是否符合规范文件 openspec archive add-logging # 将add-logging变更归档 openspec show add-logging # 展示add-logging变更的增量差异等 openspec list # 查看当前状态 openspec spec list # 显示所有规范文件(该命令已过期) openspec view # 显示变更的统计信息注规范文件一般在以下两个目录 全局主规范目录openspec/specs/变更提案目录openspec/changes/change-name/specs/三、OpenSpec 规范驱动开发工作流从提案到归档的完整闭环在现代软件工程中标准的 GitOps 与基础设施即代码IaC工作流确立了“Plan - Review - Apply”的核心范式。OpenSpec 作为一套 AI 原生的规范驱动开发Spec-Driven Development框架深度契合了这一理念并在此基础上引入了“归档Archive”机制形成了从提案到知识沉淀的完整闭环。1安装 OpenSpecnpm install -g anthropic-ai/claude-code2执行 openspec init 命令初始化工程会在 Claude Code 中自动增加 OpenSpec 相关的 SKILL附OpenSpec 安装后会自动增加 OpenSpec 相关的 SKILL后续使用 OpenSpec 修改产品功能时可使用 OpenSpec 原生命令或都使用 Claude Code 中的 SKILL3提案增加新功能# 示例在 claude 中执行命令 /openspec-propose 在 ChatModelController 打印详细的日志4人机协同修改来确认改动是否符合预期鉴于 OpenSpec 自动生成的设计方案可能存在偏差需由人工对 OpenSpec 文档含 design.md 等进行校验与修订以确保最终设计成果符合预期标准。开发者需对生成的规范进行严格校验并根据偏差程度采取不同的调整策略宏观逻辑修正若整体架构或业务方向存在偏差应通过对话交互或优化提示词引导 AI 重新生成迭代版本。微观细节微调若仅存在局部字段或具体细节的不准确开发者可直接在 IDE 中进行手动修订形成最终确认版本。语法合规校验在人工介入修改后必须执行/openspec-lint指令进行语法检查以确保手动调整后的文档依然符合 OpenSpec 的格式规范避免引入结构性错误。5Apply 操作来变更执行在规范文档通过审查与校验、确认完全符合预期后方可进入执行阶段。开发者执行/openspec-apply指令使变更真正生效并落地到代码库中此时会同步修改 tasks.md 文档的状态。在 Apply 阶段若出现代码修改不合理情况仅通过人工提示词直接修改代码是不会自动同步到 openspec 相关文档的这里推荐采用反向同步Reverse Sync / 逆向生成的方式参考流程图Step 1通过人工提示词修改不合理的代码Step 2执行/openspec-sync同步当前修改到 openspec 相关文档Step 3再人工审查是否同步完整6Archive归档与规范沉淀当代码实现完成并经过验证后必须执行归档操作以完成变更的最终收尾。通过执行/openspec-archive指令OpenSpec 会完成两项关键任务历史追溯将已完成的变更目录包含提案、设计文档等自动移动至归档文件夹如openspec/changes/archive/并附加时间戳形成可追溯的开发历史记录。规范合并系统会自动解析本次变更中的增量规范Delta Specs将其无缝合并至主规范目录openspec/specs/。四、Spec 与 Code 的一致性说明遵守SDD“规范先行代码后置”的核心思想使用 OpenSpec 时要坚持“Spec-Driven”的原则把 openspec 当作数据库的 Schema把代码当作数据即改代码前必须先改文档严格遵守 Spec 永远是 Single Source of Truth唯一事实来源绝对不要出现 Spec 与 Code 不一致的情况只有保证 Spec 到 Code 的双向闭环AI 辅助开发才能真正产生可靠的工程价值否则只会带来更多的技术债务。