OpenSpec 입문: 명세 문서로 AI 협업 프레임워크의 경계감을 잡아두기

입문급 | 약 15분 | OpenSpec의 핵심 개념(Delta Specs, Artifact 의존성 그래프), 초기화 절차, OPSX 워크플로우(propose → apply → archive), 그리고 여러 변경을 병렬로 관리하는 방법을 익히게 됩니다

---

프로젝트 소개

먼저 한 가지 사실을 인정해보자: AI 코딩 어시스턴트를 쓰다 보면 이런 상황을 겪어본 적 있지 않나요? 대화하다 보니 AI가 원래 바꾸고 싶지 않았던 부분까지 수정해버리거나, 대화 컨텍스트를 바꾼 순간 AI가 이전에 뭘 말했는지 완전히 잊어버리거나, 매번 AI에게 새 기능을 만들어 달라고 하면 결과물이 당신이 원하던 것과는 근본적으로 전혀 다른 경우.

이 문제는 AI가 너무 멍청해서가 아닙니다. 요구사항이 한 번도 「서명·날인」된 적이 없기 때문이에요. 요구사항은 오직 대화 기록 속에만 존재하고, AI가 마음껏 재량을 발휘할 여지가 너무 큽니다.

OpenSpec이 하는 일은 아주 간단합니다. 코드를 직접 쓰기 전에 사람과 AI가 한 장의 명세 문서를 기준으로 먼저 정렬(align)하고, AI는 그 문서에 따라 행동하게 만드는 것. Fission-AI가 개발했으며 20+ AI 코딩 도구(Claude Code, Cursor, Windsurf 등)를 지원합니다. 본질적으로는 AI 코딩 어시스턴트에 경량의 스펙(명세) 관리 레이어를 덧붙인 것입니다.

---

목표 독자

• 일상적으로 AI 코딩 어시스턴트를 사용하는 개발자
• 팀 협업에서 사람과 AI의 요구사항 이해가 엇갈려 고생하는 엔지니어
• AI가 만들어내는 결과물을 더 통제 가능하게 만들고 싶은 제품 관리자

핵심 의존성 및 환경

• Node.js 20.19.0+

완전한 프로젝트 구조 트리

openspec/
├── specs/                    # 시스템의 현재 동작 명세(도메인별로 구분)
│   └── <domain>/spec.md
├── changes/                  # 변경 제안(변경마다 폴더 1개)
│   ├── <change-name>/
│   │   ├── proposal.md       # 동기 + 범위 + 방안(접근)
│   │   ├── specs/             # Delta 명세(ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # 기술 설계
│   │   └── tasks.md          # 구현 체크리스트
│   └── archive/             # 보관(아카이브)된 히스토리
└── config.yaml               # 프로젝트 구성(선택)

---

단계별 안내

1단계: OpenSpec 전역 설치

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

설치 후 버전을 확인합니다:

openspec --version
# 1.2.0

2단계: 프로젝트 초기화

프로젝트 디렉터리로 이동한 뒤 초기화 명령을 실행합니다:

cd your-project
openspec init

이 명령은 세 가지를 수행합니다:

1. openspec/ 디렉터리 구조 생성
2. .claude/ 아래의 AI 스킬 파일 생성( AI 어시스턴트가 /opsx:* 명령을 인식하도록 함)
3. 프로젝트 설정 파일 config.yaml을 생성할지 물어봄(선택). 프로젝트 컨텍스트를 주입하는 데 사용됩니다.

초기화가 완료되면 프로젝트에 다음 디렉터리가 추가됩니다:

openspec/
├── specs/       # 현재 시스템 동작 명세(빈 디렉터리, 채워지길 기다리는 상태)
├── changes/     # 변경 제안 디렉터리(빈 디렉터리)
└── config.yaml  # 프로젝트 설정(생성을 선택한 경우)

3단계: OPSX 확장 워크플로우 활성화

새로 설치한 OpenSpec은 기본적으로 core 모드입니다. 명령은 4개뿐: propose、explore、apply、archive. 완전한 워크플로우( new、continue、ff、verify、bulk-archive 등)를 쓰고 싶다면 다음을 실행하세요:

openspec config profile
# expanded 또는 full 선택
openspec update

openspec update는 선택한 profile에 따라 AI 스킬 파일을 다시 생성하여, AI와의 대화에서 더 많은 명령을 사용할 수 있게 해줍니다.

4단계: 첫 번째 변경 만들기 — 다크 모드 추가

이제 AI가 당신을 대신해 변경을 만들도록 해봅시다. 예로 「앱에 다크 모드를 추가」하는 상황을 들어, AI에게 그대로 이렇게 말하면 됩니다:

/opsx:propose add-dark-mode

AI는 openspec/changes/add-dark-mode/ 아래에 네 개의 Artifact 파일을 자동으로 생성합니다:

openspec/changes/add-dark-mode/
├── proposal.md     # 이 변경은 무엇을 위한 것? 범위? 접근(방안)?
├── specs/
│   └── ui/spec.md  # UI 도메인의 Delta 명세
├── design.md       # 기술 방안을 어떻게 설계하지?
└── tasks.md        # 구체적으로 무엇을 해야 하지? 단계별 목록

proposal.md는 이런 형태를 가집니다( AI가 자동 생성, 당신과 AI가 함께 수정 가능):

# Proposal: Add Dark Mode

## Intent
사용자는 다크 모드 추가를 요청했고, 야간 사용 시 눈의 피로를 줄이기 위함입니다.

## Scope
- 설정에 테마 전환 버튼 추가
- 시스템 선호 감지 지원
- 선호를 localStorage에 영속화

## Approach
CSS 변수를 사용해 테마를 구성하고, React Context로 상태를 관리합니다.

specs/ui/spec.md는 핵심 Delta 명세이며 형식은 다음과 같습니다:

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
시스템 SHALL 사용자가 라이트 테마와 다크 테마 사이를 전환할 수 있어야 한다.

#### Scenario: Manual toggle
- GIVEN 사용자는 어떤 페이지에 있든
- WHEN 사용자가 테마 전환 버튼을 클릭하면
- THEN 테마가 즉시 전환되고, 선호는 세션을 넘어 영속화된다

#### Scenario: System preference
- GIVEN 사용자가 저장한 선호가 없는 경우
- WHEN 애플리케이션이 로드되면
- THEN 시스템의 기본(우선) 색상 구성표를 사용한다

tasks.md는 구현 체크리스트입니다:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 ThemeContext 생성(라이트/다크 상태)
- [ ] 1.2 색상 정의를 위한 CSS 변수 추가
- [ ] 1.3 localStorage 영속화 구현

## 2. UI Components
- [ ] 2.1 ThemeToggle 컴포넌트 생성
- [ ] 2.2 설정 페이지에 전환 버튼 추가
- [ ] 2.3 헤더에 바로가기 전환 추가

## 3. Styling
- [ ] 3.1 다크 테마 배색 정의
- [ ] 3.2 기존 컴포넌트가 CSS 변수를 사용하도록 수정

5단계: 구현 작업 실행

명세 문서가 확정되었다면 구현을 실행합니다:

/opsx:apply

AI는 tasks.md에 있는 작업을 항목별로 확인하고, 한 항목을 완료할 때마다 체크를 표시합니다. 그러면 AI의 행동이 바뀐 것을 발견하게 될 겁니다. 더 이상 자유롭게 재량을 발휘하지 않고, tasks.md에 따라 엄격하게 진행합니다. 구현 과정에서 설계에 문제가 생기면 바로 design.md를 수정한 뒤 다시 apply 하면, AI가 자동으로 따라갑니다.

6단계: 검증하고 변경 아카이브하기

검증(선택이지만 권장):

/opsx:verify

AI는 세 가지 관점에서 구현을 점검합니다:

아카이브:

/opsx:archive

아카이브는 두 가지를 수행합니다:

1. Delta 명세를 메인 명세 openspec/specs/ui/spec.md에 병합
2. 변경 폴더를 openspec/changes/archive/2026-04-11-add-dark-mode/로 이동

아카이브가 끝나면 시스템 명세 파일이 업데이트되고, 당신은 완전한 변경 이력을 한 벌 갖게 됩니다.

7단계: 여러 변경 병렬 관리

실제 개발에서는 중간에 다른 문제를 처리하느라 작업이 자주 끊깁니다. OpenSpec은 여러 변경을 병렬로 지원합니다:

# 가정: add-dark-mode를 하고 있는데 갑자기 bug를 고쳐야 함
/opsx:new fix-login-redirect

# 버그 수정 완료
/opsx:ff
/opsx:apply
/opsx:archive

# 이전의 다크 모드 작업으로 복귀
/opsx:apply add-dark-mode

여러 변경이 모두 끝나면 한꺼번에 아카이브합니다:

/opsx:bulk-archive

OpenSpec은 명세 충돌(두 변경 모두 specs/ui/를 수정함)을 자동으로 감지하고, 시간 순으로 병합합니다.

8단계: Schema 커스터마이즈

OpenSpec의 OPSX 워크플로우는 Schema로 정의됩니다. Artifact의 종류와 의존 관계를 완전히 커스터마이즈할 수 있어요. 예를 들어 「먼저 연구하고, 그다음 제안」하는 워크플로우를 원한다면:

# 기본 schema에서 새 schema를 파생
openspec schema fork spec-driven research-first

생성된 Schema 구조는 다음과 같습니다:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

이에 대응하는 의존성 그래프는 다음과 같습니다:

research ──► proposal ──► tasks

schema.yaml에서 정의합니다:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

9단계: CLI 자주 쓰는 명령 빠른 참조

# 초기화
openspec init

# AI 스킬 파일 업데이트(매번 업그레이드하거나 profile을 바꾼 뒤 실행해야 함)
openspec update

# 현재 설정 보기
openspec config show

# 워크플로우 profile 전환
openspec config profile

# 활성 변경 보기
openspec list

# 특정 변경의 상세 보기
openspec show add-dark-mode

# 형식 검증
openspec validate add-dark-mode

# 인터랙티브 Dashboard
openspec view

# Schema 관리
openspec schemas              # 사용 가능한 schema 목록
openspec schema which --all   # schema의 출처 확인
openspec schema validate my-schema  # schema 검증

---

자주 발생하는 문제 해결

1. AI가 /opsx:propose 명령을 찾지 못함

가장 흔한 문제입니다. openspec init을 실행한 후에는 AI 어시스턴트가 스킬 파일을 다시 로드해야 합니다. 다음을 실행하세요:

openspec update

그런 다음 대화를 다시 시작하세요. 그래도 AI가 인식하지 못한다면 .claude/ 디렉터리가 존재하는지 수동으로 확인하십시오.

2. openspec init이 Node.js 버전 오류를 보고함

node --version
# >= 20.19.0 인지 확인

# 버전이 너무 낮다면 nvm으로 업그레이드
nvm install 20 && nvm use 20

3. Delta 명세 병합 중 충돌 발생

/opsx:bulk-archive에서 두 변경이 동일한 명세 파일을 수정하면 OpenSpec이 이를 감지하고 알려줍니다. 시간 순으로 병합하는 것이 기본 동작이며, 수동 처리해야 한다면 다음처럼 합니다:

# 먼저 한 개를 개별로 아카이브
/opsx:archive fix-login-redirect

# 그다음 다른 하나를 아카이브
/opsx:archive add-dark-mode

4. 커스텀 Schema 로드 실패

보통은 schema.yaml 문법 오류 때문입니다. 다음으로 확인하세요:

openspec schema validate my-schema

흔한 오류: YAML 들여쓰기 불일치, artifact의 requires가 존재하지 않는 ID를 참조함(순환 의존성).

5. AI가 생성한 명세 형식이 요구사항을 충족하지 않음

openspec/config.yaml에 규칙을 추가할 수 있습니다:

rules:
  specs:
    - GIVEN/WHEN/THEN 형식으로 각 시나리오를 설명할 것
    - 각 Requirement는 최소 하나 이상의 Scenario를 가져야 함

이 규칙들은 AI가 생성하는 명세에 대한 지침으로 주입됩니다.

6. /opsx:apply 과정에서 AI가 일부 작업을 건너뜀

AI에게 직접 이렇게 말하세요:

작업은 tasks.md의 순서대로 실행하세요. 작업 1.3은 아직 완료되지 않았으니 건너뛰지 마세요.

OpenSpec의 fluid 특성 덕분에 Artifact를 언제든 편집할 수 있습니다. tasks.md를 수정한 뒤 다시 apply 하면, AI는 멈췄던 지점부터 계속합니다.

---

확장 읽기 / 고급 방향

Delta Specs 형식 심화: ADDED/MODIFIED/REMOVED의 세 가지 변경 유형은 각각 고유한 의미가 있습니다. ADDED는 새 요구사항 추가, MODIFIED는 기존 요구사항을 교체, REMOVED는 더 이상 필요 없는 요구사항을 삭제합니다. 이들을 합치는 규칙을 익히는 것이 OpenSpec을 제대로 쓰는 핵심입니다.

OPSX vs 레거시 워크플로우 비교: OpenSpec v1.x는 레거시 워크플로우(/openspec:proposal)를 사용하고, v1.2+부터는 OPSX를 주로 권장합니다. 핵심 차이는 이렇습니다: 레거시는 phase-locked(전부 또는 전무), OPSX는 fluid(어떤 시점이든 어떤 Artifact든 편집 가능).

20+ AI 도구 연동 가이드: OpenSpec은 .claude/skills/ 디렉터리에서 스킬 파일을 생성하며, Claude Code, Cursor, Windsurf, Copilot 등 주요 도구와 호환됩니다. 자세한 내용은 docs/supported-tools.md를 참고하세요.

팀 Slack 연동: 엔터프라이즈 팀은 [email protected]로 문의해 전용 Slack 채널 지원을 받을 수 있습니다. 여러 사람이 함께 협업하는 상황에서의 명세 관리 및 검토 프로세스에 적합합니다.

프로젝트 구성의 깊은 커스터마이징: context와 rules 외에도 config.yaml으로 기본 Schema를 설정하고, 프로젝트 기술 스택 정보(테스트 프레임워크, 코드 스타일 규칙 등)를 주입할 수 있습니다. 그러면 AI가 생성하는 명세가 실제 프로젝트에 더 잘 맞게 됩니다.