OpenSpec

변경 메타데이터 (.openspec.yaml) ​

각 변경과 함께 저장되는 메타데이터의 지원 필드와 검증 규칙.

위치 ​

각 변경은 아티팩트 옆에 openspec/changes/<change-name>/.openspec.yaml에 메타데이터를 유지합니다. 변경을 생성하면 schema와 created가 채워진 파일이 작성됩니다.

필드 ​

키유형필수효과
schema문자열예이 변경이 따르는 워크플로 스키마
created문자열, YYYY-MM-DD아니오변경이 생성된 날짜를 기록
goal문자열아니오변경이 달성하려는 목표를 기록
affected_areas문자열 목록아니오변경이 영향을 줄 것으로 예상되는 영역을 기록
initiative맵: store 및 id아니오이 변경이 속한 이니셔티브를 기록
skip_specs불리언아니오변경이 스펙 델타를 생성하지 않음을 선언하여 델타가 없어도 검증 통과
retire_capabilities불리언아니오변경이 비워낸 기능을 보관 시 삭제하도록 승인

schema ​

이 변경이 따르는 워크플로 스키마. 변경 생성 시 설정되며 프로젝트 구성보다 우선하므로, openspec/config.yaml이 나중에 변경되더라도 변경은 해당 스키마를 유지합니다. openspec schemas를 실행하여 사용 가능한 스키마 이름을 확인하세요.

initiative ​

이 변경이 속한 이니셔티브로, 스토어 ID와 이니셔티브 ID(둘 다 kebab-case)로 표현됩니다:

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

store와 id 외의 키는 거부됩니다. 현재 이 링크를 읽는 명령은 없습니다.

skip_specs ​

변경이 의도적으로 스펙 델타를 생성하지 않음을 선언합니다: 순수 리팩터링, 도구 또는 문서 변경. 이 옵션을 설정하면 검증은 델타가 없어도 허용하고, 스펙 파일을 생성할 아티팩트는 완료된 것으로 간주됩니다. specs/ 아래에 스펙 파일이 존재하는 상태에서 이를 설정하면 검증 오류가 발생합니다.

retire_capabilities ​

보관 시 기능을 폐기하도록 승인합니다. 이 변경의 REMOVED 델타가 기능이 가진 마지막 요구사항을 제거할 때, 보관 프로세스는 중단하는 대신 해당 기능의 메인 스펙을 삭제합니다. 이 플래그가 존재하는 이유는 삭제가 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를 통과합니다.
  • 보관: 파일은 확장 키를 포함하여 변경 그대로 이동합니다.

예시 ​

채워진 .openspec.yaml 예시:

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는 알 수 없는 키 경고를 실패로 처리합니다. 추가 키가 확장 키만인 변경은 통과합니다.