OpenSpec 阅读分析与使用笔记

这篇文章解决什么问题

OpenSpec 是 Fission-AI 维护的 AI 原生规格驱动开发工具，仓库地址：

Fission-AI/OpenSpec

它不是一个代码生成模型，也不是某个 IDE 的插件。它更像一层放在 AI coding assistant 和真实代码之间的“规格治理层”：

用 openspec/specs/ 记录系统当前行为。
用 openspec/changes/<change>/ 记录一个变更的提案、规格增量、设计和任务。
用 /opsx:* 命令指导 AI 先形成变更上下文，再实现代码。
用 openspec validate/status/instructions/archive 等 CLI 命令让人和 agent 都能检查当前状态。
用 schema 和 template 让团队把自己的流程写成可维护的文件，而不是埋在一次性 prompt 里。

一句话：

OpenSpec 想解决的不是“让 AI 更会写代码”，而是“让人和 AI 在写代码前先对齐要改什么、为什么改、改完如何验收”。

采集时间：2026-06-22。
当前 npm 版本：@fission-ai/openspec@1.4.1。
Node 要求：>=20.19.0。
阅读对象：GitHub main 分支、README、docs/getting-started.md、docs/concepts.md、docs/commands.md、docs/cli.md、docs/workflows.md、docs/opsx.md、docs/customization.md、docs/supported-tools.md、docs/installation.md、docs/multi-language.md、CHANGELOG.md、package.json、src/cli、src/core、src/commands、schemas/spec-driven。
说明：本文未本地安装 OpenSpec，未跑它的测试，只做官方文档、npm 元信息和源码目录的静态阅读。

先说结论

OpenSpec 的核心资产不是 slash command，而是 openspec/specs/ 和 openspec/changes/ 这套可版本化的变更记录。
它适合中大型功能、跨模块改动、API/行为契约变更、需要回看历史决策的项目。
它默认的 core profile 已经足够日常使用：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:sync、/opsx:archive。
它的完整玩法是 OPSX：把工作拆成 action，而不是锁死在线性阶段里。
它比纯 AGENTS.md 更动态，因为 agent 会查询 CLI 得到当前 change 状态、artifact 依赖和下一步说明。
它比“写一份 PRD 再交给 AI”更工程化，因为它会把完成后的 delta specs 合并回主规格，并保留 archive。
它不是测试框架，也不是代码索引工具。它不能保证实现正确，只能让“目标、范围、验收口径”更清楚。
它有明显仪式感。很小的单行 bug、样式微调、临时脚本，不一定值得引入完整 OpenSpec 流程。
workspace、context store、initiative 目前属于 beta，适合多仓协调探索，但不应该当成稳定外部自动化接口。

我的判断：

OpenSpec 是给 AI coding agent 用的“变更管理协议”。它把聊天里的短期意图沉淀成 repo 内可审查、可校验、可归档的规格和任务。

它从什么问题出发

AI 编程的问题通常不是“完全写不出来”。

真正危险的是：

需求只存在聊天里，换个上下文就丢。
用户说得很粗，agent 自己补了很多假设。
agent 开始写代码前，没有和用户确认可见行为。
实现时发现代码结构和预期不同，但没有同步更新计划。
任务完成后，只剩一堆 diff，很难知道当初为什么这样改。
多个功能并行时，规格、任务、代码、review 互相混在一起。
过几周回看时，不知道某个行为是设计如此、历史遗留，还是 AI 当时脑补。

传统项目里，人会用 issue、PRD、ADR、设计文档、测试用例、PR 描述来控制这些风险。

AI coding agent 加速了编码，也放大了这些风险。因为生成代码太快，错误方向也会被很快写得很完整。

OpenSpec 的切入点是：不要让需求只停留在对话里，要把变更意图落到仓库里的结构化文件。

OpenSpec 的基本哲学

官方反复强调几个原则：

原则	含义
fluid not rigid	不把工作锁死在阶段里，可以随时更新 artifact
iterative not waterfall	实现过程中学到新信息后，允许回头修正规格和设计
easy not complex	初始化和默认流程要轻，不要求一上来搭复杂体系
brownfield-first	面向已有代码库，不只面向从零开始的新项目

这里的 brownfield-first 很关键。

很多规格驱动工具默认是“先完整定义新系统，再实现”。但真实软件工作更多是：

改一个已有登录流程。
给已有订单模块加字段。
改一个旧接口的错误语义。
迁移某个配置项。
修一个线上边界 bug。

这类工作不是重写全量规格，而是说明“相对当前系统，什么行为要变”。

所以 OpenSpec 引入了 delta specs。它不要求每次复制整份规格，而是把变更写成：

新增什么 requirement。
修改什么 requirement。
移除什么 requirement。
必要时重命名什么 requirement。

完成后，archive 流程再把这些增量合并进主规格。

安装和初始化

OpenSpec 是 npm 包：

bash

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

也可以用 pnpm、yarn、bun 或 Nix。需要注意：

Bun 可以全局安装，但 OpenSpec 当前仍要求 Node.js 在 PATH 上可用。
官方要求 Node.js 20.19.0 或更高。
当前包名是 @fission-ai/openspec。
CLI 命令名是 openspec。

初始化：

bash

cd your-project
openspec init

初始化会做几件事：

创建 openspec/ 目录。
创建 specs/ 和 changes/。
生成或更新项目配置。
根据选择的 AI 工具写入对应的 skills 和 commands。
默认使用 core profile。

一个典型结构：

text

openspec/
├── specs/
│   └── <domain>/
│       └── spec.md
├── changes/
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/
│           └── <domain>/
│               └── spec.md
└── config.yaml

如果选了 Claude Code，可能会生成：

text

.claude/skills/openspec-*/SKILL.md
.claude/commands/opsx/<id>.md

如果选了 Cursor，可能会生成：

text

.cursor/skills/openspec-*/SKILL.md
.cursor/commands/opsx-<id>.md

如果选了 Codex，要特别注意：OpenSpec 的 Codex command 文件写到全局 Codex home，而不是项目目录：

text

$CODEX_HOME/prompts/opsx-<id>.md

如果没有设置 $CODEX_HOME，默认是：

text

~/.codex/prompts/

OpenSpec 的核心模型

OpenSpec 可以先用四个词理解：

概念	作用
spec	系统当前行为的事实来源
change	一个尚未完成的变更
artifact	change 里的文档产物
archive	完成后把 delta 合并回主规格，并保留历史

完整循环是：

text

当前规格
  -> 提出 change
  -> 写 proposal/specs/design/tasks
  -> 实现 tasks
  -> 校验实现和 artifact 是否一致
  -> sync delta specs
  -> archive change
  -> 主规格变成新的当前规格

它的思想不是“每个项目先写一本大规格书”。

更准确地说：

每个变更都带着自己的小规格、小设计和小任务；变更完成后，把真正成为系统行为的部分沉淀进主规格。

`specs/`：当前行为的事实来源

openspec/specs/ 描述系统当前已经认可的行为。

目录通常按领域组织：

text

openspec/specs/
├── auth/
│   └── spec.md
├── billing/
│   └── spec.md
├── notifications/
│   └── spec.md
└── ui/
    └── spec.md

一个 spec 不是实现说明，而是行为契约。

应该写：

用户或下游系统能观察到的行为。
输入、输出、错误条件。
权限、安全、隐私、兼容性约束。
可以被测试或人工验证的场景。

不应该写：

内部函数名。
某个类怎么拆。
用哪个私有 helper。
具体循环怎么写。
纯实现步骤。

一个简化例子：

markdown

# Auth Specification

## Purpose

定义登录、会话和退出相关行为。

## Requirements

### Requirement: Password Login

系统 MUST 在账号和密码都有效时创建登录会话。

#### Scenario: Login succeeds

- GIVEN 用户提交有效账号和密码
- WHEN 登录请求被处理
- THEN 系统创建会话
- AND 用户进入已登录状态

#### Scenario: Login fails

- GIVEN 用户提交错误密码
- WHEN 登录请求被处理
- THEN 系统返回登录失败提示
- AND 不创建会话

这里的 MUST、SHALL、SHOULD、MAY 来自 RFC 2119 风格，用来表达强度：

关键词	语义
MUST / SHALL	必须满足
SHOULD	应该满足，但可能有明确例外
MAY	可选行为

判断一段内容是否应该写进 spec，有个简单标准：

如果内部实现换掉但外部行为不变，这段内容大概率不该放在 spec 里。

`changes/`：一个变更一个文件夹

openspec/changes/<change-name>/ 是工作中的变更。

典型结构：

text

openspec/changes/add-dark-mode/
├── proposal.md
├── design.md
├── tasks.md
├── .openspec.yaml
└── specs/
    └── ui/
        └── spec.md

每个文件承担不同职责：

文件	解决的问题
`proposal.md`	为什么做、做什么、范围是什么
`specs/*/.md`	行为上新增、修改、移除什么
`design.md`	技术方案、架构取舍、风险
`tasks.md`	具体实现清单
`.openspec.yaml`	change 元数据，例如 schema

这套拆分比一个大文档更适合 AI：

agent 能单独读取 proposal 来理解意图。
agent 能单独读取 delta spec 来理解验收行为。
agent 能单独读取 design 来理解技术路线。
agent 能单独读取 tasks 来知道下一步实现什么。
CLI 能基于文件存在状态计算 artifact 进度。

artifact 流程

默认 schema 是 spec-driven，artifact 关系大致是：

text

proposal
  ├── specs
  └── design
        \ 
         -> tasks
              -> apply

更准确地说：

proposal 不依赖其它 artifact。
specs 依赖 proposal。
design 依赖 proposal。
tasks 依赖 specs 和 design。
apply 依赖 tasks。

OpenSpec 里的依赖不是传统流程审批。它不是说“你必须先进入 proposal 阶段，再进入 spec 阶段”。

它更像：

这个 artifact 已经有足够上下文可以创建了。

所以官方把 OPSX 说成 action，不说 phase。

这点很重要。因为真实工作里经常发生：

写 design 时发现 spec 过宽，需要收窄。
实现 tasks 时发现设计不可行，需要回改 design。
写代码时发现现有行为不是想象的，需要补充 proposal 背景。
验证时发现任务完成了但 spec 没覆盖边界，需要补 delta spec。

OpenSpec 的立场是允许这些回改，只要最终 artifact 和实现一致。

proposal：记录为什么做

proposal.md 不应该只是“我要加一个按钮”。

它至少要回答：

这个变更解决什么问题。
谁受影响。
范围内是什么。
范围外是什么。
高层方案是什么。
有没有回滚或迁移风险。

一个好的 proposal 能避免 agent 偷偷扩大范围。

比如“加深色模式”可以写成：

markdown

# Proposal: Add Dark Mode

## Intent

降低夜间使用时的视觉负担，并允许用户跟随系统外观设置。

## Scope

In scope:
- 提供 light/dark 两种主题
- 用户可以手动切换
- 首次访问时读取系统偏好
- 保存用户选择

Out of scope:
- 自定义主题色
- 每个页面单独配置主题
- 后台管理品牌皮肤

## Approach

复用现有样式体系，以 CSS variables 承载主题 token。

proposal 的价值是定边界。很多 AI 乱改，根源就是没有明确的 out of scope。

delta specs：OpenSpec 最关键的设计

delta specs 描述“相对当前系统，什么变了”。

常见 section：

markdown

## ADDED Requirements

### Requirement: Theme Selection

系统 SHALL 允许用户在浅色和深色主题之间切换。

#### Scenario: Manual theme switch

- GIVEN 用户打开设置页
- WHEN 用户选择深色主题
- THEN 界面立即切换为深色主题
- AND 下次打开仍保持该选择

## MODIFIED Requirements

### Requirement: Session Expiration

系统 MUST 在 15 分钟无操作后过期会话。

#### Scenario: Idle timeout

- GIVEN 用户已登录
- WHEN 用户 15 分钟没有操作
- THEN 会话失效
- AND 下一次受保护请求要求重新登录

## REMOVED Requirements

### Requirement: Remember Me

该行为被移除，因为安全策略要求每次浏览器重启后重新认证。

三种 section 含义：

section	含义	archive 后
`ADDED`	新增行为	追加进主 spec
`MODIFIED`	修改已有行为	替换或更新对应 requirement
`REMOVED`	移除已有行为	从主 spec 删除

官方 1.0 变更记录和命令文档还提到过 RENAMED Requirements，用于重命名 requirement 并保留内容。实际使用时建议先跑 openspec validate，因为不同版本的文档示例主要围绕 ADDED/MODIFIED/REMOVED 展开。

delta specs 的优势：

reviewer 只看变更，不用重新读整份 spec。
多个 change 可以同时修改不同 requirement。
行为变更能被独立讨论。
archive 时可以把增量合并回主规格。

delta specs 的风险：

requirement 名称不稳定会让 merge 困难。
写了实现细节会污染主规格。
MODIFIED 如果没说清“原来是什么、现在是什么”，后面很难审查。
REMOVED 如果没有原因，未来回看会不知道是误删还是决策。

design：记录怎么做

design.md 是技术方案层。

它应该放：

架构决策。
方案比较。
数据流。
API 变化。
迁移策略。
风险和回滚。
涉及文件或模块。
为什么不用另一个方案。

它不应该变成：

逐行代码说明。
纯任务清单。
和 proposal 重复的背景说明。
没证据的“未来扩展性”设计。

一个好的 design 示例结构：

markdown

# Design: Add Dark Mode

## Technical Approach

使用现有 CSS 变量体系增加主题 token。
应用根节点根据用户偏好设置 `data-theme`。

## Decisions

### Decision: Use CSS variables

原因：
- 现有样式已经集中在全局样式中
- 运行时切换不需要重新加载页面
- 不新增状态管理依赖

### Decision: Persist user preference locally

原因：
- 当前用户设置没有服务端 profile 模块
- 深色模式不影响跨设备业务状态

## File Changes

- `src/styles/theme.css`
- `src/components/ThemeToggle.vue`
- `src/layout/AppShell.vue`

OpenSpec 的好处是 design 不是一次性给人看的文档。后面的 /opsx:apply、/opsx:verify 都会参考它。

如果实现时发现 design 过时，应该改 design，而不是让文档和代码分叉。

tasks：让 agent 知道怎么落地

tasks.md 是实现清单。

OpenSpec 明确要求用 checkbox，因为 /opsx:apply 依赖 checkbox 跟踪进度：

markdown

# Tasks

## 1. Theme State

- [ ] 1.1 增加主题状态读取逻辑
- [ ] 1.2 保存用户主题偏好
- [ ] 1.3 首次访问时读取系统主题

## 2. UI

- [ ] 2.1 增加主题切换控件
- [ ] 2.2 将控件接入设置页
- [ ] 2.3 确认移动端布局不被撑开

好的 task 应该：

小到一个 agent session 能完成。
有明确完成判断。
顺序合理。
能映射到 spec 或 design。
不混入“顺手优化整个模块”。

坏 task 通常长这样：

markdown

- [ ] 优化主题系统
- [ ] 处理所有边界情况
- [ ] 完善测试
- [ ] 重构样式

这些都太泛。AI 看到这种任务，很容易自己脑补。

OPSX 是什么

OpenSpec 1.0 之后的核心工作流叫 OPSX。

OPSX 的重点是：

command 是 action，不是 phase。
artifact 由 schema 定义。
agent 通过 CLI 查询当前状态。
生成 instruction 时会合并项目 context、artifact rules 和 template。
任务可以中断和恢复。
变更完成后可以 sync 和 archive。

默认快速路径：

text

/opsx:propose
  -> /opsx:apply
  -> /opsx:sync
  -> /opsx:archive

扩展路径：

text

/opsx:new
  -> /opsx:ff 或 /opsx:continue
  -> /opsx:apply
  -> /opsx:verify
  -> /opsx:archive

默认 core profile 包含：

命令	作用
`/opsx:propose`	一步创建 change 和规划 artifact
`/opsx:explore`	先探索问题，不创建 change
`/opsx:apply`	按 tasks 实现
`/opsx:sync`	把 delta specs 合并进主 specs
`/opsx:archive`	归档完成的 change

扩展命令包含：

命令	作用
`/opsx:new`	只创建 change 骨架
`/opsx:continue`	一次创建下一个可创建的 artifact
`/opsx:ff`	fast-forward，一次创建所有规划 artifact
`/opsx:verify`	检查实现是否匹配 artifact
`/opsx:bulk-archive`	批量归档多个完成的 change
`/opsx:onboard`	引导式完整教程

要启用扩展命令：

bash

openspec config profile
openspec update

`/opsx:explore`：先探索，不提交变更

当需求还不清楚时，应该先用 /opsx:explore。

它适合：

性能问题但不知道瓶颈在哪。
想改架构但不确定方案。
bug 原因不明。
用户需求太粗。
需要比较多个方案。

它不应该直接写代码。

一个合理流程：

text

用户：/opsx:explore 搜索页面为什么慢
AI：读取路由、数据加载、组件渲染和接口调用
AI：总结三个可能瓶颈
用户：先处理重复请求
用户：/opsx:propose fix-search-duplicate-requests

explore 的价值是把“我要改点东西”变成“我要改这个具体问题”。

`/opsx:propose`：默认推荐起点

/opsx:propose 是 core profile 的默认起点。

它会：

创建 openspec/changes/<change-name>/。
生成 proposal。
生成 delta specs。
生成 design。
生成 tasks。
停在可实现状态。

适合：

已经知道要做什么。
变更规模中等。
不想一步步审每个 artifact。
想尽快进入实现，但不想跳过规格。

它和旧的“一条 prompt 让 AI 写代码”不同。它先让 agent 把要做的事写成一组文件，再开始实现。

`/opsx:new`、`/opsx:continue`、`/opsx:ff`

这三个是扩展模式里对 artifact 创建的细分。

/opsx:new 只做 scaffold：

text

openspec/changes/<change-name>/
└── .openspec.yaml

它适合你想先占一个 change 名称，但还不想一次生成完整文档。

/opsx:continue 一次创建一个 artifact。它会查询状态，判断哪些 artifact ready，哪些 blocked。

适合：

大需求。
需要逐步审 proposal、spec、design。
不想让 AI 一次生成太多上下文。
每一步都可能改变方向。

/opsx:ff 是 fast-forward。它按依赖顺序一次生成所有规划 artifact。

适合：

范围清楚。
需求不复杂。
用户愿意后续再修 artifact。

经验判断：

场景	建议
小到中等、目标清晰	`/opsx:propose` 或 `/opsx:ff`
大改、跨模块、风险高	`/opsx:new` + 多次 `/opsx:continue`
还没想清楚	`/opsx:explore`
只修一行 typo	不一定需要 OpenSpec

`/opsx:apply`：按 tasks 实现

/opsx:apply 会读 tasks.md，找到未完成项，然后实现。

它应该：

按任务顺序推进。
修改代码。
根据需要运行验证。
完成后把 checkbox 改成 [x]。
如果实现发现 artifact 不准确，更新 artifact。

这里最重要的是“tasks 是进度状态”。

如果 agent 实现了代码却不勾选 tasks，后续恢复时会重复做。

如果 agent 勾选了任务但没有实现，/opsx:verify 可能能发现，但不要依赖它兜底。

`/opsx:verify`：检查 artifact 和实现是否一致

/opsx:verify 主要看三类问题：

维度	检查内容
completeness	tasks 是否完成、requirements 是否有实现证据
correctness	实现是否符合 spec 意图、边界是否处理
coherence	design 决策是否反映在代码里

它不是测试框架。

它更像一次面向 OpenSpec artifact 的 review：

spec 说有系统偏好检测，但代码里没有。
design 说用 CSS variables，但实现改成了 Tailwind class。
tasks 全勾了，但某个 scenario 没测试。
实现做了 proposal 明确 out of scope 的事。

它不会强制阻止 archive，但会提示风险。

我的建议：

低风险小改可以跳过。
有 API、权限、安全、迁移、数据结构变化时应该跑。
AI 实现量很大时应该跑。

`/opsx:sync` 和 `/opsx:archive`

/opsx:sync 把 change 里的 delta specs 合并到主 openspec/specs/。

它不会归档 change。

适合：

长期变更中途想先更新主 specs。
多个并行 change 需要基于新规格继续工作。
想单独 review spec merge。

/opsx:archive 完成 change。

它会：

检查 artifact 状态。
检查 tasks 是否完成。
如果 delta specs 未同步，会提示同步。
把 change 移到 openspec/changes/archive/YYYY-MM-DD-<name>/。
保留 proposal、design、tasks、specs 作为历史。

archive 之后，active changes 目录会变干净，主 specs 也包含新行为。

这一步是 OpenSpec 闭环的关键。

如果只 propose 和 apply，不 archive，那么 OpenSpec 会退化成“多写几份临时文档”。

CLI 命令分层

OpenSpec 有两类交互：

AI 聊天里的 slash commands，例如 /opsx:propose。
终端里的 CLI，例如 openspec validate。

CLI 又分成人用和 agent/script 用。

人用命令偏交互：

命令	作用
`openspec init`	初始化项目
`openspec view`	打开交互式 dashboard
`openspec config edit`	编辑全局配置
`openspec feedback`	通过 GitHub CLI 提交反馈
`openspec completion install`	安装 shell completion

agent/script 友好的命令通常支持 --json：

命令	作用
`openspec list --json`	列出 changes 或 specs
`openspec show <item> --json`	读取 change 或 spec
`openspec validate --all --json`	批量校验
`openspec status --change <id> --json`	查看 artifact 状态
`openspec instructions <artifact> --change <id> --json`	获取下一步生成说明
`openspec templates --json`	查看模板路径
`openspec schemas --json`	查看 schemas

这说明 OpenSpec 不是只靠静态 prompt。

更真实的流程是：

text

agent 收到 /opsx:continue
  -> 调 openspec status --json
  -> 发现 specs ready
  -> 调 openspec instructions specs --json
  -> 读取 proposal 作为依赖
  -> 生成 delta spec
  -> 更新状态

`openspec validate`

validate 用来检查 specs 和 changes 的结构。

常见用法：

bash

openspec validate add-dark-mode
openspec validate --changes
openspec validate --specs
openspec validate --all
openspec validate --all --strict --json

它能发现：

artifact 缺失。
spec 格式不符合要求。
requirement section 为空。
requirement 里缺少 SHOULD/MUST/SHALL 这类关键词。
delta section 不合法。
严格模式下更多结构问题。

OpenSpec 1.4.0 还修过 requirement header 大小写解析问题，并改进了“关键词只写在标题里”的提示。

我的建议：

PR 前至少跑 openspec validate --all。
CI 可以用 openspec validate --all --json。
如果 AI 生成 artifact 质量不稳定，先调 config rules 和 templates，不要只怪模型。

`openspec status` 和 `openspec instructions`

这两个命令是 agent 工作流的核心。

openspec status --change <id> 告诉你：

当前 change 使用哪个 schema。
哪些 artifact 已完成。
哪些 artifact ready。
哪些 artifact blocked。
apply 还缺什么。

openspec instructions <artifact> --change <id> 会生成给 agent 的具体说明。

说明内容会合并：

schema 里的 artifact instruction。
artifact template。
openspec/config.yaml 里的全局 context。
openspec/config.yaml 里对应 artifact 的 rules。
已完成依赖 artifact 的内容。

这就是 OpenSpec 比普通 prompt 文件强的地方。

普通 prompt 文件是静态的。OpenSpec instructions 是按当前 change 状态动态组装的。

项目配置 `openspec/config.yaml`

项目配置是最容易被低估的部分。

一个典型配置：

yaml

schema: spec-driven

context: |
  Tech stack: TypeScript, Vue 3, Node.js, PostgreSQL
  API style: REST JSON
  Testing: Vitest for unit tests, Playwright for e2e
  Rule: 不新增依赖，除非 proposal 明确说明
  Language: Chinese (Simplified)
  All artifacts must be written in Simplified Chinese.

rules:
  proposal:
    - 必须写清 in scope 和 out of scope
    - 必须说明是否影响已有 API
  specs:
    - 使用 Given/When/Then 写 scenario
    - 不要写内部函数名
  design:
    - 复杂流程需要写数据流
    - 必须列出迁移和回滚风险
  tasks:
    - 每个任务必须可以独立勾选
    - 不要包含笼统的“优化代码”

配置作用：

字段	作用
`schema`	默认 workflow schema
`context`	注入所有 artifact instruction
`rules`	按 artifact 注入额外规则

schema 选择优先级：

CLI flag：--schema <name>。
change metadata：openspec/changes/<change>/.openspec.yaml。
project config：openspec/config.yaml。
默认：spec-driven。

多语言也通过 context 做。

例如中文：

yaml

context: |
  语言：中文（简体）
  所有产出物必须用简体中文撰写。

这个设计很朴素，但实用。因为语言、技术栈、项目约束本质上都是给 agent 的上下文。

schema：把团队流程变成文件

OpenSpec 的 schema 定义 artifact 类型和依赖。

默认 schema 是 spec-driven。

它大致包含：

yaml

name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]

  - id: design
    generates: design.md
    requires: [proposal]

  - id: tasks
    generates: tasks.md
    requires: [specs, design]

apply:
  requires: [tasks]
  tracks: tasks.md

你可以 fork 默认 schema：

bash

openspec schema fork spec-driven my-workflow

也可以新建：

bash

openspec schema init research-first

schema 通常放在：

text

openspec/schemas/<schema-name>/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── specs.md
    ├── design.md
    └── tasks.md

schema 的价值：

不是每个团队都要 proposal -> specs -> design -> tasks。
有些团队需要先 research。
有些团队需要 security review。
有些团队只想 proposal -> tasks。
有些团队要和内部 RFC、ADR、test plan 对齐。

用 schema 后，流程不再写死在 OpenSpec 源码里。

官方也提到社区 schema，例如 superpowers-bridge，用来把 OpenSpec 的 artifact governance 和 obra/superpowers 的执行纪律结合起来。

profile 和 delivery

OpenSpec 不只是装一次命令。

它有全局 profile，决定生成哪些 workflow：

profile	默认包含
`core`	`propose`、`explore`、`apply`、`sync`、`archive`
custom	用户选择任意 workflow

用：

bash

openspec config profile

可以调整：

delivery：生成 skills、commands，还是两者都生成。
workflows：选择哪些 OPSX command。

调整后需要在项目里执行：

bash

openspec update

否则项目内的 agent 文件还是旧的。

OpenSpec 1.2.0 之后 profile 系统变得重要，因为默认 core 会避免一上来生成过多命令。

支持哪些 AI 工具

OpenSpec 当前支持 25+ AI coding tools。

官方文档里的 tool IDs 包括：

text

amazon-q
antigravity
auggie
bob
claude
cline
codebuddy
codex
continue
costrict
crush
cursor
factory
forgecode
gemini
github-copilot
iflow
junie
kilocode
kimi
kiro
lingma
opencode
pi
qoder
qwen
roocode
trae
vibe
windsurf

几个值得注意的点：

Claude Code 支持 skills 和 commands。
Cursor 支持 skills 和 commands。
Codex 的 commands 写入全局 Codex home。
GitHub Copilot 的 prompt 文件主要被 IDE 扩展识别，不是 Copilot CLI。
Kimi、Trae、ForgeCode、Mistral Vibe 等部分工具是 skills-only 或没有 command adapter。
不同工具的 slash command 语法可能不同，有的用 /opsx:propose，有的用 /opsx-propose，有的用 skill invocation。

非交互初始化：

bash

openspec init --tools claude,cursor
openspec init --tools all
openspec init --tools none
openspec init --profile core

这对团队模板、脚手架、CI 初始化很有用。

workspace beta：多仓协调视图

OpenSpec 还有 workspace beta。

它不是 repo-local openspec/ 的替代品。

它的定位是：

在本机建立一个协调视图，把多个 repo 或目录链接起来，方便 agent 打开和理解一个跨仓工作集。

核心概念：

概念	含义
workspace	本机私有的协调视图
context store	可持久化的共享上下文容器
initiative	context store 里的一个协调主题
link	workspace 里指向某个 repo 或 folder 的稳定名字
change	具体要实现的变更，仍属于 owning repo

workspace 状态通常在全局数据目录：

text

getGlobalDataDir()/workspaces/<workspace-name>/
├── .openspec-workspace/
│   └── view.yaml
├── AGENTS.md
└── <workspace-name>.code-workspace

view.yaml 里记录本机路径：

yaml

version: 1
name: platform
context: null
links:
  api: /repos/api
  web: /repos/web

注意：

workspace 是本机视图，不等于提交状态。
linked repo 不需要提前有 repo-local openspec/。
workspace setup/update 不会修改 linked repo。
workspace skills 只安装到 workspace root。
workspace 命令仍是 beta，外部自动化不应假设 JSON 结构长期稳定。

常用命令：

bash

openspec workspace setup
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace list
openspec workspace link api /repos/api
openspec workspace relink api /new/path/api
openspec workspace doctor
openspec workspace update --workspace platform --tools codex,claude
openspec workspace open platform --agent codex-cli
openspec workspace open --editor

适合场景：

一个 feature 横跨 web、api、worker。
大 monorepo 里只想把几个子目录暴露给 agent。
多个 repo 共享一个 initiative。
需要打开一个 VS Code multi-root workspace。

不适合：

单 repo 小改。
要求团队共享同一份本机路径。
稳定 CI 自动化。

context store 和 initiative beta

context store 是 durable shared context 容器，通常是一个 Git 管理的文件夹。

initiative 是 context store 里的一个具体协调主题。

比如：

text

context store: platform-context
initiative: billing-launch

从源码结构看 OpenSpec

仓库是 TypeScript ESM 项目。

package.json 里能看到：

CLI bin：bin/openspec.js
exports：dist/index.js
构建：node build.js
测试：vitest
类型：TypeScript
配置和校验：zod、yaml
CLI：commander
交互：@inquirer/*
UI 输出：chalk、ora
telemetry：posthog-node

主要源码目录：

目录	作用
`src/cli`	Commander CLI 入口
`src/commands`	各 CLI 子命令实现
`src/core`	初始化、更新、archive、schema、validation、workspace 等核心逻辑
`src/prompts`	agent prompt / skill 相关内容
`src/telemetry`	匿名使用统计
`src/ui`	CLI 终端 UI
`schemas/spec-driven`	默认 schema 和模板

src/core 里比较关键的模块：

模块	作用
`init.ts`	初始化项目和工具配置
`update.ts`	刷新生成的 agent 文件
`archive.ts`	归档 change
`specs-apply.ts`	应用 delta specs
`artifact-graph`	artifact 依赖图和状态
`schemas`	schema 解析与管理
`project-config.ts`	项目配置读取
`global-config.ts`	全局配置
`workspace`	workspace beta
`context-store`	context store beta
`validation`	spec/change 校验
`command-generation`	为不同工具生成 command/skill

src/commands 里能看到：

文件	命令类别
`change.ts`	`new change`、`set change`
`config.ts`	`openspec config`
`schema.ts`	`openspec schema`
`validate.ts`	`openspec validate`
`show.ts`	`openspec show`
`spec.ts`	spec 相关命令
`workspace.ts`	workspace 命令
`context-store.ts`	context store 命令
`initiative.ts`	initiative 命令
`completion.ts`	shell completion
`feedback.ts`	GitHub feedback

这说明 OpenSpec 本身是一个偏 CLI 和文件生成的工具，不是运行时代码框架。

和 AGENTS.md 的区别

AGENTS.md 通常是项目长期规则：

回答语言。
不要跑测试。
不要新增依赖。
代码风格。
目录习惯。
提交流程。

它解决的是“这个项目里 agent 应该怎么做人”。

OpenSpec 解决的是“这一个 change 到底是什么”。

对比：

维度	AGENTS.md	OpenSpec
范围	全项目长期规则	单个变更
更新频率	低	每个 change 都会变
内容	行为约束	proposal/spec/design/tasks
状态	静态文本	CLI 可查询状态
归档	通常没有	archive 保留历史
验证	人工遵守	`validate/status/instructions` 支持

最好的用法不是二选一。

应该是：

text

AGENTS.md：项目约束
OpenSpec config：规格生成规则和项目上下文
OpenSpec change：这次变更的意图、行为、设计和任务

和 Superpowers 的区别

superpowers 更像一套 agent 工作纪律：

brainstorming
writing plans
TDD
subagent-driven development
code review
finishing branches

它强调执行过程的质量。

OpenSpec 更强调变更 artifact 的治理：

proposal
delta specs
design
tasks
sync
archive

它强调变更本身要沉淀成 repo 内文件。

对比：

维度	OpenSpec	Superpowers
核心对象	change artifacts	agent skills / workflow discipline
最强点	规格、delta、archive	澄清、计划、TDD、review
文件形态	`openspec/`	skills 和流程说明
完成闭环	specs merge + archive	verify + finish branch
适用重点	需求和行为变更治理	编码执行纪律

它们可以互补。

一个组合方式：

用 OpenSpec /opsx:explore 或 /opsx:propose 定义 change。
用 Superpowers 的 planning/TDD/review 约束实现过程。
实现后用 OpenSpec /opsx:verify 检查 artifact 一致性。
最后 /opsx:archive 保留规格历史。

官方 customization 文档里提到的 superpowers-bridge schema，说明这个方向已经有人在做。

和 GitHub Spec Kit 的区别

OpenSpec README 自己拿 GitHub Spec Kit 做过比较。

不展开营销口径，只看方法论差异：

维度	OpenSpec	Spec Kit
默认倾向	轻量、迭代、brownfield	更完整、更流程化
流程	action-based OPSX	phase 更明显
安装	npm / Node	官方语境里更重
规格变更	delta specs	更偏全流程规格
自定义	schema + templates	extension / template 体系

如果团队已经有很强的正式规格流程，Spec Kit 可能更贴近。

如果团队主要是在已有代码库里和 AI 一起频繁改功能，OpenSpec 的轻量 delta 方式更容易落地。

和 Kiro 的区别

Kiro 是 IDE/产品级方案，OpenSpec 是 repo 内 CLI 和 artifact 方案。

差异大致是：

维度	OpenSpec	Kiro
工具绑定	多 agent / 多 IDE	绑定 Kiro 环境
模型选择	由你的 coding assistant 决定	由产品提供
文件资产	放在 repo	依赖 IDE 工作流
可定制性	schema/template 可改	更产品化

OpenSpec 的优势是可迁移。你今天用 Claude Code，明天用 Cursor 或 Codex，openspec/ 里的 change 仍在。

最适合 OpenSpec 的场景

适合：

新功能从需求到实现。
修改已有行为，尤其是 API 或权限。
需要多人 review 的变更。
跨前后端的 feature。
数据迁移、配置语义调整。
安全、隐私、兼容性相关改动。
长期维护的产品模块。
多个 AI 工具协作同一仓库。
需要回看“为什么这样改”的项目。

不适合：

拼写错误。
单个 CSS 间距。
一次性小脚本。
已经完全明确的机械替换。
没有长期维护价值的临时实验。
用户明确说“不需要文档，不需要计划，直接改这一行”。

判断标准：

如果这个改动未来有人会问“为什么这样做”，值得用 OpenSpec。

一个推荐的日常流程

对大多数团队，不必一上来启用所有命令。

可以从 core profile 开始：

bash

npm install -g @fission-ai/openspec@latest
openspec init --tools claude,cursor,codex

然后在项目里配置：

yaml

schema: spec-driven

context: |
  语言：中文（简体）
  所有 OpenSpec 产出物用简体中文。
  不新增依赖，除非 proposal 明确说明。
  行为规格只写外部可观察行为，不写内部实现。

rules:
  proposal:
    - 写清 In scope 和 Out of scope
  specs:
    - 每个 requirement 至少包含一个可验证 scenario
  design:
    - 涉及数据或权限时必须写风险
  tasks:
    - 每个任务必须使用 checkbox

日常使用：

text

不确定需求：
  /opsx:explore
  -> /opsx:propose
  -> /opsx:apply
  -> /opsx:archive

需求明确：
  /opsx:propose add-something
  -> review generated artifacts
  -> /opsx:apply
  -> openspec validate --all
  -> /opsx:archive

复杂需求：
  openspec config profile
  openspec update
  -> /opsx:new
  -> /opsx:continue
  -> review
  -> /opsx:continue
  -> /opsx:apply
  -> /opsx:verify
  -> /opsx:archive

常见坑

1. 把 spec 写成实现文档

坏：

markdown

### Requirement: Theme Context

系统 MUST 新增 `ThemeContext.tsx` 并暴露 `setTheme`。

好：

markdown

### Requirement: Theme Selection

系统 SHALL 允许用户切换浅色和深色主题。

实现文件属于 design 或 tasks，不属于 spec。

2. proposal 没写 out of scope

没有 out of scope，AI 很容易顺手扩展。

比如“加深色模式”会被扩成：

自定义主题。
用户云同步。
后台配置。
品牌皮肤。
动效重写。

如果只需要 MVP，就明确写出去。

3. tasks 太大

坏：

markdown

- [ ] 实现登录重构

好：

markdown

- [ ] 1.1 梳理现有登录入口
- [ ] 1.2 增加 TOTP challenge 状态
- [ ] 1.3 接入登录成功后的跳转
- [ ] 1.4 补充失败提示

task 越小，agent 越不容易乱发挥。

4. 实现变了但 artifact 没改

这是 OpenSpec 最大的实际风险之一。

比如 design 写了 Redis 限流，实现时改成内存限流，但 design 没更新。

后果：

/opsx:verify 会发现不一致。
archive 后历史会误导未来维护者。
下一个 agent 可能基于错误 design 继续改。

正确做法：实现发现方案变化时，先更新 design，再继续 apply。

5. archive 被跳过

只生成 change，不 archive，会导致：

active changes 堆积。
主 specs 不更新。
后续变更不知道当前行为。
OpenSpec 变成一次性计划工具。

完成后应该 archive。

6. 把 workspace 当共享项目状态

workspace 是本机 view。

不要指望：

别人的路径和你一样。
workspace registry 可以直接进 CI。
.openspec-workspace/view.yaml 是团队共享事实来源。

共享事实应该放 repo-local openspec/ 或 Git 管理的 context store。

7. 忘记 `openspec update`

升级包或改 profile 后，要跑：

bash

openspec update

否则 agent 看到的 skills/commands 可能不是最新。

版本演进重点

从 CHANGELOG 看，几个节点值得注意：

版本	重点
`0.1.0`	初始发布
`0.8.0`	增加 Codex slash command 支持
`0.9.0`	增加 Codex 和 GitHub Copilot 相关支持
`0.17.0`	增加全局 config 和 completion
`0.18.0`	增强 OPSX artifact workflow
`0.19.0`	增加 `/opsx:explore` 和 Continue
`0.20.0`	增加 `/opsx:verify`
`1.0.0`	OPSX 正式重构，旧 `/openspec:*` 移除
`1.2.0`	profile system、`/opsx:propose`、AI tool auto-detection
`1.3.0`	增加 Junie、Lingma、ForgeCode、IBM Bob
`1.4.0`	增加 Kimi、Mistral Vibe，core profile 包含 sync
`1.4.1`	workspace view state 移到 `.openspec-workspace/view.yaml`

最重要的是 1.0.0。

1.0 之前更像一组固定命令。1.0 之后是 OPSX：schema、artifact graph、dynamic instructions、skills、sync/archive 的组合。

telemetry

OpenSpec 会收集匿名使用统计。

官方说明收集范围是命令名和版本，不收集参数、路径、内容和 PII，并且 CI 中自动禁用。

关闭方式：

bash

export OPENSPEC_TELEMETRY=0

或：

bash

export DO_NOT_TRACK=1

如果在企业内网或高隐私环境，建议直接在 shell profile 或 CI 环境里设置。

我会怎么在真实项目里用

我的默认策略：

小改不强行 OpenSpec。
中等以上功能从 /opsx:propose 开始。
不清楚需求先 /opsx:explore。
有风险的改动必须 review generated artifacts。
openspec/config.yaml 里写清项目约束和语言。
specs 只写行为，不写实现。
design 写关键取舍，不写废话。
tasks 控制粒度，让 agent 可以逐项完成。
实现偏离 artifact 时，先修 artifact。
完成后 archive，不让 changes 目录长期堆积。

一个务实的判断：

OpenSpec 不是为了让每次开发更快，而是为了让 AI 写出来的东西更可控、更可审查、更能留下上下文。

如果一个团队只追求“今天让 AI 快速改完”，OpenSpec 会显得麻烦。

如果一个团队在意“一个月后还能解释这个行为为什么存在”，OpenSpec 的价值会明显很多。

OpenSpec 阅读分析与使用笔记 ​

这篇文章解决什么问题 ​

先说结论 ​

它从什么问题出发 ​

OpenSpec 的基本哲学 ​

安装和初始化 ​

OpenSpec 的核心模型 ​

specs/：当前行为的事实来源 ​

changes/：一个变更一个文件夹 ​

artifact 流程 ​

proposal：记录为什么做 ​

delta specs：OpenSpec 最关键的设计 ​

design：记录怎么做 ​

tasks：让 agent 知道怎么落地 ​

OPSX 是什么 ​

/opsx:explore：先探索，不提交变更 ​

/opsx:propose：默认推荐起点 ​

/opsx:new、/opsx:continue、/opsx:ff ​

/opsx:apply：按 tasks 实现 ​

/opsx:verify：检查 artifact 和实现是否一致 ​

/opsx:sync 和 /opsx:archive ​

CLI 命令分层 ​

openspec validate ​

openspec status 和 openspec instructions ​

项目配置 openspec/config.yaml ​

schema：把团队流程变成文件 ​

profile 和 delivery ​

支持哪些 AI 工具 ​

workspace beta：多仓协调视图 ​

context store 和 initiative beta ​

从源码结构看 OpenSpec ​

和 AGENTS.md 的区别 ​

和 Superpowers 的区别 ​

和 GitHub Spec Kit 的区别 ​

和 Kiro 的区别 ​

最适合 OpenSpec 的场景 ​

一个推荐的日常流程 ​

常见坑 ​

1. 把 spec 写成实现文档 ​

2. proposal 没写 out of scope ​

3. tasks 太大 ​

4. 实现变了但 artifact 没改 ​

5. archive 被跳过 ​

6. 把 workspace 当共享项目状态 ​

7. 忘记 openspec update ​

版本演进重点 ​

telemetry ​

我会怎么在真实项目里用 ​

参考资料 ​

OpenSpec 阅读分析与使用笔记

这篇文章解决什么问题

先说结论

它从什么问题出发

OpenSpec 的基本哲学

安装和初始化

OpenSpec 的核心模型

`specs/`：当前行为的事实来源

`changes/`：一个变更一个文件夹

artifact 流程

proposal：记录为什么做

delta specs：OpenSpec 最关键的设计

design：记录怎么做

tasks：让 agent 知道怎么落地

OPSX 是什么

`/opsx:explore`：先探索，不提交变更

`/opsx:propose`：默认推荐起点

`/opsx:new`、`/opsx:continue`、`/opsx:ff`

`/opsx:apply`：按 tasks 实现

`/opsx:verify`：检查 artifact 和实现是否一致

`/opsx:sync` 和 `/opsx:archive`

CLI 命令分层

`openspec validate`

`openspec status` 和 `openspec instructions`

项目配置 `openspec/config.yaml`

schema：把团队流程变成文件

profile 和 delivery

支持哪些 AI 工具

workspace beta：多仓协调视图

context store 和 initiative beta

从源码结构看 OpenSpec

和 AGENTS.md 的区别

和 Superpowers 的区别

和 GitHub Spec Kit 的区别

和 Kiro 的区别

最适合 OpenSpec 的场景

一个推荐的日常流程

常见坑

1. 把 spec 写成实现文档

2. proposal 没写 out of scope

3. tasks 太大

4. 实现变了但 artifact 没改

5. archive 被跳过

6. 把 workspace 当共享项目状态

7. 忘记 `openspec update`

版本演进重点

telemetry

我会怎么在真实项目里用

参考资料