変更メタデータ (.openspec.yaml)
各変更に保存されるメタデータのサポートされるフィールドとバリデーションルール。
場所
各変更は、その成果物の隣に openspec/changes/<change-name>/.openspec.yaml としてメタデータを保持します。変更を作成すると、schema と created が入力されたファイルが書き込まれます。
フィールド
| キー | 型 | 必須 | 効果 |
|---|---|---|---|
schema | string | はい | この変更がたどるワークフロースキーマ |
created | string, YYYY-MM-DD | いいえ | 変更が作成された日付を記録する |
goal | string | いいえ | 変更が行うことを記録する |
affected_areas | string のリスト | いいえ | 変更が影響を与えると想定される領域を記録する |
initiative | マップ: store と id | いいえ | この変更が属するイニシアチブを記録する |
skip_specs | boolean | いいえ | 変更が spec の差分を生成しないことを宣言し、差分ゼロでバリデーションが通るようにする |
retire_capabilities | boolean | いいえ | この変更が空にした capability の削除をアーカイブに許可する |
schema
この変更がたどるワークフロースキーマ。変更作成時に設定され、プロジェクト設定より優先されるため、openspec/config.yaml が後から変更されても、変更はそのスキーマを保持します。利用可能なスキーマ名を一覧表示するには、openspec schemas を実行してください。
initiative
この変更が属するイニシアチブ。store ID と initiative ID で指定し、どちらも kebab-case です:
initiative:
store: platform-specs
id: unify-billingstore と id 以外のキーは拒否されます。現時点では、このリンクを読み取るコマンドはありません。
skip_specs
この変更が意図的に spec の差分を生成しないことを宣言します: 純粋なリファクタリング、ツール、またはドキュメントの変更です。これを設定すると、バリデーションは差分ゼロを受け入れ、spec ファイルを生成するはずの成果物は完了とみなされます。specs/ の下に spec ファイルが存在する状態でこれを設定すると、バリデーションエラーになります。
retire_capabilities
アーカイブが capability をリタイアすることを許可します。この変更の REMOVED 差分によって capability の最後の requirement が削除された場合、アーカイブは停止する代わりに、その capability の main spec を削除します。このフラグが存在するのは、削除は git からのみ復元可能であり、作者の判断に委ねられているためです。
拡張キー
小文字の x- で始まるトップレベルのキーは、トラッカー ID やオーナーなど、別のツールやチームが変更の隣に保持するデータのために使用できます:
schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1
x-owner:
team: payments- 名前: 小文字の
x-プレフィックスの後に少なくとも1文字が続き、空白を含まない必要があります。プレフィックス以降は任意の大文字・小文字や綴りが使用できるため、x-jiraKeyやx-trackerIDは該当します。X-Tracker、単独のx-、x- trackerは該当せず、未知のキーとして報告されます。 - 値: 任意の YAML 値。OpenSpec はこれを読み取らず、バリデーションも行わず、動作も変わりません。
- スコープ: トップレベルのみ。
initiative内のx-キーは、そこにある他のキーと同様に引き続き拒否されます。 - バリデーション: 拡張キーは未知のキーとして報告されることはないため、それらを持つ変更は
openspec validate --strictをパスします。 - アーカイブ: ファイルは変更と共に変更されないまま移動します。拡張キーも含まれます。
例
入力済みの .openspec.yaml:
schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
- auth
- apiバリデーション
このファイルは、コマンドが書き込みまたは読み取りを行うたびにバリデーションされます。バリデーションに失敗した書き込みはスローされ、何も書き込まれません。既存ファイルの読み取りは、無効な YAML、契約に違反するフィールド、または利用できないスキーマ名がある場合に失敗します。ファイルが存在しないことはエラーではなく、変更はメタデータなしとして扱われます。
config.yaml とは異なり、不正な値が警告付きで破棄されることはありません。メタデータエラーはコマンドを停止させます。
- 未知のトップレベルキー: OpenSpec はこれらを無視します。
status、instructions、validate、archiveは効果がないことを報告します。JSON 出力は構造化された結果に警告を含めます。拡張キー は未知のキーではなく、報告されることはありません。 - 厳格なバリデーション:
openspec validate --strictは未知キーの警告を失敗として扱います。追加のキーが拡張キーのみである変更はパスします。