OpenSpec 퀵스타트: 설치, 워크플로우, 그리고 흔한 함정

40페이지짜리 PRD가 아닌, 델타(deltas) 형태의 스펙

Page content

OpenSpec은 Fission AI가 제공하는 무료 오픈소스 CLI 도구로, 코드가 작성되기 전에 사용자가 코딩 에이전트와 평범한 마크다운으로 변경 사항에 대해 합의할 수 있게 해줍니다. 무거운 스펙 기반 프레임워크의 단계별 복잡한 절차 없이 이를 가능합니다.

스펙 기반 개발(Spec-Driven Development)을 시도하는 대부분의 팀은 동일한 트레이드오프에서 멈추게 됩니다. 에이전트의 추측을 막기에는 충분한 프로세스가 있어야 하지만, 50줄짜리 버그 수정을 위해 제안 문서를 작성할 정도로 복잡한 스캐폴딩은 피해야 하기 때문입니다. OpenSpec의 답은 ‘전체 시스템을 먼저 문서화하려는’ 본능을 완전히 건너뛰고, ADDED, MODIFIED, REMOVED 델타를 사용해 변경 사항이 실제로 건드리는 부분에 대해서만 스펙을 작성하는 것입니다. 매번 전체를 다시 쓰는 방식은 아닙니다.

AI 코딩 어시스턴트를 활용한 OpenSpec 스펙 기반 개발 워크플로우

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

OpenSpec란 무엇인가?

OpenSpec는 자체 철학을 네 줄로 설명합니다. 비(非)경직형(fluid), 반복적(iterative), 단순(easy), 그린필드뿐 아니라 브라운필드를 위해 설계됨(built for brownfield). 실질적으로 이는 잠금(phase-lock)된 단계가 없다는 뜻입니다. 도구 중립적 SDD 워크플로우가 설명하는 것처럼 ‘규정-계획-구현’의 엄격한 순서를 강요당하는 대신, 변경 사항의 어떤 시점에서든 제안서, 스펙 또는 작업 목록을 수정할 수 있습니다.

OpenSpec에서의 변경 사항은 해당 폴더 내에서 최대 4개의 마크다운 산출물을 생성합니다:

산출물 목적
proposal.md 변경 사항의 존재 이유와 변경 내용을 평이한 언어로 기술
specs/ 델타 요구 사항 및 시나리오 – 해당 변경 사항에 대한 테스트 가능한 스펙
design.md 기술적 접근 방식 (선택 사항), 기술적 접근 방식이 필요한 변경 사항용
tasks.md 에이전트가 수행하는 구현 체크리스트

변경 사항이 구현되고 아카이브되면, 그 델타 스펙은 openspec/specs/로 병합됩니다. 이는 시스템의 현재 상태를 유지 가능한 방식으로 설명하는 문서가 되며, 스펙 기반 개발이란 무엇인가?에서 다루는 “스펙을 진실의 원천(source of truth)으로 사용한다"는 개념과 동일합니다. 다만 한 번에 모두 작성하는 것이 아니라, 변경 사항별로 스코프를 정해서 작성한다는 점이 다릅니다.

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나 스크립트 기반 설정에서 선택자를 건너뛰려면 다음을 사용하세요:

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

설치 후 IDE를 재시작하여 새로 작성된 스킬과 명령을 인식할 수 있게 하세요. 대신 어시스턴트가 설치 전 과정을 수행하게 하려면, OpenSpec가 제공하는 설정 프롬프트를 Claude Code 또는 다른 에이전트에 붙여넣을 수 있습니다. 이 프롬프트는 설치를 실행하고 openspec init을 실행한 후, 어떤 설정이 적용되었는지 보고합니다.

핵심 워크플로우: 탐색(Explore), 제안(Propose), 적용(Apply), 아카이브(Archive)

첫날에 거의 모든 사람이 혼동하는 유일한 부분이 있습니다: openspec 명령어는 터미널에서 실행되지만, /opsx: 명령어는 AI 어시스턴트의 채팅 창에서 실행됩니다. 별도의 ‘대화형 모드’를 들어갈 필요는 없습니다. 채팅 창에서 슬래시 명령을 입력하는 것이 시작 방법입니다.

flowchart LR A["/opsx:explore (선택 사항)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs 병합| E["openspec/specs/"]
  • **/opsx:explore**는 무위험(thinking) 사고 파트너입니다. 코드베이스의 관련 부분을 읽고, 옵션을 제시하며, 디스크에 아무것도 쓰기 전에 계획을 형성합니다. 성급한 에이전트가 자신감 있게 잘못된 것을 만들어내는 것을 막아주기 때문에, 이를 습관으로 형성하는 것이 특히 중요합니다.
  • **/opsx:propose <이름>**은 openspec/changes/<이름>/ 폴더를 생성하고, 제안서, 델타 스펙, 선택적인 디자인, 작업 목록을 한 단계에서 작성합니다. 구현이 시작되기 전에 이 시점에서 계획을 검토합니다.
  • **/opsx:apply**는 작업 목록을 처리하며, 진행하면서 항목을 체크합니다. 진전이 채팅历史记录뿐 아니라 파일에 저장되므로, 컨텍스트 윈도우를 비우거나 새 세션을 시작하여 /opsx:apply가 멈췄던 곳에서 정확하게 이어서 작업할 수 있습니다.
  • **/opsx:archive**는 완료된 변경 사항을 openspec/changes/archive/YYYY-MM-DD-<이름>/로 파일링하고, 그 델타 스펙을 정합적인 openspec/specs/ 트리로 병합합니다.

기본 core 프로파일은 정확히 이 네 가지 명령어와 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 문서 또는 디자인 문서가 있다면, 이를 일괄적으로 스펙으로 변환해야 할 대상이 아니라 탐색(exploration)을 위한 소스 자료로 취급하세요. 관련 섹션을 /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-*, 또는 지원 도구 목록에서 해당 도구의 equivalent).

“AI가 필요 이상으로 많은 스펙을 생성합니다.” 긴 후기에서 가장 자주 인용되는 불만입니다: 에이전트가 30분짜리 기능을 800줄짜리 스펙으로 만들 수 있습니다. OpenSpec는 모든 요청에 주입되는 context: 필드를 의도적으로 50KB로 제한하여 규율을 강제하지만, 델타 스펙 자체에는 하드 제한이 없으므로, 생성된 스펙을 실제로 중요(load-bearing)한 부분으로 줄이는 것은 도구가 대신 해주는 것이 아니라 사용자가 유지해야 하는 습관입니다.

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

“실제로 어떤 AI 모델을 사용해야 하는가?” OpenSpec의 자체 문서에서는 계획과 구현 모두에 고추론(high-reasoning) 모델을 권장합니다 – Opus급과 Codex급 모델이 구체적으로 언급됩니다 – 그리고 구현 전에 컨텍스트 윈도우를 비우는 것이 좋습니다. 깔끔한 컨텍스트는 길고 누적된 세션보다 측정 가능한 더 나은 결과를 낳기 때문입니다.

“Spec Kit, Kiro, Superpowers, BMAD와 어떻게 다른가?” 이는 Reddit에서 가장 빈번한 질문이며, 정직한 답은 “프로세스의 무게(process weight)“입니다. 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에도 명시되어 있습니다: 합의가 중요한 곳, 즉 대부분의 비자명한(non-trivial), 멀티파일 작업에는 사용하고, 오타 수정이나 일주일 안에 삭제할 일회용 프로토타입에는 건너뛰세요.

“에이전트가 이미 거부한 것을 다시 제안하는 것을 어떻게 막는가?” /opsx:archive에는 거절된 변경 사항에 대한 전용 상태가 없으므로, 아이디어가 이미 조사되어 거절되었다는 것을 미래의 제안에 알리는 것이 없습니다. decision.md 패턴과 에이전트가 다시 제안하기 전에 아카이브를 검색하도록 만드는 설정 규칙에 대해서는 OpenSpec 거절된 제안: 의사결정 메모리 컨벤션을 참조하세요.

OpenSpec가 적합한 경우와 아닌 경우

적합한 경우:

  • 시스템 전체를 사전에 문서화하지 않고도 검토 가능한 스펙을 원하는 브라운필드 코드베이스.
  • Spec Kit보다 가벼운 절차를 원하지만 코드 전에 문서화된 계획을 원합니다.
  • 여러 파일, 스키마 변경, 또는 주니어 엔지니어가 짧은 디자인 문서를 원할 만한 작업.
  • 이미 풀 리퀘스트에서 계획을 검토하는 데 commit된 팀 – 델타 스펙은 변경된 내용만 기술하므로 깔끔하게 diff됩니다.

적합하지 않은 경우:

  • 제안-검토 단계가 절약되는 것보다 비용이 더 큰 한 줄짜리 버그 수정과 일회용 프로토타입.
  • Spec Kit의 더 무겁고 지시적인 구조나 Kiro와 같은 AWS 네이티브, IDE 통합 경험이 필요한 팀 – 각 도구가 어떤 상황에서 이기는지 보기 위해 도구 비교의 의사결정 프레임워크를 참조하세요.
  • 현재로서는 크로스-리포 기능, OpenSpec의 베타 stores 기능을 시도할 의향이 있는 경우를 제외하고. 이 기능은 계획 사항을 공유 리포지토리로 이동시켜 여러 코드베이스와 에이전트가 동일한 계획을 읽을 수 있게 합니다.
  • 특정 기능이 아예 스펙을 받을 자격이 있는지 판단하지 못 하는 사람 – OpenSpec는 이미 구조가 오버헤드를 정당화한다고 결정된 후에만 도움이 되므로, 먼저 스펙 기반 개발 vs 바이브 코딩을 읽어보세요.

결론

OpenSpec의 내기는 스펙 기반 개발의 고통 대부분이 근본적인 아이디어가 아니라 의례(ceremony)에서 온다는 것입니다. 전체 재작성 대신 델타, 잠금 없는 단계, 브라운필드 우선 워크플로우는 사용자가 처음부터 빌드하지 않은 코드베이스에서 OpenSpec를 Spec Kit이나 Kiro보다 눈에 띄게 가볍게 도입할 수 있게 합니다. 트레이드오프도 현실적입니다 – 규율 없이는 스펙 부풀림이 진정한 위험이며, 하나의 요구 사항에 대한 동시 변경 사항 충돌 처리는 여전히 성숙해가는 중이고, 이코시스템은 GitHub의 자체 도구보다 젊은 편입니다. 실제 프로젝트 하나에 설치하고, explore-propose-apply-archive를 끝까지 통과하는 작은 변경 사항을 실행한 후, 더 가벼운 의례가 실제 워크로드에 xứng치한지 거기서부터 판단하세요.

유용한 링크

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.