OpenSpec

项目配置 ​

只需在 config.yaml 中写几行，即可让工作流按你的意愿规划变更。

openspec/config.yaml 告诉工作流你希望如何规划变更。

例如，以下配置会更新 tasks.md 工件的创建规则：

yaml
rules:
  tasks:
    - End every task with a commit

当智能体运行时，它会读取这些规则，并确保每个任务都以提交步骤结束。

规则要简短。这里的所有内容都会进入智能体的上下文，冗长的规则可能会使输出变差。

工作原理 ​

config.yaml 包含智能体在创建工件或执行工作流时收到的指令。

每次运行都会发生以下过程：

  1. 你运行一个工作流（例如 /openspec-propose）。
  2. 智能体调用 openspec instructions 命令。
  3. 该命令从 config.yaml 中读取你的上下文和规则。
  4. OpenSpec 的内置指令与你的自定义内容会合并为一个提示词，提供给智能体。
  5. 智能体按照该提示词编写工件。

例如，假设有一个 context 字段以及本页顶部的规则，以下是 openspec instructions 针对 tasks.md 返回的内容（已精简并标注）：

xml
<artifact id="tasks" change="add-dark-mode" schema="spec-driven">

  <!-- 来自你的 config.yaml：context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- 来自你的 config.yaml：tasks 的规则 -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- 来自 OpenSpec：内置指导 -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

  <template>
    ...the tasks.md structure to fill in...
  </template>

</artifact>

你的配置会先送达，然后才是 OpenSpec 的内置指令和模板。规则会追加到内置内容中，绝不会替换它们。对 config.yaml 的修改会在下一次运行时传递给智能体。

字段 ​

有三个字段会影响智能体收到的内容。每个字段的精确约定（类型、限制、校验）见 项目配置（config.yaml）。

字段作用注入到
context智能体始终会收到的指令所有环节：每个工件、apply、archive
rules针对单个工件的额外指令仅该工件的创建过程
operations关于如何执行某个工作流步骤的指导仅 apply 和 archive

config.yaml 的其他字段（schema、store、references）用于选择项目使用哪个 schema 以及哪个 OpenSpec 根目录。约定页面中涵盖了这些内容。

最后一列是精确的，因此某个字段只会到达其中列出的步骤。特别是，verify 永远不会收到 rules。它会根据工件中写明的内容来检查实现。

context ​

context 是智能体在创建工件、执行任务或归档变更时收到的背景信息。

yaml
context: |
  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

使用 context 来提供应当影响工作流输出的事实和约束。将长期有效的项目文档放在项目的文档文件中，并省略智能体通过阅读代码就能了解的任何内容。

其他语言：由于上下文会到达每个工件，你可以添加 Write all artifacts in Spanish.，指示智能体用西班牙语编写 proposal、spec、design 和 tasks 工件。

rules ​

rules 附加到单个工件，并以工件 id 作为键。每一行都会添加到该工件的内置指导中：

yaml
rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test

这样 proposal 会保持简短，tasks.md 也始终会规划浏览器测试。其他所有工件都不受影响。

operations ​

operations 指导智能体如何执行 apply 和 archive，而不是规定工件的内容：

yaml
operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving

在执行 apply 期间，智能体会在完成任务时运行 lint 检查。在 archive 期间，它会以摘要收尾。

当 config.yaml 不够用时 ​

配置会在标准工作流之上添加指令，但无法改变存在哪些工件或它们的结构方式。当你需要这种级别的控制，或者规则无法稳定地引导行为时，请复刻一个 schema。