OpenSpec + Claude Code 实战指南：让 AI 不只是会写代码，而是先按规格把事做对

这两年，AI 编码工具越来越像一个"高产、聪明、执行力很强，但偶尔也会自作主张的新同事"。

你让它写个功能，它往往真能写出来；

但写出来的东西是不是你真正要的、边界是不是清楚、设计是不是一致、后续是不是好维护，就不一定了。

很多团队已经感受到一种很现实的落差：

不是 AI 不会写代码，

而是 AI 太容易在需求还没对齐时，就把代码写得飞起。

于是，问题开始从"怎么让 AI 写得更快"，转向"怎么让 AI 写得更准、更稳、更可追溯"。

这正是 OpenSpec 的价值所在。

它不是再造一个 AI，也不是替代 Claude Code。更准确地说，OpenSpec 是一套面向 AI 编码助手的规范驱动开发工作流；Claude Code 则是把这套工作流真正执行起来的强执行代理。

一个更像"方向盘"，一个更像"发动机"。

放在一起用，目标不是让 AI 写更多代码，而是让 AI 少写那些方向看似对、其实需求没对齐的代码。

先给结论：

如果你只是想让 AI 帮你"写一段代码"，OpenSpec 可能显得有点正式；

但如果你已经开始用 Claude Code 做真实项目、改现有代码库、推进多人协作任务，那 OpenSpec 往往不是"锦上添花"，而是"避免反复返工"的那层护栏。

这篇文章适合谁看

这篇文章尤其适合下面几类人：

• 已经在用 Claude Code、Cursor、Windsurf 之类 AI 编码工具的人；
• 经常做真实项目改造，而不是只写 demo 的开发者；
• 想把"聊天式开发"升级成"有留痕、有规范、有归档"的团队负责人；
• 看过一些 OpenSpec 教程，但被旧命令、旧流程、旧截图绕晕过的人。

读完你能得到什么

这篇文章会尽量回答 5 个最现实的问题：

1. OpenSpec 到底解决什么问题？
2. 它和 Claude Code 为什么适合一起用？
3. OpenSpec 1.2.0 之后，命令和工作流到底怎么理解？
4. 不同场景下，应该怎么走 propose / explore / apply / archive？
5. 团队如果想低成本落地，最小实践方案该怎么搭？

你不需要先接受一整套"新方法论"，再决定要不要用它。

更实际的方式是：先把文章读完，看看它能不能帮你解决下面这些老问题------

• AI 总是抢跑，需求还没对齐就开始写代码；
• 功能确实做出来了，但设计决策留不下来；
• 聊天里讲过的约束，过几天就没人记得；
• 一旦多人并行或者跨会话继续，整个上下文就开始漂移。

如果这些问题你都遇到过，那 OpenSpec 大概率值得认真看一遍。

---

一、先说人话：OpenSpec 到底是什么

一句话解释：

OpenSpec 是一套把"需求、规格、设计、任务、实现、归档"串起来的 AI 协作工作流。

它强调的不是"想到什么就直接让 AI 开始改"，而是：

1. 先把这次变更说清楚；
2. 再把系统行为和边界写清楚；
3. 必要时把技术方案定清楚；
4. 再把任务拆成可执行清单；
5. 最后才让 AI 进入实施阶段。

这套思路，本质上就是 Spec-Driven Development（规范驱动开发） 在 AI 编程时代的落地版本。

OpenSpec 的核心价值，不是多几个命令，而是把原本散落在聊天记录里的"共识"，沉淀成项目里的正式工件。这样一来，AI 的上下文不再只依赖会话记忆，而是开始依赖项目内可追踪、可审查、可归档的事实。

换句话说：

• 没有 OpenSpec 时，很多需求只存在于聊天里；
• 有了 OpenSpec 后，需求、设计和任务会变成项目内的正式资产。

这件事对个人开发者有帮助，对团队协作更重要。

因为团队最怕的不是 AI 写得慢，而是：

• 每个人都在用 AI，但每个人理解的范围不一样；
• 每个人都在提效，但结果不可复盘、不可审计、不可继承；
• 过几天回头看，只记得"改过"，却说不清"为什么这么改"。

OpenSpec 的意义，就是尽量把这种"聊天式开发"升级为"带工件留痕的工程式开发"。

---

二、为什么它和 Claude Code 很搭

Claude Code 的强项很明显：

• 能读取真实代码库上下文；
• 能连续执行多步任务；
• 能跑命令、查文件、改代码、补测试；
• 对真实工程改造比只会"补全一段代码"的工具更有行动力。

但工具越强，越需要约束。

因为越能干的代理式工具，越容易在下面这些场景里"用力过猛"：

• 需求边界没说清，就开始大范围改动；
• 设计方案还没定，已经先把实现铺开；
• 聊天里说过的关键限制，没有被固化进项目；
• 多任务切换后，前一次变更的上下文被新的目标冲掉；
• 最终代码能跑，但没人说得清"为什么这么实现"。

Claude Code 负责把事推进下去，OpenSpec 负责把事定义清楚。

所以两者组合起来，比较接近一种更成熟的协作关系：

• Claude Code：偏执行，擅长"做"；
• OpenSpec：偏约束，擅长"先把该做什么说清楚"。

一个负责"干活"，一个负责"把活干明白"。

这也是为什么，OpenSpec 特别适合搭配 Claude Code 这类能真正落地执行的 AI 代理，而不是只停留在问答层面的助手。

---

三、OpenSpec 1.2.0 最值得先知道的变化

如果你看过较早期的教程，最容易踩坑的地方只有一个：

现在的 OpenSpec，命令体系和工作流已经不是早期那套"旧版 OpenSpec"了。

对 1.2.0 来说，最关键的变化主要有这几项。

1. 默认 profile 变成了 core

现在默认全局 profile 是 core，只包含 4 个核心工作流：

• propose
• explore
• apply
• archive

这意味着：你新装 OpenSpec 后，并不会默认看到所有扩展命令。

2. propose 成了新手最佳入口

1.2.0 新增了 Propose workflow 。它可以一步生成完整的 change proposal、specs、design 和 tasks，不再要求你先 new 再 ff。

这对新手特别友好：

你不需要先理解整套工作流拓扑，先从一句需求出发，就能快速得到一套完整的规划工件。

3. openspec init 会自动识别已有 AI 工具目录

现在 openspec init 会扫描 .claude/、.cursor/ 等已有目录，并预选检测到的工具。

这看起来像小优化，但实际上很实用：

它让 OpenSpec 更像"装到现有项目里"，而不是"逼你重新建一个世界"。

4. 工作流从"阶段锁定"转成"行动驱动"

新版 OPSX 的核心思想可以概括成一句话：

Actions, not phases.

也就是：

• 重点不是强行卡死在某个阶段；
• 而是用一组动作，把需求澄清、工件生成、实施、验证、归档连接起来。

你仍然要讲顺序，但顺序不再僵硬到"一旦前进就不能回头"。

5. Delta Specs 的语义更清晰了

在规范同步这件事上，OpenSpec 不再是"把整份规格文件整体替换掉"，而是支持更语义化的 delta sections，例如：

• ADDED Requirements
• MODIFIED Requirements
• REMOVED Requirements
• RENAMED Requirements

这让规格变更更像"增量演进"，而不是"整份重写"。

---

四、先用人话理解 OpenSpec 的目录结构

OpenSpec 真正有价值的地方，不只是命令，而是它会把"这次变更的思考过程"落到项目目录里。

一个典型项目初始化后，核心目录大致如下：

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

再展开一点看：

openspec/
├── specs/                    # 当前系统的正式规格（source of truth）
│   └── <domain>/
│       └── spec.md
├── changes/                  # 每次变更的工作区
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/
│           └── <domain>/
│               └── spec.md   # delta specs：本次变更影响什么
└── config.yaml               # 项目级配置（可选）

这套结构里，最重要的是两个目录：

1. specs/：系统现状的正式规格

这里更接近"当前事实"。

也就是说：

• 它描述的是系统现在应该怎么工作；
• 它不是临时讨论区；
• 它是项目未来回看时最接近"正式口径"的地方。

2. changes/：每次变更的工作区

这里更接近"这一次准备怎么改"。

每个 change 都有自己的 proposal、design、tasks 和 delta specs。等变更完成后，再归档并把 delta specs 合并回主 specs。

这意味着，团队以后回头看一个功能，不只是知道"代码改成这样了"，还知道：

• 为什么要改；
• 改动范围是什么；
• 关键设计决策是什么；
• 任务是怎么拆出来的；
• 最终是否已经归档。

对工程团队来说，这比把一切埋在聊天记录里靠谱得多。

---

五、OpenSpec 里的两层命令体系，别混了

很多人第一次上手会有一个典型困惑：

OpenSpec 到底有哪些命令？为什么有的是 openspec xxx，有的是 /opsx:xxx？

答案很简单：它本来就分两层。

第一层：CLI 命令

这是你在终端里敲的命令，偏"人类管理项目和配置"。

例如：

• openspec init
• openspec update
• openspec list
• openspec validate
• openspec archive
• openspec config profile

第二层：工作流命令

这是你在 Claude Code、Cursor、Windsurf 这类 AI 工具对话里调用的命令，偏"让 AI 进入具体工作流动作"。

例如：

• /opsx:propose
• /opsx:explore
• /opsx:apply
• /opsx:archive
• /opsx:new
• /opsx:continue
• /opsx:ff
• /opsx:verify
• /opsx:sync
• /opsx:bulk-archive
• /opsx:onboard

最通俗的理解方式：

• openspec ...：像在装工具、管配置、查状态；
• /opsx:...：像在让 AI 真正开始按流程办事。

---

六、先装起来：安装、初始化、升级

按照当前官方 Quick Start，OpenSpec 需要 Node.js 20.19.0 或更高版本。

基础安装流程如下：

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

如果你主要是给 Claude Code 用，也可以显式指定工具：

openspec init --tools claude

如果你希望一次配置多个工具：

openspec init --tools claude,cursor

如果是自动化或无交互初始化，也可以用：

openspec init --force

初始化后会创建什么

openspec init 主要会创建两部分：

1. 项目内的 openspec/ 目录；
2. 针对所选 AI 工具生成的 skills / command 文件。

例如选择 Claude Code 时，通常会生成对应的 .claude/skills/ 内容。

升级后别忘了 openspec update

这是很多人会漏掉的一步。

当你升级 OpenSpec CLI 后，应该在项目里执行：

openspec update

它的作用不是"升级 npm 包"，而是重新生成项目里的指令文件和工作流配置，让当前项目和你现在的 profile / workflow 选择保持一致。

你可以把它理解为：

• npm install -g ...：更新工具本体；
• openspec update：把新规则同步到当前项目。

---

七、最常用的 CLI 命令表

很多人一上来最容易混淆的，就是"终端命令"和"对话里的工作流命令"。

这一节先把 CLI 层讲清楚：它主要负责安装、初始化、配置、检查、更新和归档等"项目管理动作"。你可以把它理解成 OpenSpec 的"系统层命令"。

下面这张表，重点讲终端里的 openspec 命令。适合放在文章里做"查阅型速览"。

1. CLI 核心命令总览

命令	主要作用	适合什么时候用	常见示例
openspec init	初始化项目，创建 openspec/ 结构并配置 AI 工具集成	第一次在某个项目接入 OpenSpec	openspec init --tools claude
openspec update	根据当前 profile / delivery 重新生成项目内指令文件	升级 CLI 后，或改了 profile 后	openspec update
openspec list	查看当前 change 或 specs 列表	想知道项目里有哪些活跃变更 / 规格	openspec list / openspec list --specs
openspec show <item>	读取指定 change 或 spec 内容	想快速看某个对象内容	openspec show add-dark-mode
openspec view	打开交互式 dashboard	想可视化浏览项目状态	openspec view
openspec validate	校验 change / spec 结构是否有问题	归档前、CI 校验、批量检查	openspec validate --all --strict
openspec archive	在 CLI 层归档已完成 change，并合并 specs	脚本化、终端化归档场景	openspec archive add-dark-mode --yes
openspec status	查看 artifact 进展状态	想知道某个 change 当前推进到哪	openspec status --json
openspec instructions	获取下一步建议或指令	给 agent / 脚本取下一步动作	openspec instructions --json
openspec templates	查看模板路径	团队准备自定义模板时	openspec templates --json
openspec schemas	查看可用 schema / 工作流支持	想了解有哪些 artifact workflow	openspec schemas
openspec config profile	配置 profile 和 workflow 选择	想从 core 切到扩展工作流时	openspec config profile
openspec config list	查看当前配置	排查为什么某些命令没出现	openspec config list

2. 你最可能用到的 CLI 命令详解

命令	关键参数 / 选项	解释	实战建议
openspec init [path]	--tools <list>、--force、--profile <profile>	初始化 OpenSpec，并为 выбран工具生成集成文件	新项目直接用；老项目接入前建议先提交一次 Git，方便回滚
openspec update [path]	--force	升级后重新生成项目指令文件	只升级 npm 包、不执行 update，是最常见踩坑点
openspec list	--specs、--changes、--sort、--json	查看规格或变更列表	想快速确认当前项目里有哪些活跃 change 时很好用
openspec validate [item-name]	--all、--changes、--specs、--strict、--json	检查 artifacts 或 specs 的结构问题	团队可以把 --all --json 接入 CI
openspec archive [change-name]	--yes、--skip-specs、--no-validate	归档 change 并合并 delta specs	工具类 / 文档类变更可考虑 --skip-specs
openspec config profile [preset]	core 等 preset	切换 profile / workflow 选择	改完后记得执行 openspec update

3. openspec config profile 到底是干什么的

这个命令非常关键，但也最容易被轻视。

它不是简单的"选个风格"，而是在控制：

• 你当前项目要不要启用 expanded workflows；
• 安装哪些 workflow 对应的技能 / 命令；
• 当前项目生成出来的命令集长什么样。

所以你经常会看到这样一组操作一起出现：

openspec config profile
openspec update

第一句是"改配置"，第二句才是"让当前项目真的生效"。

---

八、最关键的 /opsx 工作流命令表

如果说 CLI 命令是"把环境准备好"，那 /opsx 命令就是"让 AI 真正开始干活"。

这一层最值得记住的不是每个命令的拼写，而是它们背后的工作流语义：探索、提案、实施、验证、归档。

这部分才是 OpenSpec 真正的使用核心。因为你日常和 Claude Code 协作时，主要打交道的就是这些命令。

1. 默认 core 工作流命令

命令	功能定位	作用说明	什么时候最适合用
/opsx:propose	一步建完整 planning artifacts	创建 change，并生成 proposal、specs、design、tasks	需求基本明确，想快速开工
/opsx:explore	需求探索 / 方案调研	先调研问题、比较方案、澄清边界，不立即创建 artifacts	需求不清、方案未定、先摸底
/opsx:apply	进入实施	按 tasks.md 逐项改代码、补文件、跑测试，并勾选完成项	planning 完成后开始真正干活
/opsx:archive	归档闭环	检查工件状态、必要时同步 delta specs、归档到 archive 目录	实现完成，准备收尾

2. 扩展工作流命令

命令	功能定位	作用说明	更适合什么场景
/opsx:new	只创建 change 脚手架	先建 change 目录与元数据，不一次生成全部 artifacts	想手动控制规划节奏
/opsx:continue	逐个生成下一个 artifact	按依赖链一次只生成一个工件	复杂需求、想逐步评审
/opsx:ff	一次补齐 planning artifacts	按依赖顺序自动完成 proposal/specs/design/tasks	已经确定范围，但想走 expanded 路线
/opsx:verify	验证实现与工件一致性	从完整性、正确性、一致性三个维度检查实现	归档前质量把关
/opsx:sync	手动同步 delta specs	把 change 下的增量规格合并进主 specs，但不归档	长周期 change、并行 change 依赖最新规格
/opsx:bulk-archive	批量归档多个 change	校验多个变更并处理 spec 冲突	多任务并行后统一收口
/opsx:onboard	引导式上手教程	用真实代码库跑一遍完整 OpenSpec workflow	新成员培训、团队试点

3. /opsx 命令详细解释表

下面这张表更适合做"正文内详细说明"。

命令	它会做什么	不会做什么	使用建议
/opsx:propose [change-name-or-description]	创建 openspec/changes/<change-name>/，并生成 proposal、specs、design、tasks 等 planning artifacts	不直接改业务代码	新手默认从它开始，最快形成闭环
/opsx:explore [topic]	围绕某个主题调研代码库、比较方案、澄清边界，还能帮助形成下一步 change 思路	默认不创建 artifacts	不明确时先 explore，通常比直接 propose 更稳
/opsx:new [change-name] [--schema <schema>]	创建 change 脚手架和 .openspec.yaml 元数据	不自动生成全部规划工件	想精细控制规划节奏时用
/opsx:continue [change-name]	查询依赖图，只生成"当前可生成"的下一个 artifact	不会一次性把所有工件都补齐	每一步都想人工审阅时很合适
/opsx:ff [change-name]	按依赖顺序把 planning artifacts 一次生成完	不负责后续编码实现	scope 明确但仍想用 expanded 路线时很高效
/opsx:apply [change-name]	读取 tasks.md，逐项改代码、创建文件、运行测试，并将任务勾成 [x]	不负责定义需求边界	没有像样的 tasks.md 时别急着 apply
/opsx:verify [change-name]	校查 completeness / correctness / coherence，提示 spec 与代码是否漂移	不会自动替你修完所有问题	复杂项目建议归档前必跑
/opsx:sync [change-name]	合并 delta specs 到 openspec/specs/，保留未涉及内容	不归档 change	大多数简单项目不必手动跑，archive 时会提示
/opsx:archive [change-name]	检查 artifacts、检查任务完成情况、必要时同步 specs、然后移动到 archive 目录	不强制要求所有任务全都完成后才允许继续，但会给警告	归档前最好先 verify
/opsx:bulk-archive [change-names...]	识别已完成变更，检测 spec 冲突，按顺序批量归档	不适合替代日常单个 change 的收尾	多个并行 change 一起收口时很省心
/opsx:onboard	用真实代码库带你完整走一遍 workflow	不是纯文档演示，而是会真的创建并推进一个小 change	最适合培训和新成员上手

4. 最容易混淆的三组命令

propose vs new

• propose：一步到位，直接建好 planning artifacts；
• new：只先搭 change 脚手架，后面再用 continue / ff。

判断方法很简单：

• 想快：用 propose；
• 想控：用 new。

continue vs ff

• continue：一次只生成下一个 artifact；
• ff：一口气把 planning artifacts 都补齐。

所以：

• 复杂需求、每一步都要看：用 continue；
• 需求很明确、只是想走 expanded 流程：用 ff。

sync vs archive

• sync：只同步 specs，不归档；
• archive：收尾并归档，必要时会顺带引导你同步 specs。

大多数情况下，普通团队日常并不需要频繁手动执行 sync。

---

九、默认快速路径和扩展路径，到底怎么选

OpenSpec 现在最常见的两种使用方式，其实可以概括成下面两条路径。

1. 默认快速路径：适合大多数日常开发

/opsx:propose ──► /opsx:apply ──► /opsx:archive

这种方式的特点是：

• 学习成本最低；
• 上手最快；
• 很适合明确需求的小功能、中小型改造、单人推进任务。

你可以把它理解成：

• propose：先把图纸和清单画出来；
• apply：按图施工；
• archive：验收归档。

2. 扩展路径：适合复杂功能和团队协作

/opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

它更适合这些场景：

• 需求复杂，需要逐步确认 artifacts；
• 多人协作，希望 planning 更可控；
• 对实现与规范一致性要求更高；
• 多个 change 并行，需要更清晰的边界和归档策略。

3. 一个够用的选择规则

可以直接记下面这个版本：

• 需求明确、小功能、先求跑通：默认快速路径；
• 需求复杂、方案要评审、团队协作多：扩展路径；
• 需求还没想清楚 ：先 /opsx:explore，别急着开工。

---

十、和 Claude Code 搭配时，推荐这样用

下面这部分是全文里最偏实战的一节。

不是讲"理论上可以怎么做"，而是讲 你坐在 Claude Code 里，面对真实项目时，应该怎么开口、怎么推进、怎么收口。

很多人真正关心的不是"命令解释"，而是：

OpenSpec + Claude Code 到底怎么在项目里顺手用起来？

下面给一套比较实用的建议。

场景一：明确需求的小功能

适合：页面增强、小型功能新增、范围较清晰的优化。

推荐流程：

/opsx:propose add-dark-mode
/opsx:apply
/opsx:archive

为什么这样最合适：

• 先用 propose 固化范围和任务；
• 再让 Claude Code 进入执行态；
• 最后归档，形成完整留痕。

这种方式，既比"纯聊天直接改代码"稳，也不会重到让你觉得流程压人。

场景二：需求不清、先调研再说

适合：历史包袱多、方案分歧大、技术路线未定。

推荐流程：

/opsx:explore
# 探讨问题、比较方案、明确边界
/opsx:propose fix-login-redirect
/opsx:apply

这样做的好处是：

你把"思考阶段"和"施工阶段"分开了。

少走的不是一步，而是后面可能少返工三轮。

场景三：复杂改造、需要逐步审稿

适合：架构升级、复杂业务改造、大模块重构。

推荐流程：

openspec config profile
openspec update

/opsx:new refactor-auth-module
/opsx:continue
/opsx:continue
/opsx:continue
/opsx:apply
/opsx:verify
/opsx:archive

这种方式的重点不是"多几个命令"，而是：

• proposal 可以先审；
• specs 可以单独审；
• design 可以单独审；
• tasks 可以确认后再实施。

对团队协作来说，这很重要。

因为复杂项目里，最怕的不是慢一点，而是没对齐就快推进。

场景四：新人上手或团队培训

适合：第一次试 OpenSpec，或者想做团队内部演示。

推荐命令：

/opsx:onboard

它会用真实代码库带着你完整走一遍 OpenSpec 工作流，比单纯讲概念更容易让人建立直觉。

---

十一、OpenSpec 真正提升稳定性的，不是命令，而是这 4 个习惯

说到底，OpenSpec 不是魔法。它之所以能让 AI 输出稳定不少，靠的不是"神器感"，而是工程习惯被前置了。

1. 先把范围写下来，而不是把范围藏在聊天里

聊天会漂移，会丢上下文，会让人和 AI 都记混。

proposal 的价值，就是把"做什么、不做什么"钉住。

2. 把"为什么这么设计"也写下来

很多返工，不是因为代码不会写，而是后来才发现方案假设不成立。

design 的价值，就是把关键技术决策显性化。

3. 把任务拆到可执行，而不是一句"大概实现一下"

没有任务清单时，AI 很容易"大步流星，顺便多做一点"。

有了 tasks.md 之后，实施更像按图施工，而不是临场发挥。

4. 让 change 有边界、有归档、有历史

每个 change 独立成目录，天然更利于：

• 评审；
• 追责；
• 回滚；
• 知识沉淀；
• 多任务并行时的隔离。

所以 OpenSpec 真正改变的，不是"AI 会不会写"，而是"AI 写出来的东西能不能被工程体系接住"。

---

十二、几个非常实用、也最容易踩坑的点

1. 别把旧教程当现行标准

如果你看到的是更早期教程，里面可能还在讲旧的 /openspec:proposal 一类写法。

新版 OPSX 默认推荐的是 /opsx:* 体系，思路也已经从早期工作流迁移到了 action-based 模式。

2. 看不到某些命令，不一定是坏了，可能只是 profile 没开

比如：

• verify
• sync
• bulk-archive
• onboard

这些都不属于默认 core profile。

如果你装完后没看到，先别急着怀疑安装失败。更常见的原因是：

• 当前 profile 仍然是 core；
• 你没有执行 openspec config profile；
• 改完 profile 后没执行 openspec update。

3. 升级 CLI 后不执行 openspec update，等于白升级一半

很多人只做了：

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

然后发现当前项目里的命令和 skills 没变化。

这很正常，因为你只更新了工具本身，没有刷新项目内生成物。

4. archive 是"收口"，不是"形式主义"

很多人做到能跑就算结束，然后不 archive。

这样短期看省事，长期看非常亏：

• specs 没合回主线；
• change 没归档；
• 留痕断掉；
• 后面回看和继续演进都更混乱。

5. verify 虽然不是默认必跑，但复杂项目非常值得跑

它会从三个维度去看实现是否真的和 artifacts 对得上：

• 完整性（completeness）
• 正确性（correctness）
• 一致性（coherence）

如果你的团队对 AI 输出质量要求比较高，这一步很值。

---

十三、Claude Code 2.1.92 对这套工作流有什么现实加成

单看 OpenSpec，你会觉得它解决的是"流程与留痕"；

再看 Claude Code 2.1.92，你会发现它在"执行与可用性"上也补了不少现实细节。

比较值得关注的点有这些：

1. /cost 更细了

2.1.92 给订阅用户增加了 per-model 和 cache-hit 维度的 /cost 统计。

这件事的现实意义在于：

当你开始把工作流从"纯聊天"升级成"proposal/specs/design/tasks/apply/verify"这类多步骤协作后，成本透明度会更重要。你会更容易看出：

• 哪些环节更吃 tokens；
• 哪些环节 cache 命中高；
• 哪里值得优化协作方式。

2. 会话恢复体验更强了

2.1.92 对 /resume、会话恢复提示、session list 初始数量等都做了增强。

这对 OpenSpec 这种"一个 change 可能要跑好几个阶段"的工作流很友好，因为它天然就不是那种"一问一答即结束"的短会话模式。

3. skills / agents / worktree 相关问题修了不少

这一版修复里，有几项对真实工程特别关键：

• 修复了 skills 的某些 frontmatter 解析崩溃问题；
• 修复了 git worktree 下 skills / agents 发现异常问题；
• 修复了 Windows 下 hooks 执行相关问题；
• 修复了 plan mode 在 context compaction 后丢失的问题。

这些看起来像"边角 bug"，但对依赖 skills、agents、长会话、多仓或 worktree 的团队来说，都是实打实的稳定性加成。

4. Bedrock 配置体验更顺了

2.1.92 增加了交互式 Bedrock 登录向导，并补了更多 provider 相关的行为修正。

如果你的团队有云上代理或企业环境接入诉求，这会让 Claude Code 在企业实际环境里更顺一点。

---

十四、适合团队落地的一套最小实践方案

如果你是个人试用，按默认快速路径走就够了。

但如果你是团队推进，我更建议从"最小但成体系"的方案开始。

第一步：先统一最小口径

至少约定下面这些事：

• 小需求默认走 /opsx:propose -> /opsx:apply -> /opsx:archive；
• 复杂改造允许走 expanded workflow；
• 重要改造归档前建议 verify；
• 每个 change 只解决一个逻辑单元问题；
• change 名称尽量清晰，避免 update、wip 这种无意义命名。

第二步：把项目上下文写进配置

OpenSpec 的价值之一，就是它允许把项目上下文和规则真正写进去，而不是每次靠人重新讲一遍。

比如：

• 技术栈约束；
• 架构边界；
• 命名规范；
• 测试要求；
• 安全与发布约束。

第三步：从一个高价值场景试点

不要一上来就"整个团队全面切换"。

更现实的试点方式通常是：

• 先挑一个真实需求；
• 用 OpenSpec 跑完整链路；
• 比较有无 OpenSpec 时的返工量、对齐成本、交付清晰度；
• 再决定是否在更多项目铺开。

第四步：把 archive 当成知识沉淀入口

很多团队会重视生成，不太重视归档。

其实从组织资产角度看，archive 才是最容易长期产生价值的地方。

因为它决定了：

• 团队以后是否能回溯历史变更；
• 新成员是否能理解过去的设计判断；
• AI 未来是否能更稳地接续旧决策。

---

十五、一个更真实的结论：OpenSpec 不是让开发变慢，而是把"乱快"变成"稳快"

很多人第一次听到"规范驱动开发"，本能会担心两件事：

• 会不会太重？
• 会不会写一堆文档，反而拖慢开发？

这是非常正常的担心。

但如果把 OpenSpec 放到真实 AI 协作场景里看，它解决的恰恰是另外一种更隐蔽、也更昂贵的浪费：

• 需求没对齐就开始写；
• 设计没想清楚就先实现；
• 多改了很多本不该改的地方；
• 返工时又只能重新聊一轮；
• 最终产出不可追溯、不可沉淀。

这种"乱快"，表面上快，实际上很容易在项目层面变慢。

OpenSpec 的价值，不是让你把所有事情都流程化到窒息，而是让你在真正值得讲清楚的地方，先讲清楚，再让 AI 放开手脚去做。

所以它带来的，不是"慢一点的开发"，而是：

少一点玄学，多一点共识；少一点返工，多一点留痕；少一点聊天漂移，多一点工程闭环。

这也是为什么，OpenSpec + Claude Code 这组搭配，值得认真试一试。

因为它们合在一起解决的，从来不只是"写代码"这一个动作。

它们真正解决的是：

在 AI 已经会写代码的时代，我们怎么把"想清楚、讲清楚、做清楚、留清楚"这四件事重新接回软件工程。

---

十六、写在最后：别急着追求"让 AI 更猛"，先追求"让协作更稳"

AI 编码工具的上限，当然和模型能力有关；但在真实项目里，决定结果质量的，往往不是模型有多聪明，而是 你的需求有没有沉淀、边界有没有被写清、实施有没有被约束、结果有没有被归档。

这也是为什么，很多团队一开始会觉得 OpenSpec 像是在"增加步骤"，但真正跑过几轮之后，感受到的反而通常是：

• 返工少了；
• 讨论更聚焦了；
• AI 改错方向的概率低了；
• 新同学接手时更容易看懂上下文了；
• 一段时间后再回头看，也能说清当时为什么这么做。

所以，OpenSpec 真正带来的，不是"让开发更慢"，而是把那种看起来很快、实际上很乱的推进方式，变成一种 稍微多一点前置澄清，但后面明显更稳的推进方式。

对个人开发者来说，它是给 AI 加了一层护栏；

对团队来说，它更像是在 AI 时代重新补上了一层工程纪律。

如果只用一句话概括本文，那就是：

Claude Code 负责把事情做出来，OpenSpec 负责让这件事做得更对、更稳、更能被团队接住。

下面附上命令速记和本文整理依据，方便你收藏、转发或二次整理。

---

附录一：最推荐记住的命令组合

快速路径（大多数人先用这个）

/opsx:propose <需求>
/opsx:apply
/opsx:archive

先调研再实施

/opsx:explore
/opsx:propose <change>
/opsx:apply
/opsx:archive

扩展路径（复杂项目）

openspec config profile
openspec update

/opsx:new <change>
/opsx:continue 或 /opsx:ff
/opsx:apply
/opsx:verify
/opsx:archive

---

附录二：一句话记忆版

• openspec init：装进项目
• openspec update：升级后刷新项目配置
• /opsx:explore：先想
• /opsx:propose：先立项并生成工件
• /opsx:apply：再施工
• /opsx:verify：完工前核对
• /opsx:archive：最后归档闭环

---

附录三：本文整理依据

本文结合 OpenSpec 官方 README、Getting Started、Commands、Workflows、CLI、Migration Guide、1.2.0 CHANGELOG，以及 Claude Code 2.1.92 官方 changelog 进行了核对，重点以 2026 年 4 月可验证的官方口径为准。