Schema

Schema 定义了工件及其依赖关系。它允许你自定义 OpenSpec 工作流以匹配你的团队工作方式。

默认 Schema

OpenSpec 提供两个默认 schema：

Schema	工件	命令
spec-driven	proposal → specs → design → tasks	propose, explore, apply, archive
campaign-driven	campaign → initiatives → changes	campaign, initiative, change

Schema 结构

name: spec-driven
artifacts:
  - name: proposal
    description: Proposal for the change
    content: proposal.md
  - name: specs
    description: Delta specifications
    content: specs/
  - name: design
    description: Design document
    content: design.md
  - name: tasks
    description: Implementation tasks
    content: tasks.md
dependencies:
  specs: proposal
  design: specs
  tasks: design

自定义 Schema

你可以创建自定义 schema 来定义自己的工件和依赖关系。

示例：TDD Schema

name: tdd-driven
artifacts:
  - name: test
    description: Test specification
    content: tests/
  - name: implementation
    description: Implementation code
    content: src/
  - name: documentation
    description: User documentation
    content: docs/
dependencies:
  implementation: test
  documentation: implementation

示例：Mobile Schema

name: mobile-driven
artifacts:
  - name: user-stories
    description: User stories
    content: user-stories/
  - name: wireframes
    description: Wireframes
    content: wireframes/
  - name: ui-spec
    description: UI specification
    content: ui-spec.md
  - name: implementation
    description: Implementation
    content: src/
dependencies:
  wireframes: user-stories
  ui-spec: wireframes
  implementation: ui-spec

创建自定义 Schema

1. 创建 Schema 文件

mkdir -p openspec/schemas
touch openspec/schemas/custom.yaml

2. 编辑 Schema

# openspec/schemas/custom.yaml
name: custom-workflow
description: 自定义工作流

artifacts:
  - name: research
    description: Research findings
    content: research.md
  - name: proposal
    description: Proposal
    content: proposal.md
  - name: design
    description: Design document
    content: design.md
  - name: prototype
    description: Prototype
    content: prototype/
  - name: tests
    description: Test specifications
    content: tests/
  - name: implementation
    description: Implementation
    content: src/

dependencies:
  proposal: research
  design: proposal
  prototype: design
  tests: prototype
  implementation: tests

3. 应用 Schema

# 初始化时应用
openspec init --schema custom

# 或动态切换
openspec schemas use custom

Schema 配置

你可以在项目配置中引用自定义 schema：

# openspec/config.yaml
schema: custom-workflow
schema-path: openspec/schemas/custom.yaml

Schema 命令

# 列出可用 schema
openspec schemas list

# 查看 schema 详情
openspec schemas show custom-workflow

# 使用新 schema
openspec schemas use custom-workflow

# 创建新 schema
openspec schemas create my-workflow

Schema 最佳实践

1. 保持简单 - 只包含必要的工件
2. 明确依赖 - 明确定义工件顺序
3. 记录规则 - 为每个工件添加规则
4. 版本控制 - 将 schema 文件纳入版本控制

下一步

• 核心概念 - 了解核心概念
• 工作流 - 探索工作流模式
• 自定义 - 自定义 OpenSpec