Spec-Driven Development — Vibe Coding 다음 단계, AI 에이전트 개발 방법론

Claude Code, Cursor, Copilot 다 있어요. 근데 왜 아직도 버그가 나고 코드가 망가질까요.

개발자: "알림 시스템 추가해줘"
에이전트: 토스트 메시지 컴포넌트 생성

개발자: "아니, 백엔드 알림이 필요해"
에이전트: 이메일 알림 서비스 생성

개발자: "SMS도 지원해야 해"
에이전트: SMS 프로바이더 추가

개발자: "재시도 로직은?"
에이전트: 지수 백오프 추가

...10번의 반복...
→ 처음 의도와 다른 코드베이스
→ 일관성 없는 패턴
→ 아무도 전체를 이해 못 함

이게 Vibe Coding의 한계예요. 500줄 넘어가면 무너지기 시작해요.

---

Spec-Driven Development가 뭔가

Vibe Coding:
아이디어 → 프롬프트 → 코드 → 문제 → 재프롬프트 → ...

Spec-Driven Development (SDD):
아이디어 → 스펙 작성 → 스펙 검증 → 에이전트 실행 → 검증

핵심 철학:

"코드를 먼저 쓰지 말고
스펙을 먼저 써라.
에이전트는 스펙을 구현한다."

Stack Overflow 2026년 3월 연구:

스펙 먼저 쓴 팀:
롤백률 67% 낮음

스펙 없이 프롬프트한 팀:
롤백률 67% 높음

---

스펙의 6가지 필수 요소

좋은 스펙은 에이전트가 질문 없이 실행할 수 있어야 해요.

## 1. 목표와 범위 (Goal & Scope)
무엇을 만드는가, 왜 만드는가
명시적으로 범위 밖인 것도 적기

## 2. 기능 요구사항 (Functional Requirements)  
구체적이고 테스트 가능한 문장으로
"사용자가 이메일/비밀번호로 로그인할 수 있다.
 세션은 비활동 30분 후 만료된다.
 로그인 실패는 IP당 분당 5회로 제한된다."

## 3. 제약 조건 (Constraints)
기술 스택, 보안 요건, 성능 기준
기존 코드베이스 패턴

## 4. 이전 결정 사항 (Prior Decisions)
이미 내린 아키텍처 결정
에이전트가 재발명하지 않도록

## 5. 작업 분해 (Task Breakdown)
단계별 순서
의존성 관계

## 6. 검증 기준 (Verification Criteria)
Given/When/Then 형식
완료 조건

---

실전 예시 — 알림 시스템

# SPEC: 주문 알림 시스템

## 목표
주문 상태 변화 시 사용자에게 멀티채널 알림 발송

## 범위
### 포함
- 이메일 (SendGrid), SMS (Twilio), 인앱 알림 (WebSocket)
- 사용자 채널별 on/off 설정
- 조용한 시간 (오후 10시~오전 8시 SMS 차단)

### 제외
- 푸시 알림 (모바일 앱 없음)
- 마케팅 알림 (이건 별도 시스템)
- 관리자 알림

## 기능 요구사항
- 각 채널은 독립적으로 on/off 가능
- 알림 타입: 주문 확인, 결제 완료, 배송 시작, 배달 완료, 실패
- 실패 시 재시도: 3회, 지수 백오프 (1분, 5분, 15분)
- 배달 추적 로그 보관 30일

## 기술 제약
- 기존 PostgreSQL 사용 (새 DB 금지)
- TypeScript, Express 기존 스택
- 이메일 서비스는 SendGrid만 (Mailgun 사용 금지)

## 이전 결정
- 사용자 인증은 JWT 사용 (세션 기반 금지)
- 에러 처리는 커스텀 AppError 클래스 사용

## 검증 기준
- Given 주문이 배송 시작됨
  When 알림 서비스 호출
  Then 이메일 + SMS + 인앱 동시 발송 (채널 활성 시)
  
- Given SMS가 비활성화된 사용자
  When 알림 서비스 호출
  Then 이메일 + 인앱만 발송, SMS 없음

- Given 오후 11시
  When SMS 발송 시도
  Then SMS 큐에 다음날 오전 8시로 지연 등록

이 스펙을 에이전트에게 주면:

에이전트가 알아서 결정하는 것들:
→ 파일 구조
→ 클래스/함수명
→ 내부 구현 방식

에이전트가 절대 넘지 않는 것들:
→ 범위 밖 기능 추가
→ 금지된 라이브러리 사용
→ 기존 패턴 무시

---

SDD 워크플로우

1단계: 아이디어 명확화
─────────────────────
"어떤 문제를 해결하는가?"
한 문장으로 못 쓰면 → 아직 이해 못 한 것

2단계: 스펙 초안 작성
─────────────────────
에이전트에게 스펙 초안을 쓰게 해도 됨:

"다음 기능의 스펙을 작성해줘:
목표, 범위(포함/제외), 기능 요구사항,
기술 제약, 검증 기준 포함해서.
[기능 설명]"

→ 에이전트 초안 → 내가 검토/수정

3단계: 스펙 검증
─────────────────────
자가 점검 질문들:
□ 에이전트가 질문 없이 실행할 수 있는가?
□ 완료 조건이 명확한가?
□ 범위 밖이 명시되어 있는가?
□ 기존 코드베이스 맥락이 있는가?

4단계: 에이전트 실행
─────────────────────
"다음 스펙을 구현해줘: [스펙 내용]
구현 전에 실행 계획부터 보여줘."

→ /plan 명령으로 계획 먼저 확인
→ 계획 승인 후 구현

5단계: 스펙 대비 검증
─────────────────────
"구현된 코드가 스펙의 검증 기준을
충족하는지 확인해줘."

→ 스펙이 테스트 기준이 됨

---

Vibe Coding vs SDD 언제 뭘 쓸까

Vibe Coding이 맞는 경우:
→ 5분 안에 리뷰 가능한 작은 작업
→ 일회성 스크립트
→ 빠른 프로토타입 검증
→ 단순 버그 수정

SDD가 필요한 경우:
→ 500줄 이상 기능
→ 여러 세션에 걸친 작업
→ 여러 서비스에 걸친 변경
→ 되돌리기 비싼 작업
→ 팀원/다른 에이전트와 협업
→ 프로덕션 배포 예정

실용적 기준:

"리뷰하는데 5분 이상 걸릴 것 같으면 스펙을 먼저 써라"

---

CLAUDE.md와의 관계

CLAUDE.md = 프로젝트 레벨 스펙
            (항상 적용되는 전역 컨텍스트)

기능 스펙 = 태스크 레벨 스펙
            (이번 작업에만 적용)

두 개가 함께 작동:
CLAUDE.md: "이 프로젝트는 TypeScript, Jest, PostgreSQL 사용"
기능 스펙: "알림 시스템을 이렇게 만들어라"

# CLAUDE.md (프로젝트 전역 컨텍스트)

## 기술 스택
- TypeScript 5.3, Node.js 22
- PostgreSQL (Prisma ORM)
- Jest + Supertest (테스트)

## 코딩 컨벤션
- 함수형 우선, 클래스는 서비스 레이어만
- 에러는 AppError 클래스 사용
- 모든 비동기는 async/await

## 금지 사항
- any 타입 사용 금지
- console.log 프로덕션 코드에 금지
- DB 직접 쿼리 금지 (반드시 Prisma 사용)

## 테스트
- 모든 서비스 함수 단위 테스트 필수
- 커버리지 80% 이상 유지

---

스펙을 버전 관리하는 법

스펙도 코드처럼 관리해요.

프로젝트 구조:
myproject/
  CLAUDE.md           # 전역 컨텍스트
  specs/
    auth.md           # 인증 스펙
    notifications.md  # 알림 스펙 (현재 작업)
    payments.md       # 결제 스펙
  src/
    ...

스펙을 Git에 커밋하면:

✅ 에이전트가 이전 결정 사항 참조 가능
✅ PR 리뷰 시 스펙도 함께 리뷰
✅ 코드 변경 시 스펙도 업데이트 강제
✅ 팀원이 새로 합류해도 맥락 즉시 파악

---

흔한 실수

❌ 너무 광범위한 스펙
"인증 모듈을 더 좋게 리팩토링해줘"
→ 에이전트가 범위를 알 수 없음

✅ 구체적인 스펙
"src/lib/auth/session.ts만 리팩토링해줘.
토큰 만료 처리를 분리하고,
기존 인터페이스는 유지해."

❌ 검증 기준 없는 스펙
"회원가입 기능 만들어줘"

✅ 검증 기준 있는 스펙
"Given 유효한 이메일과 비밀번호
 When 회원가입 요청
 Then 인증 이메일 발송, DB에 사용자 생성,
      중복 이메일이면 400 에러"

❌ 구현 방법 지정
"Redux로 상태 관리해줘"

✅ 결과 지정
"장바구니 상태가 페이지 리로드 후에도 유지되어야 해.
(구현 방법은 에이전트가 결정)"

---

제목 추천

1. Spec-Driven Development — Vibe Coding 다음 단계, AI 에이전트 시대 개발 방법론
2. AI 에이전트에게 코드 시키기 전에 이걸 먼저 써라 — Spec-Driven Development 실전
3. 롤백률 67% 줄이는 방법 — AI 코딩 에이전트를 위한 스펙 작성법

2번이 제일 클릭 당길 것 같아요. 골라보세요.