OpenSpec 사용법: 설치, 핵심 개념, 워크플로

OpenSpec은 가벼운 스펙 기반 개발(Spec-Driven Development) 프레임워크입니다. 사용자와 AI 코딩 어시스턴트 사이에 “합의” 계층을 하나 더해, 무엇을 만들지 먼저 글로 적고 계획을 검토한 뒤에 코드를 쓰게 합니다. 요구 사항이 채팅 기록에만 남는 일을 막아 줍니다. MIT 라이선스의 오픈 소스이며 30개가 넘는 AI 코딩 도구를 지원하고, HagiCode 자체의 워크플로도 이것을 기반으로 합니다. 이 문서는 설치와 첫 번째 전체 흐름까지의 가장 짧은 경로이며, 전체 가이드는 별도 사이트에서 관리합니다.

핵심 개념

OpenSpec은 다섯 가지 아이디어로 이루어집니다.

스펙(specs)이 진실의 원천입니다. 시스템이 지금 어떻게 동작하는지 기술하며 openspec/specs/에 영역별로 정리되고, 요구 사항과 시나리오로 구성됩니다.
변경(change)은 작업 단위 하나입니다. 동작을 추가, 수정, 삭제하려면 openspec/changes/ 아래에 폴더를 만들어 그 작업의 제안, 설계, 작업 목록, 스펙 수정을 한곳에 모읍니다.
델타 스펙은 바뀌는 부분만 기술합니다. 변경 안에서 전체 스펙을 다시 쓰지 않고 ADDED, MODIFIED, REMOVED를 적습니다. 그래서 기존 시스템을 고치는 데 강합니다.
산출물은 서로 이어집니다. proposal(왜) → specs(무엇) → design(어떻게) → tasks(단계) → 구현. 관문이 아니라 도구이므로 언제든 돌아가서 고칠 수 있습니다.
아카이브하면 변경이 진실에 합쳐집니다. 작업이 끝나면 델타 스펙이 메인 스펙에 병합되고 변경 폴더는 날짜와 함께 changes/archive/로 옮겨집니다.

설치

Node.js 20.19.0 이상이 필요합니다(HagiCode의 다른 구성 요소는 24 이상을 권장합니다. Node.js 설치 참고).

npm install -g @fission-ai/openspec@latest
openspec --version

macOS와 Linux에서는 Homebrew로도 설치할 수 있습니다: brew install openspec. pnpm, yarn(1.x), bun으로도 전역 설치가 가능하지만 OpenSpec은 여전히 Node.js 위에서 실행됩니다.

그다음 프로젝트 디렉터리로 이동해 초기화합니다.

cd your-project
openspec init

초기화하면 어떤 AI 도구를 쓰는지 묻고 해당 도구용 스킬 또는 명령 파일을 생성합니다. 질문 없이 진행하려면 openspec init --tools claude,cursor를 쓰세요. 도구 ID 목록은 지원 도구에 있습니다.

첫 번째 전체 흐름

슬래시 명령은 터미널이 아니라 AI 어시스턴트의 채팅창에 입력합니다.

/opsx:explore            # 아직 감이 안 잡혔나요? AI가 코드를 읽고 선택지를 따져 봅니다
/opsx:propose add-dark-mode   # 변경 폴더 생성: proposal, specs, design, tasks
/opsx:apply              # 작업 목록대로 구현
/opsx:archive            # 아카이브. 델타 스펙이 메인 스펙에 병합됨

/opsx:propose는 proposal.md, specs/, design.md, tasks.md가 들어 있는 openspec/changes/add-dark-mode/를 만듭니다. 스펙은 특별한 문법이 없는 일반 Markdown입니다.

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

이 내용은 AI가 작성하고, 사용자는 코드가 쓰이기 전에 계획을 검토합니다. 기본 프로필에는 propose, explore, apply, update, sync, archive가 들어 있습니다. 확장 흐름(new, continue, ff, verify, bulk-archive 등)은 openspec config profile로 선택하고 openspec update로 적용하세요.

어시스턴트마다 명령 이름이 조금 다릅니다

/opsx:propose가 기준 표기입니다. Cursor와 GitHub Copilot에서는 /opsx-propose, Amazon Q에서는 @opsx-propose, Codex에서는 $openspec-propose입니다. openspec init은 선택한 도구에 맞는 표기를 출력해 줍니다.

업그레이드

npm install -g @fission-ai/openspec@latest   # 패키지 업그레이드
openspec update                              # 각 프로젝트의 AI 지침 파일 갱신

Homebrew로 설치했다면 brew upgrade openspec을 쓰세요.

자주 발생하는 문제

openspec: command not found: 전역 npm 디렉터리가 PATH에 없습니다. npm prefix -g를 실행해, macOS와 Linux에서는 그 디렉터리의 bin/을, Windows에서는 그 디렉터리 자체를 PATH에 추가하세요.
“Requires Node.js 20.19.0 or higher”: node --version으로 확인하고 업그레이드하세요.
채팅창에 /opsx:propose가 나타나지 않음: 터미널이 아니라 어시스턴트에 입력했는지 확인하고, openspec update로 파일을 다시 생성한 뒤 어시스턴트를 재시작하세요. Codex처럼 스킬만 지원하는 도구는 $openspec-propose 같은 표기를 써야 합니다.
초기화가 내 도구를 설정하지 않음: openspec init을 다시 실행하거나 --tools를 지정하세요.