OpenSpec

schema.yaml ​

스키마 정의의 모든 필드입니다. 스키마를 읽거나 작성할 때 사용합니다.

schema.yaml은 워크플로가 생성하는 계획 파일을 나열합니다. 또한 해당 파일의 순서와 구현으로의 인계를 정의합니다.

위치 ​

프로젝트 스키마는 openspec/schemas/<name>/ 아래에 있습니다:

text
openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec은 해당 디렉터리를 세 위치에서 확인합니다. 처음 일치하는 위치가 선택됩니다.

복사본디렉터리
1. 프로젝트<project>/openspec/schemas/<name>/
2. 사용자, macOS 및 Linux~/.local/share/openspec/schemas/<name>/
2. 사용자, Windows%LOCALAPPDATA%\openspec\schemas\<name>\
3. 패키지CLI와 함께 설치된 스키마

XDG_DATA_HOME이 설정되어 있으면 모든 플랫폼에서 사용자 디렉터리가 $XDG_DATA_HOME/openspec/schemas/<name>/로 이동합니다.

디렉터리 이름은 --schema, config.yaml, .openspec.yaml에서 사용하는 조회 키입니다. name 필드가 디렉터리 이름과 다르더라도 OpenSpec은 여전히 조회에 디렉터리 이름을 사용합니다.

openspec schema which <name>는 활성 디렉터리와 그 디렉터리가 가리는 우선순위가 낮은 복사본을 출력합니다.

최상위 필드 ​

필드계약
name필수. 스키마 이름으로 저장되는 비어 있지 않은 문자열입니다. 조회에는 여전히 디렉터리 이름이 사용됩니다.
version필수. 스키마 리비전으로 저장되는 양의 정수입니다. 이 값은 OpenSpec의 동작을 변경하지 않습니다.
descriptionopenspec schemas에서 출력하는 선택적 문자열입니다. 값이 없으면 스키마에 설명이 없습니다.
artifacts필수. 아티팩트 항목의 비어 있지 않은 목록입니다.
apply선택적 apply 설정입니다. 블록이 없으면 OpenSpec은 apply 기본값을 사용합니다.

아티팩트 필드 ​

artifacts 아래의 각 항목은 하나의 계획 파일 또는 파일 집합을 정의합니다.

필드계약
id필수. 의존성, 프로젝트 규칙, 명령 및 apply 설정에서 사용되는 고유한 비어 있지 않은 문자열입니다.
generates필수. 에이전트에게 변경 폴더 내 아티팩트를 작성할 위치를 알려주는 상대 경로 또는 glob입니다.
description필수. 에이전트에게 전송되는 지침에서 아티팩트에 레이블을 지정하는 문자열입니다.
template필수. 스키마의 templates/ 폴더에 있는 아티팩트 형식에 대한 상대 경로입니다.
instruction에이전트에게 생성할 콘텐츠를 알려주는 선택적 안내입니다.
requires먼저 완료되어야 하는 아티팩트 ID 목록입니다. 기본값: [].

generates ​

경로는 변경 폴더에서 시작합니다. add-auth라는 변경의 경우:

yaml
generates: proposal.md

아티팩트는 다음 위치에 생성됩니다:

text
openspec/changes/add-auth/proposal.md

glob은 여러 파일과 일치할 수 있습니다:

yaml
generates: specs/**/*.md

이 패턴은 openspec/changes/add-auth/specs/ 아래의 Markdown 파일과 일치합니다.

OpenSpec은 generates에서 다음 glob 형식을 인식합니다:

  • 와일드카드 및 문자 클래스: *, ?, [를 포함하는 값입니다. 예: specs/**/*.md, review-[ab].md.
  • 중괄호 확장: review-{api,ui}.md와 같은 대안 및 file-{1..3}.md와 같은 범위입니다.
  • Extglob: @(proposal|design).md, +(proposal|design).md, !(proposal|design).md와 같은 패턴입니다.

리터럴 파일 이름: 앞에 붙은 !만으로는 glob이 되지 않습니다. 해당 파일을 지정하려면 generates: '!review.md'를 사용하세요. (proposal|design).md와 같은 일반 괄호와 review-{api}.md와 같은 단일 요소 중괄호도 리터럴로 유지됩니다.

OpenSpec은 절대 경로, .. 세그먼트가 포함된 경로, 중괄호나 괄호를 16단계보다 더 깊게 중첩하는 glob(예: {a,{b,{c,...}}})을 거부합니다. 실제 패턴에는 한두 단계면 충분합니다. 또한 중괄호가 1,024개를 초과하는 패턴으로 확장되는 glob도 거부합니다. 예를 들어 {a,b}를 11번 반복하거나 file-{1..5000}.md와 같은 범위를 사용하는 경우입니다. 오류 메시지는 Artifact output pattern expands to more than 1024 patterns입니다. 실제 패턴은 몇 개로만 확장됩니다.

완료 ​

OpenSpec은 출력이 존재하는지 확인합니다. 아티팩트가 완료되었는지 판단하기 위해 파일을 읽지는 않습니다.

generates 값완료 조건
proposal.md해당 파일이 존재합니다.
specs/**/*.mdglob이 하나 이상의 파일과 일치합니다.

template ​

경로는 스키마의 templates/ 폴더에서 시작합니다. review-first 스키마에서는 다음과 같습니다:

yaml
template: proposal.md

OpenSpec은 다음 파일을 읽습니다:

text
openspec/schemas/review-first/templates/proposal.md

OpenSpec은 템플릿의 내용을 출력 형식으로 에이전트에게 제공합니다. 템플릿을 변경 폴더로 복사하지는 않습니다.

OpenSpec은 절대 경로와 .. 세그먼트가 포함된 경로를 거부합니다.

requires ​

  • 의존성: requires의 모든 ID는 같은 스키마의 다른 아티팩트를 가리켜야 합니다.
  • 준비 상태: 아티팩트는 모든 의존성이 완료된 후 준비 상태가 됩니다.
  • 잘못된 그래프: 누락된 ID, 중복된 ID 및 의존성 순환은 유효성 검사에 실패합니다.
  • 동시에 준비된 경우: 여러 아티팩트가 준비되었을 때 artifacts에서의 순서에 따라 OpenSpec이 먼저 반환할 아티팩트가 결정됩니다.

apply 필드 ​

apply는 구현이 시작되기 전에 존재해야 하는 항목을 정의합니다.

필드계약
requires필수. apply 지침이 준비되기 전에 존재해야 하는 아티팩트의 비어 있지 않은 목록입니다.
tracks변경 폴더에 있는 Markdown 작업 파일에 대한 선택적 상대 경로 또는 glob입니다. 기본값: null.
instructionapply가 준비되었을 때 에이전트에게 전송되는 선택적 안내입니다. OpenSpec은 기본적으로 내장 안내를 사용합니다.

아티팩트의 requires는 계획 순서를 제어합니다. apply.requires는 apply 지침이 준비되는 시점을 제어합니다.

tracks ​

경로는 변경 폴더에서 시작합니다. add-auth라는 변경에서 tracks: tasks.md는 다음 파일을 읽습니다:

text
openspec/changes/add-auth/tasks.md

tracks: "**/tasks.md"와 같은 glob은 일치하는 모든 파일을 읽습니다. 예: backend/tasks.md, frontend/tasks.md. OpenSpec은 해당 파일의 작업과 진행 상황을 결합합니다. 상태와 목록이 동일한 파일을 추적하도록 아티팩트의 generates 필드에도 같은 값을 사용하세요. generates의 중괄호 제한(최대 16단계 깊이, 최대 1,024개 확장 패턴)도 여기에 적용됩니다.

일치하는 파일이 없거나 일치한 파일에 작업 텍스트가 있는 체크박스가 없으면 apply는 차단된 상태로 유지됩니다. OpenSpec은 다음 체크박스 형식을 집계합니다:

markdown
- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

모든 Markdown 목록 마커를 사용할 수 있습니다: -, *, + 또는 최대 아홉 자리 숫자 뒤에 . 또는 )가 오는 형식입니다. 앞쪽 공백도 허용됩니다. spec-driven 페이지의 tasks.md 섹션에서는 기본 스키마가 생성하는 더 엄격한 형식을 정의합니다.

추적된 파일이 apply 상태를 결정합니다:

  • blocked: 일치하는 파일이 없거나, 읽을 수 있는 파일에 작업 텍스트가 있는 체크박스가 없습니다.
  • ready: 하나 이상의 작업이 대기 중이거나, 일치한 파일 하나를 읽을 수 없지만 다른 파일이 작업을 제공하는 경우입니다.
  • all_done: 추적된 모든 작업이 체크되어 있고 일치한 모든 파일을 읽었습니다.

일치한 파일을 읽을 수 없으면 apply는 읽을 수 있는 파일의 작업과 진행 상황을 유지하지만 해당 변경을 all_done으로 표시하지 않습니다. apply JSON 출력은 사용할 수 없는 각 파일과 그 이유를 식별합니다.

OpenSpec은 절대 경로와 .. 세그먼트가 포함된 경로를 거부합니다.

apply 기본값 ​

동작기본값
필수 아티팩트스키마의 모든 아티팩트
진행 상황 추적추적 파일 없음
에이전트 안내내장 apply 안내

전체 예시 ​

yaml
name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

유효성 검사 ​

openspec schema validate <name>는 다음을 확인합니다:

  • 필드 유형 및 필수 필드
  • 상대 경로
  • 아티팩트 ID, 의존성 및 순환
  • apply.requires ID: 각 ID는 스키마의 아티팩트여야 합니다.
  • 템플릿 파일

알 수 없는 apply.requires ID가 있는 스키마는 로드되지 않으므로, 해당 스키마를 사용하는 모든 명령이 오류를 보고합니다.

apply.tracks가 어떤 아티팩트의 generates 값과 정확히 같지 않으면 유효성 검사는 실패시키지 않고 경고합니다. OpenSpec은 두 문자열을 비교하여 추적된 아티팩트를 찾으므로, 그 외의 경우에는 해당 파일이 어떤 아티팩트의 진행 상황에 속하는지 구분할 수 없습니다. 여기에는 task.md와 같은 오타가 포함되며, tracks: tasks/main.md와 generates: tasks/*.md를 비교하는 경우도 포함됩니다. 이 경우 glob이 실제로 파일을 생성하더라도 문자열은 여전히 다릅니다. apply는 어느 경우든 파일을 계속 읽지만, openspec list와 openspec status는 대신 tasks.md를 집계합니다.

유효성 검사는 다음 실수를 잡아내지 못합니다:

실수결과
instrution처럼 필드 철자가 틀린 경우OpenSpec은 이를 무시합니다. 유효성 검사는 오타를 보고하지 않습니다.
name이 스키마 디렉터리와 다른 경우유효성 검사를 통과합니다. OpenSpec은 여전히 조회에 디렉터리 이름을 사용합니다.