LPZ 的个人网站

title: OpenSpec：让 AI 编码代理"先对齐再写码"的轻量级 Spec 框架 date: 2026-05-19 tags:

AI
Agent
Spec
SDD
OpenSpec

Why：为什么需要 OpenSpec？

AI 编码代理（Claude Code、Codex、Cursor、Copilot、Trae 等）写代码已经够快了，真正卡住团队的是**"它到底要写什么"**：

需求散落在聊天记录里，下一次会话上下文一丢就忘；
同一个功能不同代理理解不一致，越改越偏；
想做"先约定再实现"的 Spec-Driven Development，又被 Spec Kit 的强阶段闸门 / Kiro 的 IDE 锁定劝退；
现实中绝大多数活儿是 brownfield（在已有系统上改），不是 greenfield。

Fission-AI/OpenSpec 给出了一个轻量答案：在代码之前加一层"人和 AI 都能读、都能改的 Spec 层"，让需求先落到磁盘上，再让代理去实现。

它的设计哲学只有四句话：

fluid not rigid（流动而非僵化） iterative not waterfall（迭代而非瀑布） easy not complex（简单而非复杂） brownfield not just greenfield（先服务存量项目）

和同类对比：

对比对象	痛点	OpenSpec 的取舍
GitHub Spec Kit	阶段闸门重、Markdown 量大、需要 Python 环境	工件可随时回改，无强制阶段顺序
AWS Kiro	锁定 IDE，仅支持 Claude 系列模型	通过斜杠命令对接 25+ 主流代理
不写 spec	提示词模糊、结果不可预测	用最小仪式把"约定"留下来

What：它是什么？

一句话：一个开源的、文件即真理（file-as-truth）的轻量 Spec 框架——把"系统现在怎么运转"和"这次准备怎么改"都用 Markdown 存进 openspec/ 目录，再通过斜杠命令让 AI 代理按 Spec 干活。

核心概念只有两个目录：

openspec/
├── specs/          # 真理源：系统当前的行为契约
│   └── <domain>/
│       └── spec.md
└── changes/        # 提议中的修改：每个 change 一个文件夹
    └── <change-name>/
        ├── proposal.md   # 为什么 + 大致是什么
        ├── design.md     # 怎么做（技术方案）
        ├── tasks.md      # 实现清单（带勾选框）
        └── specs/        # delta spec：ADDED / MODIFIED / REMOVED
            └── <domain>/spec.md

几个关键设计：

specs/ vs changes/ 分离：可以同时跑多个 change 而不互相打架；archive 时 delta 才会合并到主 spec。
Delta Spec：用 ## ADDED Requirements / ## MODIFIED Requirements / ## REMOVED Requirements 三类标题，明确表达"相对当前规范的增量"，天然适配 brownfield。
行为契约而非实现说明：spec.md 写"系统应该 SHALL/MUST 做什么"，不写函数名 / 库选型；这些放 design.md 和 tasks.md。
斜杠命令驱动代理：/opsx:propose、/opsx:apply、/opsx:archive 这些命令在 25+ 代理里都能用，等价于"团队级标准化的提示词"。
CLI 做工程支撑：openspec list / show / validate / view / update 用来管理、校验、刷新工件。

工件之间的关系：

proposal ──► specs ──► design ──► tasks ──► implement
   │           │          │          │
  why         what        how       steps
                ▲                     │
                └────── 实现中边干边回改 ──┘

How：怎么用？

1. 安装与初始化

要求 Node.js ≥ 20.19.0：

bash

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

cd your-project
openspec init

init 会扫描你已经在用的 AI 代理（Claude Code、Codex、Cursor、Copilot、Trae……），把对应的斜杠命令和指引写进各自的配置目录，然后建好 openspec/ 骨架。

也支持 pnpm / yarn / bun / nix。需要切换到包含 /opsx:new、/opsx:ff、/opsx:verify、/opsx:bulk-archive 的"扩展工作流"，可以执行 openspec config profile 切到非 core profile，再 openspec update。

2. 默认快速路径（core profile）

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

直接告诉代理：

/opsx:propose add-dark-mode

代理会创建 openspec/changes/add-dark-mode/，并把 proposal、specs、design、tasks 一次性铺好。

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!

人类负责 review 和微调这些 Markdown，确认"约定"无误，再继续：

/opsx:apply       # 按 tasks.md 一项项实现
/opsx:archive     # 把 delta 合进主 specs/，把 change 移到 archive/

3. 写一个 delta spec 长什么样

markdown

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

要点：

### Requirement: 写"系统应该做什么"，用 SHALL / MUST / SHOULD / MAY（RFC 2119）表达强度；
#### Scenario: 用 GIVEN / WHEN / THEN 给可测试的具体例子；
archive 时：ADDED 追加、MODIFIED 替换、REMOVED 删除——非常符合直觉。

4. 扩展工作流（按需开启）

切到扩展 profile 后，可以拆得更细：

/opsx:new        # 只建空脚手架
/opsx:continue   # 一次造一个工件，逐步审阅
/opsx:ff         # fast-forward：一把生成全部规划工件
/opsx:apply      # 实现
/opsx:verify     # 校验实现是否对齐 spec / design / tasks
/opsx:archive    # 归档
/opsx:bulk-archive  # 批量归档多个完成的 change

什么时候用谁，记一句话就够了：

需求清楚就 /opsx:ff，需要边走边想就 /opsx:continue。

5. 常用 CLI 速查

命令	作用
`openspec init`	初始化目录与各代理的命令
`openspec list`	列出当前所有 change
`openspec show <change>`	展示某个 change 的全部工件
`openspec validate <change>`	校验 spec / delta 的格式
`openspec view`	启动交互式 dashboard
`openspec update`	升级后刷新各代理的提示词 / 命令

6. 可以用，但要心里有数

模型选择：官方建议 Opus 4.5、GPT 5.2 这种推理强的模型来 propose 和 apply；小模型容易把 spec 和实现混着写。
上下文卫生：开始 /opsx:apply 前清一下上下文，避免代理被旧对话带偏。
workspace 命令仍在迭代：跨仓协作的 openspec workspace 系列处于 active development，别在它之上搭长期自动化。
Telemetry：默认采集匿名命令名和版本，不收路径 / 内容；介意可 export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1。

一个 mental model

specs/ 是"系统现在长什么样"的真理源，changes/<name>/ 是"这次准备怎么改"的提案包；AI 代理的工作就是把提案落实回真理源。

类比一下熟悉的工具：

openspec/specs/ ≈ 主分支的代码
openspec/changes/<name>/ ≈ 一个 PR 分支，里面带着 proposal（PR 描述）+ delta（diff）+ tasks（checklist）
/opsx:archive ≈ merge：把 delta 合到主 spec，把整个 change 归档留痕

这样组织之后，你和 AI 之间不再是"靠聊天传需求"，而是靠一份双方都能改的 Markdown 在协作。出问题时，回去看 openspec/changes/archive/ 里的工件，比翻聊天记录可靠得多。

参考

仓库：https://github.com/Fission-AI/OpenSpec
入门：https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md
概念：https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md
工作流：https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md
命令参考：https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md
支持的代理：https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md

Why：为什么需要 OpenSpec？ ​

What：它是什么？ ​

How：怎么用？ ​

1. 安装与初始化 ​

2. 默认快速路径（core profile） ​

3. 写一个 delta spec 长什么样 ​

4. 扩展工作流（按需开启） ​

5. 常用 CLI 速查 ​

6. 可以用，但要心里有数 ​

一个 mental model ​

参考 ​