OpenSpec工作流概览

一、项目定位

OpenSpec 是开源、面向 AI 编程助手的规范驱动开发（Spec-Driven Development, SDD）轻量框架，核心理念：Spec First, Code Later（规范优先，代码后置）。专为 Cursor、Claude Code、GitHub Copilot、Windsurf 等主流 AI 编码工具设计，不绑定大模型、无需额外 API Key、兼容存量老项目迭代，直击当下 AI 编程两大头号痛点：

1. 需求模糊
   
   ：口头对话提需求，AI 自由发挥、频繁理解偏差、代码反复返工；
2. 上下文丢失
   
   ：对话窗口关闭、新建会话后，全部业务约束、设计决策直接消失，需要重复复述需求。

二、传统 AI 编程的根本缺陷

普通 AI 编程依赖会话临时上下文：

• 需求、边界条件、代码约束全部保存在聊天记录；
• 会话生命周期有限，上下文窗口溢出、重启会话即 “失忆”；
• 人与 AI 没有书面共识契约，AI 靠 “猜测意图” 生成代码，结果不可复现。

OpenSpec 解决方案：把会话内临时上下文，转为仓库内持久化的结构化规范文档。人与 AI 先对齐规范、确认契约，AI 再编写代码；规范永久保存在代码仓库，跨会话、跨工具随时复用上下文。

三、核心设计机制：Delta Specs（增量规范）

这是 OpenSpec 和同类 SpecKit 最大区别，主打存量项目友好（Brownfield-First）：

• openspec/specs/
  
  ：基准规范，系统当前稳定行为，作为唯一事实来源；
• openspec/changes/
  
  ：增量变更提案，存放本次功能改动；增量规范分为三类变更标记：
• ADDED
  
  ：新增业务规则
• MODIFIED
  
  ：修改已有逻辑
• REMOVED
  
  ：废弃功能

无需重写整套系统文档！只描述本次改动内容，大幅降低规范维护成本，非常适合老系统持续迭代。

变更完整生命周期：draft（草稿）→ review（评审）→ approved（确认）→ apply（生成代码）→ verify（验证）→ archive（归档合并入主规范）

四、标准工作流（三条核心斜杠命令）

1. /opsx:propose 提案生成
   
   开发者提出大致想法，AI 自动输出提案、结构化 Spec、任务清单；人工审阅修改，敲定 “要做成什么样”，形成人与 AI 共同认可的契约。
2. /opsx:apply 执行编码
   
   AI 自动加载基准规范 + 本次增量 Spec，严格依照规范生成代码，杜绝超出范围改动。
3. /opsx:archive 归档
   
   功能验证通过后，将增量规范合并进主规范，永久沉淀上下文；未完成提案保留，下次打开项目可直接继续开发，不存在上下文丢失。

五、核心能力与价值

✅ 解决需求模糊所有需求转化为结构化规范（场景、前置条件、输出约束、异常分支），消除自然语言歧义，AI 不再自由 “脑补需求”，输出可预测、可评审。

✅ 根治上下文丢失规范文件纳入 Git 管理，跟随项目永久保存；新建会话、切换 AI 工具、隔天继续开发，AI 自动读取仓库规范，不用反复讲解业务。

✅ 变更全程可追溯每一处代码改动都对应一份 Spec 提案，PR 可直接关联需求文档，团队协作清晰，便于代码审查。

✅ 轻量化无侵入只增加一个 openspec/ 目录，不改造现有工程结构、不强制开发语言；支持前端 / 后端 / 全栈任意项目。

✅ 多 AI 工具原生适配通过各编辑器自定义指令机制自动注入规范：Cursor、Claude Code、Copilot 均可无缝接入。

六、OpenSpec vs SpecKit（选型区分）

七、典型落地场景

1. 复杂后端业务迭代，防止 AI 随意改动历史逻辑；
2. 长期跨多天开发的大型功能；
3. 团队多人共用 AI 助手协作，统一需求理解；
4. 老系统重构、模块改造，约束 AI 不随意大范围重构；
5. 追求 AI 代码稳定性，降低反复沟通、返工成本。

八、简单入门示例

需求：给登录增加 “记住我” 会话时效控制

1. 执行 /opsx:proposeAI 生成 spec 片段：

GIVEN 用户登录
WHEN 勾选记住我
THEN 会话有效期30天
WHEN 未勾选记住我
THEN 会话有效期24小时无活动自动失效

2. 人工确认规范无误 → /opsx:applyAI 严格基于这份规范实现登录会话逻辑；
3. 测试通过 → /opsx:archive规范永久存入仓库。下次新开会话修改登录逻辑，AI 自动读取这份历史约束。

九、局限性客观说明

• 适合确定性业务开发；高度探索式、实验性原型开发收益有限；
• 需要养成 “先写规范再编码” 的工作习惯，存在少量学习成本；
• 不能完全消除代码 Bug，解决的是需求对齐、上下文持久化问题，不等同自动化测试。

#AI 编程框架 #OpenSpec #规范驱动开发 #程序员 AI 工具 #开源项目分享