openspec-schema

OpenSpec 架构技能

使用 openspec schema 子命令创建和管理自定义工作流架构。架构定义了有哪些产物及其依赖关系。默认的 spec-driven 架构提供 proposal -> specs -> design -> tasks 流程，但自定义架构可以支持不同的工作流。

适用场景

• 用户需要自定义工作流（例如，先研究、快速迭代）。
• 用户说“创建架构”“自定义工作流”或“派生 spec-driven 架构”。
• 调试架构解析（openspec schema which）。
• 验证自定义架构的结构。

前置条件

• 已安装 OpenSpec CLI（参见 openspec-install）。

工作流

从头创建新架构

openspec schema init my-workflow
# Interactive: prompts for description, artifacts, default
# Non-interactive:
openspec schema init rapid --description "Rapid iteration" --artifacts "proposal,tasks" --default

创建包含 schema.yaml 和 templates/ 的 openspec/schemas/my-workflow/。

派生现有架构

openspec schema fork spec-driven my-workflow

复制 spec-driven 架构以便自定义。

验证架构

openspec schema validate my-workflow
# Or validate all:
openspec schema validate

检查架构解析结果

openspec schema which spec-driven
# Shows: package, project, or user source
openspec schema which --all

架构结构

openspec/schemas/<name>/
├── schema.yaml       # Artifact definitions and dependencies
└── templates/
    ├── proposal.md   # Template for each artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

schema.yaml 示例

name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []
  - id: proposal
    generates: proposal.md
    requires: [research]
  - id: tasks
    generates: tasks.md
    requires: [proposal]

架构优先级

1. 项目：openspec/schemas/<name>/（本地，受版本控制）
2. 用户：~/.local/share/openspec/schemas/<name>/（全局）
3. 软件包：内置架构（例如 spec-driven）

输出

• 位于 openspec/schemas/<name>/ 的自定义架构，包含 schema.yaml 和模板。

后续步骤

• 使用 openspec-new 应用该架构：/opsx:new my-change --schema my-workflow。
• 或在 openspec-config（openspec/config.yaml）中将其设为默认架构。

故障排除

• “未找到架构”：运行 openspec schemas 查看可用架构；运行 openspec schema which <name> 查看解析结果。
• 验证错误：运行 openspec schema validate <name> --verbose 查看详情。
• 规则中存在未知产物 ID：运行 openspec schemas --json 查看各架构的产物 ID。

参考资料

• OpenSpec CLI：架构命令
• OpenSpec 概念：架构
• OpenSpec 自定义