이전에 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

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

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

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

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

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

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（왜·무엇을）
│
┌───────┴───────┐
...

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

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

활용 장면:

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

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