OpenSpec 是 Fission-AI 开发的轻量级规范驱动开发 (SDD, Spec Driven Development) 工具，它试图解决 AI 编程中最常见但最容易被低估的问题：需求只停留在聊天记录里，模型就会在后续实现中丢失上下文、误解边界、擅自扩展范围，最终形成看似可运行但偏离意图的代码。OpenSpec 的做法不是把 AI 变成更强的“一次性代码生成器”，而是在代码仓库里建立可审阅、可迭代、可归档的规格层：openspec/specs/ 保存当前系统行为的真相源，openspec/changes/ 保存每一次拟议变更的 proposal、delta specs、design 和 tasks，等实现完成后再 archive 合并回规格库。它的核心哲学是 fluid not rigid、iterative not waterfall、easy not complex、brownfield-first，也就是用足够轻的流程约束模型，而不是用笨重的阶段门把工程变成文档仪式。截止 2026-04-07，官方 README 和 v1.2.0 Release 已经把 OPSX 作为主工作流，默认 core profile 提供 /opsx:propose、/opsx:explore、/opsx:apply、/opsx:archive 四个关键动作；如果需要更强的过程控制，可以通过 openspec config profile 启用 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync 等扩展命令。理解 OpenSpec 的关键不是背命令，而是理解它把 AI 编程拆成两个可验证对象：一是“要实现什么”的行为契约，二是“这次改动如何影响既有行为”的增量变更。只要这个边界清晰，OpenSpec 就能成为一种实用的 harness：不盲信 LLM 的临场发挥，而是要求模型先产出可读的规格、任务与设计，再由人和 CLI 校验后进入实现。
OpenSpec 解决什么问题？
OpenSpec 的背景是 AI coding assistant 已经足够强，但仍然不稳定。模型在短任务里可以根据自然语言快速生成代码，在长任务、存量项目和跨模块修改中却很容易出现三类问题：
- 上下文漂移：需求在聊天历史中逐渐被稀释，模型后续实现时只记得局部目标，忘记非目标、兼容性要求和异常场景。
- 范围漂移：用户只想改一个行为，模型可能顺手重构、改 UI、替换依赖，导致 diff 变大且难以 review。
- 验证漂移：模型声称“已实现”，但没有把实现与原始需求、验收场景、已知约束重新对齐。
官方 README 把这个问题概括为：当需求只存在于聊天历史时，AI 编程助手强大但不可预测；OpenSpec 增加了一个轻量规格层，让人和 AI 在写代码前先就“要构建什么”达成一致$^{[1]}$。这和项目里的 harness engineering 直觉一致：不要信任 LLM 会自动记住正确格式、正确边界和正确任务状态，必须把关键意图落到可检查的工件里。
OpenSpec 的直接收益不是“代码自动更正确”，而是让错误更早暴露：
- 在实现前 review proposal，可以发现目标是否跑偏。
- 在实现前 review delta specs，可以发现行为契约是否遗漏。
- 在实现前 review design，可以发现技术路线是否过度复杂。
- 在实现中按 tasks 推进，可以发现任务状态是否真实。
- 在完成后 archive，可以把已确认的行为更新回规格库，避免下一轮对话重新口头解释。
这套机制尤其适合存量项目。新项目可以从一份完整 PRD 开始，但现实中的大多数工程工作都是在既有系统上做小步增量修改。OpenSpec 因此强调 brownfield-first：用 delta 描述“当前系统要怎么变”，而不是每次从零重写一份完整系统规格$^{[4]}$。
最新定位：轻量、通用、OPSX 化
OpenSpec 官网将它定位为 lightweight spec-driven framework，并强调 Universal、Open Source、No API Keys、No MCP $^{[2]}$。这个定位很关键：它不是一个模型服务、不是 MCP 服务，也不是某个 IDE 的私有功能，而是一个围绕仓库文件和 AI 指令生成的规格工作流。
截止 2026-04-07，官方 GitHub README 展示的 Quick Start 是：
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
然后在 AI 工具里发起：
/opsx:propose <what-you-want-to-build>
v1.2.0 Release 在 2026-02-23 发布，重点变化包括 profiles、单步 propose workflow、Pi 与 Kiro 支持，以及 AI tool auto-detection $^{[7]}$。这意味着一些较早资料里的工作流写法需要更新：过去常见的 /opsx:new + /opsx:ff 仍然存在于扩展模式，但默认 core profile 更推荐用 /opsx:propose 直接生成完整规划工件。
OpenSpec 的官方哲学可以压缩成四句话$^{[4]}$：
- fluid not rigid：命令是可执行动作，不是锁死的阶段门。
- iterative not waterfall：实现中发现新信息，可以回头改 proposal、specs、design 或 tasks。
- easy not complex：初始化和使用成本要低，默认只保留必要流程。
- brownfield-first：更关注存量项目上的增量修改，而不是只服务从零开始的 0 到 1 项目。
这使 OpenSpec 和传统“先写一堆文档再开发”的流程不同。它不是瀑布式文档管理，而是给 AI 编程引入一个最小可用的规格反馈环。
核心模型：specs/ 与 changes/
理解 OpenSpec 的第一步是理解它的双目录模型$^{[3]}$：
openspec/
├── specs/ # 当前系统行为的真相源
│ └── <domain>/
│ └── spec.md
├── changes/ # 拟议变更，每个变更一个目录
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # delta specs，描述本次如何改变行为
│ └── <domain>/
│ └── spec.md
└── config.yaml # 可选项目配置
specs/ 是 source of truth，描述系统当前应该如何工作。它可以按功能域、组件或 bounded context 组织，例如 auth/、payments/、search/、api/、frontend/ 等$^{[4]}$。
changes/ 是拟议修改。每次改动都有独立目录，里面放本次变更的意图、规格增量、技术设计和实现任务。官方文档强调这种分离的价值：多个变更可以并行存在，review 不会污染主规格，archive 时再把 delta 干净地合并回真相源$^{[4]}$。
用工程语言说，specs/ 类似“当前行为契约库”，changes/ 类似“待合并的行为补丁”。它让 AI 不再只面对一段临时聊天，而是面对一个可持久化、可 diff、可 review 的任务上下文。
Spec 不是实现计划
OpenSpec 的 spec.md 描述的是行为契约，不是实现计划。官方 Concepts 文档明确建议：spec 应该写可观察行为、输入输出、错误条件、外部约束和可测试场景；不应该写内部类名、函数名、框架选择、逐步实现细节，这些内容属于 design.md 或 tasks.md$^{[4]}$。
一个典型 spec 结构如下：
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
这个结构体现了三层约束：
| 层级 | 作用 | 关键问题 |
|---|---|---|
Purpose |
说明这个规格域覆盖什么 | 这个 spec 管哪类行为？ |
Requirement |
描述系统必须满足的行为 | 系统应该做什么？ |
Scenario |
给出可验证场景 | 在什么条件下应该产生什么结果？ |
这里的 SHALL、MUST、SHOULD、MAY 继承了 RFC 2119 风格，用于表达需求强度$^{[4]}$。实际写作中不必过度形式化，但至少要做到：如果需求可以写成自动化测试，spec 里的 scenario 应该能成为测试设计的输入。
Delta Specs：OpenSpec 适合存量项目的关键
OpenSpec 最有价值的概念是 delta specs。它不要求每次变更都重写完整规格，而是要求描述本次对既有行为的增量影响$^{[4]}$：
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA.)
delta 的三类区块很直接：
| 区块 | 含义 | Archive 后的效果 |
|---|---|---|
ADDED Requirements |
新增行为 | 追加到主 spec |
MODIFIED Requirements |
修改既有行为 | 替换主 spec 中对应 requirement |
REMOVED Requirements |
删除或废弃行为 | 从主 spec 删除 |
这就是 OpenSpec 和普通“开发计划文档”的差异：计划文档通常只描述“我要做什么”，delta specs 还描述“系统行为从 A 变到 B”。对于存量系统，这一点比完整 PRD 更重要，因为 bug 修复、重构、兼容性调整、权限变更等工作经常不是新增功能，而是修改已有行为。
OPSX 工作流：动作而不是阶段
官方 Workflows 文档强调 OPSX 是 actions, not phases。传统流程容易变成“规划完成后不能回头”，但 OPSX 允许 proposal、specs、design、tasks 在学习过程中被更新$^{[5]}$：
proposal -> specs -> design -> tasks -> implement
^ ^ ^ |
| | | |
+---------+--------+----------+
update as you learn
默认 core profile 只暴露四个命令$^{[6]}$：
| 命令 | 用途 |
|---|---|
/opsx:propose |
创建 change，并一次性生成 planning artifacts |
/opsx:explore |
在还不确定需求时先探索、比较方案、调查代码 |
/opsx:apply |
根据 change 里的 tasks 执行实现 |
/opsx:archive |
完成后归档，并把规格变更合并回主规格 |
扩展工作流提供更细的控制$^{[6]}$：
| 命令 | 用途 |
|---|---|
/opsx:new |
只创建变更脚手架 |
/opsx:continue |
按依赖逐个生成下一个 artifact |
/opsx:ff |
fast-forward，一次性生成所有规划工件 |
/opsx:verify |
验证实现是否匹配 artifacts |
/opsx:sync |
将 delta specs 合并到主 specs |
/opsx:bulk-archive |
批量归档多个变更 |
/opsx:onboard |
引导式教程 |
我的理解是：默认模式适合“目标已经比较清晰”的中小变更，扩展模式适合高风险、高复杂度、需要逐步 review 的变更。不要把扩展命令当成必须流程，否则 OpenSpec 会从轻量 harness 变成新的文档负担。
CLI 的角色：人类和 Agent 共用的控制面
OpenSpec 的 slash commands 运行在 AI coding assistant 的聊天界面里，而 openspec CLI 是本地控制面。CLI 文档把命令分成 setup、browsing、validation、lifecycle、workflow、schemas、config 等类别$^{[8]}$。
常用命令如下：
openspec init
openspec update
openspec list
openspec list --specs
openspec show <change-or-spec>
openspec validate <change>
openspec view
openspec archive <change> --yes
对人类开发者来说，list、show、view、validate 是 review 工具；对 Agent 来说，带 --json 的 list、show、validate、status、instructions、templates、schemas 可以作为结构化输入$^{[8]}$。这也体现了 OpenSpec 的工程设计：不要只让模型读自由文本，尽量给它可以解析和校验的结构化状态。
安装要求也需要注意。官方 Installation 文档要求 Node.js 20.19.0 或更高版本，并支持 npm、pnpm、yarn、bun 和 Nix 安装方式$^{[9]}$。如果团队切换或新增 AI 工具，官方建议升级包后在项目内运行 openspec update，重新生成 agent 指令和 slash command 绑定$^{[1]}$。
和 Spec Kit、Kiro、普通提示词的区别
OpenSpec 官方 README 给出的对比很直接$^{[1]}$：
- 相比 Spec Kit，OpenSpec 更轻、更可迭代，更偏向存量项目；Spec Kit 更强调完整阶段和较重的 Markdown 结构，适合复杂 greenfield 场景。
- 相比 Kiro，OpenSpec 不绑定单一 IDE 或模型，使用开发者已有的工具。
- 相比没有 specs 的 AI 编程，OpenSpec 提供更可预测的意图对齐和 review 入口。
掘金文章也把 Spec-Kit 与 OpenSpec 视为同属 SDD、解决“实现什么”的竞争工具，而把 Superpowers 视为解决“如何高质量实现”的执行方法论工具$^{[10]}$。这个判断有参考价值，但要注意二级资料可能滞后于官方版本。比如官方 v1.2.0 后默认路径已经强调 /opsx:propose 和 core profile，且目录结构以 openspec/ 为准；阅读第三方教程时应优先用官方 README、docs 和 release note 校正命令与目录。
我更倾向于这样选型：
| 场景 | 更适合的选择 | 原因 |
|---|---|---|
| 存量项目的小到中型功能迭代 | OpenSpec | delta specs 能表达已有行为如何变化 |
| 需求还不清晰的探索 | /opsx:explore 后再 OpenSpec |
先澄清，不急着生成工件 |
| 大型新系统从零开始 | Spec Kit 或更重的规格流程 | 可能需要更完整的 constitution、plan、research、contracts |
| 一次性脚本或很小修复 | 不一定需要 OpenSpec | 流程成本可能高于收益 |
| 高风险安全、权限、计费改动 | OpenSpec 扩展工作流或更严格流程 | 需要逐步 review specs、design 和 tasks |
使用 OpenSpec 的实践建议
第一，先把 openspec/project.md 或项目上下文补齐。初始化后，官方文档建议让 AI 读取项目上下文文件并补充技术栈、约定和架构模式$^{[1]}$。这一步不是形式主义，它会影响后续 proposal、design 和 tasks 的默认假设。
第二，spec 只写可观察行为。不要在 spec 里写“创建 UserService 类”“使用 Redis 实现缓存”之类实现细节。除非这些是对外契约的一部分，否则应该放进 design.md。
第三，delta 要完整覆盖行为变化。修改需求时不要只写“支持 2FA”，还要写清楚登录流程、失败场景、记住登录、会话过期、恢复流程是否变化。
第四，review artifacts 后再 apply。/opsx:propose 能一次性生成完整工件，但这不表示工件正确。符合 zero trust 原则的做法是先读 proposal、specs、design、tasks，再让模型实现。
第五，使用 CLI 做结构校验。至少在实现前运行 openspec validate <change>；复杂项目可以把 validate 接到 CI 或 PR 检查里。
第六，archive 不是清理垃圾，而是把已经实现并确认的行为合并回真相源。没有 archive，规格库不会持续反映系统当前状态，下一次变更仍然会依赖聊天记忆。
第七，不要同时引入两套 SDD 真相源。如果项目已经用 Spec Kit 管理需求，再并行引入 OpenSpec，容易让模型不知道该遵循哪一套 specs。除非团队有明确分层规则，否则二选一更稳。
OpenSpec 的边界
OpenSpec 不能替代工程判断。它让需求变得可见、可 review、可归档，但不会自动保证需求正确，也不会保证实现正确。
常见风险包括：
- 模型生成的 spec 本身有错：因此人必须 review，而不是把 OpenSpec 当成自动 PRD 生成器。
- spec 写得过细：如果把内部实现塞进 spec，后续重构会被无意义约束拖住。
- spec 写得过空：如果只写一句“支持登录”，没有 scenario，validate 即使通过也很难指导实现。
- archive 不及时：change 完成后不归档，主 specs 会落后于代码。
- 第三方教程滞后：OpenSpec 命令和 profile 在 v1.2.0 已有变化，应优先看官方 docs。
所以，OpenSpec 最适合被理解为一种“轻量规格 harness”：它把 AI 的自由发挥限制在可审阅工件之后，把临时聊天记忆升级成仓库内的行为契约，但仍然需要人类对需求、架构、测试和安全负责。
参考文献
[1] Fission-AI. OpenSpec: Spec-driven development (SDD) for AI coding assistants. GitHub, 2026.
[2] Fission-AI. OpenSpec: A lightweight spec-driven framework. OpenSpec.dev, 2026.
[3] Fission-AI. Getting Started. OpenSpec Documentation, 2026.
[4] Fission-AI. Concepts. OpenSpec Documentation, 2026.
[5] Fission-AI. Workflows. OpenSpec Documentation, 2026.
[6] Fission-AI. Commands. OpenSpec Documentation, 2026.
[7] Fission-AI. v1.2.0 - Profiles, Pi & Kiro Support. GitHub Releases, 2026.
[8] Fission-AI. CLI Reference. OpenSpec Documentation, 2026.
[9] Fission-AI. Installation. OpenSpec Documentation, 2026.
[10] 爪哇缪斯. AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南. 掘金, 2026.