OpenSpec

스키마 ​

OpenSpec이 생성하는 것을 변경하세요: 아티팩트, 순서, 그리고 템플릿.

스키마는 변경 제안이 생성하는 것을 정의합니다: 어떤 아티팩트를, 어떤 순서로, 어떤 템플릿에서 생성할지. 예를 들어, 기본 번들 스키마인 spec-driven은 대략 다음 순서로 네 가지 아티팩트를 생성하며, 각각 이전 단계의 결과를 기반으로 합니다:

proposal → specs → design → tasks

이것들이 다른 문서가 되어야 할 때 — 더 적은 수의 문서, 다른 이름, 또는 다른 구조를 의미하더라도 — 스키마를 포크하세요.

스키마가 위치하는 곳 ​

OpenSpec은 스키마를 세 곳에서 순서대로 찾아 가장 먼저 발견된 것을 사용합니다:

  1. 프로젝트: openspec/schemas/, 저장소와 함께 커밋되어 팀 전체가 사용합니다.
  2. 컴퓨터: macOS 및 Linux에서는 ~/.local/share/openspec/schemas (또는 $XDG_DATA_HOME을 설정한 경우 그 하위), Windows에서는 %LOCALAPPDATA%\openspec\schemas. 여기에 있는 스키마는 작업하는 모든 프로젝트에서 사용 가능합니다.
  3. 패키지: spec-driven와 같은 빌트인이 openspec 자체 내부에 포함되어 있습니다.

동일한 이름이 여러 곳에 존재할 수 있으며, 더 구체적인 위치가 우선합니다. openspec schema which는 어떤 복사본이 사용 중인지 보여줍니다:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

스키마의 구성 ​

스키마는 일반 파일들의 폴더로 정의됩니다: 아티팩트를 선언하는 schema.yaml 하나와 각 아티팩트의 템플릿. 다음은 빌트인 spec-driven입니다:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md
  • schema.yaml: 각 아티팩트, 생성되는 파일, 시작 템플릿, 먼저 필요한 것, 그리고 에이전트가 생성 시 받는 지시문을 선언합니다. 모든 필드의 계약은 schema.yaml에 있습니다.
  • templates/: 아티팩트별 마크다운 골격으로, 에이전트가 채워 넣습니다.

다음은 schema.yaml에서 tasks 아티팩트 항목을 간략히 정리한 것입니다:

yaml
artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

빌트인 스키마는 openspec 패키지 내부에 포함되어 있으므로 직접 편집하지 않습니다. 포크하여 나만의 복사본을 얻으세요.

사용자 지정 스키마 생성 ​

나만의 스키마를 얻는 방법은 두 가지입니다:

  1. 기존 스키마 포크 후 복사본 편집. 기존 스키마가 원하는 것에 가까울 때 여기서 시작하세요. 이미 모든 것이 작동하기 때문입니다.
  2. 처음부터 시작 — 아무것도 맞지 않을 때 openspec schema init으로 빈 스키마를 스캐폴딩합니다.

기존 스키마 포크 ​

  1. 시작하려는 스키마를 프로젝트 루트에서 실행하여 포크합니다:

    console
    $ openspec schema fork spec-driven

Note: Schema commands are experimental and may change.
✔ Forked 'spec-driven' to 'spec-driven-custom'

Source: .../openspec/schemas/spec-driven (package)
Destination: /your-project/openspec/schemas/spec-driven-custom

    두 번째 인수를 전달하여 이름을 선택합니다(openspec schema fork spec-driven team-flow). 이름은 케밥 케이스입니다.

  2. 복사본 편집: schema.yaml과 템플릿. 포크 편집에서 변경할 내용을 다룹니다.

  3. 검증:

    bash
    openspec schema validate spec-driven-custom

    이 명령은 변경 작업 중간에 발생하기 전에 손상된 스키마(누락된 템플릿, 잘못된 YAML, 의존성 순환)를 발견하는 유일한 명령입니다.

  4. openspec/config.yaml에서 프로젝트가 이를 가리키도록 합니다. fork가 config.yaml을 그대로 두기 때문에 이 단계는 사용자가 직접 수행합니다:

    yaml
    schema: spec-driven-custom

  5. 새 변경 제안이 이제 사용자의 스키마를 따릅니다. 이전에 생성된 변경은 시작 시점의 스키마를 유지합니다.

config.yaml을 건드리지 않고 기본값을 모든 곳에서 대체하려면 동일한 이름으로 포크합니다: openspec schema fork spec-driven spec-driven. 그러면 프로젝트의 복사본이 빌트인을 가립니다. 스키마가 위치하는 곳에서 설명했습니다.

처음부터 시작 ​

openspec schema init은 복사하는 대신 새 스키마를 스캐폴딩합니다:

console
$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

스캐폴드는 비어 있습니다. 아티팩트는 빌트인 네 개의 ID에서만 오며, 생성된 템플릿에는 지시문이 없어 사용자가 직접 작성할 때까지 에이전트가 받는 안내가 적습니다. 거기서부터 fork 단계가 그대로 적용됩니다: 검증한 다음 config.yaml이 이를 가리키도록 합니다.

포크 편집 ​

포크에는 편집할 두 종류의 파일이 있습니다:

  • templates/는 각 문서의 골격을 변경합니다. tasks 템플릿에 섹션을 추가하면 새로운 tasks.md마다 해당 섹션으로 시작합니다. 첫 줄의 # 제목을 유지하세요: 아티팩트가 이를 상속하므로 생성된 모든 파일이 제목이 있는 문서로 열립니다.
  • schema.yaml은 워크플로 자체를 변경합니다: 어떤 아티팩트가 존재하는지, 각각이 먼저 필요한 것, 그리고 에이전트가 생성 시 받는 지시문.

예를 들어, 더 간결한 플로우를 위해 design 문서를 제거하려면:

  1. schema.yaml에서 design 항목을 삭제합니다.

  2. tasks의 requires 목록에서 design를 제거합니다.

  3. 검증:

    console
    $ openspec schema validate spec-driven-custom

✓ Schema 'spec-driven-custom' is valid

2단계를 건너뛰면 검증이 이를 발견합니다:

console
✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

수동 편집 후에는 매번 검증하세요. 그렇지 않으면 손상된 스키마가 워크플로가 존재하지 않는 파일을 요청할 때 변경 작업 중간에 발생합니다. config.yaml과 마찬가지로 스키마 편집은 다음 실행 시 에이전트에게 전달됩니다.

포크는 스냅샷 ​

openspec update는 설치된 스킬과 명령을 새로 고치며 openspec/schemas/에 절대 손을 대지 않습니다. 포크는 사용자가 남긴 그대로 계속 작동하지만, 이는 빌트인 스키마가 발전할 때 개선 사항을 더 이상 받지 못함을 의미하기도 합니다. 나중에 이를 받아들이려면 새 이름으로 빌트인을 다시 포크하고 차이점을 이식하세요.

스키마 공유 ​

스키마 공유는 폴더를 복사하는 것을 의미합니다.

  • 팀과 공유: openspec/schemas/를 커밋하면 저장소의 모든 사람이 사용합니다.
  • 프로젝트 간 공유: 스키마가 위치하는 곳의 사용자 수준 디렉터리에 폴더를 넣습니다.
  • 커뮤니티에서: 커뮤니티 카탈로그에 공유 스키마가 나열되어 있습니다. 하나를 openspec/schemas/<name>에 복사하면 나만의 것처럼 작동합니다.

스키마를 직접 복사하는 대신 이름으로 설치할 수 있도록 공개 및 비공개 스키마 레지스트리를 준비 중입니다.

Superpowers와 함께 OpenSpec 사용 ​

커뮤니티가 유지 관리하는 superpowers-bridge 스키마는 OpenSpec 아티팩트를 Superpowers 실행 스킬에 연결합니다. 프로젝트에 복사하기 전에 브리지의 설치 및 호환성 노트를 따르세요.

브리지는 OpenSpec 외부에서 출시됩니다. OpenSpec은 Superpowers 통합을 테스트하거나 버전을 관리하지 않습니다.