프로젝트 설정

프로젝트에 OpenSpec 추가하기: init 실행 후 작성된 내용 확인하고 조정하기.

OpenSpec을 저장할 위치 선택

• 저장소 내 (기본값): 스펙과 변경사항이 해당 코드 옆에 위치하며 함께 버전 관리됩니다. 이 페이지의 나머지 부분은 이 방식을 따릅니다.
• 스토어: 여러 저장소에서 공유하는 별도의 계획 저장소로, 다중 저장소 구성이나 저장소에서 계획을 완전히 분리하려는 경우에 사용합니다. 스토어 (베타)에서 언제 유용한지와 설정 방법을 다룹니다.

프로젝트 초기화

CLI가 설치되어 있다면 (설치), 프로젝트 루트에서 init을 실행하세요. 터미널에서:

cd <your-project>
openspec init

Init은 사용 중인 AI 도구를 묻고, 선택한 도구에 맞는 워크플로우 파일을 작성한 후 결과를 보고합니다:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

새로운 명령을 적용하려면 IDE를 다시 시작하세요.

Init을 다시 실행해도 안전합니다:

• 이미 설정한 도구는 Created 대신 Refreshed를 출력합니다.
• 새 도구를 선택한 상태에서 init을 다시 실행하면 해당 도구가 추가됩니다.
• --tools 플래그를 사용하면 선택기를 건너뜁니다 (CLI 참조).

기존 project.md 마이그레이션

Init은 레거시 openspec/project.md를 config.yaml에 복사하지 않습니다. 파일을 유지하면서 AI 기반 마이그레이션 요청을 출력합니다.

AI 채팅에서:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

config.yaml을 검토한 후, 준비가 되면 project.md를 삭제하세요.

Init이 설치하는 것

Init을 실행하면 프로젝트에 두 가지를 생성합니다:

• 저장소 루트에 openspec/ 폴더
• AI 도구 폴더(.agents/, .claude/ 등)에 추가되는 워크플로우 파일 (스킬 및 명령)

소스 코드와 마찬가지로 모두 커밋하세요. Init은 저장소의 다른 부분을 변경하지 않습니다 (이전 OpenSpec 버전의 잔여 파일을 발견하면 정리 전에 확인을 요청합니다).

openspec/ 폴더

모든 OpenSpec 아티팩트가 프로젝트 루트의 이 폴더에 위치합니다. 다음과 같은 구조입니다:

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

프로젝트 구성에서 config.yaml을 다룹니다.

워크플로우 파일 (스킬 및 명령)

이것들은 OpenSpec 워크플로우로, 작업 시 사용하게 될 액션입니다. 대부분의 도구가 사용하는 공유 .agents/ 폴더에 설치된 스킬 형태로 나타내면 다음과 같습니다:

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

이것은 기본 세트와 두 개의 선택적 워크플로우입니다. 프로필에서 전체 12개를 확인할 수 있습니다.

기본적으로 각 워크플로우는 두 가지 형태로 설치됩니다:

• 스킬 (openspec-apply-change): 작업을 요청하면 에이전트가 스스로 불러오는 지침입니다.
• 명령 (/opsx:apply in Claude Code): 동일한 워크플로우의 짧은 이름으로 된 입력 진입점입니다.

두 형태는 기능적으로 동일합니다. 워크플로우의 스킬과 명령은 동일한 지침을 담고 있습니다.

두 가지 형태가 있는 이유: 명령이 먼저 등장했고, 각 도구마다 고유한 방식으로 표현됩니다. 스킬은 도구 간 공유되는 최신 표준이지만 모든 도구가 스킬을 직접 호출할 수 있는 것은 아니므로, 명령은 해당 도구의 진입점으로 유지됩니다.

일부 도구는 스킬 형태로만 설치됩니다. 도구가 스킬을 직접 실행하는 경우, init은 명령을 건너뛰고 그 내용을 알립니다 (Commands skipped for: codex (uses skills)).

당사는 스킬을 선호하며 명령을 결국 폐지할 계획입니다.

설치 대상 변경

대화형 선택기는 전달 형태와 워크플로우 세트를 변경합니다 (프로필). 터미널에서:

openspec config profile

다음은 스킬만 사용하도록 전환하는 예입니다:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

예라고 답하면 현재 프로젝트에 즉시 적용됩니다. 다른 프로젝트는 다음 openspec update 시 적용됩니다. 이 설정은 머신별로 전역적입니다.

Claude Code에 워크플로우가 표시되지 않는 경우

Claude Code는 전달 설정에 따라 다음 프로젝트 경로 중 하나 또는 둘 모두에서 OpenSpec 워크플로우를 불러옵니다:

• Skills: .claude/skills/openspec-*/SKILL.md
• Commands: .claude/commands/opsx/<id>.md

파일이 없는 경우 프로젝트를 새로 고치세요. 터미널에서:

openspec update

명령 파일이 존재하지만 /opsx:에 OpenSpec 명령이 표시되지 않으면 Claude Code를 업데이트하고 다시 시작하세요. 명령이 여전히 로드되지 않으면 스킬도 활성화하세요. 터미널에서:

openspec config set delivery both
openspec update

Claude Code를 다시 시작한 후 채팅에서 /openspec-propose를 실행하세요. 일부 워크플로우만 누락된 경우 프로필을 변경하세요.

설정이 완료되었습니다. 빠른 시작에서 첫 번째 변경사항을 진행할 수 있습니다.