项目配置（config.yaml）

openspec/config.yaml 的每一个字段：本项目用于规划的 schema、context 和 rules。

位置

每个 OpenSpec 项目都把配置文件放在项目根目录下的 openspec/config.yaml。

字段

键	类型	必需	作用
schema	字符串	是	本项目变更所遵循的工作流 schema
context	字符串	否	注入到每个 artifact、apply 和 archive 中
rules	映射：artifact ID → 字符串列表	否	添加到单个 artifact 内置指导中的额外规则
operations	映射：operation → 指导列表	否	针对 apply 和 archive 工作的建议性指导
store	字符串	否	当此 openspec/ 目录仅包含配置时，作为回退的 OpenSpec 根目录
references	列表	否	其 specs 会被索引到指令中的 store

无效字段绝不会导致命令失败。每个字段独立校验，坏值会被丢弃并给出警告。无法读取或不是有效 YAML 的文件会被忽略并给出警告，但 openspec validate 除外，它会以退出码 1 结束，以便 CI 捕获该问题。

这些字段应填写什么内容，请参阅项目配置。

schema

本项目每个变更所遵循的工作流 schema。有效值为 spec-driven 或项目定义的 schema 名称。运行 openspec schemas 可列出可用的 schema 名称。

context

注入到每个 artifact 的指令中，并提供给 apply 和 archive 的自由文本。上限为 50KB，超过该值的内容会被忽略并给出警告。

rules

针对单个 artifact 的额外规则，会添加到 schema 的内置指导中：

rules:
  proposal:
    - Keep proposals under 500 words

Artifact ID 不限于内置名称，因此自定义 schema 中的 artifact 也可以作为键。

operations

关于 apply 和 archive 工作如何开展的指导性建议，与 artifact 规则分开：

operations:
  apply:
    guidance:
      - Keep test summaries concise

仅会读取 apply 和 archive。

store

用作 OpenSpec 根目录的 store id，仅当此 openspec/ 目录仅包含配置（没有 specs/ 或 changes/）时才会被采用。它是回退方案，绝不会成为覆盖。完整的解析顺序见根目录解析。

references

本项目工作所依赖其 specs 的 store id。每个 store 的 specs 索引（id、摘要、获取命令）会被添加到指令输出中。Spec 内容绝不会内联，根目录解析也绝不会受影响。条目可以是一个 store id，或是一个包含 id 和可选 remote 克隆源的对象：

references:
  - platform-specs
  - id: billing-specs
    remote: git@github.com:acme/billing-specs.git

示例

一个填写完成的 config.yaml：

schema: spec-driven

context: |
  Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

rules:
  proposal:
    - Keep proposals under 500 words
    - Always state what is out of scope
  tasks:
    - Break tasks into chunks of max 2 hours

operations:
  apply:
    guidance:
      - Keep test summaries concise
  archive:
    guidance:
      - Summarize the archive outcome before finishing

旧版名称

当 config.yaml 不存在时，会将 openspec/config.yml 作为别名读取。当两个文件都存在时，以 config.yaml 为准，忽略 config.yml。openspec init 会创建 config.yaml。