自定义

OpenSpec 提供三个层次的自定义方式：

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

项目配置

openspec/config.yaml 是为团队自定义 OpenSpec 最简单的方式。你可以用它来：

设置默认模式——无需在每条命令中都指定 --schema
注入项目上下文——让 AI 了解你的技术栈、约定等
添加产物级规则——为特定产物添加自定义规则
添加操作指引——为 apply 和 archive 操作提供建议
记住集成选项——例如是否 opt-in GitHub Copilot 云端编码智能体

快速设置

openspec init

该命令会以交互方式引导你创建配置文件。你也可以手动创建：

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

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

工作方式

默认模式：

# Without config
openspec new change my-feature --schema spec-driven

# With config - schema is automatic
openspec new change my-feature

上下文和规则注入：

生成任意产物时，你的上下文和规则都会注入 AI prompt：

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

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

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

Context 会出现在所有产物中。
Rules 只会出现在与之匹配的产物中。

操作指引：

operations.apply.guidance 和 operations.archive.guidance 是可选数组，用于提供 agent 执行这些操作时的建议。它们与 rules 相互独立：操作指引不会限制产物内容，产物规则也不会被重新归类为操作指引。

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

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

这两个接口会将当前项目的 context 和匹配的 operationGuidance 作为独立的可选字段返回。每次调用都会从已解析的根目录读取最新快照。使用 --store <id> 时，变更、上下文和指引均来自该存储库，而非当前代码仓库。Archive 指令命令是只读的：它不会检查或合并差异规格说明、写入主规格说明、移动变更，也不会执行静态归档工作流。

项目上下文是 prompt 层面的必需输入。生成的工作流会读取它，并应用相关的项目事实、约定和限制。操作指引是可选的补充建议：工作流会考虑所有条目，并遵循适用且与内置工作流兼容的内容。

这两个字段都与 CLI 控制的状态、已解析路径、内置步骤、明确的用户选择以及产物规则相互独立。工作流会报告上下文冲突，同时保留具有控制效力的值。它不会遵循不适用或相互冲突的指引，并会说明原因。这两个字段都不是可强制执行的检查；除非用户另行要求，否则工作流不会将它们复制到实现文件、规格说明、变更产物或摘要中。

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

Archive、bulk archive 和独立的 sync 会将 openspec status --json 输出中的 artifactPaths.specs.existingOutputPaths 作为唯一的差异规格说明来源。没有 specs 产物的模式，或实际输出路径列表为空的变更，都没有内容需要同步；不会通过其他产物推断差异规格说明。

语义合并写入主规格说明之前，工作流会读取当前的 openspec instructions specs --change <name> --json 输出。返回的 specs 规则仅约束此次合并所生成的主规格说明。单项 archive 会将该快照传给内部 sync；单独运行 sync 时会直接获取快照；bulk archive 则会在首次写入规格说明之前，先获取所有必需快照。如果 archive/specs 指令请求返回非零退出码或无效 JSON，这是查找失败，而非输入为空：工作流会在受影响的规格写入或变更移动之前停止（bulk archive 会在任何批量写入或移动之前停止）。

此配置不会改变归档执行阶段、用户 prompts、文件系统操作、语义合并的责任归属、直接的 openspec archive 命令，也不会改变产物 rules 的结构和输出。

模式解析顺序

OpenSpec 需要选择模式时，会按以下顺序检查：

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

自定义模式

当项目配置不够用时，可以创建完全自定义的模式来定义工作流。自定义模式位于项目的 openspec/schemas/ 目录中，并与代码一同进行版本控制。

your-project/
├── openspec/
│   ├── config.yaml        # Project config
│   ├── schemas/           # Custom schemas live here
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Your changes
└── src/

从现有模式派生

最快的自定义方式是从内置模式派生：

openspec schema fork spec-driven my-workflow

该命令会将整个 spec-driven 模式复制到 openspec/schemas/my-workflow/，随后你可以自由编辑。

生成的内容：

openspec/schemas/my-workflow/
├── schema.yaml           # Workflow definition
└── templates/
    ├── proposal.md       # Template for proposal artifact
    ├── spec.md           # Template for specs
    ├── design.md         # Template for design
    └── tasks.md          # Template for tasks

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

从头创建模式

如果要完全从头定义工作流：

# Interactive
openspec schema init research-first

# Non-interactive
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

模式结构

模式会定义工作流中的产物以及它们之间的依赖关系：

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`	依赖项——必须先存在的产物

按你希望的顺序列出产物。requires 决定哪些产物可以开始；当多个产物同时就绪时，artifacts: 列表的顺序决定先处理哪个。

模板

模板是用于指导 AI 的 Markdown 文件。创建相应产物时，模板会注入 prompt 中。

## 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 注释
展示预期结构的示例格式

验证模式

使用自定义模式之前，请先验证：

openspec schema validate my-workflow

此操作会检查：

schema.yaml 语法是否正确
所有被引用的模板是否存在
是否存在循环依赖
产物 ID 是否有效

使用自定义模式

创建完成后，可以这样使用：

# Specify on command
openspec new change feature --schema my-workflow

# Or set as default in config.yaml
schema: my-workflow

调试模式解析

不确定实际使用了哪个模式？运行以下命令检查：

# See where a specific schema resolves from
openspec schema which my-workflow

# List all available schemas
openspec schema which --all

输出会显示模式来自项目、用户目录还是软件包：

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

注意： OpenSpec 还支持将用户级模式放在 ~/.local/share/openspec/schemas/ 下，以便在多个项目间共享；不过建议将模式放在项目级的 openspec/schemas/ 中，因为它会与代码一起进行版本控制。

示例

快速迭代工作流

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

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

添加审查产物

从默认模式派生，并添加审查步骤：

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

社区模式

OpenSpec 也支持通过独立仓库分发、由社区维护的模式。这些模式提供具有明确观点的工作流，可将 OpenSpec 与其他工具或系统集成，类似于 github/spec-kit 的社区扩展目录为 spec-kit 提供扩展的方式。

社区模式不会打包进 OpenSpec 核心，而是保存在各自仓库中，并按各自的节奏发布。要使用某个模式，请将其模式包复制到项目的 openspec/schemas/<schema-name>/ 目录中（各仓库的 README 均包含安装说明）。

模式	维护者	仓库	说明
`intent-driven`	@harikrishnan83	intent-driven-dev/openspec-schemas	在实现前记录变更意图、可观察行为、技术设计和长期架构决策。新增与变更关联的 ADR 审查 manifest，并将符合条件的长期决策写为不可变、可被后续 ADR 取代的记录。
`superpowers-bridge`	@JiangWay	JiangWay/openspec-schemas	将 OpenSpec 的产物治理与 obra/superpowers 执行技能（头脑风暴、编写计划、通过 subagents 进行 TDD、代码审查、收尾）集成。添加以证据为先的 `retrospective` 产物，补足 Superpowers 原生流程未覆盖的环节。
`nanopm`	@nmrtn	nmrtn/nanopm	以产品管理为先的工作流。先运行 nanopm 规划流水线（审计 → 策略 → 路线图 → PRD），再进入实现阶段。将产品规划衔接到 OpenSpec 的规格驱动工程工作流。如果存在 `.nanopm/`，产物会读取其中内容：提案引用审计，设计引用策略，任务引用 PRD 分解。
`e2e-runbooks`	@Lukk17	Lukk17/openspec-schemas	面向能力的端到端测试手册。每项能力都有不可变规格说明、不可变任务模板，并为每次执行生成带时间戳的运行记录。断言只关注可观察行为（HTTP 状态、响应正文、持久化状态，不检查日志片段）；每次运行都会记录 UTC 开始/结束时间、持续时间，以及估算的 LLM token 消耗量。
`anvil`	@jikkujoyce	jikkujoyce/openspec-schemas	遵循 TDD 并包含对抗式审查步骤的规格驱动工作流。流程：`proposal` → `specs` → `design` → `review` → `test-plan` → `tasks` → `apply` → `verify`。`review` 由具备全新上下文的只读审查者编写（如有条件则使用第二个模型），并输出 `VERDICT:` 行，指示 agent gate `test-plan`、`tasks` 和 `apply` 直至通过审查；OpenSpec 只检查产物是否存在，因此需通过自己的 CI 或钩子实施此 gate。`test-plan` 会将每个规格场景映射到具名测试，同时作为由 `verify` 审计的红/绿进度记录。
`ml-research`	@tsenst	idealo/openspec-schemas	机器学习实验工作流。流程：`proposal` → `design` → `evaluation` → `tasks` → `apply` → `specs`。`evaluation` 在实验运行前确定指标、成功标准和证伪条件；`apply` 写入 `results.md`；`specs` 仅将有证据支持的发现（包括被证伪的假设）记录为带有链接 `Evidence:` 块的 `Finding:` 需求。
`epic-driven`	@ivanferic	IvanFeric/openspec-epic-driven	Epic 驱动的工作流。流程：`explore`（可选）→ `epic-propose` → `epic-next` 选择子故事 → 子故事的 `apply` → 子故事的 `archive` → `epic-sync`。Epic 没有 `apply` 阶段，只有在其所有故事完成后才会归档。`epic-propose` 创建愿景、故事和路线图；`epic-next` 推荐一个子故事，`epic-next <story> start` 会将子故事的规划委托给常规的 `openspec-propose` 工作流；`epic-status` 显示该 Epic 中所有故事的当前状态；`epic-replan` 可以修改计划，同时保留当前进行中或已完成的故事；`epic-sync` 更新故事的完成标记。