OpenSpec 쓰는 법

OpenSpec(Fission-AI/OpenSpec)은 코딩 에이전트와 스펙(명세)을 먼저 맞춰 두고 구현하게 하는 오픈소스 스펙 주도 개발(SDD, Spec-Driven Development) 프레임워크다. MIT 라이선스, npm 패키지 @fission-ai/openspec 최신 v1.13.2, GitHub 기준 약 7.0만 스타(작성 시점). 공식 사이트 openspec.dev.

이 글은 “OpenSpec 쓰는 법”만 따라간다. 설치 → openspec init → 채팅에서 /opsx:explore·/opsx:propose·/opsx:apply·/opsx:archive 흐름까지, README·설치 문서·지원 도구 문서만 근거로 적는다.

핵심 요약 (TL;DR)

• 무엇인가: 채팅 히스토리만으로 요구사항이 흩어지지 않게, 마크다운 스펙·제안·작업 체크리스트를 폴더로 남겨 AI와 사람 모두 같은 계획을 보게 하는 CLI + 슬래시 커맨드 레이어.
• 요구사항: Node.js 20.19.0 이상. Homebrew로 설치하면 Node도 의존성으로 같이 깔린다.
• 버전(작성 시점): npm @fission-ai/openspec@latest → 1.13.2. 라이선스 MIT.
• 한 줄 경로: npm i -g @fission-ai/openspec@latest(또는 brew install openspec) → 프로젝트에서 openspec init → AI 채팅에서 /opsx:propose … → /opsx:apply → /opsx:archive.
• 폴더: openspec/specs/(현재 동작의 소스 오브 트루스), openspec/changes/<이름>/(진행 중 변경: proposal·specs·design·tasks).

할 수 있는 일

먼저 용어만 짧게 풀어 둔다.

• 스펙 주도 개발(SDD): 코드를 쓰기 전에 “무엇을 만들지”를 스펙(요구사항·시나리오)으로 먼저 합의하는 방식. OpenSpec은 그 스펙을 가벼운 마크다운으로 남긴다.
• 코딩 에이전트: Cursor, Claude Code, Codex, GitHub Copilot 등 에디터·터미널에서 코드를 쓰고 명령을 실행하는 AI 조수.
• 슬래시 커맨드: AI 채팅창에 /opsx:propose처럼 쳐 넣는 단축 명령. 터미널의 openspec …과 장소가 다르다.
• 브라운필드(brownfield): 이미 코드가 있는 기존 프로젝트. OpenSpec은 그린필드뿐 아니라 기존 레포에도 맞춘다고 README가 명시한다.
• 아티팩트: 한 변경 폴더 안의 proposal.md·specs/·design.md·tasks.md 같은 산출물.

공식 README·docs 기준으로 바로 할 수 있는 일은 대략 이렇다.

• 아이디어 탐색: /opsx:explore로 코드베이스를 읽고 옵션을 저울질한 뒤 계획을 다듬는다(아직 파일 안 써도 됨).
• 변경 제안 한 번에 초안: /opsx:propose add-dark-mode처럼 치면 openspec/changes/…/ 아래에 proposal·specs·design·tasks가 생긴다.
• 체크리스트대로 구현: /opsx:apply가 tasks.md를 따라가며 구현한다.
• 완료 후 아카이브: /opsx:archive가 델타 스펙을 본편 openspec/specs/에 머지하고 폴더를 changes/archive/로 옮긴다.
• 대시보드·검증 CLI: openspec list, openspec show, openspec validate, openspec view.
• 30개 이상 도구 연동: Cursor·Claude Code·Codex·Copilot 등. 도구마다 커맨드 철자가 조금 다르다(아래 표).
• (베타) Stores: 계획을 별도 레포에 두고 여러 코드 레포·팀이 공유하는 모드. 팀용 확장.

필요한 것

링크: GitHub · openspec.dev · Getting Started · Installation · Supported Tools · npm.

설치 / 초기화

1) CLI 설치

# npm (Node 20.19.0+ 필요)
npm install -g @fission-ai/openspec@latest

# 또는 Homebrew (Node를 의존성으로 같이 설치)
brew install openspec

# 확인
openspec --version

pnpm·yarn·bun·Nix·Deno 경로도 설치 문서에 있다. Bun으로 패키지만 깔아도 실행은 결국 Node가 PATH에 있어야 한다(공식 경고).

2) 프로젝트에서 init

cd your-project
openspec init

openspec init이 쓰는 도구를 고르고, 해당 에이전트용 스킬·커맨드 파일을 심는다. 비대화형으로는 예를 들어:

openspec init --tools cursor,claude
# 또는 전부
openspec init --tools all

원하면 AI 채팅에 설치 프롬프트를 붙여 넣을 수도 있다. 설치 문서의 “Install with your AI assistant” 절: install.md를 가져와 따르라는 한 줄.

3) 첫 워크플로 (채팅)

터미널 두 줄(npm i -g …, openspec init) 다음은 AI 채팅이다.

# (선택) 아직 뭘 만들지 모를 때
/opsx:explore

# 이미 알고 있을 때 — 예시
/opsx:propose add-dark-mode

# 스펙 리뷰 후 구현
/opsx:apply

# 끝나면 아카이브
/opsx:archive

성공 시 대략 이런 폴더가 생긴다.

openspec/
├── specs/                 # 현재 시스템 동작의 소스 오브 트루스
├── changes/
│   └── add-dark-mode/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/         # 델타(추가·수정·삭제 요구사항)
└── config.yaml            # 선택

스펙은 특수 문법이 아니라 일반 마크다운이다. 요구사항 + WHEN/THEN 시나리오 형태. AI가 초안을 쓰고, 사람은 코드 전에 계획을 리뷰한다.

4) 업데이트

npm install -g @fission-ai/openspec@latest   # 또는 brew upgrade openspec
openspec update                              # 프로젝트마다 스킬·커맨드 갱신

막히는 지점 / 표

도구별 호출 이름(핵심만) — 문서는 /opsx:propose를 정식 이름으로 쓰고, 실제 타이핑은 도구마다 다르다.

기본(core) 프로필 커맨드: propose, explore, apply, update, sync, archive. 확장 프로필에 new, continue, ff, verify, bulk-archive, onboard가 있다.

텔레메트리: 익명 사용 통계(명령 이름·버전만). 끄려면 openspec config set telemetry.enabled false 또는 OPENSPEC_TELEMETRY=0 / DO_NOT_TRACK=1.

마치며

OpenSpec은 “AI한테 대충 말해 두고 결과만 보는” 대신, 스펙을 먼저 합의하고 같은 체크리스트로 구현·아카이브까지 이어 주는 얇은 레이어다. Node 20.19+만 있으면 npm i -g @fission-ai/openspec@latest → openspec init → 채팅에서 /opsx:propose(또는 도구별 철자)로 바로 시작할 수 있다. 자세한 시나리오·브라운필드 도입·Stores 베타는 공식 docs를 이어서 보면 된다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.