OpenSpec

專案配置 (config.yaml) ​

openspec/config.yaml 的每個欄位：本專案規劃時使用的 schema、context 與 rules。

位置 ​

每個 OpenSpec 專案將其配置檔案存放在專案根目錄的 openspec/config.yaml。

欄位 ​

鍵型別必填效果
schemastring是本專案變更所遵循的工作流程 schema
contextstring否注入到每個 artifact、apply 與 archive
rulesmap: artifact ID → 字串列表否為單一 artifact 的內建指引新增額外規則
operationsmap: operation → 指引列表否針對 apply 與 archive 工作的建議指引
storestring否當此 openspec/ 為純配置時使用的後備 OpenSpec 根目錄
referenceslist否其 specs 被索引到 instructions 的 stores

無效欄位不會導致命令失敗。每個欄位獨立驗證，無效值會被丟棄並附上警告。無法讀取或非有效 YAML 的檔案會被忽略並附上警告，但 openspec validate 會exit 1 以便 CI 捕捉。

這些欄位應寫入什麼內容，詳見專案配置。

schema ​

本專案中每個變更所遵循的工作流程 schema。有效值為 spec-driven 或專案自定義的 schema 名稱。執行 openspec schemas 以列出可用的 schema 名稱。

context ​

注入到每個 artifact 的 instructions 並提供給 apply 與 archive 的自由文字。上限為 50KB，超過的值會被忽略並附上警告。

rules ​

為單一 artifact 新增額外規則，附加至 schema 的內建指引：

yaml
rules:
  proposal:
    - Keep proposals under 500 words

Artifact ID 不限於內建名稱，因此來自自訂 schema 的 artifacts 也可作為鍵使用。

operations ​

針對 apply 與 archive 工作執行方式的建議指引，與 artifact 規則分開：

yaml
operations:
  apply:
    guidance:
      - Keep test summaries concise

僅讀取 apply 和 archive。

store ​

用作 OpenSpec 根目錄的 store id，僅在此 openspec/ 目錄為純配置（無 specs/ 或 changes/）時查詢。它是後備選項，絕非覆寫。完整解析順序詳見根目錄解析。

references ​

本專案工作所參考的 store ids 之 specs。每個 store 的 specs 索引（id、摘要、fetch 指令）會被加入 instructions 輸出。Spec 內容不會被內嵌，根目錄解析也不受影響。項目可為 store id 或包含 id 與選用 remote clone 來源的 map：

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

範例 ​

一份填寫完整的 config.yaml：

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。