OpenSpec 的一次变更，到底怎么从立项走到归档？

0030 秒速览：一次变更在磁盘上到底动了什么

读完这一篇，你能自己回答四个问题：我该在终端敲还是在 AI 对话框里敲？打开项目里那个 openspec/ 文件夹，哪几个子目录能改、哪几个不能改？状态显示 blocked by: design 时我到底卡住了没有？以及——归档之后，我怎么确认「真相」真的被更新对了，而不是只听命令说了一声成功。

按你现在的处境，直接跳到这一节

一条可执行的上手路径

先给一组量级

01它到底是什么？——先破掉四个错误印象

「工作流程」这四个字容易让人以为它是一条流水线：立项、设计、开发、测试、上线，一级一级往下走。实际恰好相反——官方把这件事总结成四个英文词：actions, not phases，意思是「这些是随时可以做的动作，不是你必须依次经过的阶段」。下面四个错误印象，是我见过最多的四个。

01.1 它不是「阶段门」——工件任何时刻都能改

01.2 它不是插件，也没有「进入模式」

它没有「打开后进入的交互界面」，没有常驻进程，也没有 openspec start 这种命令——官方文档专门回答过这个问题：没有单独的交互模式可进。你在 AI 助手的对话框里敲一个斜杠命令，那就是「进入 OpenSpec」的全部方式。至于为什么有人会以为它是插件：因为 openspec init 确实会往你的项目里写文件，但写的是给 AI 读的指令文件，不是一个运行中的程序（见 03）。

01.3 它不是任务管理器——唯一的机制是复选框

它不追踪「谁在做哪个任务」，没有看板、没有甘特图、没有负责人字段。tasks.md 只是一份带复选框的清单：- [ ] 没做、- [x] 做完了。整套「施工进度」就靠这一个状态位——/opsx:apply 跑完后重新进来，它从第一个未勾选的任务继续。07 会讲这个设计带来的一个真实后果：归档不会因为你没勾完任务而拦住你。

01.4 它完全不碰 Git——这是设计，不是遗漏

官方团队文档里有一句可以直接引用的原话：OpenSpec never touches git。展开说：它不提交、不建分支、不推送、不拉取，连它自己的 beta 功能 stores（把「规划」放到一个独立仓库、多个代码仓都能指向它）也不会自动 clone 或 sync。

它只做一件事：在项目根目录的 openspec/ 里读写 Markdown。剩下的——什么时候提交、走哪个分支、PR 怎么评审——全部交给你现有的 Git 工作流。对你的实际含义是：openspec/ 就是个普通目录，该跟着代码一起提交，specs、进行中的 changes、归档三者都在你的项目历史里。

01.5 它是什么（一句话版本）

这里有两个词必须立刻分清，否则后面所有细节都会错位——specs 是现在时，change 是将来时：

01.6 机制：三层分工，各管一件事

整套流程能同时做到「灵活」和「不跑偏」，靠的是三层分工。理解这三层，就理解了后面所有 JSON 输出（一种机器可读的键值文本格式）、文件路径与命令行为的来源：

02它解决什么问题？——多写一小段计划，换来了什么

说句公平的话：这套流程确实多了一道手续——你要先写一小段计划，才能让 AI 动手。如果你从没被下面这三个场景咬过，这道手续对你就是纯成本。反过来，如果被咬过，你会知道它换来的东西值不值：

02.1 官方口径换来的四件事（附我的判断）

下面第一、二列来自官方 overview 文档，第三列是我自己的判断——厂商说的「得到什么」通常都成立，问题在于「什么条件下才成立」：

02.2 一个必须先接受的现实：它会变

这篇文章讲的是一个移动中的对象。截至 2026-09-13，我实测到的节奏是这样的（复核方式见 98，命令可原样粘贴）：

结论很实际：本文每一个「坑」都标注了它属于哪个版本。1.13.0 一次性修掉了好几个「静默失效」的问题（14），如果你的版本更旧，那些坑就是活的。openspec --version 是第一件该做的事。

03我该在哪敲命令？——终端和对话框的两半架构

理解这套流程最容易卡住的一点，不是命令多，而是命令跑在两个不同的地方。官方文档把它称为「最常见的绊脚石」：一半在终端，一半在 AI 对话框。把这件事记住，后面 90% 的「为什么没反应」你都能自己回答。

03.1 两半各自干什么

03.2 在终端里敲斜杠命令，会发生什么

这是最常见的第一个错误。它看起来像报错，其实不是——斜杠命令压根不是终端命令，你在跟空白的另半边说话。

$ /opsx:propose add-dark-mode
zsh: no such file or directory: /opsx:propose

$ openspec init          # 装斜杠命令，一次就好
$ openspec status --change add-dark-mode --json
# 然后回到 AI 对话框里敲 /opsx:propose

03.3 openspec init 到底做了什么

它做两件事：① 在你的项目里建出 openspec/ 骨架；② 把你选中的 AI 助手所需的指令文件写进对应目录——可能是 skill，可能是 command 文件，也可能两样都写。这两者的区别决定你后面怎么敲命令：

03.4 我这条命令到底该怎么敲

同一个意图，为什么每个工具写法不一样？因为文件名决定了你怎么敲。下面是官方 How To Invoke 表在 2026-09-13 的样子，第三列是我自己的「怎么确认自己属于哪一行」：

03.5 装了却敲不出来，按这个顺序查

04磁盘上到底有哪几个目录？——真相、提案、历史

整套工作流程在磁盘上只围绕一个目录转：项目根目录下的 openspec/。它里面有三类东西，用「时态」区分最清楚——现在时的真相、将来时的提案、过去时的历史。

04.1 目录长什么样（含真实文件树）

openspec/
├── specs/                           # ① 真相：系统现在是什么样
│   ├── auth/spec.md                 #    按"能力"分目录，每个能力一份 spec.md
│   ├── payments/spec.md
│   └── ui/spec.md
├── changes/                         # ② 提案：正在进行的变更，一次一个文件夹
│   ├── add-dark-mode/
│   │   ├── proposal.md              #    为什么做
│   │   ├── specs/ui/spec.md         #    delta：这次要改什么（不是整份规格）
│   │   ├── design.md                #    怎么做
│   │   ├── tasks.md                 #    分几步做（唯一会被"执行"的工件）
│   │   └── .openspec.yaml           #    可选元数据：schema / created / skip_specs / retire_capabilities
│   └── archive/                     # ③ 历史：做完的变更按日期封存
│       └── 2025-01-24-add-auth/     #    日期前缀保证天然按时间排序
│           ├── proposal.md
│           ├── design.md
│           ├── tasks.md
│           └── specs/auth/spec.md
└── config.yaml                      # 项目级配置（可选但推荐）

04.2 这张树不是示意图，是我从官方仓库数出来的

上面那棵树的结构来自官方 Concepts 文档；下面这组数字来自我在 2026-09-13 抓取的官方仓库自己的 openspec/。提醒一句：它们每天都在动，换个日子抓就会得到不同的值——复核命令见 98。

归档目录里的日期前缀能直接看出版本的演进史：最早的一批是 2025-01-11-add-update-command、2025-01-13-add-list-command；最新的一批是 2026-05-06-*（同一天归档了两个 workspace 相关的变更）、2026-05-14-workspace-change-planning，最后停在 2026-07-28-fix-schema-init-force-validation-order。一共分布在 31 个不同日期上，其中 2026-02-17 一天就归档了 8 个。同一天的多个变更可以同批归档——这一点对 12 要讲的并行流程很关键。

04.3 三个区域的规则完全不一样

04.4 一个真实的 .openspec.yaml——两行字管四件事

变更目录里那个可选文件，是我在官方仓库里实测到的样子。它非常短——我抓的进行中变更 fix-archive-retirement-guidance，整个文件只有 schema 和 created 两行、40 字节：

# openspec/changes/fix-archive-retirement-guidance/.openspec.yaml
schema: spec-driven
created: 2026-08-19

两行字背后是这个文件能承担的四件事，每一件都只在特定场合才需要写：

04.5 官方文档在这里落后于官方代码

05四件工件谁依赖谁？——是菱形，不是一条箭头

一次变更里的四件工件不是四个章节，而是四个各自回答一个问题的文件。它们的关系被写进 schema（一份描述「有哪些工件、谁依赖谁」的 YAML 配置；YAML 是一种靠缩进表达层级的文本格式），而 schema 决定命令行会告诉你「下一步该写哪件」。

05.1 四件工件各管一件事

05.2 那处自相矛盾：线性箭头 vs 菱形依赖

四件工件的顺序被反复表述为一条箭头：proposal → specs → design → tasks。这个说法出现在官方 README、overview 文档，以及 Concepts 文档的「内置 schema」一节。

但同一份 Concepts 文档在上一节贴出的 schema 原文，写的是另一种东西：

# openspec/schemas/spec-driven/schema.yaml（官方 Concepts 文档里的原文）
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # 根节点
  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # 只依赖 proposal
  - id: design
    generates: design.md
    requires: [proposal]      # 也只依赖 proposal —— 与"specs 之后才是 design"不符
  - id: tasks
    generates: tasks.md
    requires: [specs, design] # 要两件都齐

把它画成图，形状不是一条链，而是一个菱形——specs 和 design 是并排的两条边，不是先后的两级：

05.3 那么「可以跳过 design」到底能不能跳

更微妙的是同一份文档、同一个 schema 的下一段那句话：「你可以跳过 design，如果不需要它」（原文：You can skip design if you don't need it）。但按上面的 requires，一旦跳过 design，tasks 就会缺一条依赖——而官方 CLI 文档里的示例输出正是这么显示的：

$ openspec status --change add-dark-mode
Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)     # ← 跳过的代价：tasks 卡住

所以「可以跳过」这句话，在默认 schema 下的真实含义是：你确实可以不要 design，但你得用别的方式让 tasks 变得合法——要么换一个不含 design 的自定义 schema（10 给了完整写法），要么手写 tasks.md（为什么「有效」，见下一节）。

05.4 三态与「下一步是什么」

每件工件只有三个状态，判定规则简单到近乎粗暴——看文件在不在，以及它依赖的工件是不是都齐了：

05.5 status --json 的真实形状

命令行把状态直接以 JSON（一种机器可读的键值格式）暴露给 AI 用，这是 skill 与引擎之间的正式接口。官方给的样例长这样（字段名保留原样，注释是我加的）：

$ openspec status --change add-dark-mode --json
{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isPlanningComplete": false,
  "isComplete": false,
  "applyRequires": ["tasks"],                     # 能不能开工，只看这一条
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
    {"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked",
     "requires": ["specs", "design"], "missingDeps": ["design"]}
  ]
}

两个容易被忽略但很有用的细节：

• 列表顺序是依赖顺序，而且同时就绪的工件按 schema 声明顺序排、不按字母序（默认 schema 里 specs 和 design 都是 proposal 之后立刻可写，官方明确说它们保持 schema 里的先后）。所以「第一个 ready 的条目就是下一步该写的」可以直接当规则用。
• isPlanningComplete 只回答「规划工件齐不齐」，不回答「活干完没有」。想看实施进度得看 tasks.md 的勾选数（/opsx:apply 与 /opsx:archive 会替你数）。isComplete 是它的兼容别名，值相同。

05.6 边界：这道「门」是命令，不是机制

06delta 归档时到底怎么合并？

如果整套流程只有一处必须真懂，那就是这一节。delta 是「改动清单」，而不是「新版本的规格」；归档时它的每一节被应用到主规格上。理解了合并规则，你才能预判「归档之后我的 specs 会变成什么样」——这是新手最容易在归档后才发现问题的地方。

06.1 delta 长什么样

它是一份普通 Markdown，用二级标题把「这次要做的操作」分成几节。下面这份 delta 放在变更目录里的 specs/auth/spec.md，注意它的措辞全是「要变成什么」，不是「现在是什么」：

# Delta for Auth（change 内 specs/auth/spec.md）

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA.)

06.2 四种操作的归档行为

06.3 ## Purpose：只有「新能力」才需要它

当你的 delta 创建的是一个此前不存在的能力（主规格里还没有那个目录），可以在文件开头写一小段 ## Purpose，说明这个能力是干什么的。归档时它会成为新建主规格的 Purpose 段。

06.4 判断该写 ADDED 还是 MODIFIED

06.5 退役一个能力：全流程唯一的「删除」

当一次变更删掉了某个能力的最后一条 requirement，合理的结果是这份规格本身没有存在意义了。OpenSpec 的处理方式很克制——它不是「顺手删掉」，而是必须被显式要求。这是官方文档里最细的一处设计，值得完整走一遍：

07从立项到归档，一次变更要走几步？

把前面的零件拼起来，一次完整的工作流程是这样走的。我按「你在哪敲、磁盘上发生了什么、这一步谁在干活」三样对齐来写——这三样对齐之后，「流程」才算真的清楚。

07.1 七步时间线

$ npm install -g @fission-ai/openspec@latest
$ cd my-app
$ openspec init                       # 建 openspec/ 骨架 + 写指令文件
$ openspec --version                   # 第一件该做的事：先知道自己是哪个版本

07.2 哪几步是必须的

07.3 一条来自官方的最佳实践：一次变更只做一件事

08最小例子：add-dark-mode 走一遍

用一个足够小、但每个环节都真实存在的例子把流程走完：给一个应用加暗色模式。这个例子的原始版本出自官方 README 的演示；下面我把它展开成「每个文件里到底写了什么、归档后主规格变成什么样」，并补上官方演示里没显示的中间状态。

08.1 目标与起点

起点：一个已有前端项目的仓库，样式系统是现成的（所以这是典型的 brownfield 改动——在已有项目上改，不是从零开新项目）。目标：用户能切换亮 / 暗主题，默认跟随系统偏好。

# 终端：只做两件事
$ npm install -g @fission-ai/openspec@latest
$ cd my-app && openspec init
# 之后都在 AI 对话框里

08.2 四步走完（每一步的状态变化）

你： /opsx:explore
AI： 你想探索什么？
你： 想加暗色模式，但不确定怎么加才干净。
AI： 我看了一下你的样式设置……最干净的路径是 CSS 变量 +
     一个小的主题 context，配系统偏好检测。不引入新依赖。
     要把它立成变更吗？

你： /opsx:propose add-dark-mode
AI： Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做、改什么
     ✓ specs/       — 需求与场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实施清单
     Ready for implementation!

### 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

你： /opsx:apply
AI： 实施任务……
     ✓ 1.1 增加主题 context provider
     ✓ 1.2 创建切换组件
     ✓ 2.1 加入 CSS 变量
     ✓ 2.2 接上 localStorage 持久化
     全部任务完成！

你： /opsx:archive
AI： 归档到 openspec/changes/archive/2026-09-13-add-dark-mode/
     规格已更新。可以开始下一个功能了。

08.3 归档前后，磁盘上变了什么

openspec/
├── specs/
│   └── ui/
│       └── spec.md   ←──────┐
└── changes/                 │
    └── add-dark-mode/       │
        ├── proposal.md      │
        ├── design.md        │
        ├── tasks.md         │
        └── specs/ui/        │
            └── spec.md ─────┘ 合并

openspec/
├── specs/
│   └── ui/
│       └── spec.md   # 已含暗色模式的需求
└── changes/
    └── archive/
        └── 2026-09-13-add-dark-mode/  # 全部保留
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/ui/spec.md       # delta 原文也在

这里有一个很多人第一次会困惑的点：delta 文件在归档后依然存在。它是被抄送到主规格，而不是移动过去——所以归档目录里那份 specs/ui/spec.md 内容还是「这次要改什么」（ADDED / MODIFIED 的措辞），而主规格里那份已经变成了「系统现在是什么样」。两份文件、两种时态，这是设计而非重复。

08.4 合并那一刻，具体发生了什么

以 ADDED 为例：主规格里新增一节 ### Requirement: Theme selection，连同它的 #### Scenario: ... 一起追加进去。已存在的其他需求一个字都不动——这正是 delta 机制的核心好处：你改十个能力中的一个，另外九个不受影响。

08.5 别用「命令退出码 0」当作合并正确的证据

08.6 自己复核这个例子最快的方法

$ mkdir /tmp/osx-demo && cd /tmp/osx-demo
$ git init && openspec init
$ git add -A && git commit -m "before change"   # 先存一个基线
# 在 AI 对话框里：/opsx:propose add-dark-mode → 读一遍 → /opsx:apply → /opsx:archive
$ git diff openspec/specs/                      # ← 合并到底改了什么，全在这里
$ git log -p openspec/specs/                    # 看历史上每次归档的空白改动（见 14 节）

09我该用几条命令？——core 与 expanded 两档

命令不是一次全给你的。新装默认只装 6 条（core 档），想要更细的控制再切到 expanded 档。这不是「阉割版」，官方把它当作给新手的默认节奏来设计：先用最少的命令把流程跑顺，再按痛点加。

09.1 core（默认）：六条命令

09.2 expanded：六条更细的控制

09.3 怎么切换到 expanded

$ openspec config profile           # 交互式选择档位（也有 openspec config profile core 这种直给写法）
$ openspec update                  # 必须补这一步，命令文件才会真正生成

09.4 先用 core 跑通，再按痛点切

10配置与 schema：怎么改才不跑偏

到这里为止，流程都是「AI 按模板写文件」。但模板里注入什么，是由两层东西决定的：项目配置 config.yaml 决定「这个项目的约定」，schema 决定「有哪些工件、谁依赖谁」。两者都能改，而且改动立刻生效（不需要重启，因为每次调用都重新读一遍）。

10.1 openspec/config.yaml 的三个字段

一份可以直接抄着改的最小 config.yaml（结构取自官方文档的示例，把内容换成你自己的）：

# openspec/config.yaml
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

官方仓库自己的配置是一个更好的真实样本：它把技术栈（TypeScript、Node ≥20.19.0、pnpm、Commander.js）、产品语言约定（「规格要用面向用户的产品行为语言写」「能用正面表述就不要用实现否定的 SHALL」）和跨平台约定（「路径一律用 path.join()，永不硬编码斜杠」，因为工具要跑在 macOS / Linux / Windows 上）都放进 context，再按 specs / tasks / design 分别加规则。注意它的写法：这些都是「每次写工件都会用到的判断标准」，而不是「这一次要做的事」——后者属于 proposal，不该进 config。

10.2 注入是怎么发生的（两个标签）

10.3 三个会咬人的配置细节

10.4 schema 的四级优先级

新建一个变更时，用哪套 schema 是按这个顺序定的（从高到低）。这个顺序解释了两件事：为什么「这次想试个新流程」不需要改项目配置，以及为什么配置改动不需要重启。

10.5 自定义 schema：给「跳过某件工件」一个正当做法

回到 05 那个矛盾（「可以跳过 design」vs tasks 依赖 design）。正规解法不是手写文件，而是写一套自己的 schema：

$ openspec schema fork spec-driven my-workflow   # 从内置的拷贝一份改
$ openspec schema init research-first            # 或从零交互式创建
$ openspec schema validate my-workflow           # 改完先验证结构
$ openspec schema which my-workflow              # 排查"到底读的哪一份"

官方给的例子是一个「研究先行」的流程：在 proposal 前面插一个 research 工件，并让 tasks 只依赖 proposal——于是 specs 和 design 就被合法地跳过了（不是绕过，而是这套图里本来就没有它们）：

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []            # 先做研究
  - id: proposal
    generates: proposal.md
    requires: [research]    # 提案基于研究
  - id: tasks
    generates: tasks.md
    requires: [proposal]    # 跳过 specs 与 design，直接拆任务

10.6 一句判断：这句话下个月还有效吗

11我怎么知道现在卡在哪、下一步该干什么？

这套流程不需要你记「现在处于哪个阶段」，因为你随时可以问。命令行就是那个权威的状态来源，而 skill 也正是靠问它来决定下一步的。会读这几个输出，你就能自己判断「卡在哪、该做什么」。

11.1 四条查询命令

想知道「AI 到底拿到了什么」，直接跑一次 instructions 就行——它把四个来源拼成的整套东西原样打印出来：

$ openspec instructions design --change add-dark-mode --json
# 输出里包含：
#   · 这件工件的模板（要写哪几段）
#   · config.yaml 里的 <context> 与匹配到这件工件的 <rules>
#   · 依赖工件的内容（design 只依赖 proposal，所以这里给的是 proposal.md）
#   · 该工件的 outputPath 与 rules
$ openspec instructions apply --change add-dark-mode      # 施工指令（含"没有 delta"的警告）
$ openspec instructions archive --change add-dark-mode --json   # 归档的只读输入，不会归档

11.2 validate：能拦住什么、拦不住什么

把两条最常用的接进 CI，就是这两行：

# 提交前：抓住"归档了但任务没勾完"的变更
$ openspec validate --archived

# CI 里：全量校验，只要与问题相关的那几项，保留退出码
$ openspec validate --all --report findings --json

11.3 「校验通过」不等于「合并正确」

11.4 1.13.0 新增的一道提醒：apply 的「就绪」可能不完整

这一条很典型，体现了这套流程的「就绪」判定有多细。1.13.0 之前的逻辑是：apply 只看 schema 的 apply.requires（也就是 tasks 在不在）。于是出现了一个尴尬状态——

如果你的 tasks.md 先于 specs 写好了，那么：openspec status 认为「可以开工了」，但这次变更其实一条 delta 都没有，而「零 delta」正是 openspec validate 要拒绝的状态。两边对同一件事给出了相反的判断。

1.13.0 的处理方式是给提醒、不给拦截：openspec instructions apply 现在会把「这次变更没有 delta specs」作为警告报出来（文本和 JSON 都有），并给出两条出路：

同一版还改进了「卡住时的提示质量」：以前一个只有 proposal 的变更会告诉你 Missing artifacts: tasks，读起来像是「照着 proposal 直接写 tasks 就行」——而它其实还缺 tasks 自己依赖的 specs。现在会把缺失的整条前置链报出来（JSON 里的字段是 missingPrerequisites）。这类「把话说完整」的改动，是 1.13.0 的主题。

11.5 一句话选命令

12两个变更同时改同一块，会怎样？

「可以同时做多个变更」是这套设计反复宣传的优点，而且它在这个项目的官方仓库里被大规模实践着——我在 2026-09-13 数出来是 26 个进行中的变更、83 个已归档、36 份主规格同时存在。但并行有一个真实且被官方自己记录在案的失败模式，而且官方对外文档对它的描述和仓库内部复盘对它的描述并不一致。这一节把两边都摆出来。

12.1 为什么并行基本不会撞车

12.2 危险点：同一条 requirement，后归档的会覆盖先归档的

官方文档对这个场景有两种口径。我把它们并排放在这里，因为它们说的其实是两个不同层次的「冲突」——注意两段引文都来自官方，只是出自不同的文档：

看起来矛盾，其实是同一个问题的两面：Git 只能保护「文件级」的并发写入；一旦两个 delta 都顺利落到了主规格上（同一分支先后归档、或分支已合并），保护层就消失了，此时决定结果的是 OpenSpec 自己的合并算法——而它是整条替换语义，没有三方合并、没有基准指纹、也没有冲突标记。（把两条口径这样对齐，是我的分析；两份文档本身都没有说「另一个说法不对」。）

12.3 复盘文档里的那个具体案例

12.4 今天的工具做到了哪一步

值得注意那份复盘文档的定位：它是一份设计方案（分四个阶段——先止血、再加变基（rebase：把别人已合入的改动先接到自己分支底下，再重放自己的改动）工作流、再提高 delta 粒度、最后做结构化规格图），而不是已实现的功能清单。就我在 2026-09-13 核对到的状态而言，落地的是其中最小的一步——检测，而非拦截：

12.5 三条可操作的防线

12.6 团队场景下还有一条时序约定

13归档前该确认什么？

流程的最后一段有两件事：确认实现与规格一致（verify），以及把变更安全地并进真相（archive）。归档是整条链路上唯一会改主规格的操作，所以它被设计得相当谨慎——值得逐条看清楚。

13.1 verify：三个维度，一份待办

它的输出形态是「问题清单 + 建议」，并明确不阻塞归档（官方大意：它不会拦住归档，只是把你可能想先处理的问题摊出来）。所以别把它当审批门，把它当一份可以立刻执行的待办——尤其是在你手工改过代码之后。

13.2 手工改过代码怎么办

13.3 archive 的七步（含失败回滚）

这是官方 CLI 文档里列出的执行顺序，我按「对你意味着什么」重述：

无人值守时必须显式带 --yes（以及变更名），否则它会停在确认提示上：

# 人在终端：名字就够，它会问你一次
$ openspec archive add-dark-mode

# CI / AI 代理：必须带 --yes，其余参数原样带上
$ openspec archive add-dark-mode --yes

# 想跳过校验：注意它会同时禁用"能力退役"
$ openspec archive add-dark-mode --yes --no-validate

13.4 归档前问自己三个问题

13.5 归档不是「把文件夹收起来」

14哪些坑会「不报错，但结果是错的」？

这一节集中讲一类最危险的问题：openspec validate 说合法、openspec archive 打印成功并退出 0，而主规格已经悄悄偏离了你的本意。OpenSpec 1.13.0（2026-09-09）一次性修掉了其中四个——所以每个坑都附带版本分界，先跑 openspec --version 对一下。

14.1 四个静默失效（1.13.0 修复）

14.2 另外四个与版本无关的操作坑

14.3 一个具体到能抄的例子：REMOVED 的列表符号

这是 14.1 第一条的可复制形态。左边那种写法在 1.13.0 之前什么都不会发生；右边那种才是稳妥的：

## REMOVED Requirements

* ### Requirement: Remember Me
* (Deprecated in favor of 2FA.)

## REMOVED Requirements

- ### Requirement: Remember Me
- (Deprecated in favor of 2FA.)

14.4 边界：这些坑会随版本失效，别当永久知识

15什么时候不该用这套流程？

这一节可能是全文最省你时间的一节。官方自己在文档里就写了这条边界，原话大意是：一行错别字的修复不需要三条需求和一份设计文档——让仪式感与风险相匹配（Match the ceremony to the stakes）。把这套流程用在它不该用的地方，最常见的后果不是效率低，而是团队开始绕过它，然后连该用的地方也不用了。

15.1 按风险配档位

15.2 三个「看起来该用、其实先别用」的信号

15.3 让仪式感与风险成正比

15.4 最后一条边界：它是「协议」，不是「保证」

16和 Spec Kit / Kiro / 什么都不用比，该怎么选？

官方 README 里有一节叫「How we compare」，直接点名了另外两个选项。这一节我把它重述一遍，并加上我自己的判断列——因为厂商自述的对比天然带立场，而你要做的是判断「哪个约束符合我的工作方式」。

16.1 三家对比（第二列是官方口径，第三列是我的判断）

16.2 真正该比的三个问题

抛开功能表，选规格流程时值得问的是这三件事——它们才决定你三个月后还在不在用它：

16.3 按「我最想被哪件事约束」选

17术语对照表

这套流程的术语密度不低，而且有几个词在日常英语里很普通、在这里却是专指。下表第三列是「为什么重要 / 何时用 · 别当什么用」——它才是这张表的重点。第一次读遇到不懂的词，可以直接跳到这里查，但正文里每个词的首次出现处都已经解释过了。

98参考来源与证据边界

本文的事实分三类：官方文档（可点击核对）、我自己实测 / 算出来的数（附可粘贴的复核命令）、以及我的判断（在正文里都用「我的判断 / 我建议 / 大概」这类措辞标出）。下面依次交代。

98.1 官方来源（均为 2026-09-13 抓取 main 分支）

98.2 我自己实测 / 自算的数据（附复核方式）

下面每一条你都能用同样的命令重跑一遍。这些数字本身就是「一手料」——它们不在任何文档里，需要真的去数：

# ① GitHub 仓库状态（本文取 68,077 stars、最近推送 2026-09-11）
$ curl -s https://api.github.com/repos/Fission-AI/OpenSpec \
    | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['stargazers_count'],d['pushed_at'])"

# ② npm 版本与发布时间（本文取 latest=1.13.0 @ 2026-09-09，共 48 个版本）
$ curl -s https://registry.npmjs.org/@fission-ai/openspec \
    | python3 -c "import json,sys;d=json.load(sys.stdin);v=d['dist-tags']['latest'];print(v,d['time'][v],len(d['versions']))"

# ③ 上周下载量（本文取 378,332，窗口 2026-09-05 → 2026-09-11）
$ curl -s "https://api.npmjs.org/downloads/point/last-week/@fission-ai/openspec"

# ④ 官方仓库自己用了多少规格 / 变更（本文取 36 / 26 / 83，顶层 6 个条目）
$ curl -s "https://api.github.com/repos/Fission-AI/OpenSpec/git/trees/main?recursive=1" \
    | python3 -c "
import json,sys
paths=[t['path'] for t in json.load(sys.stdin)['tree']]
top=sorted({p.split('/')[1] for p in paths if p.startswith('openspec/')})
specs={p.split('/')[2] for p in paths if p.startswith('openspec/specs/') and len(p.split('/'))>2}
ch={p.split('/')[2] for p in paths if p.startswith('openspec/changes/') and len(p.split('/'))>2}
ar={p.split('/')[3] for p in paths if p.startswith('openspec/changes/archive/') and len(p.split('/'))>3}
print('top',top); print('specs',len(specs),'active',len(ch-{'archive'}),'archived',len(ar))"

发版节奏那个「≈8.7 天」是这么算出来的，你可以手工复核：1.6.0 发布 2026-07-10，1.13.0 发布 2026-09-09，相隔 61 天；其间共有 7 次发版间隔（1.6.0→1.7.0→…→1.13.0）；61 ÷ 7 ≈ 8.71 天。最近两次分别是 1.11.0（08-26）→1.12.0（09-03）的 8 天、1.12.0→1.13.0（09-09）的 6 天。这是算术，不是引用。

98.3 官方对外口径与我实测数字的对账

同一个项目有两个对外出口（官网首页与 GitHub / npm 接口），它们给的数不一定同步。我把两边都摆出来，并说明各自的口径——这比替你选一个更有用：

98.4 证据边界（请这样使用本文）

99一句话总结