迁移到 OPSX

本指南将帮助您从旧版 OpenSpec 工作流迁移到 OPSX。迁移过程经过精心设计，确保平滑过渡——您的现有工作将被保留，而新系统提供了更大的灵活性。

有什么变化？

OPSX 用灵活的、基于操作的方法取代了旧的阶段锁定工作流。以下是关键变化：

方面	旧版	OPSX
命令	/openspec:proposal、/openspec:apply、/openspec:archive	默认：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:update、/opsx:sync、/opsx:archive（扩展工作流命令可选）
工作流	一次性创建所有产物	可以逐步创建，也可以一次性创建——由您决定
回退	笨拙的阶段关卡	自然流畅——随时更新任何产物
自定义	固定结构	基于 Schema 驱动，完全可定制
配置	带标记的 CLAUDE.md + project.md	在 openspec/config.yaml 中配置，简洁清晰

理念转变： 工作不是线性的。OPSX 不再假装它是线性的。

---

开始之前

您的现有工作很安全

迁移过程的设计宗旨是保留：

• openspec/changes/中的活跃更改 — 完全保留。您可以使用 OPSX 命令继续它们。
• 已归档的更改 — 未动。您的历史记录保持完整。
• openspec/specs/ 中的主要规范 — 未动。这些是您的事实来源。
• CLAUDE.md、AGENTS.md 等中的内容 — 保留。仅删除 OpenSpec 标记块；您所写的一切都保留。

删除的内容

仅删除将被替换的 OpenSpec 管理的文件：

内容	原因
旧版斜杠命令目录/文件	被新的技能系统取代
openspec/AGENTS.md	过时的工作流触发器
CLAUDE.md、AGENTS.md 等中的 OpenSpec 标记	不再需要

各工具的旧版命令位置（示例——您的工具可能不同）：

• Claude Code：.claude/commands/openspec/
• Cursor：.cursor/commands/openspec-*.md
• Devin Desktop，前身为 Windsurf：.windsurf/workflows/openspec-*.md
• Cline：.clinerules/workflows/openspec-*.md
• Roo：.roo/commands/openspec-*.md
• GitHub Copilot：.github/prompts/openspec-*.prompt.md（仅 IDE 扩展；Copilot CLI 不支持）
• Codex：OpenSpec 现在使用规范的 .agents/skills/openspec-* 路径。旧版 .codex/skills 路径下的 OpenSpec 管理的 SKILL.md 文件仅在已有替换文件后才进行调和；自定义文件和不同副本保留不动。如果未标记的 .agents 树中已包含 OpenSpec 技能，OpenSpec 会保留其现有的 Codex ($openspec-*) 或通用 (/openspec-*) 渲染，而不是猜测旧版目录。使用 openspec init 明确选择 codex 来切换所有权。旧版提示清理仍然只针对 $CODEX_HOME/prompts 或 ~/.codex/prompts 中 OpenSpec 允许列表中的文件名。
• 以及其他（Augment、Continue、Amazon Q 等）

迁移会检测您已配置的所有工具并清理其旧版文件。

删除列表看似很长，但这些全都是 OpenSpec 最初创建的文件。您自己的内容永远不会被删除。

需要您注意的内容

有一个文件需要手动迁移：

openspec/project.md — 该文件不会自动删除，因为它可能包含您编写的项目上下文。您需要：

1. 查看其内容
2. 将有用的上下文移至 openspec/config.yaml（请参阅下方指南）
3. 准备好后删除该文件

我们做出此变更的原因：

旧的 project.md 是被动的——代理可能读取它，也可能不读，可能忘记所读内容。我们发现可靠性参差不齐。

新的 config.yaml 上下文会主动注入每个 OpenSpec 规划请求。这意味着当 AI 创建工件时，您的项目约定、技术栈和规则始终存在。可靠性更高。

权衡：

由于上下文会注入到每个请求，因此您需要保持简洁。专注于真正重要的内容：

• 技术栈和关键约定
• AI 需要知道的非显而易见约束
• 之前经常被忽略的规则

不必追求完美。我们仍在探索最佳实践，并会在实验过程中改进上下文注入的工作方式。

---

运行迁移

openspec init 和 openspec update 都会检测旧版文件，并引导您完成相同的清理过程。根据您的情况选择使用：

• 新安装默认使用 core 配置文件（propose、explore、apply、update、sync、archive）。
• 迁移安装会通过根据需要编写 custom 配置文件来保留您之前安装的工作流。

使用 openspec init

如果您想要添加新工具或重新配置已设置的工具，请运行此命令：

openspec init

init 命令会检测旧版文件并引导您完成清理：

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

当您确认是的时会发生什么：

1. 旧版斜杠命令目录被删除
2. 从 CLAUDE.md、AGENTS.md 等文件中剥离 OpenSpec 标记（您的内容保留）
3. openspec/AGENTS.md 被删除
4. 新技能安装到 .claude/skills/
5. 创建带有默认模式的 openspec/config.yaml

使用 openspec update

如果您只想迁移并将现有工具刷新到最新版本，请运行此命令：

openspec update

update 命令也会检测并清理旧版工件，然后刷新生成的技能/命令以匹配您当前的配置文件和交付设置。

非交互 / CI 环境

对于脚本化迁移：

openspec init --force --tools claude

--force 标志会跳过提示并自动接受清理。

这包括清理全局 Codex 提示目录中由 OpenSpec 管理的 Codex 提示文件。清理仅针对 OpenSpec 允许列表中的旧版 Codex 提示文件名，仅在存在替换的 .agents/skills/openspec-* 技能后才将其删除，并保留所有其他文件。

---

将 project.md 迁移到 config.yaml

旧版 openspec/project.md 是一个用于项目上下文的自由格式 markdown 文件。新版 openspec/config.yaml 是结构化的，并且——关键的是——注入到每个规划请求中，因此您的约定始终在 AI 工作时存在。

之前（project.md）

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

之后（config.yaml）

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

主要区别

project.md	config.yaml
自由格式 markdown	结构化 YAML
一大段文本	独立的上下文和按工件规则
不清楚何时使用	上下文出现在所有工件中；规则仅出现在匹配的工件中
无法选择模式	明确的 schema: 字段设置默认工作流

保留什么，舍弃什么

迁移时请有选择性。问自己：“AI 在每个规划请求中都需要这个吗？”

适合放入 context: 的内容

• 技术栈（语言、框架、数据库）
• 关键架构模式（单体仓库、微服务等）
• 非显而易见的约束（“我们不能使用库 X，因为...”）
• 经常被忽略的关键约定

改为放入 rules: 的内容

• 特定于工件的格式（“在规范中使用 Given/When/Then”）
• 审查标准（“提案必须包含回滚计划”）
• 这些仅出现在匹配的工件中，使其他请求更轻量

完全舍弃的内容

• AI 已知的通用最佳实践
• 可以概括的冗长解释
• 不影响当前工作的历史背景

迁移步骤

1. 创建 config.yaml（如果 init 尚未创建）：

   schema: spec-driven

2. 添加您的上下文（保持简洁——这将出现在每个请求中）：

   context: |
     Your project background goes here.
     Focus on what the AI genuinely needs to know.

3. 添加按工件规则（可选）：

   rules:
     proposal:
       - Your proposal-specific guidance
     specs:
       - Your spec-writing rules

4. 将所有有用的内容迁移后，删除 project.md。

不必过度思考。 从要点开始并迭代。如果您发现 AI 遗漏了重要内容，就添加进来。如果觉得上下文太臃肿，就精简。这是一个活的文档。

需要帮助？使用此提示

如果您不确定如何精炼 project.md，请向您的 AI 助手提问：

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

AI 将帮助您识别什么是必要的，什么可以裁剪。

---

新命令

命令的可用性取决于配置文件：

默认（core 配置文件）：

命令	用途
/opsx:propose	一步创建更改并生成规划工件
/opsx:explore	无结构地思考想法
/opsx:apply	从 tasks.md 实现任务
/opsx:update	修订更改的规划工件并保持其一致性
/opsx:sync	将增量规范合并到主要规范中
/opsx:archive	完成并存档更改

扩展工作流（自定义选择）：

命令	用途
/opsx:new	启动新的更改脚手架
/opsx:continue	创建下一个工件（一次一个）
/opsx:ff	快进——一次性创建规划工件
/opsx:verify	验证实现是否符合规范
/opsx:bulk-archive	一次存档多个更改
/opsx:onboard	引导式端到端入职工作流

使用 openspec config profile 启用扩展命令，然后运行 openspec update。

从旧版命令映射

旧版	OPSX 等效命令
/openspec:proposal	/opsx:propose（默认）或 /opsx:new 然后 /opsx:ff（扩展）
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

新功能

这些功能是扩展工作流命令集的一部分。

精细的工件创建：

/opsx:continue

根据依赖关系一次创建一个工件。当您希望逐步审查时使用此命令。

探索模式：

/opsx:explore

在提交更改之前与合作伙伴一起思考想法。

理解新架构

从阶段锁定到自由流动

旧版工作流强制线性推进：

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

如果你正在实施阶段，却发现设计有问题？
没办法。阶段门禁不会让你轻易回退。

OPSX 使用操作（actions），而非阶段（phases）：

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

依赖图

制品（Artifacts）构成一个有向图。依赖关系是启用条件，而非门禁：

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

当你运行 /opsx:continue 时，它会检查哪些制品已就绪，并提供下一个可创建的制品。你也可以按任意顺序创建多个已就绪的制品。

Skills 与 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 中，Codex 仅支持 skills 模式。OpenSpec 不再生成 Codex 自定义提示文件；请改用生成的 .agents/skills/openspec-* 目录。

---

继续现有变更

你正在进行的变更可以与 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: |
  Your project background, tech stack,
  conventions, and constraints.

# 可选：按制品配置规则
# 仅注入到匹配的制品中
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Schema 解析

在确定使用哪个 schema 时，OPSX 按以下顺序检查：

1. CLI 标志：--schema <name>（最高优先级）
2. 变更元数据：变更目录中的 .openspec.yaml
3. 项目配置：openspec/config.yaml
4. 默认值：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

详情参见 Customization。

---

故障排除

"Legacy files detected in non-interactive mode"

你正在 CI 或非交互环境中运行。请使用：

openspec init --force

迁移后命令未出现

重启你的 IDE。Skills 在启动时检测。

"Unknown artifact ID in rules"

检查你的 rules: 键是否与 schema 的制品 ID 匹配：

• spec-driven：proposal、specs、design、tasks

运行以下命令查看有效的制品 ID：

openspec schemas --json

配置未生效

1. 确保文件位于 openspec/config.yaml（不是 .yml）
2. 验证 YAML 语法
3. 配置更改立即生效——无需重启

project.md 未迁移

系统有意保留 project.md，因为它可能包含你的自定义内容。请手动审阅，将有用的部分迁移到 config.yaml，然后删除该文件。

想查看将被清理的内容？

运行 init 并拒绝清理提示——你将看到完整的检测摘要，而不会做任何更改。

---

快速参考

迁移后的文件结构

project/
├── openspec/
│   ├── specs/                    # 未变更
│   ├── changes/                  # 未变更
│   │   └── archive/              # 未变更
│   └── config.yaml               # 新增：项目配置
├── .claude/
│   └── skills/                   # 新增：OPSX skills
│       ├── openspec-propose/     # 默认核心配置
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # 扩展配置新增 new/continue/ff 等
├── 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:propose      快速开始（默认核心配置）
/opsx:apply        实施任务
/opsx:archive      完成并归档

# 扩展工作流（如已启用）：
/opsx:new          创建变更脚手架
/opsx:continue     创建下一个制品
/opsx:ff           创建规划制品

---

获取帮助

• Discord：discord.gg/YctCnvvshC
• GitHub Issues：github.com/Fission-AI/OpenSpec/issues
• 文档：docs/opsx.md 查看完整的 OPSX 参考