Claude Code에게 “사용자 인증 기능 추가해줘”라고 요청했더니 JWT 토큰을 구현했는데, 정작 필요했던 건 OAuth였던 경험 있으신가요? AI 코딩 도구가 강력해질수록 ‘의도’를 명확히 전달하는 게 더 중요해졌습니다. OpenSpec는 코드 작성 전에 명세를 먼저 합의하는 경량 워크플로우로, AI가 엉뚱한 구현을 하는 문제를 근본적으로 해결합니다.
핵심 포인트:
- “무엇을” 먼저 합의하고 “어떻게”는 나중에: 코드 작성 전 명세 단계에서 AI와 합의하여 예측 불가능한 구현 제거
- 3개 명령어로 완결되는 워크플로우: proposal → apply → archive로 변경사항 제안부터 구현, 아카이브까지 체계적 관리
- 기존 코드베이스 수정에 최적화: 이미 운영 중인 프로젝트에서 변경 전/후를 명확히 분리해 대규모 시스템에서도 추적 가능
채팅 기록 속에 흩어진 요구사항의 문제
AI 코딩 어시스턴트는 점점 강력해지고 있습니다. Cursor, Claude Code, GitHub Copilot 같은 도구들은 몇 줄의 프롬프트로 수백 줄의 코드를 생성합니다. 문제는 이런 ‘바이브 코딩(vibe coding)’ 방식이 프로토타입에는 좋지만, 실제 프로덕션 코드에는 위험하다는 점입니다.
이 문제를 해결하기 위해 등장한 개념이 명세 기반 개발(Spec-driven development, SDD)입니다. 코드를 작성하기 전에 ‘무엇을 만들 것인가’에 대한 명세를 먼저 정의하고, 이를 AI와 사람이 함께 검토하고 합의한 뒤 구현으로 넘어가는 방식입니다. 명세를 살아있는 문서로 만들어 프로젝트와 함께 진화시키는 것이 핵심입니다.
“장바구니에 할인 쿠폰 기능 추가해줘”라고 요청하면 AI는 그럴듯한 코드를 만들어냅니다. 하지만 쿠폰 중복 사용 방지는? 유효기간 검증은? 할인율 상한선은? 이런 세부사항은 채팅 기록 어딘가에 흩어져 있거나, 아예 빠져있습니다. AI는 패턴 인식에는 탁월하지만 마음을 읽지는 못합니다.
GitHub의 블로그 포스트에 따르면, 이 문제의 핵심은 AI의 코딩 능력이 아니라 우리의 접근 방식입니다. AI를 검색 엔진처럼 다루는 대신, 명확한 지시가 필요한 페어 프로그래머로 대해야 합니다.
OpenSpec이 해결하는 방식
OpenSpec는 명세 기반 개발을 AI 코딩 워크플로우에 적용한 경량 도구입니다. 코드 작성 전에 ‘무엇을 만들 것인가’에 대한 합의를 먼저 도출하고, 명세를 실행 가능한 살아있는 문서로 관리합니다.
핵심은 두 가지 폴더 구조입니다:
openspec/specs/: 현재 시스템의 진실(source of truth)openspec/changes/: 제안된 변경사항과 그 차이점(delta)
이 분리 구조 덕분에 기존 코드베이스를 수정할 때도 ‘무엇이 바뀌는가’를 명확히 추적할 수 있습니다. 처음부터 새로 만드는 프로젝트뿐 아니라 이미 복잡해진 운영 중인 시스템에서도 효과적입니다.
4단계로 완성되는 개발 워크플로우
OpenSpec의 작동 방식은 직관적입니다. 예를 들어, 사용자 프로필 검색 화면에 역할(Role)과 팀(Team)별 필터 기능을 추가한다고 해봅시다.
1단계: 변경 제안 작성(Draft Proposal)
“프로필 검색에 역할과 팀별 필터 추가”라는 요구사항을 AI에게 전달하면, AI가 openspec/changes/add-profile-filters/ 폴더를 생성하고 proposal.md, tasks.md, 그리고 spec delta를 작성합니다.
# 슬래시 커맨드를 지원하는 도구에서
/openspec:proposal Add profile search filters
# 또는 자연어로
"프로필 검색 필터 추가하는 OpenSpec 변경 제안 만들어줘"2단계: 검토 및 조율(Review & Align)
생성된 명세를 확인하고 피드백을 주고받습니다.
openspec list # 변경사항 목록 확인
openspec show add-profile-filters # 제안 상세 내용 보기
openspec validate add-profile-filters # 명세 형식 검증“역할 필터에 acceptance criteria 추가해줄래?”라고 요청하면, AI가 spec delta와 tasks.md를 업데이트합니다. 이 과정을 반복하며 명세를 다듬습니다.
3단계: 구현(Implement)
명세에 합의했다면 구현을 시작합니다.
# 슬래시 커맨드 지원 도구
/openspec:apply add-profile-filters
# 또는 자연어
"명세가 좋아 보여. 이제 구현하자"AI가 tasks.md에 정의된 작업을 하나씩 수행하며 체크박스를 채워갑니다. Task 1.1 ✓, Task 1.2 ✓…
4단계: 아카이브(Archive)
모든 작업이 완료되면 변경사항을 아카이브합니다. 이 과정에서 spec delta가 openspec/specs/의 실제 명세에 병합됩니다.
/openspec:archive add-profile-filters
# 또는
openspec archive add-profile-filters --yes이제 시스템의 ‘진실’이 업데이트되었고, 다음 변경사항을 위한 준비가 끝났습니다.
실전 예시: 2단계 인증 추가하기
실제 사용 예시를 보겠습니다. 2단계 인증(2FA) 기능을 추가한다고 가정합니다.
AI에게 요청하면 다음 구조가 자동 생성됩니다:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # 현재 인증 명세
└── changes/
└── add-2fa/
├── proposal.md # 왜, 무엇을 변경하는가
├── tasks.md # 구현 체크리스트
├── design.md # 기술적 결정사항 (선택)
└── specs/
└── auth/
└── spec.md # 변경될 부분만 포함된 deltaDelta 형식 예시:
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
시스템은 로그인 시 제2 인증 요소를 반드시 요구해야 합니다.
#### Scenario: OTP required
- WHEN 사용자가 유효한 인증 정보를 제출하면
- THEN OTP 챌린지가 요구됩니다Tasks 예시:
## 1. Database Setup
- [ ] 1.1 users 테이블에 OTP secret 컬럼 추가
- [ ] 1.2 OTP 검증 로그 테이블 생성
## 2. Backend Implementation
- [ ] 2.1 OTP 생성 엔드포인트 추가
- [ ] 2.2 로그인 플로우에 OTP 요구사항 반영
- [ ] 2.3 OTP 검증 엔드포인트 추가
## 3. Frontend Updates
- [ ] 3.1 OTP 입력 컴포넌트 생성
- [ ] 3.2 로그인 플로우 UI 업데이트중요한 점은 이 파일들을 직접 작성하지 않는다는 것입니다. AI가 요구사항과 기존 코드베이스를 분석해서 생성합니다.
기존 도구와의 차이점
spec-kit과 비교:
GitHub의 spec-kit은 새 프로젝트를 처음 시작할 때(0→1) 강점이 있지만, 기존 기능을 수정할 때(1→N)는 OpenSpec이 더 효과적입니다. OpenSpec는 현재 상태와 제안된 변경사항을 분리해서 관리하기 때문에, 여러 명세에 걸쳐 수정이 필요한 경우에도 명확하게 추적할 수 있습니다.
Kiro와 비교:
Kiro는 변경사항을 여러 spec 폴더에 분산시키는 반면, OpenSpec는 하나의 feature와 관련된 모든 것(proposal, tasks, spec deltas)을 한 폴더에 모아둡니다. 이는 feature 단위 추적을 훨씬 쉽게 만듭니다.
명세 없이 개발하는 방식과 비교:
명세 없이 AI에게 프롬프트만 던지면, AI는 애매한 프롬프트에서 요구사항을 추측하고, 그 중 일부는 틀립니다. OpenSpec는 코드 작성 전에 ‘무엇을 만들 것인가’에 대한 합의를 도출해서 예측 가능성을 제공합니다.
어떻게 시작하나요?
OpenSpec 도입은 간단합니다.
1. 설치
npm install -g @fission-ai/openspec@latest
openspec --version # 설치 확인Node.js 20.19.0 이상이 필요합니다.
2. 프로젝트 초기화
cd your-project
openspec init초기화 과정에서 사용 중인 AI 도구(Claude Code, Cursor, Copilot 등)를 선택하면, OpenSpec가 자동으로 슬래시 커맨드를 설정합니다. 프로젝트 루트에 openspec/ 디렉토리와 AGENTS.md 파일이 생성됩니다.
3. 프로젝트 컨텍스트 작성 (선택사항)
# AI에게 요청
"openspec/project.md를 읽고 우리 프로젝트의 기술 스택과 컨벤션을 채워줘"이 파일에는 프로젝트 전반의 아키텍처 패턴, 코딩 컨벤션, 표준 등을 정의합니다.
4. 첫 변경사항 만들기
# AI에게 요청
"사용자 프로필에 아바타 업로드 기능 추가하는 OpenSpec 제안 만들어줘"이제 OpenSpec 워크플로우를 경험할 준비가 끝났습니다.
지원되는 AI 도구
OpenSpec는 다양한 AI 코딩 도구를 지원합니다:
네이티브 슬래시 커맨드 지원:
- Claude Code:
/openspec:proposal,/openspec:apply,/openspec:archive - Cursor:
/openspec-proposal,/openspec-apply,/openspec-archive - GitHub Copilot:
.github/prompts/에 커맨드 설치 - Codex: 글로벌 프롬프트에 자동 설치
- CodeBuddy, Windsurf, Cline, Crush 등
AGENTS.md 호환 도구:
슬래시 커맨드가 없더라도 openspec/AGENTS.md를 자동으로 읽는 도구들(Amp, Jules, Gemini CLI 등)도 사용 가능합니다. 자연어로 “OpenSpec 워크플로우 따라줘”라고 요청하면 됩니다.
팀 단위 도입 전략
OpenSpec를 팀에 도입할 때는 점진적으로 접근하세요:
- 새 기능부터 시작: 기존 코드를 전부 명세화하려 하지 말고, 다음 기능 개발부터 OpenSpec로 진행하세요.
- 각자 선호하는 도구 사용 가능: 어떤 팀원은 Claude Code를, 다른 팀원은 Cursor를 써도 같은 명세를 공유할 수 있습니다.
- 점진적으로 확장: 각 변경사항이 아카이브되면서 시스템을 문서화하는 살아있는 명세가 자연스럽게 쌓입니다.
- 도구 전환 시 업데이트: 팀원이 다른 AI 도구로 전환하면
openspec update명령어로 최신 슬래시 커맨드를 동기화하세요.
OpenSpec가 빛을 발하는 3가지 상황
Red Hat 개발자 블로그에서 제시한 spec-driven 개발의 이점은 OpenSpec에도 그대로 적용됩니다:
1. 새 프로젝트 시작 (0→1): 처음부터 만드는 프로젝트에서 약간의 사전 작업으로 AI가 원하는 대로 구현하도록 유도합니다.
2. 기존 시스템의 기능 추가 (N→N+1): 복잡한 코드베이스에 기능을 추가할 때 가장 강력합니다. 새 기능이 기존 시스템과 어떻게 상호작용해야 하는지 명확히 하고, 아키텍처 제약사항을 인코딩합니다.
3. 레거시 현대화: 레거시 시스템을 재구축할 때, 원래 의도를 현대적 명세로 포착하고, 새 아키텍처를 설계한 뒤, AI가 기술 부채 없이 시스템을 재구축하게 합니다.
명세가 곧 소스 코드가 되는 미래
우리는 “코드가 진실”에서 “의도가 진실”로 전환하는 시대를 살고 있습니다. AI가 명세를 실행 가능하게 만들면서, 명세가 무엇을 만들지 결정하게 되었습니다.
OpenSpec는 이 전환을 현실로 만드는 실험입니다. API 키도 필요 없고, 복잡한 설정도 없습니다. 세 개의 명령어만으로 AI 코딩의 예측 가능성과 추적성을 확보할 수 있습니다. 프로토타입의 속도를 유지하면서도 프로덕션의 안정성을 얻는 방법, OpenSpec로 시작해보세요.
참고자료:
답글 남기기