【AI 주도 개발】 고민된다면 이것! OpenSpec 치트시트【사양 주도 개발】

이전에 Harinezumi 님이 실천적인 OpenSpec 관련 기사를 작성해 주셨는데, 그것을 바탕으로 저도 OpenSpec을 활용하고 있습니다.

이번 기사에서는 여러분도 보다 친숙하고 가볍게 OpenSpec을 활용하실 수 있도록 특징과 명령어를 정리한 치트시트(Cheat Sheet)를 작성했습니다.

OpenSpec을 사용하다가 명령어를 잊어버렸을 때나, 다른 사양 주도 개발(Specification-Driven Development) 기법과 비교하고 싶을 때 참고 정보로 사용해 주세요.

실제로 어떤 파일이 생성되는지나 어떻게 활용할 수 있는지에 대한 구체적인 예시는 Harinezumi 님의 실천적인 기사를 참고해 주시기 바랍니다.

OpenSpec — 사양 주도 개발의 지식을 기분 좋게 순환시키기 (Amplify + AgentCore 핸즈온 포함)

AI 코딩 어시스턴트와 인간이 '무엇을 만들 것인가'를 코드 작성 전에 합의하기 위한 경량 프레임워크.

→ fluid not rigid (유연함)
→ iterative not waterfall (반복적)
→ easy not complex (간단함)
...

리포지토리: Fission-AI/OpenSpec | MIT | npm:

@fission-ai/openspec

장점	설명
합의 후 제작	인간과 AI가 스펙(Spec)으로 합의한 후 코드를 작성하므로, 재작업(rework)이 줄어듦
...
사양 주도 개발(SDD) 도구는 여러 가지가 존재합니다. 각각 접근 방식이 다릅니다.

항목	OpenSpec	cc-sdd	Spec Kit (GitHub)	Kiro (AWS)
사상	경량·유연·페이즈 게이트(Phase Gate) 없음	경계 주도·자율 구현·TDD 중시	엄격한 페이즈 파이프라인	IDE 통합형 사양 관리
진실의 원천 (Source of Truth)	스펙 (openspec/specs/)	코드 (스펙은 계약)	사양 (Constitution + 템플릿)	스펙
워크플로우 제어	액션 기반 (자유로운 순서)	페이즈 게이트 있음 (승인 후 구현)	엄격한 4단계 파이프라인	IDE 내에서 단계적으로 진행
대응 도구 수	29개 도구	8개 도구	4개 도구 (Copilot, Claude, Gemini, Cursor)	Kiro IDE 전용
...	/opsx:apply로 구현	/kiro-impl로 서브 에이전트 자율 구현+리뷰	/speckit.implement로 구현	IDE 내에서 자동 구현
델타 관리	델타 스펙 (ADDED/MODIFIED/REMOVED)	없음 (코드가 진실)	없음	없음
커스터마이징	스키마로 자유롭게 정의	템플릿·규칙 편집	템플릿·확장 카탈로그	제한적
셋업	npm install -g + openspec init	npx cc-sdd@latest	Python 환경 + pip install	IDE 도입만 수행
Stars	50.9k	3.4k	15k+	-

이런 경우	권장 도구
가볍게 시작하고 싶다, 도구를 가리지 않는다	OpenSpec
...

# 설치 (Node.js 20.19.0+)
npm install -g @fission-ai/openspec@latest
# 프로젝트 초기화
...

openspec/
├── specs/ # 진실의 원천 (현재 사양)
│ ├── auth/spec.md
...

OpenSpec에는 두 가지 프로파일(Profile)이 있으며, 워크플로우의 입도(Granularity)가 다릅니다.

항목	Core (기본값)	Expanded (확장)
대상	빠르게 진행하고 싶은 경우	단계적으로 제어하고 싶은 경우
계획 생성 방식	propose로 일괄 생성	new → continue / ff로 단계적 생성
검증	없음 (수동 확인)	verify로 자동 검증
아카이브	1건씩	bulk-archive로 일괄 대응 가능
활성화	기본값	openspec config profile → openspec update

Core는 「제안→구현→아카이브 (Archive)」를 최단 시간 내에 회전시키기 위한 프로파일입니다. /opsx:propose 하나로 proposal, specs, design, tasks를 모두 생성하여 즉시 구현에 들어갈 수 있습니다.

Expanded는 계획 페이즈 (Phase)를 세밀하게 제어하고 싶을 때 사용하는 프로파일입니다. 아티팩트 (Artifact)를 하나씩 확인하며 진행하는 continue, 일괄 생성하는 ff, 구현 후의 정합성 체크 verify 등 더 많은 명령어를 사용할 수 있습니다.

명령어	설명	언제 사용하는가
/opsx:propose <name>	변경 제안 + 모든 아티팩트 생성	신규 기능을 시작할 때
/opsx:explore	아이디어 탐색·조사	요구사항이 불명확할 때
/opsx:apply	태스크 (Task) 구현	코드를 작성할 준비가 되었을 때
/opsx:sync	델타 스펙 (Delta Spec)을 중심으로 머지 (Merge)	사양을 업데이트하고 싶을 때
/opsx:archive	변경 완료·아카이브	모든 작업이 끝났을 때

명령어	설명	언제 사용하는가
/opsx:new <name>	변경 스캐폴드 (Scaffold) 생성	단계적으로 진행하고 싶을 때
/opsx:continue	다음 아티팩트를 하나씩 생성	하나씩 확인하며 진행하고 싶을 때
/opsx:ff	모든 계획 아티팩트 일괄 생성	요구사항이 명확하여 한꺼번에 진행하고 싶을 때
/opsx:verify	구현과 사양의 정합성 검증	아카이브 전 확인
/opsx:bulk-archive	여러 변경 사항을 일괄 아카이브	병행 작업 완료 시
/opsx:onboard	프로젝트 온보딩 (Onboarding)	신규 멤버 참여 시

openspec init # 초기화
openspec init --tools all # 모든 툴 대응으로 초기화
openspec update # 에이전트 지시사항 재생성
...

# 1. 변경 스캐폴드 생성
/opsx:new add-user-search
# 2. 아티팩트를 순서대로 생성 (proposal → specs → design → tasks)
...

/opsx:new add-dark-mode → /opsx:continue → /opsx:apply → /opsx:archive

/opsx:explore 인증 방식의 비교 검토 → /opsx:new add-jwt-auth → /opsx:continue → /opsx:apply → /opsx:archive

/opsx:new add-dark-mode → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

/opsx:new feature-a → /opsx:ff → /opsx:apply
/opsx:new fix-bug-b → /opsx:ff → /opsx:apply
→ /opsx:bulk-archive

/opsx:propose나 /opsx:continue로 생성되는 4개의 아티팩트는 각각 서로 다른 질문에 답합니다.

변경의 의도·스코프 (Scope)·대략적인 접근 방식을 기술합니다. 팀이나 AI가 "이 변경은 무엇을 위한 것인가"를 이해하기 위한 출발점입니다.

포함 내용:

• Intent (의도): 왜 이 변경이 필요한가
• Scope (스코프): 무엇이 대상이며, 무엇이 대상 외인가
• Approach (접근 방식): 대략적인 방침

기술적인 접근 방식과 아키텍처 (Architecture) 상의 결정을 기술합니다. "왜 이 방법을 선택했는가"에 대한 근거도 포함합니다.

포함 내용:

• Technical Approach (기술적 접근 방식)
• Architecture Decisions (아키텍처 결정 및 그 이유)
• Data Flow (데이터 플로우)
• File Changes (변경 대상 파일)

현재 사양에 대해 "무엇이 추가/변경/삭제되는가"를 기술합니다. 요구사항과 시나리오 (Given/When/Then)로 구성되며, 테스트 가능한 형태로 동작을 정의합니다. 아카이브 시 메인 스펙 (Main Spec)으로 머지됩니다.

포함 내용:

• ADDED Requirements: 새롭게 추가하는 요구사항
• MODIFIED Requirements: 변경하는 기존 요구사항
• REMOVED Requirements: 폐지하는 요구사항

구현 체크리스트. AI가 /opsx:apply로 구현할 때의 작업 지시서가 된다.

포함할 내용:

• 그룹화된 태스크 (헤더로 분류)
• 계층적 번호 매기기 (1.1, 1.2, 2.1...)
• 체크박스 (- [ ], - [x])로 진척도 관리

proposal.md → 「왜·무엇을」을 정의
↓
design.md → 「기술적인 실현 방법」을 정의
...

proposal（왜·무엇을）
│
┌───────┴───────┐
...

축	체크 내용
Completeness	모든 태스크 완료? 모든 요구사항 구현 완료? 시나리오 커버?
...

요구사항이 불명확할 때, 변경을 만들기 전에 아이디어를 탐색·조사할 수 있다. 아티팩트(Artifact)는 생성되지 않는다.

You: /opsx:explore 모바일 앱의 인증을 어떻게 구현해야 할까
AI: 현재 코드베이스를 조사합니다...
Web 측은 세션 기반 인증 (Session-based authentication)을 사용하고 있네요.
...

활용 장면:

• 기술 선정의 비교 검토
• 성능 문제의 원인 조사
• 기존 코드의 전체상 파악
• 여러 접근 방식의 비교

규칙	설명
변경은 초점을 좁힌다	1 논리 단위 = 1 변경 폴더
불명확하다면 탐색부터	/opsx:explore로 문제 공간을 이해
아카이브 전에 검증	/opsx:verify로 불일치를 조기에 발견
명확한 명명	add-dark-mode ○ / feature-1 ×
단계적 엄격함	보통은 Lite, 고위험 시에만 Full
컨텍스트 위생	구현 전에 컨텍스트를 클리어

도구	ID
Claude Code	claude
...

전 29개 도구 대응. openspec init --tools all로 전체 대응 가능.