1. OpenSpec 是什么

OpenSpec 是一个开源的规格驱动开发（Spec-Driven Development）框架，由 Fission-AI 维护。它不试图教会 AI 新的编程技巧，而是在人和 AI 之间加一层轻量级的「同意层」——在任何代码被写出来之前，双方先就「要做什么」达成一份写在纸面上的约定。

核心设计：

1. Specs（规格） — 描述系统当前行为的 Markdown 文档，按能力（capability）组织在 openspec/specs/，是「唯一事实来源」
2. Changes（变更） — 每项工作独立一个文件夹（openspec/changes/<name>/），内含 proposal、design、tasks、delta specs 四个产物
3. Delta（增量） — 不重写整份规格，只描述 ADDED / MODIFIED / REMOVED 的差异，让棕地项目（brownfield）也能低成本接入

项目哲学写得很直白：

1
2
3
4

→ fluid not rigid          流动，而非僵化
→ iterative not waterfall  迭代，而非瀑布
→ easy not complex         简单，而非复杂
→ built for brownfield     为存量代码而生，不只是绿地

• 项目仓库：https://github.com/Fission-AI/OpenSpec
• 安装包：@fission-ai/openspec
• 当前版本：v1.7.0（2026 年下半年）

版本演进大致：0.x 时代初版以 Claude Code 优先；1.0.0 稳定了 CLI、规格格式与归档流程；1.6.x 带来 Stores（独立仓库规划）Beta 与自定义 schema；1.7.0 增加了 CodeArts/Hermes/ZCode 支持，并将 skills 改为可静态分发。

支持 Claude Code、Cursor、Codex、Gemini CLI、Copilot、亚马逊 Q、Devin、Kilo Code、Trae 等 30+ 种 AI 工具。OpenSpec 本身也用 OpenSpec 开发——主仓库的 openspec/specs/ 和 openspec/changes/ 是活生生的实例，是看「真实规模的规格长什么样」的好地方。

2. 为什么需要它

AI 编程助手确实很能打，但无规格编程的体验，多数开发者都遇到过：

• 你在聊天框里写了句「加深色模式」，AI 立刻 npm create vite，选了一个你不想要的方案
• 需求只活在上下文里，窗口一关、会话一换，设计意图就蒸发，下一次 AI 重新自由发挥
• 改行为没有 diff 概念，AI 动不动重写整个文件，review 的时候只能全量读
• 棕地项目里你只想改 auth/，AI 却觉得应该顺手把整个 user/ 也重构了

OpenSpec 解决的是「对齐问题」：把需求从易失的聊天记录里捞出来，放进仓库里可版本控制的规格文件，让 AI 先看齐、再动手。

3. 核心概念：五个词就够了

OpenSpec 的整套心智模型可以压缩成五句话：

1. Specs 是真相。 openspec/specs/ 里的文件描述系统现在如何工作，按域组织（auth/、payments/、ui/）。每条 Requirement 配若干 Scenario，使用 RFC 2119 的 SHALL / MUST / SHOULD / MAY 关键词。

2. Change 是一个工作单元。 任何行为变化——新增、修改、移除——都放进 openspec/changes/ 下的独立文件夹，一个变更、一个文件夹、一个特性。

3. Delta 规格描述变化，而非世界。 在 change 文件夹里，不重写整份 spec，只写增量：ADDED 这条需求、MODIFIED 那条、REMOVED 这个。这是 OpenSpec 对存量系统友好的关键技巧——你描述的是 diff，不是目标状态。

4. 产物按依赖链生成。 一个 change 里包含若干文档，按自然顺序展开：

   1 2	proposal ──► specs ──► design ──► tasks ──► implement why what how steps 动手做

5. 归档（archive）把变更折叠回真相。 工作完成后 archive 操作把 delta spec 合并进主规格，change 文件夹移入 changes/archive/ 并打上日期戳。规格描述的是新的现实，循环闭合。

两个目录，specs/ 是事实，changes/ 是提案。归档就是把提案变成事实。

OpenSpec 反复强调一个短语：「enablers, not gates」（助推器，而非闸门）。传统的规格流程是瀑布：规划期过了才能进实施期，回头是痛苦的。OpenSpec 拒绝这一点。proposal → specs → design → tasks 的顺序只表示「下一步可以做什么」，而不是「必须做什么」。实现到一半发现设计错了？直接改 design.md，继续干。意识到范围应该缩小？回头更新 proposal。没有任何东西锁死。依赖关系存在的唯一理由是让 AI 有上下文（没有规格就写不出好任务），不是为了限制你。代价也诚实：因为没人推着你走，你得靠自己的纪律让 change 保持聚焦，而不是任其蔓延。

4. 核心工作流：从想法到归档

新版 OPSX 工作流（现为默认）把一次功能开发拆成如下路径，可选环节用括号标出：

1

(/opsx:explore) → /opsx:propose → /opsx:apply → /opsx:archive

4.1 Explore — 动手之前的思考伙伴

触发时机： 你想做点什么，但还没想清楚「该做成什么样」。

做什么：

• 读你的代码基线，理解现有结构
• 摆出几种可行方案并给出代价对比
• 把模糊的想法变成具体的计划雏形
• 不产生任何规格文件——是「无毛边试验」

想清楚之后，可以自然过渡到 /opsx:propose。

4.2 Propose — AI 起草，你来审

输入 /opsx:propose add-dark-mode，AI 一次性生成整套规划产物：

1
2
3
4
5
6

openspec/changes/add-dark-mode/
├── proposal.md    # 为什么做、范围、非目标
├── specs/         # 本变更涉及的 delta 需求与场景
│   └── ui/spec.md
├── design.md      # 技术方案、权衡、回滚策略
└── tasks.md       # 实现清单

你读一遍、改几处、批准，AI 才被允许进入实现。这一步的收益是：在 200 字 proposal 里发现「方向错了」的成本几乎为零，等到 AI 写完 400 行代码再发现就是真金白银。

4.3 Apply — 按任务清单干活，随时回头修

• 按 tasks.md 的 checkbox 逐个实现
• 发现 design.md 不再成立，直接改，然后继续
• 完成一项勾一项，进度对外可见
• 支持的命令还有 /opsx:update（修订产物）、/opsx:continue（逐产物生成）、/opsx:ff（快进生成全套）

4.4 Archive — 合并 Delta，落地为真相

1

/opsx:archive

• 把 change 里的 ADDED / MODIFIED / REMOVED delta 合并进 openspec/specs/ 的主规格
• 把 change 文件夹挪到 changes/archive/2025-01-23-add-dark-mode/ 并加日期戳
• 主规格从未实现的场景中删除（若 delta 与此冲突会停下来报告差异，而不是撒谎说「已同步」）

归档之后，你的规格说的就是系统现在的样子，可以开始下一项工作。

4.5 目录结构一览

初始化后仓库里的 openspec/ 目录通常长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

openspec/
├── config.yaml          # 项目配置：schema、context、rules
├── specs/               # 主规格：当前系统行为的真相
│   ├── auth/spec.md
│   └── ui/spec.md
├── changes/             # 进行中的变更
│   ├── add-dark-mode/
│   │   ├── proposal.md
│   │   ├── specs/
│   │   ├── design.md
│   │   └── tasks.md
│   └── archive/         # 已归档变更
│       └── 2025-01-23-some-feature/
└── schemas/             # 可选：自定义模板
    └── your-schema/
        ├── schema.yaml
        └── templates/

.claude/skills/ 里会自动生成 AI 助手可直接调用的 SKILL.md 文件，以 /opsx:propose、/opsx:apply 等命令形式暴露给 harness。

4.6 OPSX vs 旧版工作流

仓库里的旧版（legacy）工作流用 /openspec:proposal 号令，OPSX 是重构后的新标准。差异一张表：

OPSX 的关键洞察：工作不是线性的。 OPSX 停止假装它是。

对于探索驱动的场景，OPSX 也提供 expanded profile：/opsx:new（只铺骨架）、/opsx:continue（一次一个产物）、/opsx:ff（一次全生成）、/opsx:verify（验证实现）、/opsx:bulk-archive（批量归档）、/opsx:onboard（全流程导览）。用 openspec config profile 切换，用 openspec update 生效。

5. Spec 格式：纯 Markdown，无特殊语法

这是 OpenSpec 最讨喜的部分——规格文件就是一种带约定的 Markdown，不需要学 DSL：

1
2
3
4
5
6
7
8
9

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- WHEN the user clicks the theme toggle
- THEN the app switches to dark mode and persists the choice

修改是 ## MODIFIED Requirements，删除是 ## REMOVED Requirements。AI 写这些文件，你审查，任何一行看不懂就是这条规格的一个问题——可观察、可测试、可交接是硬要求。

名词强度也有讲究：

写规格默认用 MUST/SHALL，SHOULD 只在你真的想要「除非有充分理由不做」时才用。

6. 项目配置：让 AI 懂你项目的上下文

openspec/config.yaml 是可选但强烈推荐的文件。它能把项目特定的上下文和约束注入所有 AI 生成的产物：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript  

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

context 被包裹在 <context>...</context> 标签里，注入每个产物的指令开头；rules 只在对应产物时生效；schema 决定产物 ID 的集合。这样 AI 不需要每次从头猜你的技术栈或者测试风格。

7. 与同类工具对比

OpenSpec 的官方文档很诚实地给了三方对比：

对使用者最有意义的对比也许是和 Superpowers 的关系——两者都强调「先对齐再写代码」，但路径正交：

可以组合使用：OpenSpec 管「做什么」，Superpowers 管「怎么做」。

8. 安装与支持平台

要求 Node.js 20.19.0 及以上。

1
2
3
4
5
6

# 全局安装
npm install -g @fission-ai/openspec@latest

# 进入项目目录并初始化
cd your-project
openspec init

init 会问你选哪些工具（claude、cursor、codex…），然后把对应工具的 SKILL.md 和命令文件写到你项目的里。之后就能在你的 AI 工具里看到 /opsx:* 系列命令了。升级：

1
2

npm install -g @fission-ai/openspec@latest
openspec update   # 刷新 CLI 生成的指令文件

文档也提供「让 AI 自己来」的选项：把 安装 prompt 贴给你的编程助手，它会安装 CLI、运行 openspec init、做结果验证。

各工具的命令文件形态（完整 30+ 见 Supported Tools）：

注：不同工具对 slash 命令的拼法不同——Claude Code 喜欢 opsx:propose，Cursor 喜欢 opsx-propose，Amazon Q 用 @opsx-propose——但 concept 是同一个。openspec init 结束后会给你的工具精准对应的使用提示。

9. 使用建议

9.1 第一次体验

1
2
3

npm install -g @fission-ai/openspec@latest
cd 你的项目
openspec init          # 选 claude / cursor / codex / ...

然后跟你的 AI 说一句：

1

/opsx:propose add-rate-limiting

重点不是 AI 干得多快，而是它先生成了 proposal.md、spec 增删、design 权衡、tasks 清单——你读了两分钟，改了三个词，然后才批准它写代码。 这一次性的对齐成本，把整个工程的返工率直接砍下来。

9.2 Context hygiene（上下文卫生）

OpenSpec 文档里专门提了一条：规格驱动开发受益于一扇干净的上下文窗口。在开始实现前把 AI 会话里无关的聊天清掉，过程中维持好的会话纪律——长上下文同样会稀释规划的清晰度。

9.3 Model 选择

官方推荐用高推理能力模型跑规划与实现：规划阶段尤其明显，高推理模型在「同义需求识别」「权衡展示」「拆任务粒度」上差距显著。实现阶段模型压力稍小，但建议沿用同一档以免断代。

9.4 Telemetry

OpenSpec 收集匿名使用统计（只有命令名和版本号，无参数、路径、内容或 PII）。CI 环境自动关闭。如需完全关闭：

1
2
3

export OPENSPEC_TELEMETRY=0
# 或遵守 Do Not Track 约定
export DO_NOT_TRACK=1

10. 常见问题

Q: OpenSpec 会让流程变慢吗？

A: 它确实多一步——写个简短计划再动手。但对于大多数场景，这个 200 字 proposal 2 分钟可以读完的东西，能帮你避免上百行错误代码的返工。真正单行修复就别走流程，OpenSpec 也不强迫。

Q: 我的项目是棕地，几十万行代码，怎么用？

A: 这正是 OpenSpec 的发力点。Delta 规格意味着你不需要先写出整个系统的 spec——只要为你正在改的那一小块行为（比如 auth/session-expiry）写 ADDED/MODIFIED delta 就够了。50,000 行的老应用可以一个 change 一个 change 地引入规格，而不需要先停下来写全量文档。

Q: 和 README 里的 AGENTS.md 那种「告诉 AI 本仓库规则」有什么区别？

A: AGENTS.md 是仓库级别的静态 prompt——告诉 AI「本项目用 Prettier」。OpenSpec 的 specs 是——行为层面的、当前有效的、被实现然后通过 archive 循环维护的——规格文档。一个告诉 AI 「规矩」，一个告诉 AI 「现实」。两者正交，可一起用。

Q: 团队跨仓库怎么用？

A: OpenSpec 1.6 起提供 Stores（Beta）：把规划挪到独立的规划仓库，通过 git push 共享给你所有成员和所有 agent。平台团队拥有 specs，产品团队只读引用，规划先于代码存在。（参阅 Stores Beta 指南）

Q: 如何贡献？

A: 小修小补直接 PR。新功能或结构性改动，要求先提一个 OpenSpec change proposal，达成意图与目标对齐再写代码——对自己的规矩，自己也在用。接受 AI 生成代码，前提是标注所用 coding agent 与模型版本。

11. 小结

OpenSpec 的核心洞察：

1. AI 能写代码，不等于 AI 知道你要什么。 先把对齐写下来，再动手。
2. Markdown 规格加 delta 是对棕地项目最低摩擦的规格引入方式。 你描述的变化，不是描述世界。
3. 流动的、非线性的工作流是真实的工作。 阶段闸门是过去式，依赖应该是 enablers 而非 gates。

完整的工作循环：

1
2
3
4

1. (/opsx:explore)   思考与选项
2. /opsx:propose     AI 起草 proposal/spec/design/tasks
3. /opsx:apply       按任务清单实现，可回改
4. /opsx:archive     delta 合并、变更归档

如果你已经在用 AI 编程助手且经历过「说了半天 AI 做歪了」或「代码能跑但设计莫名其妙」的返工，OpenSpec 值得试一次。从 /opsx:propose add-dark-mode 开始，看 AI 是不是先规划再动手。