Skip to main content

Openspec是什么？如何使用？

· 6 min read

OpenSpec 解决了一个我在 AI 编码里反复踩的坑：你和 AI 达成的共识，/clear 之后全没了。

  • 问题本质：AI 在长对话中遗忘早期约束，清空上下文后设计共识归零
  • OpenSpec 的解法：把共识写成结构化文档（proposal → spec → tasks），存进文件系统，不依赖对话记忆
  • 核心流程：Propose → Apply → Archive，四步闭环，所有变更可追溯
  • Delta Spec 机制：改需求不重写规格，用 ADDED/MODIFIED/REMOVED 增量描述，自动合并
  • 和 Superpowers 的关系：OpenSpec 管"写什么"，Superpowers 管"怎么写"——一个定方向，一个定纪律
  • 得物团队落地数据：10 天净增 25,546 行代码，研发提效 36%，关键是把规范写成 AI 的"可执行契约"

不是 Vibe Coding，是 Spec-Driven​

AI 写代码这件事，目前最大的瓶颈已经不是模型能力——是上下文管理和意图表达。

你在 Claude Code 里跟 AI 聊了半天，把需求拆明白了，架构设计也沟通清楚了，AI 开始写代码。写到一半你觉得不对劲，重新开了个会话——前面积累的共识全丢了。更糟的是，AI 写出来的代码逻辑看起来都对，但你隐隐觉得"不太对"——需求前期就没对齐，后面全是错的。

这就是典型的 Vibe Coding。

OpenSpec 要做的，就是把"你脑子里想的东西"和"AI 理解的东西"之间的落差，压缩到最小。

OpenSpec 到底是什么​

OpenSpec 是 Fission AI 开发的一个开源 CLI 工具，专门配合 Claude Code、Cursor 等 AI 编码助手做 规范驱动开发（Spec-Driven Development, SDD）。

说白了，它在代码仓库里建了一套"活规范"（Living Spec），每次改代码之前，先写一份结构化的提案文档——包括为什么要改、改什么、怎么改、怎么验证——然后 AI 按清单执行，改完自动归档。

这跟传统的 PRD 文档有本质区别：PRD 写完就过时了，没人维护。OpenSpec 的规范是活的——每次变更都会更新主规范，它是代码库的可执行真相来源，不是一次性的需求文档。

核心机制：Delta Spec​

OpenSpec 最聪明的设计是 Delta Spec。

改代码的时候，你不需要重写整份规范文档——你只写"增量"：这一轮新增了什么、修改了什么、删除了什么。

## ADDED Requirements
### Requirement: 深色模式切换
系统 MUST 在导航栏提供主题切换按钮。

#### Scenario: 用户切换主题
- GIVEN 用户在任意页面
- WHEN 用户点击主题切换按钮
- THEN 页面颜色方案立即切换为深色/浅色

## MODIFIED Requirements
### Requirement: 导航栏布局
系统 SHALL 在导航栏右侧预留主题切换按钮位置。

归档的时候，OpenSpec 自动把增量和主规范合并——新增的追加进去，修改的替换对应段落，删除的拿掉。这比每次手动维护整份文档可靠得多。

和 Superpowers 什么关系​

这两个名字经常一起出现，但它们是解决不同问题的。

OpenSpecSuperpowers
管什么写什么（What）怎么写（How）
解决什么需求漂移、共识消失AI 跳过测试、代码质量差
核心机制Delta Spec + 归档TDD 铁律 + 反合理化设计
什么时候用需要结构化需求管理需要约束 AI 执行纪律

OpenSpec 定方向，Superpowers 定纪律，Claude Code 做执行——三层互补，缺哪块补哪块。

不过 Superpowers 比较适合个人开发者快速原型，如果你要管的是一整个团队的需求变更、多人协作、代码可追溯性，OpenSpec 是更对口的工具。

怎么用​

先装 CLI：

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

进项目初始化：

cd your-project
openspec init

它会自动识别你用的 AI 工具（支持 Claude Code、Cursor、Copilot 等 25+ 种），然后生成 openspec/ 目录结构：

openspec/
├── specs/            # 主规范——系统的单一事实来源
│   └── ui/
│       └── spec.md
├── changes/          # 活跃变更
│   └── add-dark-mode/
│       ├── proposal.md   # 为什么要改
│       ├── design.md     # 技术方案
│       ├── tasks.md      # 实施清单
│       └── specs/        # 增量规范

然后三个命令走完整条流水线：

  1. /opsx:propose 添加深色模式 — AI 自动生成 proposal + spec + design + tasks，冻结需求
  2. /opsx:apply — AI 按 tasks.md 逐项实现，改完一条勾一条
  3. /opsx:archive — 归档变更，增量规范合并进主规范，变更目录保留审计记录

关键的体验是：每一步都是 Actions，不是 Phases。小改动可以跳过 design 直接写 tasks，大功能走完整流程。它不强制你按固定阶段走，你根据复杂度自己掌握。

得物团队的落地经验​

得物技术团队用这套工具链做了一个 10 天的新业务模块，数据如下：

  • 净增代码 25,546 行
  • 研发提效 36%
  • AI 自主完成 738 次文件读取、550 次代码编辑、662 次终端命令执行

但比数据更有价值的是他们总结的三层规范体系：

层次目录作用
约束层.claude/rules/告诉 AI 禁止什么、必须遵守什么
示范层.claude/code-design/告诉 AI 标准代码长什么样
视觉层.claude/ui-design/告诉 AI 页面应该长什么样

得物团队发现了一个反直觉的结论：只有约束层是不够的。AI 会生成"合法但不地道"的代码——规范都对，但风格完全不对。加入示范层和视觉层之后，AI 的输出质量和一致性才明显提升。

换句话说：规范不是"写几条规则就完事了"——你给 AI 的输入质量，直接决定它的输出质量。这一点，比选什么模型重要得多。

References​