OpenSpec 到底怎么用

0030 秒速览：三条结论 + 按处境挑入口

读完这篇你能做到一件事：在自己的项目里跑通一次「想法 → 图纸 → 施工 → 归档」的完整闭环，并且知道什么时候不该用它。

你现在的处境，对应该看哪一节

最小可用的一条路（照抄就能跑）

# 第一步：在你的终端里（iTerm / VS Code 终端 / PowerShell 都行）
npm install -g @fission-ai/openspec@latest   # 装 CLI，需要 Node.js 20.19.0 或更高
cd your-project
openspec init                              # 交互式选你的 AI 工具，生成对应的指令文件

# 第二步：切到你的 AI 助手聊天框里（Claude Code / Cursor / Codex …）
/opsx:propose add-dark-mode                # AI 起草图纸，你审
/opsx:apply                                # 照图施工，逐项打勾
/opsx:archive                              # 归档，delta 合进主规格

两条终端命令负责装，三句聊天指令负责干活——整篇就是把这三句背后的东西拆开讲清楚。

01OpenSpec 是什么：先破掉四个最像的错想

错想一：它会替你写代码？

不会，而且这是它刻意不做的部分。真正写代码的仍然是你的 AI 编程助手（Claude Code、Cursor、Codex、GitHub Copilot 这些）。OpenSpec 管的是写代码之前和之后的两件事：动手前把"要做什么、怎么做、分几步"落成文件；动手后验收、把改动合并进"系统现状说明书"、归档留痕。

官方仓库给自己的一句话定位是"一个 AI 原生的、面向规格驱动开发的系统"（an AI-native system for spec-driven development）。规格驱动开发（Spec-Driven Development，简称 SDD）里的"规格"，指的就是这种用自然语言写死的"系统应该表现出什么行为"的说明文件——后面每次出现都按这个意思理解。

换句话说：你的 AI 助手是施工队，OpenSpec 是那张签了字的施工图，加一套把图纸归档的流程。变的是它现在照着图施工，而不是听你临场口述。

错想二：它是一套很重的规格文档体系，得先把规格写全？

不是。它官方明说自己的原则里有一条叫 "built for brownfield not just greenfield"——为存量项目（已经有代码、跑了一段时间的项目，行话叫 brownfield）而生，不只服务从零开始的新项目。落地方式很克制：你不必先把整个系统的规格补全，只为你这一次改动涉及的那部分写规格；主规格随着一次次归档慢慢长出来。

官方 FAQ 里有一句很直白的回答：存量代码库才是主场景（"Existing codebases are the main event"）。所以"接入前得先重构/先补文档"这个担心是反过来的。

错想三：它就是让 AI 写 PRD（产品需求文档）？

不是一类东西，差别有三处，而且每一处都直接影响你会不会用错：

第三条最关键：tasks.md 里是带复选框的清单，AI 施工时会一项项勾掉——你第二天回来能看见"做到第几步了"。

错想四：它跟 TDD（测试驱动开发）是一回事？

不是，但它们不冲突。测试驱动是"先写测试、再写代码"，关注的是代码层面的正确性。规格驱动是"先把要做什么写清楚、再写代码"，关注的是你和 AI 对目标的理解是否一致。规格里可以包含验收场景（场景就是一段"给定…当…则…"的具体例子），测试只是验证手段之一。

它真正对立的做法是"氛围编程"（Vibe Coding）：想到哪说到哪、让 AI 自由发挥。OpenSpec 的定位是给氛围编程补上图纸和归档，而不是给它加一套官僚流程。这一点从它的五条设计原则里能直接看出来（见本节末尾）。

那它到底是什么：一句话 + 一个类比

用装修打个比方：openspec/specs/ 是这套房子现在的样子（哪面是承重墙、水电怎么走）；openspec/changes/ 里的一个文件夹是这一次要动的那面墙的施工图袋；归档就是"改完了，把竣工图并回房子现状图"。

这个类比到哪儿就不准了：真实装修改完就结束了，而软件永远在变——归档之后那份"现状说明书"马上又会被下一次改动盯上。所以别把它当"一次性项目文档"，它是持续被重写的活文档。另外，这里的图纸还要给 AI 看，所以它得写到 AI 能照着做的具体程度。

它的五条设计原则（官方 README 原话）

官方 README 把价值观写成五句短句，理解这五句就理解了它为什么长这样：

02它到底解决什么问题：三个真实失效模式

直接用 AI 写代码，最大的痛点通常不是"代码写得烂"（那看得见、能改），而是决策过程丢了——需求只活在聊天记录里，过一会儿你就想不起当初为什么这么设计。

失效模式一：需求只活在聊天里，AI 会"失忆"

聊天窗口一关、上下文一清，AI 就不知道你们上次谈到哪了。下次改代码，你得把背景重新讲一遍——而且讲的可能和上次不完全一样。更糟的是你自己也会忘：三周后打开 git 历史，满屏 Add feature、Fix bug，没人知道当初为什么这样设计。

OpenSpec 的处理方式很朴素：把这些意图写进仓库里的文件。文件比聊天记录耐用得多——它进 git、能被评审、换模型换工具都不丢，而且 AI 每次都能从文件里读到完整上下文。

失效模式二：AI 自由发挥，范围悄悄蔓延

你让它加个深色模式，它顺手把你的主题系统重构了。这不是它坏，而是它有主动性：只要有机会它认为"顺手"，它就会做。问题在于这些顺手做的东西没经过你同意，也没被记下来。

对抗办法不是把话讲得更狠，而是把边界写进文件：proposal 里有明确的范围段（改什么、不改什么），AI 施工时以文件为准。你审图时最重要的动作之一就是盯住这个"不改什么"。

失效模式三：团队（包括 AI）没有共同语言

产品、后端、前端各说各话，而且现在多了一个成员：AI。一个 change 文件夹恰好是一份产品、工程师、AI 都能读的计划书——它跟代码走同一套协作流程（git 提交、PR 评审），而不是活在某个人的聊天窗口里。

反过来：什么时候别用它

官方 FAQ 的回答是"不，不必什么都用它"——一次改一个错别字，走完整套流程不划算。

03怎么装、怎么升级，以及命令该敲在哪儿

装之前先确认这三件事

第一步：装 CLI（终端）

npm install -g @fission-ai/openspec@latest
# 也支持 pnpm / yarn / bun / nix，分别是：
#   pnpm add -g @fission-ai/openspec@latest
#   yarn global add @fission-ai/openspec@latest
#   bun add -g @fission-ai/openspec@latest
# 装完确认：
openspec --version

第二步：在项目里初始化（终端）

cd your-project
openspec init

# 不想交互式回答问题？可以非交互地指定 AI 工具：
openspec init --tools claude,cursor
openspec init --tools all      # 给所有支持的工具都生成
openspec init --tools none     # 先不生成工具文件
openspec init ./my-project     # 初始化到指定目录

openspec init 会问你用哪个 AI 助手，再按选择生成对应的指令文件（比如 Claude Code 下是 .claude/skills/ 里的 openspec-* 目录）。它是交互式的；在 CI 或非交互环境里跑会因为没有终端可提问而停下——这时用 --tools 明确指定。

升级：两条命令，顺序不能反

升级要分两步，因为指令文件是由"已装好的那个 CLI"生成的：如果你先跑 openspec update 而没升级包，它会告诉你"一切都是最新的"，实际上新版才有的命令根本没生成。

# 1) 先在终端升级包本身
npm install -g @fission-ai/openspec@latest

# 2) 再到每个项目里刷新 AI 指令文件（每个项目各跑一次）
cd your-project
openspec update

好消息是 openspec update 现在会主动问你：它会去 npm 问一句有没有更新的版本，如果发现你落后了，会打印类似这样的提示并提议帮你升级：

# openspec update 可能打印的内容（官方文档示例）
A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

这里有个细节能解释"我明明升级了为什么没生效"：它会去问"当前这个二进制是从哪个目录加载的"，而不是信赖 npm 的退出码。PATH 上还有更靠前的旧安装时，它会告诉你，而不是假装成功——那行 Running from: 就是给你排查用的。

还有一处细节决定"它认为你已是最新"是否可信：skill 文件里记着"是哪个版本生成的"，所以只要版本号一致，它就不动——哪怕你手改过。而命令文件没有版本戳，靠内容比对，你怎么改都会被判定为漂移并覆盖掉。想强制重写就加 --force。

命令敲在哪里：这是新手第一号卡点

OpenSpec 同时有两套命令，它们运行在两个完全不同的地方。搞混这一个事实，后面所有东西都会显得莫名其妙。

两者的关系是单向的：你在终端跑一次 openspec init，它把斜杠命令"装进"你的 AI 工具；之后日常干活基本都在聊天框里。

命令的拼写因工具而异，以 init 的输出为准

标准写法是 /opsx:propose，但不同工具注册命令的方式不同，拼写会变。这跟对错无关，纯粹是各工具加载文件的方式不同。官方给的口径是：一排命令文件叫 opsx-propose.md 的，你敲 /opsx-propose；放在 commands/opsx/ 目录下的，你敲 /opsx:propose。

好消息：openspec init 结束时会把你选中的那几个工具的正确写法打印出来。以它为准，比背上面这张表可靠。

安装相关的三条实务细节

• 命令找不到（openspec: command not found）：多半是全局 npm 的 bin 目录不在 PATH 上。跑 npm prefix -g 看全局包装在哪——macOS / Linux 上可执行文件在它下面的 bin/，Windows 上就在该目录里。把它加进 PATH。（npm bin -g 在 npm 9 已被删除，别再用它。）
• 它不收集你的代码：官方说明遥测只上报命令名和版本号，不含参数、路径、内容和个人信息，CI 环境自动关闭。介意的话一条命令关掉（见 12 节）。
• 卸载没有专门命令：它就是一个全局包加项目里几个文件。跑 npm uninstall -g @fission-ai/openspec，然后按需删掉项目里的 openspec/ 目录和生成出来的工具文件。

04最小例子：一句"我想要深色模式"到代码落地

这是官方 README 里的经典走查，也是你能亲手跑完的最短闭环。全程四步，人只在两个地方把关：审图、验证结果。中间写代码的脏活是 AI 的。

第 1 步：想法模糊？先聊透（不写任何文件）

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

注意这一步不创建任何文件、不写一行代码：它只是把"我模糊地想要深色模式"变成"用 CSS 变量加一个小的主题上下文、探测系统偏好、不加新依赖"这样具体到能开工的方案。你可以探索三条死路、从每条里学到东西，然后只立项活下来的那条。

第 2 步：一句话生成全套图纸

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

到这里，你已经有了一个装好四件东西的文件夹。你应该停下来读它。这是 OpenSpec 存在的意义所在：在它还只是一段话的时候发现理解偏了，而不是在写了 400 行代码之后。

第 3 步：照图施工

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

施工中如果发现图纸不对（比如设计里说存 localStorage，你其实想用 cookie），直接改图纸再继续即可，不必推倒重来——展开见 11 节。

第 4 步：验收归档，主规格同步更新

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

归档做了三件事：把这次改动的规格（delta）合并进主规格、把 change 文件夹搬到归档目录并加上日期前缀、之后它就不再出现在"进行中的改动"列表里。

生成出来的目录长什么样

openspec/
├── specs/                        # 主规格（source of truth）：系统"现在"是什么样
│   └── ui/
│       └── spec.md               # 按能力/领域一个目录一份，比如 ui、auth、payments
├── changes/
│   ├── add-dark-mode/            # 本次改动的"图纸袋"
│   │   ├── proposal.md           # 为什么做、改什么、不改什么
│   │   ├── specs/                # 本次新增/修改的需求（delta）
│   │   │   └── ui/
│   │   │       └── spec.md
│   │   ├── design.md             # 技术方案（简单改动可以不要）
│   │   └── tasks.md              # 带复选框的施工清单
│   └── archive/
│       └── 2025-01-23-add-dark-mode/   # 归档：日期前缀 + 原文件夹名
└── config.yaml                   # 项目配置（可选，init 时会问你要不要建）

05两个半场：终端和聊天框各管什么

这个区分值得单独讲，因为理解它之后，"为什么能支持 30+ 个工具"这个问题就自动有答案了。

为什么一个项目要长成两半

因为"规则"和"入口"是两种不同的东西：

• CLI（终端那一半）是引擎。它知道规矩：一个 change 文件夹该长什么样、哪个工件依赖哪个、怎么把一份 delta 合并进主规格。这部分跟你的 AI 工具无关，所以能保持一致。
• 斜杠命令（聊天框那一半）是方向盘。而每个 AI 工具的方向盘都长得不太一样：Claude Code 叫 commands，Cursor 有自己的格式，有些工具干脆叫 skills。你跑 openspec init 时，OpenSpec 按你选中的工具生成对应格式的文件，于是同一个"提案"的意图在哪都能用。

好处是工作流只学一次、换工具不用重学；代价是同一条命令的拼写可能不同（见上一节那张表）。

两半的核对清单

没有"可进入的交互模式"

FAQ 特意回答这个问题，因为问的人太多：OpenSpec 没有"启动交互模式"这一步。你就像平时一样打开 AI 助手、在聊天框敲一个斜杠命令——那个命令就是你"进入 OpenSpec"的方式，AI 认出它、加载对应的 skill、开始按流程走。

唯一真正"交互式"的东西在终端里：openspec view，一个浏览规格和改动的看板。但那是看板，不是干活的地方。

skill 与 command file：它到底往你项目里写了什么

这两个东西都是"为了让 AI 认识工作流"而生成的文件，你不用选——openspec init 按工具决定。

有一个容易踩的点：生成的文件归 OpenSpec 所有，别在里面写你自己的指令——下次 openspec update 可能把它们覆盖掉。你自己的项目规矩应该写在 openspec/config.yaml 的 context 里（见 12 节）。

06四种工件：图纸袋里装了什么

每个 change 文件夹里有四种工件（artifact，指一套流程里产出的单份文档）。记住它们的顺序和依赖方向，你就理解了这套流程的骨架。

四件工件各管一件事

依赖方向是"菱形"，不是一条直线

初学者容易以为这是流水线：写完 proposal 写 specs，写完 specs 写 design。看官方 status 的输出就知道不是——proposal 一写完，specs 和 design 同时变成"可写"状态，两者都完成后 tasks 才解锁。

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

所以真实形状是这样的：

proposal ──┬──► specs ──┐
           │            ├──► tasks ──► implement
           └──► design ─┘
   ▲             ▲            ▲              │
   └─────────────┴────────────┴──────────────┘
            边做边学，随时回头改

design.md 是可以不要的

这一点新手常常不知道，于是每个小改动都被要求写一份技术方案文档。官方的口径是：只有符合下列任一条时才需要 design.md——跨服务/跨模块的改动或引入新架构模式；新增外部依赖或数据模型有重大变化；涉及安全、性能、迁移的复杂度；有需要先定下来的技术分歧。一个改按钮颜色的需求不需要 design.md。

07delta spec：为什么只写"改了什么"，而不是重写整份规格

这是整套设计里最关键的一个机制，也是"为什么它改老系统特别好用"的答案。

主规格与 delta 的分工

官方的定位是一句很准的话：你描述的是"差异"（diff），不是"终点"（destination）。这就是它能优雅地改老系统的原因。

delta 用四个标题说明改动的种类

一份真实的 delta 长什么样

规格就是普通 Markdown，没有新语法要学。核心约定只有两条：需求用 SHALL/MUST 写，场景用 GIVEN / WHEN / THEN 写。下面这份是新建能力时的完整形态（注意它开头有 ## Purpose）：

## Purpose

Lets users take their data out of the product in a portable format.

## ADDED Requirements

### Requirement: User can export data
The system SHALL allow users to export their data in CSV format.

#### Scenario: Successful export
- **WHEN** user clicks "Export" button
- **THEN** system downloads a CSV file with all user data

MODIFIED 是整块替换：这是最容易吃亏的地方

官方排错文档专门给这个错误留了一段。它的表现形式是这样的：

# openspec validate 会报的错（官方示例）
MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

意思是：你写 MODIFIED 时，必须把"原本就有、且这次仍然保留"的所有场景一并带上，不能只写你改的那一个。因为归档时它整块替换旧版本，你漏掉的场景会一起消失。官方给的修法是：回 openspec/specs/<能力路径>/spec.md 把那些场景原样拷进 delta。

还有一个常见误用：如果只是"新增一块关注点"而没有改动原有行为，要用 ADDED，不要用 MODIFIED。官方管这个叫 common pitfall。

需求该写多细：一条可执行的判据

官方 writing-specs 文档给的判据是一句话："一个没看过代码的测试者，能不能判断它过没过？"答不能，就需要改。

### Requirement: Dark mode
The app SHOULD support dark mode somehow.

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

SHALL / MUST / SHOULD / MAY 的分量不一样

这四个词来自一份互联网标准文档（RFC 2119），OpenSpec 沿用了它们的分量约定。新手默认应该用 SHALL/MUST；只有当你真的想说"除非有正当理由，否则不建议"时才用 SHOULD。

为什么 spec 里不该出现技术选型

官方给了一条很好用的自查："如果实现的换法变了、但对外的行为没变，那这件事就不属于 spec。"队列、库、表结构属于 design.md 或代码；混进需求里，需求就既不可验收、又会随代码过时。

08磁盘上到底留下什么：怎么查、怎么验

这一节讲怎么用终端命令亲眼确认它。命令都可以直接复制去跑。

四个常用查看命令

# 1) 看当前有哪些进行中的 change
openspec list

# 2) 看主规格清单（注意：不加 --specs 列的是 change，不是规格）
openspec list --specs

# 3) 看某个 change 的工件进度（哪件做完了、哪件被卡住）
openspec status --change add-dark-mode

# 4) 看某个条目的详细内容；名字有歧义时用 --type 指明是 change 还是 spec
openspec show add-dark-mode
openspec show auth --type spec

# 附带一个交互式看板（终端里的浏览器）：
openspec view

校验：在归档之前发现问题

openspec validate 检查结构和一致性，包括"MODIFIED 需求有没有漏掉现存场景"这种跨文件的一致性。它可以进 CI：

openspec validate add-dark-mode        # 校验单个 change
openspec validate --changes            # 校验所有 change
openspec validate --specs              # 校验所有规格
openspec validate --all --strict       # 严格模式 + 全部，适合 CI
openspec validate --all --json         # 给脚本 / agent 用的结构化输出
openspec validate --archived           # 检查已归档的 change 是否还有没勾完的任务

--archived 值得单独说：它不校验规格（归档时已应用过），专门检查 changes/archive/ 下每个 change 的 tasks.md 是否全部勾完，有没勾的就以非零退出码结束——适合放进提交前的钩子，拦住"带着半成品被归档"。

归档在磁盘上做的三步

归档也可以直接在终端跑，不必走聊天框：

openspec archive                          # 交互式：问你要归档哪个、再确认
openspec archive add-dark-mode            # 指定 change
openspec archive add-dark-mode --yes      # 不问，直接归档（agent / CI 用）
openspec archive update-ci-config --skip-specs   # 这次不改规格（纯工具/文档类改动）

两个容易忽略的元数据开关

change 文件夹里还有一个 .openspec.yaml，平时不用碰，但有两个开关只在这里生效：

为什么要额外加标记？因为这是归档流程里唯一会删除文件的步骤，必须被明确要求。规则还不止一条：只要那个主规格里除了标题、## Purpose 和需求块之外还有别的东西（比如一段 ## Notes、一条需求下面的注释），归档也会拒绝并指出那几行——你得先把它们挪进 Purpose 或某条需求，或者自己手动删文件。

09三种场景，三条不同路线

同一个工具，在三种处境下该走的路不一样。这一节把差异讲清楚，你可以对号入座。

场景一：需求清楚的新功能

比如"给博客加 RSS 订阅"。需求明确，走最短路径即可：

You: /opsx:propose add-rss-feed
# AI 生成四件套。你重点审两处：
# 1. proposal 里的"不改什么"（别让它顺手重构全站）
# 2. specs 里的 WHEN/THEN 场景（条目排序、转义、分页覆盖了没有）
You: 看起来可以，开工。把分页放到 v2，这次只做全量输出。
# AI 先用 /opsx:update 把范围收窄，再 /opsx:apply 施工，最后 /opsx:archive 归档

官方的 examples 文档给这条路的说法是"三个命令搞定"：propose 起草、apply 构建、archive 归档。审图那一步是它专门强调的："这是 OpenSpec 为之而生的时刻——在错误的理解还只是一段话的时候抓住它，而不是在 400 行代码之后。"

场景二：老项目修 bug（这才是它的主场）

存量项目是它官方定位的主场景。不用重写、不用先补全文档，路线是"先摸清现状，再圈小范围"：

场景三：多个改动并行

这得益于"一个 change 一个独立文件夹"：做 A 的时候插进来紧急修复 B，两者互不干扰——各有各的文件夹、tasks.md 和归档时机。

You: 我 add-dark-mode 做到一半，现在得先修一个登录 bug。
You: /opsx:propose fix-login-redirect
You: /opsx:apply
You: /opsx:archive
You: 回到深色模式。
You: /opsx:apply add-dark-mode    # 显式点名，因为现在有两个 change

三条路线的对照

10全部指令：你在哪一步敲哪一条

先说结论：日常 90% 的时间你只用到三条——propose（出图）、apply（施工）、archive（归档）。其余的都是在这三条周围打辅助。

默认就有的一组（core 档位）

新装默认是 core 档位，装着这六条斜杠命令。它们全部敲在 AI 聊天框里。

需要手动开启的一组（expanded / 自定义档位）

下面这六条默认不装。想要精细控制出图节奏的人才需要它们，开启方式见本节的最后一段。

核心三件套长什么样（逐个拆）

/opsx:propose add-dark-mode      # 名字写清楚；也可以直接写一句自然语言的描述
/opsx:explore                    # 想法还模糊时先聊透，再 propose

openspec/changes/add-dark-mode/
├── proposal.md
├── specs/ui/spec.md    # 具体路径取决于这个 change 涉及哪个能力
├── design.md
└── tasks.md

/opsx:apply                    # 只有一个进行中的 change 时自动推断
/opsx:apply add-dark-mode      # 有多个并行 change 时必须点名

/opsx:archive
# 终端等价物（agent / CI 里要带 --yes）：
openspec archive add-dark-mode --yes

/opsx:update：只改图纸、不碰代码

这条命令值得单独讲，因为它是"规格驱动"和"在聊天里改需求"最大的区别所在。它的行为很具体：

• 它读这个 change 的所有工件（内部用的是 openspec status --change <name> --json），然后应用你要求的修改；如果你什么都没指定，它会替你检查工件之间有没有互相矛盾。
• 它会双向调和已有工件：改 design 可能反向牵动 proposal，改需求可能牵动 tasks。
• 它每改一件都先跟你确认，一次一件。
• 结尾会建议下一步该 /opsx:continue（还缺工件）、/opsx:apply（把改过的图纸落进代码），还是 /opsx:archive（都做完了）。
• 它不会创建缺失的工件——那是 /opsx:continue 的事。

You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage
AI:  Reading add-dark-mode artifacts...
     The design references localStorage in two places; tasks 1.3 covers
     localStorage persistence; the proposal doesn't mention storage.

     Proposed revisions:
     1. design.md - swap localStorage decision for cookie storage
     2. tasks.md - reword task 1.3 to cookie persistence

     Apply revision 1? (design.md)

/opsx:verify：三个验收维度

它检查三个方面，报告分成 CRITICAL / WARNING / SUGGESTION 三档，并且不会拦住归档——它只把问题摆出来。官方口径是"归档前跑一遍能早点发现不一致"。

官方文档的输出示例，能看出它具体到什么程度：

# /opsx:verify 的典型输出（官方文档示例，有删节）
COMPLETENESS
✓ All 8 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "System preference detection" has no test coverage

COHERENCE
⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

SUMMARY
Critical issues: 0
Warnings: 2
Ready to archive: Yes (with warnings)

开关这两档：profile 与 delivery

"装哪些命令"由两个设置决定，都在全局配置里，改完之后要在项目里跑一次 openspec update 才会落到项目文件上。

# 查看 / 修改全局配置，再把它应用到当前项目
openspec config profile          # 交互式向导：先给你现状摘要，再让你选改什么
openspec config profile core     # 快速预设：工作流切回 core（保留投递方式）
openspec config list             # 看当前所有设置
openspec update                 # 把选择落到本项目的生成文件上

向导里有个设计细节值得知道：如果你选"保持当前设置"退出，它不会写任何东西、也不会弹升级提示；但如果设置没变、而项目里的文件与全局设置不一致，它会警告并建议你跑 openspec update。另外，勾选清单里的 [x] 只表示"这个工作流在全局配置里被选中了"，要真正落到项目文件上还是得跑 update。

11需求变了：改这张图，还是重开一个 change

这是用起来之后最容易做错的判断，代价很具体：要么让一个 change 变成大杂烩（图纸没人愿意看），要么让本来一件事的历史被拆成三段互不相干的故事。

官方的判据：同一件工作被细化 vs 意图根本变了

官方文档里对应的原话是两句：FAQ 里说"当它是同一件工作、被细化时用 update；当意图根本改变、或范围炸成了不同的工作时，重新开始"；/opsx:update 的说明里说"如果你的修改改变了这个 change 的意图，就改用一个新 change 重来"。

三问自测（把上面的判据落到可操作）

前两问答"是"、第三问答"不能"→ 用 /opsx:update 改图。否则开新 change。

改图的具体动作

不管走哪条路，"怎么改图纸"这件事本身没有门槛：工件就是普通的 Markdown 文件，改它有两种等价方式——直接在编辑器里改文件，或者在聊天里告诉 AI"把设计改成用后台任务，不要同步调用"。官方特意说明：没有专门的"改提案"命令，因为你不需要；文件就是唯一真相，改文件就是改图纸。而且 AI 永远从文件的当前内容出发工作，所以改完接着跑 /opsx:apply 就行。

12项目配置：让 AI 每次都知道你们家的规矩

如果你每次都要重复提醒"我们用 TypeScript、接口是 REST 风格、测试用 Vitest"，那这份配置就是为你准备的。把项目背景写一次，之后每次生成工件时它都会自动带上。

文件在哪、装的时候怎么建

位置是 openspec/config.yaml。openspec init 会问你要不要建它，官方推荐建。注意扩展名必须是 .yaml，不能写成 .yml——这是官方排错文档里列出的第一个"配置没生效"的原因。

一份能照抄的完整配置

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# openspec init 问你（或替你决定）的 GitHub Copilot 云 coding agent 开关
githubCopilot:
  cloudAgent: false

四个字段分别管什么

官方把注入机制写得很直白：生成工件时，context 和 rules 被塞进 AI 的提示词，形如 <context>…</context> + <rules>…</rules> + <template>…</template> 三段。context 进所有工件，rules 只进匹配的那一个。operations 下的建议则是每次执行时现取快照——改了立刻生效，不用重启。

关掉遥测 + 几个常用开关

# 彻底关掉匿名遥测（也可以设环境变量 OPENSPEC_TELEMETRY=0 或 DO_NOT_TRACK=1）
openspec config set telemetry.enabled false

# 看配置存在哪里、现在都有什么
openspec config path
openspec config list
openspec config get telemetry.enabled

# 用显式字符串写入（避免被当成数字 / 布尔）
openspec config set user.name "My Name" --string
openspec config unset user.name

# 用编辑器打开配置文件
openspec config edit

# 重置全部配置（会先确认）
openspec config reset --all --yes

遥测的默认状态是"未设置即开启"（opt-out 模型）。环境变量的优先级高于配置文件，而且 CI 被设成真值时（true/1/yes）无视配置直接关闭。

初始化时的三个实用参数

13进阶：自定义工作流（schema）与跨仓库规格（Stores）

如果你现在是一个人一个仓库，这一节可以跳过，需要时再回来。

schema：定义"有哪些工件、谁依赖谁"

默认那套 spec-driven（proposal → specs → design → tasks）本身就是一个 schema。你可以 fork 一份改成自己的流程——官方举的典型例子是"研究前置型"：research → proposal → tasks。

openspec schema fork spec-driven my-workflow   # 拷一份出来改
openspec schema validate my-workflow          # 改完校验结构和模板
openspec schemas                              # 看有哪些可用
openspec schema which spec-driven              # 看某个名字到底从哪儿解析来的（排查用）

# 不想 fork 的话，也能直接新建一个
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

解析优先级是三层，从近到远：项目里 openspec/schemas/<name>/ → 用户级 ~/.local/share/openspec/schemas/<name>/ → 包里内置的 schema。所以同名时项目里的会赢——这也解释了为什么"我改了但没生效"通常是因为改到了另一层。

社区还有现成的 schema 包（极简版、事件驱动版等），官方 customization 文档里有目录。但默认那套够用很久，别一上来就改流程。

Stores：一个需求横跨三个仓库时怎么办

单人单仓库时，openspec/ 跟代码放在一起就行。但一个需求同时涉及 API 服务、Web 应用、共享库三个仓库时，规格该放哪？官方给的答案是 Stores：把 openspec/ 单独放一个仓库，用 git push 共享。

# 建一个本地 store 并注册（standalone 的 OpenSpec 仓库）
openspec store setup team-plans
openspec store register /path/to/store
openspec store list
openspec store doctor                 # 检查本地 store 配置有没有问题

# 报告"解析出的根"的关系健康度 / 打印当前装配出的工作集（根 + 被引用的 store）
openspec doctor
openspec context

14审图十分钟：到底盯哪几处

审图是这套流程里人最值钱的十分钟：AI 出图很快，但图错了，施工越快返工越多。难处在图纸有好几页，新手不知道该看哪。

三处必看

官方给的快速检查清单

官方 writing-specs 文档末尾有一份勾选清单。它的六条问的是同一件事的六个面，值得抄下来当审图模板：

两个可以拿去用的自问句

怎么把图纸改到你满意

三种改法，按代价从小到大：

1. 在聊天里指出问题："范围太宽，去掉管理后台那部分。" 最便宜，通常也最对。
2. 退回去 explore：如果问题出在"想法本身还没想清"，退回 /opsx:explore 聊透，再让一份更准的 proposal 出来。
3. 重开一个 change：如果意图已经根本变了（见 11 节的三问自测）。

在开始实现之前就指出问题，比以后纠正要便宜得多——这也是"先出图纸"的整个理由。

15七个常见坑

每一条都能在官方文档里找到出处。

另外三个"不是坑但很反直觉"的点

• 归档不会因为你没勾完任务而拦住你。它只警告。如果你确实想归档一个部分完成的工作，可以继续；否则先把任务做完。这个设计是有意的，但第一次遇到会以为它坏了。
• /opsx:sync 通常不需要手动跑。归档会问你要不要同步。只有"长跑型 change 想在归档前就合并"或"并行 change 需要基于最新规格"时才手动调它。官方 FAQ 的原话是"大多数用户永远不需要直接调用它"。
• 生成的指令文件不要手改。skills 文件带版本戳、命令文件靠内容比对——你怎么改都会被判定为漂移并覆盖。你自己的规矩请写进 config.yaml。

16排错：六个真会遇到的问题

每一条都来自官方 troubleshooting 文档，顺序按"最快能检查"排。

1 · 敲了 /opsx:propose，什么都没发生

按代价从低到高排查，官方给的就是这个顺序：

1. 你可能敲错地方了。斜杠命令在 AI 聊天框里，不在终端。如果在 shell 里敲的，这就是原因。
2. 重新生成文件。在项目根目录跑 openspec update，它会重写你配置过的每个工具的 skill/命令文件。
3. 重启你的助手。多数工具只在启动时扫描技能和命令，开个新窗口往往就好了。
4. 确认文件真的存在。比如 Claude Code 下看 .claude/skills/ 里有没有 openspec-* 目录。
5. 确认你初始化的是这个项目。技能是按项目写的；换了目录或 clone 了新仓库，就要在那个目录里跑一次 openspec init 或 openspec update。
6. 确认你的工具支持命令文件。Codex、CodeArts、ForgeCode、Hermes、Kimi Code、Mistral Vibe、Zed Agent 和共享的 .agents 目标不生成 opsx-* 命令文件，所以 /opsx 永远不会自动补全——它们走 skill 调用形式（见 03 节那张拼写表）。

2 · Change not found

它无法确定你指哪个 change。两个动作：明确写出名字，或者先看看有哪些。

openspec list                     # 终端：看当前有哪些进行中的 change
/opsx:apply add-dark-mode        # 聊天：把名字写出来

顺便确认你在正确的项目目录里——技能是按项目写的。

3 · No artifacts ready

意思是：每个工件要么已经生成了，要么在等它依赖的东西。看谁在挡路：

openspec status --change <name>

记一下顺序：proposal 解锁 specs 和 design；specs 和 design 两个都完成才解锁 tasks。看到 [-] tasks (blocked by: design) 就说明设计还没写。

4 · openspec validate 报错 / 警告

读它给的消息——它会点名文件、说明问题。常见原因是缺必需小节（比如一份规格没有任何场景），或者 delta 标题格式写错了。按前面说的修，再重跑。第 15 节里那个"MODIFIED 漏场景"的报错是唯一值得单独记的。

openspec validate <name>              # 校验一个
openspec validate --all               # 校验全部
openspec validate --all --strict      # 更严，适合 CI
openspec validate --archived          # 已归档的 change 里有没有没勾完的任务

5 · AI 生成的工件不完整或者偏了

官方把这个归因成一件事：AI 拿到的上下文不够。四个可用的手段：

官方给的"把 AI 引向好草稿"的具体话术也值得抄：把意图和边界一起说——"加一个深色模式开关，首次加载跟随系统设置——不要动现有主题 API"（后半句和前半句一样重要）；点名你在意的情况——"确保有一个场景覆盖已经手动选过主题的用户"。

6 · 用 bun 装的，为什么还要 Node？

因为它是用 Node 运行的。bun / npx 只负责把它下载下来，运行时的引擎仍然是 Node，所以 PATH 里必须有 20.19.0 或更高版本的 node。openspec --version 能跑通就说明这件事没问题。

7 · 想报告问题或问人

官方请求附带的信息：OpenSpec 版本（openspec --version）、Node 版本（node --version）、你用的 AI 工具、以及完整命令和完整输出。

97它和别的方案差在哪

市面上"管 AI 写代码"的东西大致分三类。官方 README 直接点名对比了两个同行，下面是加上了"什么都不用"这一栏的完整对照。

最后一列的措辞不是我编的，是官方 README 里 "How we compare" 那一节的原意。要公平地说一句：对手的"重"不是缺点，是取舍——如果你的组织需要审批留痕、每个阶段都要检查点，那"更轻"对你就不是优点。

它和"就写个 PRD 放仓库里"的最后一个区别

有人会问："我自己写个 PRD.md 提交到仓库，不也一样落盘了吗？"三处不同：一是结构——四种工件各管一件事、依赖方向固定，而不是一份什么都能塞的文档；二是可执行——tasks.md 的复选框会被逐项执行和打勾，形成闭环；三是会自动合并——归档那一刻，规格里"改动的那部分"被自动并回系统现状说明书，而不是留在某个角落慢慢过期。

98术语对照表

99一页纸速查表

读第二遍时只看这一节。左边是"我要…"，右边是敲什么。

终端命令（openspec …）

聊天框命令（/opsx:…）

配置文件要点

# openspec/config.yaml —— 文件名的扩展名必须是 .yaml
schema: spec-driven          # 默认流程，可用 --schema 覆盖
context: |                   # 注入每一个工件（上限 50KB）
  Tech stack: TypeScript, React, Node.js, PostgreSQL
rules:                       # 只注入到对应工件
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
operations:                  # 给 apply / archive 的建议（不是 rules，约束不了内容）
  apply:
    guidance:
      - Run focused tests before the full suite

上手路线（三天，每天一个目标）

100一句话总结

101参考来源与证据边界

一手来源（全部联网读取）

• npm 包与版本：registry.npmjs.org/@fission-ai/openspec —— 本文校对时刻 latest = 1.13.0（发布于 2026-09-09），engines.node = >=20.19.0；过去一月下载量 1,768,196（npm downloads API）。
• 官方仓库 README：github.com/Fission-AI/OpenSpec（本文读取的是随 1.13.0 包一起发布的 README 全文）—— 五条设计哲学、深色模式走查、安装与升级、Stores beta、模型与上下文卫生建议、与 Spec Kit / Kiro 的对比措辞。
• 官方文档（main 分支，逐个抓原文核对）：docs/cli.md（CLI 全量命令与参数）、docs/commands.md（斜杠命令参考）、docs/getting-started.md（目录结构、delta 格式、归档行为）、docs/how-commands-work.md（两个半场）、docs/overview.md 与 docs/concepts.md（五个核心概念）、docs/writing-specs.md（好需求与好场景的判据、RFC 2119 关键词、retire 规则）、docs/customization.md（config.yaml 全字段、schema、社区 schema）、docs/troubleshooting.md（排错条目）、docs/faq.md、docs/glossary.md、docs/examples.md、docs/workflows.md、docs/explore.md、docs/stores-beta/user-guide.md。
• 随包发布的 schema 定义与模板：schemas/spec-driven/schema.yaml、templates/{proposal,spec,design,tasks}.md —— 本文里 #### Scenario: 必须四个井号、"每条需求至少一个场景"、## Purpose 只给新能力写、MODIFIED 必须带全场景这些规则，都是从这份定义里读出来的。
• GitHub API：仓库 stars 68,077、forks 4,675、许可证 MIT、最近推送 2026-09-11（api.github.com/repos/Fission-AI/OpenSpec）。

本文自己做的核对

• 版本锚点：旧文锚在 v1.12.0，本文锚在 v1.13.0——直接查 npm registry 的 dist-tags.latest 与发布时间，不靠记忆。
• 把"命令现状"逐条对到官方原文：旧文里出现过的每条命令（install / init / update / propose / explore / apply / update / archive / verify / sync / new / continue / ff / bulk-archive / onboard / status / schemas / schema fork / schema validate / config set telemetry.enabled）都在 1.13.0 的 docs/cli.md 或 docs/commands.md 里找到了对应物；对不上的两条见下文"改掉的旧版事实"。
• 数字口径：stars 和月下载量都标了"本文校对时刻"，因为这类数字每天都在动。

证据边界与时效

• 版本口径：本文校对于 OpenSpec @ v1.13.0（2026-09-09 发布），读取的官方文档是仓库 main 分支在校对时刻的内容。工具迭代很快，命令集、profile 组成、Stores 的状态都可能变——这也是它标 evolving 的原因。
• 我没有做的事：没有真的在一个项目里跑完 openspec init 之后的完整闭环（本次核对以官方文档 + 包内 schema/模板 + registry 元数据为准）；没有逐个验证 30+ 个 AI 助手各自的命令拼写（表里写的是官方文档明确给出的几个例子）；没有评测 /opsx:verify 在真实代码库上的准确率；没有覆盖多语言、迁移指南、社区 schema 目录的全文。
• 一处口径提醒：官方 README 与官方 FAQ 都推荐"高推理模型"并点名了具体型号与版本号。本文只转述"推荐用强推理模型做规划和施工"这个方向，不把具体版本号当作长期有效的建议——模型版本更替比文档快得多，请以官方 README 当时的内容为准。同理，"官方支持 30+ 工具"这个数字也在持续增长。
• 术语对照提醒：context 在 CLI 里是一条命令（装配工作集），在 config.yaml 里是一个字段（注入给 AI 的项目背景），官方自己在 CLI 文档里点名了这个歧义。本文两处都按各自语境使用，读到时注意区分。