OpenSpec 1.0 迁移指南
如果你正在使用旧版 OpenSpec 工作流，本文将引导你无缝迁移至全新的 OPSX 系统。好消息是，整个升级过程被设计为尽可能平滑——你现有的所有工作成果都将被保留，而新系统将为你带来更强的灵活性与扩展能力。
核心变化概览
OPSX 最根本的改进，是用一套流畅、基于动作的工作流取代了旧版“阶段锁定”模式。从命令体系到工作流执行，再到回退机制与定制化能力，几乎所有方面都进行了优化。
| 方面 | 旧版 | OPSX |
|---|---|---|
| 命令 | /openspec:proposal, /openspec:apply, /openspec:archive | /opsx:new, /opsx:continue, /opsx:apply 等 |
| 工作流 | 一次性创建所有产物 | 支持增量创建或一次性创建——由你灵活选择 |
| 回退 | 笨拙的阶段门控 | 自然流畅——可随时更新任何产物 |
| 定制化 | 固定结构 | 基于 Schema，完全可定制 |
| 配置 | CLAUDE.md 标记 + project.md | 简洁的 openspec/config.yaml |
核心理念很简单：工作不是线性的，OPSX 不再假装它是线性的。
迁移前须知
现有工作完全安全
迁移过程以“保留”为核心设计原则。你可以放心：
openspec/changes/中活跃的变更——全部保留，并可以继续使用 OPSX 命令进行操作。- 已归档的变更——不受任何影响，历史记录完整保留。
openspec/specs/中的主规格——不受影响，这依然是你的核心来源。CLAUDE.md、AGENTS.md等文件中你编写的内容——全部保留，仅会移除 OpenSpec 的标记块。
会被移除的内容
只有旧版 OpenSpec 自身的管理文件会被移除，具体包括：
| 内容 | 原因 |
|---|---|
| 旧版斜杠命令目录/文件 | 被新的 skills 系统替代 |
openspec/AGENTS.md | 已废弃的工作流触发器 |
CLAUDE.md、AGENTS.md 等文件中的 OpenSpec 标记 | 不再需要 |
各工具的旧版命令文件位置（示例）：
- Claude Code:
.claude/commands/openspec/ - Cursor:
.cursor/commands/openspec-*.md - Windsurf:
.windsurf/workflows/openspec-*.md - Cline:
.clinerules/workflows/openspec-*.md - Roo:
.roo/commands/openspec-*.md - GitHub Copilot:
.github/prompts/openspec-*.prompt.md - 其他工具（Augment、Continue、Amazon Q 等）
迁移程序会自动检测你配置了哪些工具，并清理对应的旧版文件。这些文件原本就是 OpenSpec 创建的，因此你的个人内容永远不会被误删。
需要手动处理的内容
有一个文件需要你手动介入：openspec/project.md。系统不会自动删除它，因为它可能包含你编写的项目上下文。你需要：
- 检查其内容。
- 将有用的上下文迁移至
openspec/config.yaml（详见下文指导）。 - 确认无误后，手动删除该文件。
为什么要做这个改变？旧版的 project.md 是“被动”的——AI 可能会读取，也可能不读，甚至可能忘记它读过。这导致可靠性很不一致。而新的 config.yaml 上下文会主动注入到每个 OpenSpec 的规划请求中，这意味着你的项目约定、技术栈和规则在 AI 创建产物时始终存在。换言之，可靠性更高。
当然，这里存在一个权衡：因为上下文会注入到每个请求中，所以你务必要保持内容简洁。专注于真正重要的信息：
- 技术栈和关键约定。
- AI 需要知道的、非显而易见的约束。
- 那些之前经常被忽略的规则。
不必追求一步到位。我们同样还在探索什么最有效，并会随着实验不断改进上下文注入的方式。
执行迁移
openspec init 和 openspec update 这两个命令都会检测旧版文件，并引导你完成相同的清理过程。可根据你的实际情况选择：
使用 openspec init
如果你想添加新工具或重新配置已设置的工具，请运行此命令：
openspec init
init 命令会检测旧版文件并引导你完成清理过程。交互提示大致如下：
升级到新版 OpenSpec
OpenSpec 现在使用 agent skills，这是编码 AI 的新兴标准。这简化了你的设置，同时保持一切正常工作。
要移除的文件（无需保留用户内容）：
• .claude/commands/openspec/
• openspec/AGENTS.md
要更新的文件（OpenSpec 标记将被移除，你的内容会保留）：
• CLAUDE.md
• AGENTS.md
需要你注意：
• openspec/project.md
我们不会删除此文件。它可能包含有用的项目上下文。新的 openspec/config.yaml 有一个 "context:" 部分用于规划上下文。这会包含在每个 OpenSpec 请求中，比旧的 project.md 方式更可靠。
检查 project.md，将有用内容移至 config.yaml 的 context 部分，然后在准备好时删除该文件。
? 升级并清理旧版文件？(Y/n)
当你确认后，会发生以下五件事：
- 旧版斜杠命令目录被移除。
CLAUDE.md、AGENTS.md等文件中的 OpenSpec 标记被剥离（你的内容全部保留）。openspec/AGENTS.md被删除。- 新的 skills 安装到
.claude/skills/目录。 - 创建
openspec/config.yaml并设置默认 schema。
使用 openspec update
如果你只想单纯迁移，并将现有工具刷新到最新版本，请运行此命令：
openspec update
update 命令同样会检测并清理旧版产物，然后将你的 skills 刷新到最新版本。
非交互式 / CI 环境
用于脚本化迁移：
openspec init --force --tools claude
这里的 --force 标志会跳过交互提示，自动接受清理。
将 project.md 迁移到 config.yaml
旧版的 openspec/project.md 是一个自由格式的 markdown 文件，用于存放项目上下文。新版的 openspec/config.yaml 采用结构化格式，关键区别在于——它会被主动注入到每个规划请求中，确保你的约定在 AI 工作时始终存在。
迁移前 (project.md)
# 项目上下文
这是一个使用 React 和 Node.js 的 TypeScript monorepo。
我们使用 Jest 进行测试，遵循严格的 ESLint 规则。
我们的 API 是 RESTful 的，文档在 docs/api.md。
## 约定
- 所有公共 API 必须保持向后兼容
- 新功能应包含测试
- 规格使用 Given/When/Then 格式
迁移后 (config.yaml)
schema: spec-driven
context: |
技术栈：TypeScript、React、Node.js
测试：Jest + React Testing Library
API：RESTful，文档在 docs/api.md
我们为所有公共 API 保持向后兼容
rules:
proposal:
- 为风险变更包含回滚计划
specs:
- 场景使用 Given/When/Then 格式
- 在发明新模式前参考现有模式
design:
- 为复杂流程包含序列图
关键区别
| project.md | config.yaml |
|---|---|
| 自由格式 markdown | 结构化 YAML |
| 一大块文本 | 分离的上下文和按产物的规则 |
| 不清楚何时使用 | 上下文出现在所有产物中；规则只出现在匹配的产物中 |
| 无 schema 选择 | 显式 schema: 字段设置默认工作流 |
保留什么，丢弃什么
迁移时要讲究选择性。不妨问自己一个问题：“AI 在每个规划请求中都需要知道这个信息吗？”
适合放入 context: 的内容
- 技术栈（语言、框架、数据库）。
- 关键架构模式（monorepo、微服务等）。
- 非显而易见的约束（例如“我们不能使用库 X 因为…”）。
- 那些经常被忽略的关键约定。
应移至 rules: 的内容
- 产物特定的格式要求（例如“在 specs 中使用 Given/When/Then”）。
- 审查标准（例如“proposal 必须包含回滚计划”）。
- 这些规则只出现在匹配的产物中，从而让其他请求保持更轻量化。
建议完全省略的内容
- AI 已经熟知的通用最佳实践。
- 可以精炼总结的冗长解释。
- 不影响当前工作的历史上下文。
迁移步骤
- 创建 config.yaml（如果 init 尚未创建）：
schema: spec-driven - 添加你的上下文（保持简洁——这会被注入到每个请求）：
context: | 你的项目背景放在这里。专注于 AI 真正需要知道的内容。 - 添加按产物的规则（可选）：
rules: proposal: - 你的 proposal 特定指导 specs: - 你的规格编写规则 - 一旦移动了所有有用内容，删除
project.md。
不用想太多。从基本要素入手，然后逐步迭代。如果你发现 AI 遗漏了重要内容，就添加上去；如果感觉上下文过于臃肿，就精简一下。这是一个活文档。
需要帮助？使用这个提示词
如果你不确定如何提炼你的 project.md，可以尝试向你的 AI 助手发出以下提示：
我正在从 OpenSpec 的旧 project.md 迁移到新的 config.yaml 格式。这是我当前的 project.md：
[粘贴你的 project.md 内容]
请帮我创建一个 config.yaml，包含：
1. 简洁的 `context:` 部分（这会注入到每个规划请求中，所以请保持紧凑——专注于技术栈、关键约束和经常被忽略的约定）
2. 如果有产物特定的内容，为特定产物添加 `rules:`（例如，"使用 Given/When/Then" 属于 specs 规则，不是全局上下文）
省略 AI 模型已经知道的通用内容。对简洁性要无情。
AI 会帮你识别出哪些是必要的，哪些可以精简。
新命令体系
迁移完成后，你将拥有 9 个 OPSX 命令，而不再是原来的 3 个：
| 命令 | 用途 |
|---|---|
/opsx:explore | 无结构地思考想法 |
/opsx:new | 开始一个新变更 |
/opsx:continue | 创建下一个产物（一次一个） |
/opsx:ff | 快进——一次创建所有规划产物 |
/opsx:apply | 从 tasks.md 实现任务 |
/opsx:verify | 验证实现是否匹配规格 |
/opsx:sync | 预览规格合并（可选——如需要会提示归档） |
/opsx:archive | 完成并归档变更 |
/opsx:bulk-archive | 批量归档多个变更 |
从旧版命令的映射
| 旧版 | OPSX 等效 |
|---|---|
/openspec:proposal | /opsx:new 然后 /opsx:ff |
/openspec:apply | /opsx:apply |
/openspec:archive | /opsx:archive |
新功能
细粒度产物创建：/opsx:continue 命令能基于依赖关系，一次创建一个产物。当你希望在每一步都进行审查时，这个命令尤为好用。
探索模式：/opsx:explore 命令让你在正式提交变更之前，可以与助手一起无压力地思考想法。
理解新架构
从阶段锁定到流畅
旧版工作流强制线性进展：
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 规划阶段 │ ──► │ 实现阶段 │ ──► │ 归档阶段 │
└──────────────┘ └──────────────┘ └──────────────┘
如果你在实现阶段发现设计有问题？那就麻烦了。阶段门控让你很难轻松回退。
OPSX 则使用动作，而不是阶段：
┌────────────────────────────────────────┐
│ 动作（不是阶段） │
│ │
│ new ◄──► continue ◄──► apply ◄──► archive │
│ │
│ 任意顺序 │
└────────────────────────────────────────┘
依赖图
产物之间形成了一个有向图。依赖关系是“启用器”，而不是“门控”：
proposal (根节点)
│
┌─────────┴─────────┐
│ │
▼ ▼
specs design
(需要: proposal) (需要: proposal)
│ │
└───────┬───────────┘
▼
tasks
(需要: specs, design)
当你运行 /opsx:continue 时，它会检查哪些产物已准备就绪，并提供下一个可以创建的产物。你也可以按任意顺序，一次性创建多个已准备好的产物。
Skills vs Commands
旧系统使用工具特定的命令文件：
.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md
OPSX 则采用新兴的 skills 标准：
.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...
Skills 能被多种 AI 编码工具识别，并且提供了更丰富的元数据。
继续现有变更
你正在进行的变更可以无缝地使用 OPSX 命令。
有来自旧版工作流的活跃变更？
/opsx:apply add-my-feature
OPSX 会读取现有的产物，并直接从你上次的位置继续工作。
想为现有变更添加更多产物？
/opsx:continue add-my-feature
该命令会基于已存在的内容，展示还能创建什么。
需要查看当前状态？
openspec status --change add-my-feature
新配置系统
config.yaml 结构
# 必需：新变更的默认 schema
schema: spec-driven
# 可选：项目上下文（最大 50KB）
# 注入到所有产物指令中
context: |
你的项目背景、技术栈、约定和约束。
# 可选：按产物的规则
# 只注入到匹配的产物中
rules:
proposal:
- 包含回滚计划
specs:
- 使用 Given/When/Then 格式
design:
- 记录回退策略
tasks:
- 分解为最多 2 小时的块
Schema 解析顺序
在确定使用哪个 schema 时，OPSX 会按以下顺序依次检查：
- CLI 标志：
--schema（最高优先级）。 - 变更元数据：变更目录中的
.openspec.yaml。 - 项目配置：
openspec/config.yaml。 - 默认值：
spec-driven。
可用 Schema
| Schema | 产物 | 最适合 |
|---|---|---|
spec-driven | proposal → specs → design → tasks | 大多数项目 |
要列出所有可用的 schema，可以运行：
openspec schemas
自定义 Schema
你可以创建自己的工作流：
openspec schema init my-workflow
或者 fork 现有的：
openspec schema fork spec-driven my-workflow
故障排除
"在非交互模式下检测到旧版文件"
这表明你在 CI 或非交互环境中运行。请使用：
openspec init --force
迁移后命令不出现
请重启你的 IDE。Skills 是在启动时进行检测的。
"rules 中的未知产物 ID"
请检查你的 rules: 键是否匹配你当前 schema 的产物 ID：
- 对于 spec-driven 模式，有效的产物 ID 包括：
proposal、specs、design、tasks。
可以通过以下命令查看有效的产物 ID：
openspec schemas --json
配置未被应用
- 确认文件位于
openspec/config.yaml（注意是.yaml扩展名，不是.yml）。 - 检查 YAML 语法是否正确。
- 配置更改会立即生效——不需要重启。
project.md 未迁移
系统有意保留了 project.md，因为它可能包含你的自定义内容。请手动检查它，将有用部分迁移至 config.yaml，然后再删除它。
想预览会被清理什么？
运行 openspec init 并拒绝清理提示——你会看到一份完整的检测摘要，而不会执行任何实际更改。
快速参考
迁移后的文件结构
project/
├── openspec/
│ ├── specs/ # 不变
│ ├── changes/ # 不变
│ │ └── archive/ # 不变
│ └── config.yaml # 新增：项目配置
├── .claude/
│ └── skills/ # 新增：OPSX skills
│ ├── openspec-explore/
│ ├── openspec-new-change/
│ └── ...
├── CLAUDE.md # OpenSpec 标记已移除，你的内容保留
└── AGENTS.md # OpenSpec 标记已移除，你的内容保留
已移除的内容
.claude/commands/openspec/— 被.claude/skills/替代。openspec/AGENTS.md— 已废弃。openspec/project.md— 迁移到config.yaml，然后删除。CLAUDE.md、AGENTS.md等文件中的 OpenSpec 标记块。
命令速查表
/opsx:new 开始一个变更
/opsx:continue 创建下一个产物
/opsx:ff 创建所有规划产物
/opsx:apply 实现任务
/opsx:archive 完成并归档
