Schema

更改 OpenSpec 生成的内容：工件（artifacts）、它们的顺序以及它们的模板。

Schema 定义了一次变更提案（change proposal）会产出什么：哪些工件、以什么顺序、基于哪些模板。例如，默认内置的 Schema spec-driven 大致按以下顺序生成这四项，每一项都建立在前一项的基础上：

proposal → specs → design → tasks

当你希望这些工件成为不同的文档时——无论是数量更少、名称不同，还是结构不同——就可以 fork 一个 Schema。

Schema 的存放位置

OpenSpec 会按顺序在三个位置查找 Schema，并使用它找到的第一个：

1. 你的项目：openspec/schemas/，随仓库一起提交，这样整个团队都能使用它。
2. 你的机器：macOS 和 Linux 上为 ~/.local/share/openspec/schemas（若设置了 $XDG_DATA_HOME，则位于其下），Windows 上为 %LOCALAPPDATA%\openspec\schemas。放在这里的 Schema 在你使用的每个项目中都可用。
3. 软件包：内置 Schema（如 spec-driven）随 openspec 本身一起发布。

同一个名称可以同时存在于多个位置，越具体的位置优先级越高。openspec schema which 会显示当前使用的是哪一份副本：

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Schema 的组成

一个 Schema 由一个包含普通文件的文件夹定义：一个用于声明各工件的 schema.yaml，以及每个工件各自的模板。以下是内置的 spec-driven：

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml：声明每个工件、它生成的文件、它所使用的起始模板、它的前置依赖，以及 agent 创建它时收到的指令。每个字段的约定详见 schema.yaml。
• templates/：每个工件对应一个 markdown 骨架，由 agent 填写。

下面是 schema.yaml 中 tasks 工件的条目（已精简）：

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

内置 Schema 随 openspec 软件包一起发布，因此你永远不要就地编辑它们。你可以通过 fork 获得自己的副本。

创建你自己的自定义 Schema

有两种方式可以获得你自己的 Schema：

1. Fork 一个现有 Schema 并编辑你的副本。当现有 Schema 接近你的需求时，从这里开始，因为其中的一切都已经可以正常工作。
2. 当它们都不符合需求时，从零开始，使用 openspec schema init 搭建一个空的 Schema。

Fork 一个现有 Schema

1. 在项目根目录下运行以下命令，fork 你想作为起点的 Schema：

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   传入第二个参数可以指定名称（openspec schema fork spec-driven team-flow）。名称采用 kebab-case 格式。

2. 编辑副本：schema.yaml 和模板。编辑你的 fork 一节介绍了需要改动的内容。

3. 对其进行验证：

   openspec schema validate spec-driven-custom

   这是唯一一条能提前发现损坏 Schema（缺少模板、无效 YAML、依赖循环）的命令，免得你在变更进行到一半时才发现问题。

4. 在 openspec/config.yaml 中将你的项目指向它。这一步需要你自己完成，因为 fork 不会改动 config.yaml：

   schema: spec-driven-custom

5. 新建的变更提案现在会遵循你的 Schema。此前创建的变更则保留它们最初使用的 Schema。

要在不修改 config.yaml 的情况下在所有地方替换默认 Schema，可以 fork 成相同的名称：openspec schema fork spec-driven spec-driven。这样，你项目中的副本就会覆盖（shadow）内置版本，正如 Schema 的存放位置 中所解释的那样。

从零开始

openspec schema init 会搭建一个全新的 Schema，而不是复制现有 Schema：

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

搭建出的骨架非常简陋。工件只能从内置的四个 id 中选取，而且生成的模板不包含任何指令，因此在你编写自己的指令之前，agent 得到的指引会较少。接下来的步骤与 fork 流程完全相同：先验证，再在 config.yaml 中指向它。

编辑你的 fork

fork 中有两类可以编辑的文件：

• templates/ 改变每个文档的骨架。在 tasks 模板中添加一节内容，之后每个新建的 tasks.md 都会以它开头。请保留第一行的 # 标题：工件会继承它，因此每个生成的文件打开时都是一个带有标题的文档。
• schema.yaml 改变工作流本身：存在哪些工件、每个工件的前置依赖是什么，以及 agent 在创建工件时得到的指令。

例如，要移除 design 文档以获得更精简的流程：

1. 从 schema.yaml 中删除 design 条目。

2. 从 tasks 的 requires 列表中移除 design。

3. 验证：

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

如果跳过第 2 步，验证会捕捉到该错误：

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

每次手动编辑后都要进行验证。否则，损坏的 Schema 只会在变更进行到一半时才暴露出来——比如某个工作流要求一个并不存在的文件。与 config.yaml 一样，对 Schema 的修改会在下一次运行时传递给 agent。

fork 是一份快照

openspec update 会刷新已安装的技能和命令，但它绝不会触碰 openspec/schemas/。你的 fork 会完全按照你离开时的样子继续工作，这也意味着当内置 Schema 演进时，它不会再获得这些改进。如果日后想获取这些改进，可以用新名称重新 fork 内置 Schema，并将差异移植过来。

共享 Schema

共享一个 Schema 就是复制它的文件夹。

• 与团队共享：提交（commit）openspec/schemas/，仓库中的每个人都能使用它。
• 跨项目使用：将文件夹放到 Schema 的存放位置 中介绍的用户级目录。
• 来自社区：社区目录 列出了社区共享的 Schema。将其中一个复制到 openspec/schemas/<name>，它就可以像你自己的 Schema 一样工作。

我们正在开发一个支持公开与私有的 Schema 注册表，让 Schema 可以按名称安装，而不需要手动复制。

将 OpenSpec 与 Superpowers 结合使用

社区维护的 superpowers-bridge Schema 将 OpenSpec 工件与 Superpowers 的执行技能连接起来。在将它复制到你的项目之前，请先阅读该 bridge 的安装与兼容性说明。

该 bridge 独立于 OpenSpec 发布。OpenSpec 不会测试其 Superpowers 集成，也不为其提供版本管理。