專案配置

只要在 config.yaml 中寫上幾行，就能讓工作流程按照你想要的方式規劃變更。

openspec/config.yaml 會告知工作流程你希望如何規劃變更。

例如，以下配置更新了 tasks.md artifact 的建立規則：

rules:
  tasks:
    - End every task with a commit

當 agent 執行時，它會套用這些規則，並確保每個任務都以 commit 步驟結尾。

保持規則簡短。這裡的所有內容都會進入 agent 的脈絡，冗長的規則反而可能讓輸出變差。

運作方式

config.yaml 保存了 agent 在建立 artifact 或執行工作流程時所接收的指示。

每次執行會發生以下流程：

1. 你執行一個工作流程（例如 /openspec-propose）。
2. agent 呼叫 openspec instructions 命令。
3. 該命令會讀取你的脈絡，以及 config.yaml 中的規則。
4. OpenSpec 的內建指示與你的自訂內容會合併為提供給 agent 的單一提示。
5. agent 依照該提示來撰寫 artifact。

例如，搭配 context 欄位與本頁開頭的規則，以下是 openspec instructions 針對 tasks.md 回傳的內容（經過精簡與註解）：

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

  <!-- From your config.yaml: context -->
  <project_context>
    Designs and tasks must cover Windows, macOS, and Linux
    Write all artifacts in Spanish
  </project_context>

  <!-- From your config.yaml: rules for tasks -->
  <rules>
    - End every task with a commit
  </rules>

  <!-- From OpenSpec: the built-in guidance -->
  <instruction>
    ...how to write a good tasks.md...
  </instruction>

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

</artifact>

你的 config 會先到達，接著是 OpenSpec 的內建指示與範本。規則會附加在內建內容之上，而不會取代它們。對 config.yaml 的編輯會在下一次執行時傳送給 agent。

欄位

有三個欄位會影響 agent 接收到的內容。每個欄位的確切契約（型別、限制、驗證）請參閱專案配置 (config.yaml)。

欄位	作用	注入至
context	agent 一律接收的指示	所有內容：每個 artifact、apply、archive
rules	針對某個 artifact 的額外指示	僅該 artifact 的建立
operations	關於如何執行工作流程步驟的指引	僅 apply 與 archive

config.yaml 的其他欄位（schema、store、references）用來選取專案要使用哪個 schema 與哪個 OpenSpec 根目錄。契約頁面會說明這些欄位。

最後一欄是精確的，因此每個欄位只會到達該處所列的步驟。特別要注意的是，verify 永遠不會收到 rules。它會依照 artifact 所寫的內容來檢查實作。

context

context 是 agent 在建立 artifact、套用任務或封存變更時所接收的背景資訊。

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

使用 context 來提供應該影響工作流程輸出的事實與限制。把持久的專案文件保留在專案文件檔案中，並省略任何 agent 可以透過閱讀程式碼學到的內容。

其他語言：由於 context 會套用到每個 artifact，你可以加入 Write all artifacts in Spanish. 來指示 agent 用西班牙文撰寫 proposal、spec、design 和 tasks artifact。

rules

rules 會以 artifact id 為鍵，附加到單一 artifact。每一行都會加入至該 artifact 的內建指引：

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

現在 proposals 會保持簡短，而 tasks.md 一律會規劃瀏覽器測試。其他 artifact 則不受影響。

operations

operations 會指引 agent 如何執行 apply 與 archive，而不是 artifact 要寫些什麼：

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

在 apply 期間，agent 會在完成任務時執行 linter。在 archive 期間，它會以摘要作結。

當 config.yaml 不夠用時

Config 會在標準工作流程之上加入指示，但它無法變更存在哪些 artifact，或它們的結構。當你想要那種層級的控制，或規則無法一致地引導行為時，請 fork 一個 schema。