一、OpenSpec 简介
AI 编程常陷于"氛围编程"的困境：大模型缺乏长期记忆，易导致上下文丢失与需求漂移，最终引发架构混乱与技术债。为此，规范驱动开发（SDD）应运而生。它颠覆传统惯性，确立"先定规范，再写代码"的新秩序，将规范作为项目的"单一事实来源"，确保开发意图与最终实现高度一致。作为 SDD 的最佳落地载体，OpenSpec 是一款轻量级开源框架。它通过标准化工作流与结构化目录，将抽象理念具象化，让开发者与 AI 在编码前精准对齐目标，确保 AI 严格按规范"照单执行"。简言之，SDD 确立了以规范为核心的开发秩序，而 OpenSpec 则是保障这一秩序高效贯彻的工程化基础设施。
附：
- OpenSpec github：https://github.com/Fission-AI/OpenSpec
二、OpenSpec 常用命令
bash
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：安装 OpenSpec
bash
npm install -g @anthropic-ai/claude-code2：执行 openspec init 命令初始化工程，会在 Claude Code 中自动增加 OpenSpec 相关的 SKILL
附：OpenSpec 安装后会自动增加 OpenSpec 相关的 SKILL，后续使用 OpenSpec 修改产品功能时可使用 OpenSpec 原生命令或都使用 Claude Code 中的 SKILL
3：提案增加新功能
bash
# 示例：在 claude 中执行命令
/openspec-propose "在 ChatModelController 打印详细的日志"
4：人机协同修改，来确认改动是否符合预期
鉴于 OpenSpec 自动生成的设计方案可能存在偏差，需由人工对 OpenSpec 文档（含 design.md 等）进行校验与修订，以确保最终设计成果符合预期标准。开发者需对生成的规范进行严格校验，并根据偏差程度采取不同的调整策略：
-
宏观逻辑修正：若整体架构或业务方向存在偏差，应通过对话交互或优化提示词，引导 AI 重新生成迭代版本。
-
微观细节微调：若仅存在局部字段或具体细节的不准确，开发者可直接在 IDE 中进行手动修订，形成最终确认版本。
-
语法合规校验 ：在人工介入修改后，必须执行
/openspec-lint指令进行语法检查，以确保手动调整后的文档依然符合 OpenSpec 的格式规范，避免引入结构性错误。
5：Apply 操作来变更执行
在规范文档通过审查与校验、确认完全符合预期后，方可进入执行阶段。开发者执行 /openspec-apply 指令，使变更真正生效并落地到代码库中，此时会同步修改 tasks.md 文档的状态。
在 Apply 阶段若出现代码修改不合理情况，仅通过人工提示词直接修改代码，是不会自动同步到 openspec 相关文档的，这里推荐采用**反向同步（Reverse Sync / 逆向生成）**的方式（参考流程图）：
-
Step 1：通过人工提示词修改不合理的代码
-
Step 2：执行
/openspec-sync同步当前修改到 openspec 相关文档 -
Step 3：再人工审查是否同步完整
6：Archive（归档与规范沉淀）
当代码实现完成并经过验证后，必须执行归档操作以完成变更的最终收尾。通过执行 /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 辅助开发才能真正产生可靠的工程价值，否则只会带来更多的技术债务。
