[[[[Switch to English]]]]

自定义

OpenSpec 提供三个级别的自定义：

级别	作用	适用于
项目配置	设置默认值，注入上下文/规则	大多数团队
自定义 Schema	定义您自己的工作流工件	具有独特流程的团队
全局覆盖	跨所有项目共享 Schema	高级用户

---

项目配置

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

• 设置默认 Schema - 在每个命令中跳过 --schema
• 注入项目上下文 - AI 看到您的技术栈、惯例等
• 添加每个工件规则 - 特定工件的自定义规则

快速设置

openspec init

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

# openspec/config.yaml
schema: spec-driven

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

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

工作原理

默认 Schema:

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

# 有配置 - schema 是自动的
openspec new change my-feature

上下文和规则注入:

生成任何工件时，您的上下文和规则都会注入到 AI 提示中：

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

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

Schema 解析顺序

当 OpenSpec 需要 Schema 时，它按此顺序检查：

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

---

自定义 Schema

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

your-project/
├── openspec/
│   ├── config.yaml        # 项目配置
│   ├── schemas/           # 自定义 Schemas 位于此处
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # 您的变更
└── src/

Fork 现有 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: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

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

关键字段：

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

模板

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

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

模板可以包含：

• AI 应填写的章节标题
• 带有 AI 指导的 HTML 注释
• 显示预期结构的示例格式

验证您的 Schema

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

openspec schema validate my-workflow

这会检查：

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

使用您的自定义 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: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

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

添加审查工件

Fork 默认值并添加审查步骤：

openspec schema fork spec-driven with-review

然后编辑 schema.yaml 添加：

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

另请参阅

• [[[[CLI 参考: Schema 命令]]]] - 完整命令文档