设置你的项目

将 OpenSpec 添加到项目中：运行 init，查看它写入了什么，并进行调整。

选择 OpenSpec 的存放位置

• 在你的仓库中（默认）：specs 和 changes 与它们所描述的代码放在一起，并随代码一起进行版本控制。本页其余部分都按这种方式展开。
• 在 Store 中：一个独立的规划仓库，由使用它的各个仓库共享；适用于多仓库设置，或完全将规划移出仓库的场景。Stores (beta) 介绍了何时值得这样做，以及如何设置。

初始化你的项目

安装 CLI 后（安装），在项目根目录运行 init。在终端中：

cd <your-project>
openspec init

init 会询问你使用哪些 AI 工具，为你选择的工具写入工作流文件，并报告生成结果：

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

重启 IDE，使新命令生效。

重新运行 init 是安全的：

• 已设置过的工具会输出 Refreshed，而不是 Created。
• 选择新工具后再次运行 init，会添加该工具。
• --tools 标志会跳过选择器（CLI 参考）。

迁移现有的 project.md

init 不会将旧版 openspec/project.md 复制到 config.yaml 中。它会保留该文件，并输出一条由 AI 辅助迁移的请求。

在 AI 聊天中：

检查 openspec/project.md，并将其中的有用内容迁移到 openspec/config.yaml。
保持上下文简洁：只包含在创建产物、apply 和 archive 期间所需的项目级事实。
将与特定产物相关的指导移入对应产物的规则中。
将与 apply 或 archive 相关的指导移入对应的 operations 条目中。
省略通用、过时或冗长的内容。不要删除 project.md。

检查 config.yaml，然后在准备好后删除 project.md。

init 会安装什么

运行 init 会在你的项目中创建两项内容：

• 仓库根目录下的 openspec/ 文件夹
• 添加到 AI 工具文件夹（.agents/、.claude/ 等）中的工作流文件（技能和命令）

像对待其他源代码一样提交所有这些内容。init 不会更改仓库中的其他任何内容（如果发现旧版 OpenSpec 的遗留内容，它会在清理前询问）。

openspec/ 文件夹

每个 OpenSpec 产物都存放在这里，即项目的根目录下。其结构如下：

openspec/
├── config.yaml     项目设置和供 AI 使用的上下文
├── specs/          你的 specs（目前为空）
└── changes/        进行中的变更（目前为空）
    └── archive/    已完成的变更会移到这里

项目配置 介绍了 config.yaml。

工作流文件（技能和命令）

这些是 OpenSpec 工作流，即你在工作中会使用的操作。以下是以技能形式安装的工作流，位于大多数工具使用的共享 .agents/ 文件夹中：

.agents/skills/
├── openspec-explore/              先梳理一个想法
├── openspec-propose/              提出一个变更
├── openspec-apply-change/         实现一个变更的任务
├── openspec-update-change/        修订一个变更的计划
├── openspec-sync-specs/           将一个变更的 spec 更新同步到 specs/
├── openspec-archive-change/       将一个已完成的变更移到归档
├── openspec-verify-change/        检查实现是否与计划一致（默认不包含）
└── openspec-bulk-archive-change/  一次归档多个变更（默认不包含）

这是默认集合加上两个可选工作流。配置预设 列出了全部十二个工作流。

默认情况下，每个工作流会以两种形式安装：

• 技能（openspec-apply-change）：当你请求执行相关工作时，你的代理会自行采用的指令。
• 命令（Claude Code 中的 /opsx:apply）：同一工作流的键入式入口点，使用更短的名称。

两者在功能上完全相同。一个工作流的技能与其命令包含相同的指令。

为什么有两种：命令出现得更早，而每个工具定义命令的方式各不相同。技能是跨工具共享的较新标准，但并非每个工具都能直接调用技能，因此命令仍作为这些工具的入口点。

有些工具仅以技能形式安装。当工具直接运行技能时，init 会跳过命令并说明这一点（Commands skipped for: codex (uses skills)）。

我们更推荐技能，并预计最终会淘汰命令。

更改安装内容

交互式选择器会更改交付形式和工作流集合（配置预设）。在终端中：

openspec config profile

以下示例演示如何切换到仅技能：

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

回答 yes 会立即将其应用到当前项目。其他项目会在下一次 openspec update 时采用该设置。此设置是全局的，按机器分别生效。

Claude Code 不显示工作流

Claude Code 会根据你的交付设置，从以下一个或两个项目路径加载 OpenSpec 工作流：

• 技能：.claude/skills/openspec-*/SKILL.md
• 命令：.claude/commands/opsx/<id>.md

如果文件缺失，请刷新项目。在终端中：

openspec update

如果命令文件存在，但 /opsx: 未显示任何 OpenSpec 命令，请更新 Claude Code 并重启它。如果命令仍无法加载，也启用技能。在终端中：

openspec config set delivery both
openspec update

重启 Claude Code，然后在其聊天中运行 /openspec-propose。如果只有部分工作流缺失，请更改你的配置预设。

设置完成。快速开始 将从这里带你完成第一个变更。