스펙 기반 개발 실전 — Claude Code로 45분 만에 대규모 마이그레이션 끝내기

개요

AI 코딩 도구를 쓰다 보면 한 가지 답답한 점이 있습니다. 간단한 수정은 잘 해주는데, 여러 파일을 건드리는 큰 작업에서는 맥락을 잃거나 엉뚱한 방향으로 갈 때가 많다는 것입니다. Spec Driven Development(SDD)는 이 문제를 해결합니다. 코드를 바로 짜는 대신 명세서(스펙)를 먼저 작성하고, 그 스펙을 기반으로 AI가 체계적으로 구현하도록 하는 방식입니다. 이 글에서는 alexop.dev의 실전 사례를 중심으로, Claude Code에서 SDD를 적용하는 구체적인 워크플로우를 정리합니다.

---

왜 스펙을 먼저 써야 하는가

AI 코딩 에이전트는 자기회귀(autoregressive) 방식으로 동작합니다. 첫 번째 출력이 다음 출력의 입력이 되기 때문에, 초반의 작은 오해가 뒤로 갈수록 커집니다. 100줄짜리 리팩토링에서 3번째 줄의 잘못된 판단이 나머지 97줄을 전부 오염시키는 일이 흔합니다.
스펙은 이 문제를 구조적으로 해결합니다.

• 방향 고정: AI가 구현 중 갈림길에 서면 스펙을 참조하여 올바른 선택을 합니다
• 복구 지점 역할: 세션이 꼬이더라도 스펙 문서를 다시 로드하면 빠르게 복구할 수 있습니다
• 검증 기준 제공: 구현이 끝난 후 스펙과 비교하여 누락을 확인할 수 있습니다

---

Claude Code에서 SDD 4단계 워크플로우

alexop.dev의 실전 사례에서는 SQLite에서 IndexedDB로 전체 스토리지 계층을 마이그레이션하는 작업을 SDD로 진행했습니다. 이 워크플로우는 사용자가 프로덕트 매니저, Claude가 테크 리드, 서브에이전트들이 개발자인 AI 개발팀 구조입니다.

1단계: 병렬 리서치

첫 번째 단계에서 Claude는 5개의 서브에이전트를 동시에 배치합니다. 각 에이전트는 독립적인 조사 영역을 맡습니다.

• 에이전트 1: CRDT 동기화 메커니즘 분석
• 에이전트 2: WebSocket 통신 구조 파악
• 에이전트 3: IndexedDB 스토리지 패턴 조사
• 에이전트 4: 기존 SQLite 코드베이스 분석
• 에이전트 5: 마이그레이션 선행 사례 수집

각 에이전트는 격리된 컨텍스트에서 작동하므로 메인 세션이 과부하되지 않습니다. 조사가 끝나면 통합 보고서를 작성합니다.

2단계: 스펙 작성

리서치 결과를 바탕으로 기술 명세서를 생성합니다. 핵심은 프롬프트에 있습니다.

"당신의 목표는 코드를 작성하는 것이 아니라, 문서를 작성하는 것입니다."

이 한 줄이 Claude의 행동을 완전히 바꿉니다. 코드부터 짜려는 충동을 억제하고, 아키텍처 결정사항, 인터페이스 계약, 에러 처리 전략 등을 문서로 정리하게 합니다. 작성된 스펙은 이후 모든 구현의 단일 진실 공급원(single source of truth) 역할을 합니다.

3단계: 스펙 정제

구현에 들어가기 전, Claude의 질문 도구를 활용해 설계를 다듬습니다. 이 단계에서 다루는 질문들은 다음과 같습니다.

• 기존 데이터 마이그레이션 전략은 어떻게 할 것인가?
• CRDT 충돌이 발생하면 어떤 해결 정책을 적용할 것인가?
• 크로스탭 동기화는 어떤 메커니즘을 사용할 것인가?
• 오프라인 상태에서의 동작은 어떻게 보장할 것인가?

이 과정에서 사용자(프로덕트 매니저)가 의사결정을 내리고, Claude가 그 결정을 스펙에 반영합니다.

4단계: 태스크 위임과 구현

스펙이 확정되면 Claude Code의 태스크 시스템을 통해 작업을 분배합니다. 각 태스크는 서브에이전트에게 할당되며, 원자적 커밋으로 추적됩니다.

태스크 1: IndexedDB 어댑터 인터페이스 구현 → 서브에이전트 A → commit #1
태스크 2: CRDT 동기화 로직 구현 → 서브에이전트 B → commit #2
태스크 3: 마이그레이션 스크립트 작성 → 서브에이전트 C → commit #3
...
태스크 14: 통합 테스트 및 정리 → 서브에이전트 N → commit #14

---

태스크 시스템이 해결하는 문제

Claude Code의 태스크 시스템은 .claude/tasks/ 디렉토리에 JSON 파일로 저장됩니다. 각 태스크는 상태(대기 중/진행 중/완료)와 의존성 정보를 포함합니다.

이 구조가 해결하는 핵심 문제는 에이전트 기억 상실(Agent Amnesia)입니다. 기존에는 세션이 끊기거나 컨텍스트가 초과되면 진행 상황을 전부 잃었습니다. 태스크가 디스크에 저장되므로 세션을 재시작해도 어디까지 진행했는지 즉시 파악할 수 있습니다.
또한 각 서브에이전트가 격리된 컨텍스트에서 동작하므로, 하나의 태스크가 실패해도 다른 태스크에 영향을 주지 않습니다. 마치 마이크로서비스 아키텍처처럼, 장애가 격리됩니다.

---

실전 결과: 45분, 14개 커밋, 15+ 파일

alexop.dev의 사례에서 SDD 워크플로우는 다음과 같은 결과를 냈습니다.

• 소요 시간: 45분
• 완료된 태스크: 14개
• 생성된 커밋: 14개 (태스크당 1커밋)
• 변경된 파일: 15개 이상
• 최종 산출물: PR 1개, 리뷰 준비 완료

수동으로 진행했다면 2~3일이 걸렸을 SQLite → IndexedDB 마이그레이션이 1시간 이내에 끝났습니다.

---

SDD를 적용하면 좋은 상황과 그렇지 않은 상황

SDD가 효과적인 경우는 분명합니다.
적합한 경우:

• 여러 파일을 동시에 수정해야 하는 대규모 리팩토링
• 기술 스택 마이그레이션 (DB 교체, 프레임워크 전환 등)
• 요구사항이 복잡하거나 불명확한 기능 구현
• 팀원 간 맥락 공유가 필요한 작업

과한 경우:

• 한두 줄짜리 버그 수정
• 단일 파일 내 간단한 수정
• 탐색적 프로토타이핑 (빠른 실험이 목적인 경우)

핵심은 작업의 복잡도와 관련 파일 수입니다. 3개 이상의 파일을 건드려야 하고, 아키텍처 결정이 필요한 작업이라면 SDD를 고려할 만합니다.

---

SDD 3가지 성숙도 수준

스펙 기반 개발은 적용 깊이에 따라 세 단계로 나눌 수 있습니다.
Spec-First (스펙 우선):
스펙을 먼저 작성하고, 그에 맞춰 AI가 코드를 생성합니다. SDD를 처음 도입하는 팀에 적합합니다. 스펙은 가이드 역할이며, 구현이 끝나면 아카이브됩니다.
Spec-Anchored (스펙 기반 통제):
스펙이 구현 후에도 유지됩니다. 코드가 스펙에서 벗어나면 빌드 타임에 감지됩니다. 여러 팀이 협업하거나 규제 준수가 필요한 환경에 적합합니다.
Spec-as-Source (스펙이 곧 소스):
스펙 자체가 소스 코드입니다. OpenAPI 스펙에서 서버/클라이언트 코드가 자동 생성되는 것이 대표적입니다. 인간은 스펙만 편집하고, 코드는 생성물로 취급합니다.

---

GitHub Spec Kit으로 시작하기

스펙 기반 개발을 체계적으로 적용하고 싶다면 GitHub가 공개한 오픈소스 도구인 Spec Kit을 살펴볼 만합니다. Claude Code를 포함한 22개 이상의 AI 코딩 도구를 지원하며, 다음 4단계 명령어로 구성됩니다.

• /specify: 비즈니스 맥락과 사용자 요구사항을 정의합니다
• /plan: 기술 스택과 아키텍처를 결정합니다
• /tasks: 구현 가능한 단위로 작업을 분해합니다
• /implement: AI가 각 태스크를 순차적으로 수행합니다

Spec Kit의 설치는 간단합니다.

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

---

CLAUDE.md와 SDD의 조합

Claude Code 사용자라면 이미 CLAUDE.md를 활용하고 있을 것입니다. SDD와 CLAUDE.md를 함께 사용하면 시너지가 생깁니다.
CLAUDE.md의 역할:

• 프로젝트 전반의 규칙과 컨벤션 정의
• 반복적으로 사용하는 명령어와 워크플로우 기록
• 200줄 이내로 간결하게 유지

스펙 파일의 역할:

• 특정 태스크에 대한 상세한 기술 명세
• 아키텍처 결정사항과 그 근거
• 구현 중 참조하는 단일 진실 공급원

CLAUDE.md는 프로젝트의 헌법, 스펙은 개별 법안이라고 생각하면 됩니다. CLAUDE.md가 전체 방향을 잡아주고, 스펙이 구체적인 구현을 안내합니다.

---

마무리

스펙 기반 개발의 핵심은 단순합니다. 계획과 실행을 분리하는 것입니다. AI에게 바로 코딩을 시키는 대신, 먼저 문서를 쓰게 하고, 그 문서를 검토하고, 그 다음에 구현을 시키는 것입니다.
이 방식은 특히 Claude Code의 서브에이전트, 태스크 시스템, Plan Mode와 결합하면 강력해집니다. 45분 만에 14개 커밋, 15개 파일 변경이라는 결과는 SDD가 단순한 이론이 아니라 실전에서 동작하는 방법론임을 보여줍니다.
다음에 여러 파일을 건드리는 큰 작업이 생기면, 코드부터 짜는 대신 한 번 스펙을 먼저 써보시기를 권합니다. 그 30분의 투자가 2~3일의 삽질을 절약해 줄 수 있습니다.

---

참고 자료

• Spec-Driven Development with Claude Code in Action - alexop.dev
• What Is Spec-Driven Development? - Augment Code
• Spec-driven development with AI: GitHub Spec Kit - GitHub Blog
• Claude Code Best Practices - Anthropic
• Using CLAUDE.MD files - Anthropic
• Claude Code를 활용한 예측 가능한 바이브 코딩 전략 - 컬리 기술 블로그

이 글은 Claude Code를 활용하여 작성되었습니다.