OpenSpec：AI 编码助手的”规格先行”框架

OpenSpec 的核心命题是：在代码被写出之前，人类和 AI 先在规格（spec）上达成共识。它本质上是一套轻量级的「上下文工程」协议——用结构化的 Markdown 文档将 AI 编码过程中飘忽不定的对话历史”固化”下来，化作可追溯、可迭代的规格工件。

它的设计哲学非常克制：流动而非僵化、迭代而非瀑布、简单而非复杂、面向存量项目而非只为绿地项目。

1. 核心工作流：三条命令串联完整开发生命周期

从 README 中展示的样例可以看出，OpenSpec 把一次完整的功能开发抽象为三个步骤：

1.1 `/opsx:propose` —— 提案阶段

AI 会在 openspec/changes/<feature-name>/ 目录下自动生成四个核心文档：

文档	作用
`proposal.md`	为什么要做这个变更、变更了什么
`specs/`	需求和场景描述（验收标准）
`design.md`	技术方案和实现路径
`tasks.md`	可勾选的实现清单

这里的关键在于：先对齐意图，再动手写代码。人和 AI 共同审阅 proposal 和 specs，确认理解一致后才进入实现。

1.2 `/opsx:apply` —— 实现阶段

AI 按照 tasks.md 中的清单逐项执行，每完成一项就打勾。这个阶段 AI 不再凭空猜测需求，而是严格对标已达成共识的 spec。

1.3 `/opsx:archive` —— 归档阶段

变更完成后归档到 openspec/changes/archive/，同时更新主 spec 文件。项目的规格文档始终处于最新状态，成为项目的”活的文档”。

2. 实际应用场景分析

根据 OpenSpec 的特性和定位，以下场景是它最能发挥价值的地方：

2.1 用 AI Coding Agent 做中大型功能开发

当你要用 AI 编码助手实现一个复杂功能（比如”给后台管理系统加一套 RBAC 权限体系”），最怕的是一次对话塞太多上下文导致 AI 遗忘前期讨论的需求。OpenSpec 让 proposal 和 specs 成为不可丢失的”锚点”——AI 在 /opsx:apply 阶段始终能看到这些文档。适用于任何预计超过 3-5 轮 AI 交互的功能开发。

2.2 多 AI 工具协作 / 切换工具

OpenSpec 支持 25+ AI 编码助手（包括 Claude、Copilot、Cursor 等），文件格式是纯 Markdown，不绑定任何特定工具。实际场景中，你可以在 Cursor 里用 /opsx:propose 写好 specs，再切到 Claude Code 执行 /opsx:apply，规格文件两者都能读取。适合需要根据不同任务特点灵活切换 AI 工具的团队。

2.3 存量项目（Brownfield）重构或功能叠加

OpenSpec 明确标榜自己”built for brownfield not just greenfield”。对一个已经运行两年的生产项目，你不可能从零开始写完整的 PRD。OpenSpec 的轻量提案机制只关注”本次变更”的范围，不会要求你对整个系统建模。适合在现有代码库上做增量功能、渐进式重构。

2.4 多人协作的对齐工具

当一个功能涉及多人——比如后端写 API、前端写页面、产品出验收标准——OpenSpec 的 proposal 和 specs 文件夹可以作为”对齐的中间层”。每个人（以及各自的 AI 助手）都读取同一份规格来工作。社区还支持第三方 schema 包，可以与 github/spec-kit 等工具链打通。适合小团队没有专职 PM、靠 AI + 文档对齐需求的场景。

2.5 开源项目的贡献规范

README 中明确规定：小修小补直接提 PR，大改动必须先提交 OpenSpec change proposal。这意味着项目维护者可以把 proposal 作为贡献者的”入场券”——先讲清楚要做什么、为什么做、怎么做，通过 review 后再写代码。适合希望规范外部贡献流程的开源项目。

2.6 AI 编码的”可审计性”需求

每次变更都有自己的文件夹，包含 proposal.md、design.md、tasks.md，归档后形成完整的变更历史。这在金融、医疗等对合规性有要求的行业很有价值——你可以追溯每个功能的”决策路径”。适合需要保留开发决策记录的合规场景。

3. 落地建议

从实际使用角度出发，有几个关键注意事项：

模型选择：OpenSpec 官方推荐使用高推理能力的模型（如 Claude Opus 4.5、GPT 5.2），因为 proposal 和 design 阶段需要较强的架构推理能力。
上下文卫生：开始 /opsx:apply 前清空上下文窗口，避免对话历史污染当前任务的关注点。
版本管理：OpenSpec 生成的文件全部存放在项目仓库的 openspec/ 目录下，天然可以和 Git 联动——提案、实现、归档每个阶段都可以 commit，形成可追溯的版本链。
扩展工作流：除了基础三命令外，还支持 /opsx:new（新建变更）、/opsx:continue（继续未完成的变更）、/opsx:ff（快进模式）、/opsx:verify（验证）等扩展命令，通过 openspec config profile 切换。

本质上，OpenSpec 解决的是一个非常具体的问题：AI 编码助手的上下文是易失的，而软件开发的规格需要持久化。它在二者之间加了一层极薄但极关键的中间层。