定制化

OpenSpec 提供三个级别的定制化：

级别	作用	最适合
项目配置	设置默认值，注入上下文/规则	大多数团队
自定义模式	定义自己的工作流产物	具有独特流程的团队
全局覆盖	在所有项目中共享模式	高级用户

---

项目配置

openspec/config.yaml 文件是为您的团队定制 OpenSpec 的最简单方式。它允许您：

• 设置默认模式 - 避免在每个命令中使用 --schema
• 注入项目上下文 - AI 能够了解您的技术栈、约定等
• 添加针对特定产物的规则 - 为特定产物自定义规则
• 添加针对特定操作的指导 - 针对 apply 和 archive 工作的咨询性偏好
• 记住集成选择 - 例如 GitHub Copilot 云编程代理 的选择加入

快速设置

openspec init

这会引导您交互式地创建配置。或者手动创建：

# openspec/config.yaml
schema: spec-driven

context: |
  技术栈: TypeScript, React, Node.js, PostgreSQL
  API 风格: RESTful, 文档记录于 docs/api.md
  测试: Jest + React Testing Library
  我们重视所有公共 API 的向后兼容性

rules:
  proposal:
    - 包含回滚计划
    - 识别受影响的团队
  specs:
    - 使用 Given/When/Then 格式
    - 在发明新模式之前引用现有模式

operations:
  apply:
    guidance:
      - 在运行完整测试套件之前运行聚焦的测试
  archive:
    guidance:
      - 保持完成摘要简明扼要

# 由 `openspec init` 在您选择（或拒绝）GitHub Copilot 时设置
# 云编程代理；控制 `init`/`update` 是否生成其文件。
githubCopilot:
  cloudAgent: false

工作原理

默认模式：

# 没有配置
openspec new change my-feature --schema spec-driven

# 有配置 - 模式自动应用
openspec new change my-feature

上下文和规则注入：

在生成任何产物时，您的上下文和规则会被注入到 AI 提示中：

<context>
技术栈: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- 包含回滚计划
- 识别受影响的团队
</rules>

<template>
[模式的内置模板]
</template>

• 上下文 出现在所有产物中
• 规则 仅出现在匹配的产物中

操作指导：

operations.apply.guidance 和 operations.archive.guidance 是可选的数组，用于为代理应如何执行这些操作提供咨询性指令。它们与 rules 是分开的：操作指导不限制产物内容，产物规则也不会被重新标记为操作指导。

apply 和 archive 在执行时获取这些输入：

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

两个端点都返回当前项目 context 和匹配的 operationGuidance 作为单独的可选字段。每次调用都会从解析的根目录读取新的快照。当选择 --store <id> 时，变更、上下文和指导都来自该存储区，而不是当前的仓库。archive 指令命令是只读的：它不检查或合并增量规范，不写入主规范，不移动变更，也不运行静态归档工作流。

项目上下文是必需的提示级输入。生成的工作流会读取它并应用相关的项目事实、约定和约束。操作指导是可选的附加建议：工作流会考虑每个条目，并遵循那些适用且与内置工作流兼容的条目。

这两个字段都与 CLI 控制的状态、解析的路径、内置步骤、显式用户选择和产物规则保持分离。工作流在保留控制值的同时报告上下文冲突。它不会遵循不适用或冲突的指导，并会解释原因。这两个字段都不是可强制执行的检查，工作流不会将其文本复制到实现文件、规范、变更产物或摘要中，除非用户单独请求该内容。

归档和规范同步输入安全性：

归档、批量归档和独立同步使用来自 openspec status --json 的 artifactPaths.specs.existingOutputPaths 作为唯一的增量规范源。没有 specs 产物的模式，或者其具体输出列表为空的变更，则没有需要同步的内容；不会使用其他产物来推断增量规范。

在语义合并写入主规范之前，工作流会消费当前的 openspec instructions specs --change <name> --json 输出。返回的 specs 规则仅约束由该合并产生的主规范。单个归档将该快照传递给内联同步，独立同步直接获取它，批量归档在进行第一次规范写入之前获取所有必需的快照。非零或无效的 JSON 归档/规范指令响应被视为查找失败，而不是空输入：工作流会在受影响的规范写入或变更移动之前停止（对于批量归档，在任何批量写入或移动之前停止）。

此配置不会更改归档执行阶段、用户提示、文件系统操作、语义合并所有权、直接的 openspec archive 命令，或者产物 rules 的结构和输出。

模式解析顺序

当 OpenSpec 需要一个模式时，它会按以下顺序检查：

1. CLI 标志：--schema <name>
2. 变更元数据（变更文件夹中的 .openspec.yaml）
3. 项目配置（openspec/config.yaml）
4. 默认值（spec-driven）

---

自定义 schema

当项目配置不够时，创建你自己的 schema，并使用完全自定义的工作流。自定义 schema 存放在项目的 openspec/schemas/ 目录中，并与代码一起进行版本控制。

your-project/
├── openspec/
│   ├── config.yaml        # 项目配置
│   ├── schemas/           # 自定义 schema 存放于此
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # 你的修改
└── src/

派生现有 schema

最快的自定义方式是派生（fork）一个内置 schema：

openspec schema fork spec-driven my-workflow

这会复制整个 spec-driven schema 到 openspec/schemas/my-workflow/，你可以在其中自由编辑。

你将获得：

openspec/schemas/my-workflow/
├── schema.yaml           # 工作流定义
└── templates/
    ├── proposal.md       # 提案工件模板
    ├── spec.md           # 规格模板
    ├── design.md         # 设计模板
    └── tasks.md          # 任务模板

现在编辑 schema.yaml 以更改工作流，或编辑模板以更改 AI 生成的内容。

从头创建 schema

对于完全全新的工作流：

# 交互式
openspec schema init research-first

# 非交互式
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Schema 结构

一个 schema 定义了你工作流中的工件以及它们之间的依赖关系：

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: 我团队的自定义工作流

artifacts:
  - id: proposal
    generates: proposal.md
    description: 初始提案文档
    template: proposal.md
    instruction: |
      创建一个提案，解释为什么需要此更改。
      关注问题，而不是解决方案。
    requires: []

  - id: design
    generates: design.md
    description: 技术设计
    template: design.md
    instruction: |
      创建设计文档，解释如何实现。
    requires:
      - proposal    # 在提案存在之前无法创建设计

  - id: tasks
    generates: tasks.md
    description: 实施检查清单
    template: tasks.md
    requires:
      - design

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

关键字段：

字段	用途
id	唯一标识符，用于命令和规则
generates	输出文件名（支持 glob 模式，如 specs/**/*.md）
template	templates/ 目录中的模板文件
instruction	用于创建此工件的 AI 指令
requires	依赖关系 - 必须先存在的工件

按你希望它们被编写的顺序列出工件。requires 决定什么是可行的；当多个工件同时就绪时，artifacts: 列表的顺序决定哪个先来。

模板

模板是指导 AI 的 markdown 文件。在创建工件时，它们会被注入到提示中。

<!-- templates/proposal.md -->
## 为什么

<!-- 解释此更改的动机。这个问题解决的是什么？ -->

## 变更内容

<!-- 描述将会发生什么变化。具体说明新的能力或修改。 -->

## 影响

<!-- 受影响的代码、API、依赖项、系统 -->

模板可以包含：

• AI 应填写的章节标题
• 为 AI 提供指导的 HTML 注释
• 展示预期结构的示例格式

验证你的 schema

在使用自定义 schema 之前，请验证它：

openspec schema validate my-workflow

这会检查：

• schema.yaml 语法是否正确
• 所有引用的模板是否存在
• 没有循环依赖
• 工件 ID 是否有效

使用你的自定义 schema

创建后，通过以下方式使用你的 schema：

# 在命令中指定
openspec new change feature --schema my-workflow

# 或者设置为 config.yaml 中的默认值
schema: my-workflow

调试 schema 解析

不确定正在使用哪个 schema？请检查：

# 查看特定 schema 的解析来源
openspec schema which my-workflow

# 列出所有可用的 schema
openspec schema which --all

输出显示它是来自你的项目、用户目录还是包：

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

注意： OpenSpec 还支持位于 ~/.local/share/openspec/schemas/ 的用户级 schema，用于跨项目共享，但建议使用 openspec/schemas/ 中的项目级 schema，因为它们与你的代码一起进行版本控制。

---

示例

快速迭代工作流

用于快速迭代的最小工作流：

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: 快速迭代，最小开销

artifacts:
  - id: proposal
    generates: proposal.md
    description: 快速提案
    template: proposal.md
    instruction: |
      为此更改创建一个简要提案。
      专注于内容和原因，跳过详细规格。
    requires: []

  - id: tasks
    generates: tasks.md
    description: 实施检查清单
    template: tasks.md
    requires: [proposal]

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

添加审查工件

派生默认 schema 并添加审查步骤：

openspec schema fork spec-driven with-review

然后编辑 schema.yaml 添加：

  - id: review
    generates: review.md
    description: 实施前审查检查清单
    template: review.md
    instruction: |
      基于设计创建审查检查清单。
      包括安全性、性能和测试方面的考虑。
    requires:
      - design

  - id: tasks
    # ... 现有的任务配置 ...
    requires:
      - specs
      - design
      - review    # 现在任务也需要审查

---

社区 schema

OpenSpec 还支持通过独立仓库分发的社区维护 schema。这些 schema 提供预设的工作流，将 OpenSpec 与其他工具或系统集成，类似于 github/spec-kit 的社区扩展目录 对 spec-kit 的作用。

社区 schema 不内置在 OpenSpec 核心中——它们存在于自己的仓库中，并拥有自己的发布节奏。要使用某个 schema，请将 schema 捆绑包复制到你的项目的 openspec/schemas/<schema-name>/ 目录中（每个仓库的 README 都有安装说明）。

Schema	维护者	仓库	描述
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	在实施前捕获变更意图、可观察行为、技术设计和持久性架构决策。添加一个变更局部的 ADR 审查清单，并将符合条件的长久决策写入为不可变、可替代的 ADR。
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	将 OpenSpec 的工件治理与 obra/superpowers 执行技能（头脑风暴、编写计划、通过子代理进行 TDD、代码审查、收尾）集成。添加一个以证据为先的 retrospective 工件，以填补 Superpowers 本身未覆盖的空白。
nanopm	@nmrtn	nmrtn/nanopm	以项目经理优先的工作流。在实施之前运行 nanopm 的规划管道（审计 → 策略 → 路线图 → PRD）。将产品规划与 OpenSpec 的规格驱动工程工作流桥接。工件从 .nanopm/ 读取（如果存在）——提案源自审计，设计源自策略，任务源自 PRD 分解。
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	能力级别的端到端测试运行手册。每个能力获得一个不可变的规格、一个不可变的任务模板，以及每次执行的一条带时间戳的运行记录。断言仅针对可观察行为（HTTP 状态、响应体、持久化状态——绝不针对日志子串）；每次运行记录开始/结束 UTC 时间、持续时间和最佳估算的 LLM 令牌消耗。
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	规格驱动的工作流，具有 TDD 纪律和对抗性审查步骤。流程：proposal → specs → design → review → test-plan → tasks → apply → verify。review 由全新上下文的只读审查者（在有可用时使用第二个模型）编写，并输出 VERDICT: 行，指示代理门禁 test-plan、tasks 和 apply；OpenSpec 仅检查工件是否存在，因此请使用自己的 CI 或挂钩来强制执行门禁。test-plan 将每个规格场景映射到命名测试，并兼作 verify 审计的红/绿分类账。

想贡献一个社区 schema？打开一个带有你的仓库链接的问题，或提交一个 PR 在此表中添加一行。

---

另请参阅

• CLI 参考：Schema 命令 - 完整的命令文档