사용자 정의

OpenSpec은 세 가지 수준의 사용자 정의를 제공합니다:

수준	기능	적합한 대상
프로젝트 구성	기본값 설정, 컨텍스트/규칙 주입	대부분의 팀
사용자 정의 스키마	고유한 워크플로우 아티팩트 정의	고유한 프로세스를 가진 팀
전역 재정의	모든 프로젝트 간 스키마 공유	고급 사용자

---

프로젝트 구성

openspec/config.yaml 파일은 팀을 위해 OpenSpec을 사용자 정의하는 가장 쉬운 방법입니다. 이를 통해 다음을 수행할 수 있습니다:

• 기본 스키마 설정 - 매번 --schema 옵션을 생략 가능
• 프로젝트 컨텍스트 주입 - AI가 기술 스택, 관례 등을 인식
• 아티팩트별 규칙 추가 - 특정 아티팩트에 대한 사용자 정의 규칙
• 작업별 안내 추가 - apply 및 archive 작업에 대한 권장 사항
• 통합 선택 기억 - 예: GitHub Copilot 클라우드 코딩 에이전트 옵인(opt-in)

빠른 설정

openspec init

이 명령은 대화형으로 구성 파일을 생성하도록 안내합니다. 또는 수동으로 생성할 수도 있습니다:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

작동 방식

기본 스키마:

# 구성 파일 없음
openspec new change my-feature --schema spec-driven

# 구성 파일 있음 - 스키마가 자동으로 적용됨
openspec new change my-feature

컨텍스트 및 규칙 주입:

어떤 아티팩트를 생성하든, 컨텍스트와 규칙이 AI 프롬프트에 주입됩니다:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• 컨텍스트는 모든 아티팩트에 나타납니다.
• 규칙은 일치하는 아티팩트에만 나타납니다.

작업 안내:

operations.apply.guidance 및 operations.archive.guidance는 에이전트가 해당 작업을 수행하는 방법에 대한 권장 지침의 선택적 배열입니다. 이들은 rules와 별개입니다: 작업 안내는 아티팩트 내용을 제한하지 않으며, 아티팩트 규칙이 작업 안내로 다시 레이블 지정되지 않습니다.

Apply 및 archive는 실행 시 이러한 입력을 가져옵니다:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

두 명령 모두 현재 프로젝트 context와 일치하는 operationGuidance를 별도의 선택적 필드로 반환합니다. 각 호출은 해결된 루트에서 최신 스냅샷을 읽습니다. --store <id>가 선택되면 변경 사항, 컨텍스트 및 안내는 모두 현재 저장소에서 가져오며 현재 저장소에서는 가져오지 않습니다. archive 명령은 읽기 전용입니다: 델타 스펙을 검사하거나 병합하지 않고, 메인 스펙을 작성하지도 않으며, 변경 사항을 이동하지도 않고, 정적 archive 워크플로우를 실행하지도 않습니다.

프로젝트 컨텍스트는 필수 프롬프트 레벨 입력입니다. 생성된 워크플로우는 이를 읽고 관련 프로젝트 사실, 관례 및 제약을 적용합니다. 작업 안내는 선택적 추가 조언입니다: 워크플로우는 모든 항목을 고려하고 내장 워크플로우와 호환되고 적용 가능한 항목을 따릅니다.

두 필드는 CLI 제어 상태, 해결된 경로, 내장 단계, 명시적 사용자 선택 및 아티팩트 규칙과 분리되어 유지됩니다. 워크플로우는 제어 값을 보존하면서 컨텍스트 충돌을 보고합니다. 적용 불가능하거나 충돌하는 안내는 따르지 않으며 그 이유를 설명합니다. 두 필드 모두 강제 검사(check)가 아니며, 워크플로우는 사용자가 별도로 해당 콘텐츠를 요청하지 않는 한 구현 파일, 스펙, 변경 아티팩트 또는 요약문에 их 텍스트를 복사하지 않습니다.

Archive 및 spec-sync 입력 안전성:

Archive, 대량 archive 및 독립형 sync는 openspec status --json의 artifactPaths.specs.existingOutputPaths를 유일한 델타 스펙 소스로 사용합니다. specs 아티팩트가 없는 스키마나 구체적인 출력 목록이 빈 변경 사항은 동기화할 것이 없습니다: 다른 아티팩트는 델타 스펙을 추론하는 데 사용되지 않습니다.

시맨틱 병합이 메인 스펙을 쓰기 전에, 워크플로우는 현재 openspec instructions specs --change <name> --json 출력을 소비합니다. 반환된 specs 규칙은 해당 병합에서 생성된 메인 스펙에만 제약 조건을 부과합니다. 단일 archive는 이 스냅샷을 인라인 sync로 전달하고, 독립형 sync는 이를 직접 가져오며, 대량 archive는 첫 번째 스펙 쓰기 전에 필요한 모든 스냅샷을 가져옵니다. 비영(non-zero)이거나 유효하지 않은 JSON archive/specs instruction 응답은 조회 실패이며 빈 입력이 아닙니다: 워크플로우는 영향을 받는 스펙 쓰기 또는 변경 사항 이동(대량 archive의 경우, 모든 배치 쓰기 또는 이동 전) 전에 중지됩니다.

이 구성은 archive 실행 단계, 사용자 프롬프트, 파일 시스템 작업, 시맨틱 병합 소유권, 직접적인 openspec archive 명령 또는 아티팩트 rules의 구조와 출력을 변경하지 않습니다.

스키마 해석 순서

OpenSpec이 스키마가 필요할 때 다음 순서로 확인합니다:

1. CLI 플래그: --schema <name>
2. 변경 메타데이터(변경 폴더 내 .openspec.yaml)
3. 프로젝트 구성(openspec/config.yaml)
4. 기본값(spec-driven)

커스텀 스키마

프로젝트 설정만으로는 부족할 때, 완전히 커스텀한 워크플로우로 자체 스키마를 생성할 수 있습니다. 커스텀 스키마는 프로젝트의 openspec/schemas/ 디렉토리에 위치하며 코드와 함께 버전 관리됩니다.

your-project/
├── openspec/
│   ├── config.yaml        # 프로젝트 설정
│   ├── schemas/           # 커스텀 스키마가 여기에 위치합니다
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # 변경 사항
└── src/

기존 스키مة 포크하기

커스터마이징하는 가장 빠른 방법은 내장된 스키마를 포크하는 것입니다:

openspec schema fork spec-driven my-workflow

이 명령은 전체 spec-driven 스키마를 openspec/schemas/my-workflow/로 복사하며, 여기서 자유롭게 편집할 수 있습니다.

제공되는 내용:

openspec/schemas/my-workflow/
├── schema.yaml           # 워크플로우 정의
└── templates/
    ├── proposal.md       # 제안서 아티팩트용 템플릿
    ├── spec.md           # 명세서용 템플릿
    ├── design.md         # 설계 문서용 템플릿
    └── tasks.md          # 작업 목록용 템플릿

이제 schema.yaml을 편집하여 워크플로우를 변경하거나, 템플릿을 편집하여 AI가 생성하는 내용을 수정할 수 있습니다.

처음부터 스키마 생성하기

완전히 새로운 워크플로우를 위해:

# 대화형 모드
openspec schema init research-first

# 비대화형 모드
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

스키마 구조

스키마는 워크플로우의 아티팩트와它们 간의 의존 관계를 정의합니다:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

주요 필드:

필드	용도
id	고유 식별자 (명령 및 규칙에서 사용됨)
generates	출력 파일 이름 (specs/**/*.md와 같은 글롭 지원)
template	templates/ 디렉토리 내의 템플릿 파일
instruction	이 아티팩트 생성을 위한 AI 지침
requires	의존성 — 먼저 존재해야 하는 아티팩트 목록

아티팩트는 원하는 작성 순서대로 나열합니다. requires는 무엇을 만들 수 있는지 결정하며, artifacts: 목록의 순서는 여러 아티팩트가 동시에 준비되었을 때 어떤 것이 먼저 생성될지 결정합니다.

템플릿

템플릿은 AI를 안내하는 마크다운 파일입니다. 해당 아티팩트를 생성할 때 프롬프트에 주입됩니다.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

템플릿에는 다음을 포함할 수 있습니다:

• AI가 채워야 할 섹션 헤더
• AI를 위한 가이드라인이 포함된 HTML 주석
• 예상 구조를 보여주는 예시 형식

스키마 검증하기

커스텀 스키마를 사용하기 전에 검증을 수행합니다:

openspec schema validate my-workflow

이 명령은 다음 사항을 확인합니다:

• schema.yaml 구문이 올바른지
• 참조된 모든 템플릿이 존재하는지
• 순환 의존 관계가 없는지
• 아티팩트 ID가 유효한지

커스텀 스키마 사용하기

생성된 후 다음과 같이 스키마를 사용할 수 있습니다:

# 명령어에서 지정
openspec new change feature --schema my-workflow

# 또는 config.yaml에서 기본값으로 설정
schema: my-workflow

스키마 해결 과정 디버깅하기

어떤 스키마가 사용되는지 확실하지 않다면 다음 명령으로 확인할 수 있습니다:

# 특정 스키마의 경로 확인
openspec schema which my-workflow

# 사용 가능한 모든 스키마 목록 표시
openspec schema which --all

출력은 스키마가 프로젝트, 사용자 디렉토리, 또는 패키지 중 어디에서 로드되었는지 보여줍니다:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

참고: OpenSpec은 프로젝트 간 공유를 위해 ~/.local/share/openspec/schemas/에 사용자 수준 스키마도 지원합니다. 하지만 코드와 함께 버전 관리되므로 openspec/schemas/의 프로젝트 수준 스키마를 사용하는 것을 권장합니다.

---

예제

빠른 반복 워크플로우

빠른 반복을 위한 최소한의 워크플로우:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

검토 아티팩트 추가하기

기본 스키마를 포크하고 검토 단계를 추가합니다:

openspec schema fork spec-driven with-review

그런 다음 schema.yaml을 편집하여 다음을 추가합니다:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

커뮤니티 스키마

OpenSpec은 독립적인 저장소를 통해 배포되는 커뮤니티 유지 관리 스키마도 지원합니다. 이러한 스키마는 github/spec-kit의 커뮤니티 확장 카탈로그가 spec-kit에서 작동하는 방식과 유사하게, 다른 도구나 시스템과 OpenSpec을 통합하는 의견 기반 워크플로우를 제공합니다.

커뮤니티 스키마는 OpenSpec 코어에 번들로 제공되지 않으며, 각자의 저장소와 릴리스 주기를 가집니다. 하나를 사용하려면 스키마 번들을 프로젝트의 openspec/schemas/<schema-name>/ 디렉토리로 복사하면 됩니다(각 저장소의 README에 설치 방법이 있음).

스키마	유지 관리자	저장소	설명
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	구현 전에 변경 의도, 관찰 가능한 동작, 기술 설계, 영구적인 아키텍처 결정을 캡처합니다. 변경 로컬 ADR 검토 매니페스트를 추가하고 자격이 있는 장기 결정을 불변이며 대체 가능한 ADR로 기록합니다.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	OpenSpec의 아티팩트 거버넌스를 obra/superpowers 실행 스킬(브레인스토밍, 계획 작성, 서브 에이전트를 통한 TDD, 코드 검토, 완료)과 통합합니다. Superpowers가 기본적으로 다루지 않는 격차를 메우는 증거 우선 retrospective 아티팩트를 추가합니다.
nanopm	@nmrtn	nmrtn/nanopm	PM 중심 워크플로우. 구현 상류에서 nanopm의 계획 파이프라인(감사 → 전략 → 로드맵 → PRD)을 실행합니다. 제품 계획을 OpenSpec의 명세서 기반 엔지니어링 워크플로우로 연결합니다. .nanopm/이 있으면 아티팩트를 읽습니다 — 제안서는 감사를 소스로 하고, 설계는 전략을 소스로 하며, 작업 목록은 PRD 분해를 소스로 합니다.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	기능 수준의 엔드투엔드 테스트 실행서. 각 기능에는 불변 명세서, 불변 작업 목록 템플릿, 실행당 하나의 타임스탬프 기록이 있습니다. 어설션은 관찰 가능한 동작만 포함합니다(HTTP 상태, 응답 본문, 영구 상태 — 로그 부분 문자열은 제외); 각 실행은 시작/종료 UTC, 지속 시간, 그리고 최선의 추정 LLM 토큰 소비량을 기록합니다.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	TDD 규율과 적대적 검토 단계를 갖춘 명세서 기반 워크플로우. 흐름: proposal → specs → design → review → test-plan → tasks → apply → verify. review는 새 컨텍스트의 읽기 전용 검토자(사용 가능한 경우 두 번째 모델)가 작성하며, test-plan, tasks, apply를 차단하라고 에이전트에 알리는 VERDICT: 줄을 출력합니다. OpenSpec은 아티팩트의 존재 여부만 확인하므로 CI 또는 훅을 사용하여 차단을 강제합니다. test-plan은 모든 명세서 시나리오를 명명된 테스트에 매핑하며, verify가 감사하는 빨간색/초록색 원장을 이중으로 사용합니다.

커뮤니티 스키마를 기여하고 싶으신가요? 저장소 링크와 함께 이슈를 열거나, 이 표에 행을 추가하는 PR을 제출하세요.

---

관련 항목

• CLI 참조: 스키마 명령 - 전체 명령 문서