OpenSpec 빠른 시작: 설치, 워크플로우, 그리고 흔한 함정

40페이지짜리 PRD가 아닌, 증분(delta)으로 표기된 스펙.

Page content

OpenSpec은 Fission AI에서 만든 무료 오픈소스 CLI로, 코드를 작성하기 전에 사용자와 코딩 에이전트가 평범한 마크다운으로 변경사항에 대해 합의할 수 있게 해줍니다. 보다 무거운 스펙 중심 프레임워크의 단계별 의식 없이 말이죠.

스펙 주도 개발(Spec-Driven Development)을 시도하는 대부분의 팀이 동일한 트레이드오프에서 멈춰섭니다. 에이전트가 추측하도록 막을 만큼 충분한 프로세스를 갖되, 50줄짜리 버그 수정에 제안서가 필요할 정도로 복잡한 스캐폴딩을 만들지 않는 것입니다. OpenSpec의 답은 ‘먼저 전체 시스템을 문서화하려는’ 본능을 완전히 무시하고, 실제로 변경이 영향을 미치는 부분에 대해서만 스펙을 작성하는 것입니다. 이때 매번 전체 재작성 대신 ADDED, MODIFIED, REMOVED 증분(Delta)을 사용합니다.

AI 코딩 어시스턴트와 함께한 OpenSpec 스펙 주도 개발 워크플로우

이러한 변경 중심의 설계는 OpenSpec가 GitHub Spec Kit, Kiro, Superpowers와 함께 SDD 도구 카테고리 비교에서 자주 언급되는 이유이기도 합니다. 800줄에 달하는 계획 단계 없이 검토 가능한 스펙을 원하는 팀에서 보통 선택하는 도구이기 때문입니다. 이 가이드에서는 CLI 설치, 일상적으로 사용하는 4개 명령 워크플로우, 디스크에서 변경사항이 어떻게 보이는지, 그리고 Reddit과 OpenSpec의 자체 이슈 트래커에서 가장 자주 제기되는 질문과 불만사항들을 다루고 있습니다.

OpenSpec란?

OpenSpec은 자신의 철학을 4줄로 표현합니다. 경직되지 않고 유동적이며, 워터폴이 아닌 반복적이며, 복잡하지 않고 쉬우며, 그린필드뿐 아니라 브라운필드용으로 설계되었다는 것입니다. 실제로는 잠금된 단계가 없습니다. 도구 중립적 SDD 워크플로우에서 설명하듯 지정-계획-구현 순서를 엄격히 따를 필요가 없으며, 변경 단계의 어느 시점에서든 제안서, 스펙, 또는 작업 목록을 편집할 수 있습니다.

OpenSpec의 변경은 자체 폴더 내에서 최대 4개의 마크다운 산출물을 생성합니다.

산출물	목적
`proposal.md`	변경이 왜 존재하는지와 무엇을 변경하는지, 평이한 언어로 설명
`specs/`	증분 요구사항 및 시나리오 – 이 변경에 대한 테스트 가능한 스펙
`design.md`	기술적 접근 방식(선택 사항), 필요할 때만 작성
`tasks.md`	에이전트가 처리하는 구현 체크리스트

변경이 구현되어 아카이브되면, 그 증분 스펙은 openspec/specs/에 병합됩니다. 이는 시스템의 현재 상태를 나타내는 지속적이고 최신의 설명이 되며, 스펙 주도 개발이란?에서 다룬 “스펙을 진실의 원천으로 삼는다"는 동일한 개념입니다. 단, 한 번에 모든 것을 작성하는 대신 변경사항 단위로 범위를 좁혀 적용한다는 차이가 있습니다.

OpenSpec 설치

OpenSpec은 Node.js CLI이므로, 마신에는 Node 20.19.0 이상이 필요합니다.

node --version

npm을 사용하여 CLI를 전역으로 설치한 후, PATH에是否正确하게 있는지 확인하십시오:

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

npm보다 설정에 더 잘 맞는 경우 Deno, pnpm, yarn, bun, nix도 설치 경로로 지원됩니다. 설치 후 프로젝트 내에서 초기화하십시오:

cd your-project
openspec init

openspec init은 사용 중인 AI 도구를 묻고, 그에 해당하는 스킬 및 명령 파일을 작성합니다. OpenSpec는 Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro, OpenCode를 포함한 30개 이상의 어시스턴트를 지원합니다. CI나 스크립트 설정의 경우, 선택자(picker)를 완전히 건너뛰고 다음을 사용하세요:

openspec init --tools claude,cursor   # 특정 도구 설정
openspec init --tools all             # 지원되는 모든 도구
openspec init --tools none            # openspec/ 구조만, 도구 파일 없음

이후에 새로 작성된 스킬과 명령을 인식하도록 IDE를 재시작하십시오. 어시스턴트가 설치를 대신 처리하길 원한다면, OpenSpec는 Claude Code 또는 다른 에이전트에 붙여넣을 수 있는 설정 프롬프트를 제공합니다. 이 프롬프트는 설치를 실행하고 openspec init을 실행한 후 구성된 내용을 보고합니다.

핵심 워크플로우: 탐색, 제안, 적용, 아카이브

첫날 거의 모든 사람들을 혼란에 빠뜨리는 유일한 한 가지입니다. openspec 명령은 터미널에서 실행되지만, /opsx: 명령은 AI 어시스턴트의 채팅 창에서 실행됩니다. 입력해야 할 별도의 “대화 모드"는 없습니다 – 채팅에서 슬래시 명령을 입력하는 것이 시작 방법입니다.

flowchart LR A["/opsx:explore (선택 사항)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|스펙 병합| E["openspec/specs/"]

**/opsx:explore**는 부담없는 사고 파트너입니다. 코드베이스의 관련 부분을 읽고, 옵션을 나열하며, 디스크에 아무것도 기록하기 전에 계획을 형성합니다 – 성급한 에이전트가 확신을 갖고 잘못된 것을 만드는 것을 막아주기 때문에 습관으로 만드는 것이 특히 가치 있습니다.
**/opsx:propose <name>**은 openspec/changes/<name>/을 생성하고 제안서, 증분 스펙, 선택적 디자인, 작업 목록을 한 단계에서 초안으로 작성합니다. 구현이 시작되기 전에 이 계획에 대한 검토를 여기서 수행합니다.
**/opsx:apply**는 작업 목록을 따라 진행하며, 처리됨에 따라 항목을 체크합니다. 진도가 채팅 히스토리가 아닌 파일에 기록되므로, 컨텍스트 윈도우를 지우거나 새 세션을 시작해도 /opsx:apply가 멈춘 지점에서 정확히 이어서 진행할 수 있습니다.
**/opsx:archive**은 완료된 변경을 openspec/changes/archive/YYYY-MM-DD-<name>/로 이동하고, 그 증분 스펙을 정통 openspec/specs/ 트리로 병합합니다.

기본 core 프로필은 정확히 이 4개의 명령과 update, sync를 설치합니다. 확장 프로필은 한 번에 모든 것이 아니라 하나씩 산출물을 생성하기를 원하는 팀을 위해 new, continue, ff, verify, bulk-archive, onboard를 추가합니다. openspec config profile 후 openspec update를 실행하여 전환할 수 있습니다.

각 도구는 커스텀 인스트럭션을 로드하는 방식에 따라 동일한 명령을 다르게 표기합니다. Claude Code에서는 /opsx:propose, Cursor와 GitHub Copilot에서는 /opsx-propose, Amazon Q에서는 @opsx-propose, Codex에서는 $openspec-propose입니다. openspec init은 선택한 도구에 대한 정확한 형태를 출력하므로, “명령을 입력했는데 아무 일도 일어나지 않는다"는 문제에 대한 가장 빠른 해결책은 추측하는 것이 아니라 출력된 힌트를 다시 읽는 것입니다.

디스크에서 변경사항이 어떻게 보이는지

openspec/changes/add-dark-mode/ 하위의 변경 폴더는 일반적으로 제안서, 증분 스펙, 작업 목록을 다음과 같이 포함합니다:

## 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

이 ADDED/MODIFIED/REMOVED 증분 형식은 OpenSpec가 한 필드 변경에 대해 전체 스펙 파일을 다시 작성하지 않도록 하는 메커니즘입니다. 또한 OpenSpec가 명시적으로 브라운필드 우선이지 그린필드 우선이 아닌 이유이기도 합니다. 가치를 얻기 전에 전체 애플리케이션을 문서화할 필요가 없으며, 각 실제 변경이 영향을 미치는 조각만 문서화하면 openspec/specs/는 수개월간의 정상적인 작업에 걸쳐 자연스럽게 채워집니다.

터미널을 벗어나지 않고 해당 상태를 확인하는 데 유용한 CLI 명령:

openspec list                 # 활성 변경사항
openspec show add-dark-mode   # 변경사항의 산출물 보기
openspec validate --all       # 프로젝트 전체 스펙 형식 검사
openspec view                 # 대화형 대시보드

전체 openspec/ 폴더를 git에 커밋하십시오. 활성 변경사항과 아카이브는 시스템이 무엇을 하는지, 왜 변경되었는지에 대한 지속적이고 버전 관리되는 기록이 되는 것을 목적으로 합니다. 병합 후 삭제하는 임시 노트가 아니어야 합니다.

기존 코드베이스에 OpenSpec 도입하기

실제 프로젝트에서 OpenSpec를 평가하는 팀들의 가장 일반적인 우려는 “제 앱은 80,000줄인데, 전부 스펙을 먼저 작성해야 하나요?“라는 내용입니다. 아닙니다. OpenSpec의 자체 가이드라인은 이에 대해 명백합니다. 이번 주에 이미 만들기로 결정한 작고 실제적인 것을 선택하고, 곧 건드릴 영역에 대해 /opsx:explore를 실행하여 에이전트가 실제로 어떻게 동작하는지 먼저 매핑하도록 한 다음, 해당 조각에만 범위가 제한된 변경에 대해 /opsx:propose를 실행하십시오.

이미 Notion이나 Confluence에 PRD, SRS 문서, 디자인 문서가 있다면, 그것들을 대량으로 스펙으로 변환해야 할 대상이 아니라 탐색을 위한 소스 자료로 취급하십시오. 관련 섹션을 /opsx:explore 세션에 붙여넣고 에이전트가そこから 집중된 증분을 형성하도록 하십시오; 40페이지짜리 PRD를 한 번에 기계적으로 변환하면 6개월 후 아무도 신뢰하지 않는 스펙이 탄생하기 쉽습니다. 실제 변경으로 바로 뛰어들기보다 가이드된 첫 실행을 원한다면, 확장된 /opsx:onboard 명령은 코드베이스에서 작고 안전한 개선을 찾아 전체 루프를 그것에 대해 시연해줍니다.

일반적인 질문과 문제

이것들은 OpenSpec의 Discord, GitHub 이슈, 그리고 r/cursor, r/RooCode, r/opencodeCLI 같은 서브레딧의 Reddit 스레드에서 반복적으로 제기되는 문제들입니다.

“슬래시 명령을 입력했는데 아무 일도 일어나지 않았습니다.” 거의 항상 다음 중 하나입니다: 어시스턴트의 채팅 창이 아닌 터미널에서 입력했거나, openspec init 실행 후 IDE를 재시작하지 않았거나, CLI 버전이 너무 오래되어 openspec update가 모든 것이 최신이라고 보고하면서 더 새로운 워크플로우 파일을 작성하지 않은 것입니다. openspec update를 실행하고 IDE를 재시작한 후, 스킬 폴더가 존재하는지 확인하십시오(Claude Code의 경우 .claude/skills/openspec-*, 또는 지원 도구 목록에 있는 도구의 동등한 폴더).

“AI가 필요한 것보다 훨씬 더 많은 스펙을 생성합니다.” 이는 긴 리뷰 글에서 가장 자주 인용되는 불만입니다. 에이전트가 30분짜리 기능을 800줄짜리 스펙으로 바꿀 수 있습니다. OpenSpec는 규율을 강제하기 위해 모든 요청에 주입되는 context: 필드를 50KB로 제한하지만, 증분 스펙 자체에는 경계가 없으므로, 생성된 스펙을 실제로 부하를 지지하는 부분으로 줄이는 것은 도구가 대신 해주는 것이 아니라 스스로 유지해야 하는 습관입니다.

“두 변경이 동일한 요구사항을 건드렸는데, 하나가 다른 하나의 시나리오를 조용히 제거했습니다.” 이는 실제로 문서화된 엣지 케이스입니다: 아카이빙은 요구사항 이름을 키로 한 전체 블록 치환으로 MODIFIED 증분을 적용하므로, 진행 중인 두 변경이 모두 동일한 요구사항을 수정하면 두 번째를 아카이브할 때 첫 번째의 시나리오가 경고 없이 덮어쓰기되었습니다. 현재 버전은 변경의 스펙을 먼저 새로고침하라고 알려주는 드리프트 체크를 추가하여 아카이브를 중단합니다 – 하지만 동일한 영역에 여러 변경을 병렬로 실행할 경우, 이 실패 모드가 존재한다는 것을 아는 것이 여전히 가치가 있습니다.

“실제로 어떤 AI 모델을 사용해야 하나요?” OpenSpec의 자체 문서에서는 계획과 구현 모두에 고이론(reasoning) 모델 사용을 권장하며 – 특히 Opus급과 Codex급 모델이 언급됩니다 – 구현 전에 컨텍스트 윈도우를 지우는 것도 권장합니다. 깨끗한 컨텍스트가 길고 축적된 세션보다 측정 가능하게 더 나은 결과를 produzir하기 때문입니다.

“이것은 Spec Kit, Kiro, Superpowers, 또는 BMAD와 어떻게 다른가요?” 이는 Reddit에서 가장 빈번한 질문이며, 정직한 답은 “프로세스의 무게"입니다. OpenSpec의 자체 README는 비교를 직접적으로 제시합니다: Spec Kit은 철저히 하지만 무겁고, 마크다운이 더 많고 단계 게이트가 경직되어 있습니다; Kiro는 강력하지만 AWS의 IDE와 Claude 모델에 고정됩니다; OpenSpec는 그 앞단계 구조의 일부를 포기하고 자유롭게 반복할 수 있으며 이미 열려 있는 어떤 어시스턴트와도 작동할 수 있는 능력으로 교환합니다. Spec Kit, Kiro, Claude Code 스킬, BMAD-METHOD, Superpowers와의 전체 분해 분석 및 SDD 도구 비교에 대한 전문 내용은 해당 아티클을 참조하세요.

“AI는 방금 작성한 스펙을 실제로 따르나요?” 항상은 아니며, 이는 OpenSpec만의 문제가 아니라 SDD 도구 전반에 걸쳐 문서화된 문제입니다 – 큰 컨텍스트 윈도우가 에이전트가 그 모든 부분에 균등하게 주의를 기울인다는 뜻은 아니기 때문입니다. /opsx:verify 명령은 자신의 스펙과 모순되는 생성 코드를 잡기 위해 특별히 존재하며, 신뢰하여 구현을 맹신하기보다 비자명(non-trivial)한 모든 것에 대해 실행하는 가치가 있습니다.

“한 줄 수정에 이것이 필요합니까?” 아닙니다. OpenSpec의 자체 FAQ도 그렇게 말합니다: 합의가 중요한 곳에서 사용하십시오, 이는 대부분의 비자명하고 다중 파일 작업을 의미하며, 오타 수정이나 일주일 내로 삭제할 예정인 일회용 프로토타입에는 건너뛰십시오.

OpenSpec가 적합한 경우와 적합하지 않은 경우

적합한 경우:

시스템 전체를 사전에 문서화하지 않고도 검토 가능한 스펙을 원하는 브라운필드 코드베이스.
Spec Kit보다 가벼운 의식을 원하지만 코드 전에 문서화된 계획은 확보하고 싶은 솔로 개발자 및 소규모 팀.
여러 파일, 스키마 변경, 또는 주니어 엔지니어가 짧은 디자인 문서가 합리적으로 원할 만한 작업.
이미 풀 리퀘스트에서 계획을 검토하는 것을 지향하는 팀 – 증분 스펙은 변경된 내용만 설명하므로 깨끗하게 디프(diff)됩니다.

덜 적합한 경우:

제안-검토 단계가 절약하는 것보다 비용이 더 드는 한 줄 버그 수정 및 일회용 프로토타입.
Spec Kit의 더 무겁고 지시적인 구조나 Kiro와 같은 AWS 네이티브, IDE 통합 경험이 필요한 팀 – 각 도구가 어디에서 승리를 거두는지 확인하려면 도구 비교 내 의사결정 프레임워크를 참조하세요.
오늘날의 크로스 레포 기능, 단 OpenSpec의 베타 stores 기능을 시도할 의향이 있는 경우를 제외합니다. 이 기능은 계획을 자체의 공유 저장소로 이동시켜 여러 코드베이스와 에이전트가 동일한 계획을 읽을 수 있게 합니다.
특정 기능이 스펙을 받을 가치가 있는지에 대해 아직 결정 중인 모든 사람 – OpenSpec는 이미 구조가 오버헤드를 가치가 있다고 결정된 후에만 도움이 되므로, 먼저 스펙 주도 개발 vs 바이브 코딩을 읽어보십시오.

결론

OpenSpec의 배팅은, 스펙 주도 개발의 대부분의 고통이 근본적인 아이디어인 코드 존재 전에 계획에 합의하는 것이 아니라, 의식(ceremony)에서 온다는 것입니다. 전체 재작성 대신 증분, 잠금된 단계 없음, 브라운필드 우선 워크플로우는 처음부터 만들지 않은 코드베이스에 도입할 때 Spec Kit이나 Kiro보다 눈에 띄게 가볍게 만듭니다. 트레이드오프도 실제로 존재합니다 – 규율 없이 스펙 부피 증대는 진정한 리스크이며, 하나의 요구사항에 대한 동시 변경을 둘러싼 충돌 처리는 여전히 성숙하고 있으며, 생태계는 GitHub의 자체 툴링보다 젊은 편입니다. 하나의 실제 프로젝트에 설치하고, explore-propose-apply-archive를 끝까지 작은 변경으로 실행해본 후, 더 가벼운 의식이 실제 업무량에 대해 그 가치를 증명하는지 결정하십시오.

유용한 링크

OpenSpec 저장소 – 소스, 문서, CLI 패키지
OpenSpec 문서 홈 – 시작하기, 개념, FAQ, 문제 해결
GitHub Spec Kit vs Kiro vs Claude Code SDD 워크플로우 – 전체 도구 비교 및 의사결정 프레임워크, OpenSpec 포함
Superpowers 퀵스타트: 설치, 워크플로우, 그리고 체험 – OpenSpec의 가벼운 터치 워크플로우 대안으로서의 강제 스킬
요구사항부터 코드까지의 스펙 주도 개발 워크플로우 – OpenSpec가 더 유동적으로 구현하는 도구 중립적 5단계 프로세스
스펙 주도 개발이란? 단일 진실 공급원으로서의 스펙 – 핵심 SDD 개념 및 용어
스펙 주도 개발 vs 바이브 코딩: 워터폴? – 기능이 스펙을 받을 가치가 있는지에 대한 결정