심화 — 스펙 주도 개발(SDD)

개념한 마디로

코드가 아니라 명세가 진실의 원천

스펙 주도 개발(SDD, Spec-Driven Development)은 명세(spec)를 먼저 정확히 쓰고, 그 명세로부터 코드를 만들어내는 방식이다. 코드는 명세에서 파생된 산출물이 된다.

이 페이지를 한 문장으로AI에게 두 번 이상 고쳐 시켜야 할 것 같으면, 명세부터 쓰는 편이 결국 더 빠르다.

배경왜 나왔나

즉흥적 프롬프팅의 한계

AI가 코드를 순식간에 만들어주면서 새로운 문제가 생겼다. 흔히 바이브 코딩(vibe coding)이라 부르는 방식의 한계다.

즉흥적으로 시킬 때	생기는 문제
"이거 만들어줘" → 결과 보고 → "아니 이렇게"	재현 불가 — 같은 결과를 다시 만들지 못한다
요구사항이 대화 속에만 존재	의도가 기록되지 않음 · 팀 공유 불가
파일이 여러 개로 늘어남	일관성이 무너짐
리뷰 대상이 코드 diff	"왜 이렇게 짰는지"를 알 수 없다

기존 문서와 뭐가 다른가예전에도 요구사항 문서는 있었다. 문제는 작성 후 방치되어 코드와 어긋난 것. SDD는 명세를 읽고 끝내는 문서가 아니라, 구현을 만들어내는 입력으로 다룬다.

비교바이브 코딩 vs SDD

둘은 우열이 아니라 용도가 다르다

바이브 코딩이 나쁜 방식인 것은 아니다. 빠르게 시도해 보고 감을 잡는 데는 이만한 게 없다. 문제는 그 방식으로 감당하기 어려운 일에까지 계속 쓰는 것이다.

한 줄로바이브 코딩은 빨리 알아내는 데 강하고, SDD는 정확히 만들어 남기는 데 강하다.

구분	바이브 코딩	SDD
시작 방식	"이거 만들어줘" 한 줄	명세 작성부터
진행	결과를 보고 즉흥적으로 수정	명세 → 계획 → 작업 → 구현
진실의 원천	생성된 코드	명세
리뷰 대상	코드 diff	명세 (그리고 코드)
재현성	낮다 — 같은 결과를 다시 만들기 어렵다	높다 — 명세로 다시 생성
초기 속도	매우 빠름	느림 (명세 쓰는 시간)
후반 속도	느려짐 (수정·되돌리기 반복)	유지됨
팀 공유	어렵다 — 맥락이 대화에만 있다	쉽다 — 문서가 남는다
적합한 일	탐색 · 프로토타입 · 일회성 · 한 파일	여러 파일 · 팀 협업 · 복잡한 요구사항

속도는 어느 순간 역전된다

초반

바이브가 빠르다

명세 없이 바로 결과를 본다

→

중반

비슷해진다

수정 요청이 쌓이기 시작

→

후반

SDD가 앞선다

"왜 이렇게 했지?"를 되묻지 않는다

규모가 작고 짧게 끝나면 역전되기 전에 끝난다 — 그래서 작은 일엔 바이브가 정답이다. 반대로 오래 갈 일에 바이브로만 버티면 후반에 대가를 치른다.

갈아탈 때를 알려주는 신호

이런 상황이면	해야 할 일
같은 부분을 세 번째 고치고 있다	멈추고 명세부터 쓴다 고쳐 시키는 비용이 명세 쓰는 비용을 넘어선 시점
"아까 왜 이렇게 했더라?"를 되묻는다
다른 사람에게 설명해야 한다
파일이 여러 개로 늘어났다

현실적인 답은 '섞어 쓰기'

실무에서는 둘 중 하나를 고르기보다 단계에 따라 갈아탄다. 탐색은 바이브로 빠르게, 방향이 잡히면 명세로 굳힌다.

바이브로 탐색

일단 만들어 보며 무엇이 필요한지 파악한다.

명세로 역정리

지금까지 만든 것을 명세로 거꾸로 정리시킨다.

명세 기준으로 재구현

확정된 명세로 다시 만들고, 이후는 SDD로 이어간다.

프로토타입은 버리는 것이 원칙 — 알아낸 것은 명세에 남는다

2단계에서 쓰는 지시가 핵심이다. 탐색으로 얻은 지식을 날리지 않고 문서로 회수한다.

지금까지 우리가 만든 것을 명세로 거꾸로 정리해줘.
- 배경/목적, 사용자 시나리오, 요구사항, 수용 기준, 범위 밖 순서로.
- 내가 중간에 바꾼 요구사항이 있으면 최종 상태 기준으로 정리할 것.
- 애매하게 결정된 부분은 추측하지 말고 질문으로 뽑아줘.

흔한 오해"SDD를 하면 바이브 코딩은 하면 안 된다"가 아니다. 탐색 단계의 바이브 코딩은 오히려 권장된다. 다만 그 결과를 명세로 남기지 않고 그대로 본 개발로 끌고 가는 것이 문제다.

원칙4가지

SDD의 핵심 원칙

원칙 1

명세가 1급 산출물

코드는 명세에서 파생된 결과물

원칙 2

What/Why ≠ How

명세엔 무엇을·왜, 기술 선택은 계획 단계로

원칙 3

수용 기준 명시

'완료'의 정의가 문서에 있어야 한다

원칙 4

반복 가능

명세를 고치면 구현을 다시 생성

흐름표준 5단계

명세에서 구현까지

GitHub의 오픈소스 툴킷 Spec Kit이 정리한 흐름이 사실상 표준처럼 쓰인다.

constitution — 원칙

변하지 않는 규칙·금지사항·컨벤션. 프로젝트의 헌법.

specify — 명세

무엇을·왜. 사용자 시나리오와 수용 기준. 기술 얘기는 쓰지 않는다.

plan — 기술 설계

어떻게. 스택·아키텍처·데이터 모델.

tasks — 작업 분해

실행 가능한 단위 작업 목록으로 쪼갠다.

implement — 구현

에이전트가 작업을 순서대로 수행한다.

모호하면 clarify(질문으로 해소) · 어긋나면 analyze(명세↔계획↔작업 일관성 점검)로 되돌아간다

참고Spec Kit은 29종 이상의 AI 코딩 에이전트를 지원하며, Claude Code와 Codex CLI는 슬래시 명령이 아니라 스킬(skill) 방식으로 설치된다. 최근에는 이 단계들을 YAML 파이프라인으로 엮고 중간에 사람이 승인하는 게이트를 두는 방식도 지원한다.

작성법명세에 무엇을 담나

명세 템플릿

핵심은 수용 기준과 범위 밖이다. 이 둘이 없으면 AI가 빈칸을 제멋대로 채운다.

# 기능: 휴가 신청 반려 알림

## 배경 / 목적
반려 사실을 신청자가 늦게 알아 재신청이 지연된다.

## 사용자 시나리오
- 팀장이 신청을 반려하면, 신청자는 즉시 알림을 받는다.
- 신청자는 알림에서 반려 사유를 바로 확인할 수 있다.

## 요구사항
- 반려 시 사내 메신저 + 메일로 동시 발송
- 사유는 필수 입력 (미입력 시 반려 불가)

## 수용 기준 (완료의 정의)
- [ ] 반려 -> 5초 내 알림 도착
- [ ] 사유 없이 반려 시도 시 에러 메시지
- [ ] 발송 실패 시 3회 재시도 후 관리자 로그 기록

## 범위 밖
- 알림 수신 설정 화면 (다음 스프린트)

항목	왜 필요한가
배경 / 목적	왜 만드는지 — 판단이 갈릴 때 기준이 된다
사용자 시나리오	누가 어떤 상황에서 쓰는지 — 구현 방향을 좁힌다
수용 기준	'완료'의 정의 — AI의 멈춤 조건이 된다
범위 밖	과도한 구현을 막는다 (AI는 시키지 않은 것도 만든다)

연결이 강의와의 관계

SDD는 이 강의 내용의 조합이다

SDD 요소	이 강의의 어느 부분인가
명세 = AI에게 주는 배경 자료	콘텍스트 엔지니어링
수용 기준 = 멈춤 조건	루프 엔지니어링 — 검증될 때까지 반복
constitution = 항상 지킬 규칙	CLAUDE.md
tasks → implement	하네스 — 에이전트가 실제로 실행

왜 AI 시대에 특히 중요한가수용 기준이 명시돼야 AI가 스스로 루프를 돌 수 있다. "테스트가 통과할 때까지"라는 기준이 있어야 실행 → 검증 → 재시도가 성립한다.

TDD와의 관계경쟁이 아니라 층이 다르다. SDD는 무엇을 왜 만드는가(상위 의도), TDD는 그것이 동작하는지 검증. 명세의 수용 기준을 테스트로 옮기면 자연스럽게 이어진다.

판단장단점과 적용 시점

언제 쓰고, 언제 안 쓰나

장점	한계
의도가 문서로 보존된다	초기 비용 — 명세 쓰는 시간
재현·재생성이 가능하다	과잉 문서화 위험
리뷰 대상이 명확 (코드 diff → 명세)	작은 수정엔 과하다
큰 작업에서 일관성이 유지된다	명세도 낡는다 — 동기화 필요

쓸 때	여러 파일에 걸친 기능 · 팀 협업 · 요구사항이 복잡 · 재작업 비용이 큰 경우
안 쓸 때	한 줄 수정 · 탐색적 프로토타이핑 · 혼자 하는 일회성 작업

실무 감각AI에게 두 번 이상 고쳐 시켜야 할 것 같으면 명세부터 쓰는 게 빠르다.

실습직접 해보기

명세부터 쓰고 시켜보기

본인 업무 기능 하나를 골라, 아래 순서대로 실행한다. 1번에서 바로 코드를 요청하지 않는 것이 핵심이다.

아래 기능에 대한 명세를 먼저 작성해줘. 코드는 아직 쓰지 마.
- 배경/목적, 사용자 시나리오, 요구사항, 수용 기준(완료의 정의), 범위 밖 순서로.
- 애매한 부분은 추측하지 말고 나에게 질문으로 정리해줘.

[기능] (여기에 만들 기능을 한 줄로)

질문에 답했어. 답변을 반영해 명세를 확정하고, 그 다음 기술 계획(스택·구조)을 따로 정리해줘.

확정된 명세와 계획을 기준으로 작업을 단위별로 쪼개서 목록으로 만들어줘. 각 작업에 완료 판단 기준을 한 줄씩 붙여줘.

작업 목록 순서대로 구현하고, 각 작업의 완료 기준을 충족하는지 검증한 뒤 결과를 알려줘.

관찰 포인트명세 단계에서 AI가 던지는 질문들이 곧 놓칠 뻔한 요구사항이다. 즉흥적으로 시켰다면 그냥 지어냈을 부분들이다.

클로드코드 시작하기심화 · ④ 스펙 주도 개발(SDD)