推荐一个 AI 编程工作流工具：OpenSpec

如果你已经在用 Codex、Claude Code、Cursor 这类 AI 编程工具，我推荐了解一下 OpenSpec。

OpenSpec 不是 OpenAPI / Swagger 那种接口文档工具。它解决的是 AI 编程里的另一个问题：在写代码之前，先把需求、设计、任务和验收标准沉淀成项目文件，让 AI 按明确的规格执行。

简单说，它给 AI 编程增加了一套「先规划、再实现、最后归档」的工作流。

OpenSpec 是什么？

OpenSpec 是一个面向 AI 编程助手的 spec-driven development 工具。它会在项目中维护一套 openspec/ 目录，用来记录系统规格和每次变更。

典型结构如下：

openspec/
├── specs/              # 当前系统行为的规格说明
├── changes/            # 正在进行的变更
│   └── add-dark-mode/
│       ├── proposal.md # 为什么做、做什么
│       ├── design.md   # 怎么做、关键方案
│       ├── tasks.md    # 实现任务清单
│       └── specs/      # 本次变更对规格的增删改
└── config.yaml

它的核心价值是：让 AI 不只是根据聊天上下文写代码，而是根据项目里的规格、设计和任务清单写代码。

这样做有几个直接好处：

• 需求不会只散落在聊天记录里。
• AI 执行任务时有明确边界。
• 复杂功能可以先拆成任务再实现。
• 功能完成后，规格可以同步归档，方便后续追溯。
• 团队协作时，不同人或不同 AI 工具能围绕同一套变更文件工作。

什么时候推荐使用？

OpenSpec 不适合所有任务。小改动直接让 AI 改就行，不需要额外流程。

我更推荐在这些场景使用：

场景	推荐原因
中等以上功能开发	需要先明确范围、方案、任务和验收标准
复杂 Bug 修复	需要先分析问题，再确认修复边界
跨模块改动	容易遗漏影响面，适合用任务清单约束
重构	可以明确“行为不变，只调整结构”
多人协作	变更过程可追溯，便于 review
长上下文任务	防止 AI 在多轮对话后忘记前面的约束

不太推荐的场景：

• 改一两个文案。
• 调整简单样式。
• 修明显 typo。
• 临时试验代码。

一句话判断：任务越重要、越容易产生歧义，越适合用 OpenSpec。

安装方式

OpenSpec 通过 npm 安装，要求 Node.js 20.19.0+。

全局安装：

npm install -g @fission-ai/openspec@latest

检查版本：

openspec --version

当前我使用的是 1.4.1。

注意：全局安装只会让系统多一个 openspec 命令，不会自动影响任何项目，也不会让 Codex 立即出现 OpenSpec 指令。

如何接入 Codex？

如果你使用 Codex，需要执行一次初始化，让 OpenSpec 生成 Codex 可识别的 prompts 和 skills。

推荐先建一个专门的 bootstrap 目录：

mkdir -p ~/code/OpenSpecBootstrap
cd ~/code/OpenSpecBootstrap
openspec init --tools codex

这一步的作用是让 Codex 全局出现 OpenSpec 指令。它会生成类似这些文件：

~/.codex/prompts/opsx-propose.md
~/.codex/prompts/opsx-explore.md
~/.codex/prompts/opsx-apply.md
~/.codex/prompts/opsx-sync.md
~/.codex/prompts/opsx-archive.md

执行完成后，重启 Codex 或开启新会话，在 slash 菜单里搜索：

opsx

你可能会看到这些指令：

Openspec Explore
Openspec Propose
Openspec Apply Change
Openspec Sync Specs
Openspec Archive Change

也可能显示为：

/prompts:opsx-propose
/prompts:opsx-apply
/prompts:opsx-archive

显示名字不同不重要，本质都是 OpenSpec 的工作流入口。

真实项目如何启用？

Bootstrap 只是为了让 Codex 出现 OpenSpec 指令。真实项目要使用 OpenSpec，还需要进入项目目录初始化：

cd /path/to/your-project
openspec init --tools codex

这一步会在项目里生成：

openspec/
├── specs/
├── changes/
└── config.yaml

.codex/
└── skills/

之后这个项目里的 OpenSpec 变更才会有地方保存。

如果你只是安装了全局 CLI，或者只做了 bootstrap，但没有在真实项目里初始化，那么不建议直接在该项目里跑 OpenSpec 流程，因为项目内还没有 openspec/ 工作目录。

openspec init 和 openspec init --tools codex 的区别

两者都能初始化 OpenSpec。

openspec init

这是交互式初始化，会让你选择要配置哪些 AI 工具。

openspec init --tools codex

这是非交互式初始化，明确只配置 Codex。

如果你确定只用 Codex，推荐直接用：

openspec init --tools codex

如果团队里还用 Claude Code、Cursor，也可以指定多个：

openspec init --tools codex,claude,cursor

五个常用指令是什么意思？

OpenSpec 默认使用 core 工作流，包含五个指令：

指令	对应命令	作用	推荐使用时机
Openspec Explore	/opsx:explore	探索需求、分析问题、比较方案	需求不清楚，还不想正式创建变更
Openspec Propose	/opsx:propose	创建 change，并生成规划文件	准备正式做一个功能、修复或重构
Openspec Apply Change	/opsx:apply	按 tasks.md 实现代码	规划确认后，开始动代码
Openspec Sync Specs	/opsx:sync	把 delta specs 合并到主 specs/	长周期变更或想单独同步规格
Openspec Archive Change	/opsx:archive	同步并归档完成的 change	功能完成、测试通过后收尾

最常用的是这三个：

Propose -> Apply Change -> Archive Change

Explore 是可选的前置分析。Sync Specs 通常不需要单独执行，因为 Archive Change 一般会在归档时处理同步。

推荐使用流程

假设要做一个订单筛选功能，可以这样使用。

第一步，创建变更规划：

Openspec Propose add-order-filter

OpenSpec 会创建：

openspec/changes/add-order-filter/
├── proposal.md
├── design.md
├── tasks.md
└── specs/

这一步重点是确认需求和实现边界，例如：

• 要支持哪些筛选条件。
• 前端交互怎么展示。
• 接口参数怎么传。
• 哪些内容不在本次范围。
• 最终如何验收。

第二步，确认规划没问题后开始实现：

Openspec Apply Change add-order-filter

AI 会读取 tasks.md，按任务清单修改代码，并逐步勾选完成项。

第三步，功能完成后归档：

Openspec Archive Change add-order-filter

归档时会把本次变更的规格同步到主 openspec/specs/，并把 change 移入：

openspec/changes/archive/

这样，一次功能开发就完整留下了规划、任务、规格变化和归档记录。

可以用自然语言代替指令吗？

可以，但要看上下文是否清楚。

比如你先执行了：

Openspec Propose add-order-filter

然后在对话里说：

开始修改代码

如果当前只有这一个 change，Codex 通常能理解为开始执行 Apply Change。

功能完成后你说：

功能完成了，同步归档吧

通常就等价于执行 Sync Specs + Archive Change。

这种用法是可以的，但我建议遵守一个规则：

当前上下文很清楚时，可以用自然语言；项目里有多个 change 或换了新会话时，一定要带 change 名。

更稳的写法：

请按 add-order-filter 这个 OpenSpec change 的 tasks.md 开始实现

请同步并归档 add-order-filter 这个 OpenSpec change

这样可以避免 AI 选错变更。

关于 AGENTS.md

有些教程里会看到 AGENTS.md，但当前版本的 OpenSpec 普通项目初始化不一定会生成它。

现在 Codex 接入 OpenSpec 时，更常见的是这些文件：

.codex/skills/openspec-*/
~/.codex/prompts/opsx-*.md
openspec/

AGENTS.md 更多是 Codex 自己的项目说明文件，或者旧版 OpenSpec / workspace 功能中的产物。

所以没有 AGENTS.md 不代表初始化失败。只要 openspec/、.codex/skills/ 和 ~/.codex/prompts/opsx-*.md 存在，Codex 能搜索到 opsx 指令，就可以正常使用。

如果你希望给 Codex 增加项目级长期规则，可以单独创建 AGENTS.md，或者在 Codex 里使用 /init。

使用建议

我的推荐用法是：

简单小改动：

直接让 AI 修改

中等功能或复杂修复：

Openspec Propose
确认 proposal/design/tasks
Openspec Apply Change
Openspec Archive Change

需求不清楚：

Openspec Explore
讨论清楚后再 Propose

多个变更并行：

每次都带 change 名

团队协作：

把 openspec/changes 和 openspec/specs 纳入正常 review

总结

OpenSpec 最值得推荐的地方，是它让 AI 编程从“直接开始改”变成“先形成变更规格，再按任务实现”。

它不适合所有小任务，但非常适合中等以上复杂度的功能开发、重构、复杂 Bug 修复和团队协作。

如果你已经在真实项目里使用 Codex、Claude Code 或 Cursor，我建议至少把 OpenSpec 作为一种可选工作流准备好：

小任务直接聊，重要任务先 Propose。

当你希望 AI 更稳定、更可追溯地完成一次变更时，OpenSpec 会很有帮助。

参考资料

• OpenSpec GitHub
• OpenSpec Getting Started
• OpenSpec Commands
• OpenSpec CLI
• OpenSpec Supported Tools