變更 metadata（.openspec.yaml）

每個變更所儲存 metadata 的支援欄位與驗證規則。

位置

每個變更會將其 metadata 儲存在 openspec/changes/<change-name>/.openspec.yaml，與其 artifacts 並列。建立變更時，系統會寫入該檔案，並填入 schema 和 created。

鍵	類型	必填	效果
`schema`	字串	是	此變更遵循的工作流程 schema
`created`	字串，YYYY-MM-DD	否	記錄變更建立的日期
`goal`	字串	否	記錄變更旨在達成的目標
`affected_areas`	字串列表	否	記錄變更預計觸及的範圍
`initiative`	對應：`store` 和 `id`	否	記錄此變更所屬的 initiative
`skip_specs`	布林值	否	宣告此變更不會產生 spec deltas，因此零 deltas 可通過驗證
`retire_capabilities`	布林值	否	授權 archive 刪除此變更清空後不再需要的 capability

此變更遵循的工作流程 schema。它在變更建立時設定，且優先於專案 config，因此即使日後 openspec/config.yaml 有所變更，變更仍會保留其 schema。執行 openspec schemas 可列出可用的 schema 名稱。

此變更所屬的 initiative，以 store id 和 initiative id 表示，皆使用 kebab-case：

yaml

initiative:
  store: platform-specs
  id: unify-billing

除了 store 和 id 以外的鍵都會被拒絕。目前沒有指令會讀取此連結。

宣告此變更刻意不產生 spec deltas：純粹的重構、工具或文件變更。設定此欄位後，驗證會接受零 deltas，且會產生 spec 檔案的 artifacts 會被視為已完成。若 specs/ 下已存在 spec 檔案時設定此欄位，則會造成驗證錯誤。

授權 archive 淘汰某 capability。當此變更的 REMOVED deltas 移除了某 capability 最後一項需求時，archive 會刪除該 capability 的主要 spec，而非停止執行。此旗標之所以存在，是因為該刪除只能從 git 還原，因此由作者自行決定。

以小寫 x- 開頭的頂層鍵歸你所有，可供其他工具或你的團隊在變更旁儲存的資料使用，例如追蹤器 ID 或負責人：

yaml

schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1
x-owner:
  team: payments

名稱：小寫 x- 前綴後至少接一個字元，且不得包含任何空白。前綴之後的任何大小寫或拼寫皆可，因此 x-jiraKey 和 x-trackerID 都符合。X-Tracker、單獨的 x- 和 x- tracker 則不符合，會被回報為未知鍵。
值：任何 YAML 值。OpenSpec 不會讀取或驗證它，且它不會改變任何行為。
範圍：僅限頂層。initiative 內的 x- 鍵仍會被拒絕，與該處的任何其他鍵相同。
驗證：擴充鍵永遠不會被回報為未知鍵，因此 openspec validate --strict 可通過包含擴充鍵的變更。
Archive：該檔案會隨變更一起移動，內容不變，包括擴充鍵。

已填寫的 .openspec.yaml：

yaml

schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
  - auth
  - api

每當指令寫入或讀取該檔案時，都會進行驗證。寫入失敗時會拋出錯誤且不寫入任何內容。讀取現有檔案時，若 YAML 無效、欄位違反其契約，或 schema 名稱不可用，則會失敗。檔案不存在不視為錯誤，該變更會被視為沒有 metadata。

與 config.yaml 不同，無效值絕不會在警告後捨棄。metadata 錯誤會停止指令執行。

未知的頂層鍵：OpenSpec 會忽略它們。status、instructions、validate 和 archive 會回報其無任何效果。JSON 輸出會在結構化結果中攜帶警告。擴充鍵不被視為未知鍵，永遠不會被回報。
嚴格驗證：openspec validate --strict 會將未知鍵警告視為失敗。僅包含擴充鍵作為額外鍵的變更可通過驗證。