[Spec Kit ①] 왜 Spec-Driven Development인가 — 바이브 코딩의 한계를 넘어
AI가 짠 코드는 빠르지만 두 번째 요청부터 무너집니다. 명세를 진실의 원천으로 삼는 Spec-Driven Development(SDD)와 GitHub Spec Kit이 왜 등장했는지 짚습니다.
AI 코딩 도구로 첫 화면을 30초 만에 만들어 본 경험이 있으실 겁니다. 짜릿합니다. 그런데 두 번째 요청을 넣는 순간, 첫 번째에서 잘 돌던 부분이 슬그머니 깨집니다. 세 번째 요청쯤 되면, 코드가 어떻게 생겼는지 사람도 AI도 더 이상 설명하지 못합니다. 이 글은 그 "두 번째 요청의 벽"이 왜 생기는지, 그리고 GitHub Spec Kit이 제안하는 Spec-Driven Development(SDD) 가 그 벽을 어떻게 허무는지에 대한 이야기입니다.
이 글에서 배우는 것
- "바이브 코딩(vibe coding)"이 규모가 커지면 무너지는 3가지 실패 모드
- 코드가 아니라 명세(spec) 를 진실의 원천으로 두는 SDD의 핵심 전환
- Spec → Plan → Tasks → Implement로 이어지는 SDD 워크플로 한눈에 보기
- SDD가 TDD·BDD·프롬프트 엔지니어링과 어디서 만나고 어디서 갈라지는지
- 이 시리즈(총 7부)에서 우리가 함께 만들어 갈 예제와 로드맵
이 글은 Spec Kit 시리즈의 1부입니다. 시리즈 전체는 하나의 예제 프로젝트를 SDD 워크플로를 따라 0에서 1까지 만들어 가는 구성으로 이어집니다.
1. 짜릿함과 그 다음에 오는 것
"바이브 코딩"이라는 말은 자연어로 의도를 던지면 AI가 알아서 코드를 토해내는 방식을 가리킵니다. 프로토타입, 일회성 스크립트, 주말 해커톤에서는 더할 나위 없이 강력합니다. 문제는 이 방식이 상태를 갖지 않는다는 점입니다. 매 요청은 그 직전 대화 맥락에만 의존하고, 그 맥락은 길어질수록 흐려집니다.
작은 프로젝트에서는 이게 문제가 되지 않습니다. 하지만 코드베이스가 커지고, 요구사항이 누적되고, 며칠 뒤 다시 돌아와 기능을 추가하는 순간 — 즉 "진짜 소프트웨어"가 되는 순간 — 바이브 코딩은 세 가지 방식으로 무너지기 시작합니다.
실패 모드 1 — 맥락 유실 (Context Loss)
AI의 컨텍스트 창은 유한합니다. 대화가 길어지면 초반에 합의했던 결정들("인증은 JWT로", "에러는 이 포맷으로")이 창 밖으로 밀려납니다. 사람은 "아까 정한 대로"라고 말하지만, 모델에게 "아까"는 더 이상 존재하지 않습니다. 결과적으로 같은 결정을 매번 다시 설명하거나, 설명을 빠뜨려 일관성이 깨집니다.
실패 모드 2 — 일관성 붕괴 (Consistency Drift)
같은 의도라도 프롬프트의 표현이 조금만 달라지면 산출물이 달라집니다. 어제는 snake_case로 컬럼을 만들던 AI가 오늘은 camelCase로 만듭니다. 폴더 구조, 에러 처리 패턴, 네이밍 컨벤션이 요청마다 미묘하게 어긋나고, 이 미세한 어긋남이 쌓이면 코드베이스는 "여러 명이 따로 짠 것처럼" 보이게 됩니다.
실패 모드 3 — 검증 불가 (Unverifiability)
가장 치명적인 문제입니다. 명세가 머릿속(혹은 흘러간 대화 속)에만 있으면, "이 코드가 맞게 동작하는가?"를 판단할 기준점이 없습니다. AI가 그럴듯한 코드를 내놓아도, 그것이 원래 의도를 만족하는지 대조할 문서가 없습니다. 리뷰는 "느낌상 괜찮아 보이는지"에 의존하게 되고, 버그는 "원래 그렇게 하기로 했었나?"라는 질문 앞에서 책임 소재를 잃습니다.
바이브 코딩의 진짜 문제는 코드 품질이 아니라 진실의 원천(source of truth)이 없다는 데 있습니다. 무엇이 맞는지 적어둔 곳이 없으면, 빠르게 만든 코드일수록 빠르게 길을 잃습니다.
2. 발상의 전환 — 코드가 아니라 명세가 진실이다
전통적인 개발에서 명세 문서는 보통 한 번 쓰이고 잊혀집니다. 코드를 짜기 전 참고하는 출발선일 뿐, 코드가 완성되면 문서는 낡고 코드만 살아남습니다. 즉 코드가 진실의 원천이고 명세는 그 그림자입니다.
Spec-Driven Development는 이 관계를 뒤집습니다.
SDD에서 명세는 살아 있는 문서입니다. 기능을 바꾸려면 코드가 아니라 명세를 먼저 고치고, 코드는 그 명세로부터 (AI의 도움을 받아) 다시 생성·검증됩니다. 이렇게 하면 앞서 본 세 가지 실패 모드가 구조적으로 해소됩니다.
| 실패 모드 | SDD의 해법 |
|---|---|
| 맥락 유실 | 모든 결정이 명세 파일에 기록되어 컨텍스트 창 밖으로 사라지지 않음 |
| 일관성 붕괴 | 헌법(constitution) 과 명세가 매 단계 동일한 기준을 강제함 |
| 검증 불가 | 코드를 명세와 교차검증(analyze) 할 수 있는 대조 기준이 항상 존재함 |
핵심은 "문서를 더 쓰자"가 아닙니다. AI가 코드를 잘 짜게 하려면, AI에게 줄 의도를 사람이 검토할 수 있는 형태로 고정시켜야 한다는 것입니다. 명세는 사람과 AI가 공유하는 계약서입니다.
3. GitHub Spec Kit — SDD를 위한 도구상자
Spec Kit은 GitHub이 공개한 오픈소스 툴킷으로, SDD를 실제로 돌릴 수 있게 해주는 두 축으로 구성됩니다.
specifyCLI — 프로젝트에 SDD 스캐폴딩을 깔아주는 부트스트랩 도구. 사용하는 AI 에이전트(Claude Code, Copilot, Gemini 등)에 맞는 템플릿을 내려받아 세팅합니다.- 슬래시 커맨드 세트 — AI 에이전트 안에서
/speckit.*형태로 호출하는 워크플로 명령들. 각 명령이 SDD의 한 단계를 담당합니다.
특히 주목할 점은 Spec Kit이 30개 이상의 AI 코딩 에이전트를 지원하며, 에이전트 간 전환에 잠금(lock-in)이 없다는 것입니다. 명세·계획·작업이 텍스트 파일로 남기 때문에, 도구를 바꿔도 자산이 그대로 남습니다. (이 시리즈에서는 우리 블로그 독자에게 익숙한 Claude Code 연동을 기준으로 실습합니다.)
SDD 워크플로 한눈에 보기
Spec Kit이 정의하는 핵심 흐름은 Spec → Plan → Tasks → Implement 이며, 그 앞뒤로 품질 게이트가 붙습니다.
각 명령의 역할을 한 줄로 정리하면 다음과 같습니다. (자세한 실습은 시리즈 3~6부에서 다룹니다.)
| 단계 | 명령 | 한 줄 요약 |
|---|---|---|
| 헌법 | /speckit.constitution | 코드 품질·테스트·UX·성능 등 프로젝트를 관통하는 원칙을 세움 |
| 명세 | /speckit.specify | 기술 스택을 빼고 무엇/왜(요구사항·유저 스토리)에 집중 |
| 명료화 | /speckit.clarify | 명세의 빈틈을 순차적 질문으로 메움 |
| 계획 | /speckit.plan | 기술 스택·아키텍처 등 어떻게를 설계 |
| 작업 | /speckit.tasks | 계획을 의존성 순서가 있는 작업 목록으로 분해 |
| 분석 | /speckit.analyze | spec·plan·tasks 사이의 모순·누락을 교차검증 |
| 체크리스트 | /speckit.checklist | 요구사항·명확성을 검증하는 맞춤 품질 체크리스트 생성 |
| 구현 | /speckit.implement | 작업을 순서대로 실행해 실제 코드를 만듦 |
| 수렴 | /speckit.converge | 산출물과 코드베이스를 대조해 남은 일을 작업으로 회수 |
핵심 통찰: SDD는 "한 방에 생성"하지 않습니다. 여러 단계로 나눠 각 단계마다 사람이 검증(multi-step refinement)하는 구조 자체가 품질의 원천입니다.
4. SDD는 어디서 만나고 어디서 갈라지는가
SDD를 처음 접하면 "이거 결국 TDD/BDD 아니야?" 혹은 "그냥 프롬프트 잘 쓰는 거 아니야?"라는 의문이 듭니다. 위치를 정리해 두면 오해가 줄어듭니다.
| 접근 | 진실의 원천 | 강조점 | SDD와의 관계 |
|---|---|---|---|
| 프롬프트 엔지니어링 | 없음(휘발성 대화) | 한 번의 응답 품질 | SDD는 프롬프트를 파일로 고정해 재사용·검증 가능하게 만든 상위 체계 |
| TDD | 테스트 코드 | "동작이 맞는가"를 코드로 고정 | SDD는 명세에서 테스트·작업을 파생시킴 (상호 보완) |
| BDD | 시나리오(Given/When/Then) | 행위를 자연어로 기술 | SDD 명세의 유저 스토리와 결이 같음, SDD는 여기에 계획·실행을 연결 |
| SDD | 명세 파일 | 의도→계획→작업→코드의 일관된 추적 | 위 셋을 AI 워크플로로 묶는 우산 |
요약하면, SDD는 기존 기법을 대체하기보다 조율합니다. 명세라는 단일 기준점에 프롬프트의 재현성, TDD의 검증성, BDD의 가독성을 꿰어 AI 에이전트가 일관되게 일하도록 만드는 운영체계에 가깝습니다.
5. SDD가 잘 맞는 곳과 과한 곳
모든 작업에 헌법부터 세울 필요는 없습니다. 도구를 정직하게 소개하려면 한계도 같이 말해야 합니다.
- 잘 맞는 경우: 여러 번 손볼 기능, 팀이 함께 다루는 코드, 요구사항에 모호성이 있는 프로덕션 기능, 며칠~몇 주에 걸친 작업. 즉 "두 번째 요청"이 반드시 오는 일.
- 과할 수 있는 경우: 한 번 쓰고 버릴 스크립트, 명세보다 코드를 보는 게 빠른 10줄짜리 작업, 탐색적 프로토타이핑의 가장 초기 단계.
SDD의 단계들은 품질 게이트이지 의무 통행료가 아닙니다. Spec Kit도 /speckit.constitution·/speckit.clarify·/speckit.checklist를 "의미 있는 모호성이 있는 작업에서 켜는 게이트"로 권장합니다. 작업의 무게에 맞춰 게이트를 켜고 끄는 판단이 곧 SDD를 잘 쓰는 능력입니다.
6. 이 시리즈에서 함께 만들 것
개념만으로는 손에 잡히지 않습니다. 그래서 이 시리즈는 하나의 예제 프로젝트 — 실시간 데이터 품질 모니터링 서비스 — 를 SDD 워크플로를 따라 처음부터 끝까지 만들어 갑니다. 데이터 파이프라인의 신선도·정합성·이상치를 감시하고 알림을 보내는, 우리 도메인에 가까운 예제입니다.
| 부 | 주제 | 예제의 진행 |
|---|---|---|
| 1부 (이 글) | 왜 SDD인가 | 문제 정의와 큰 그림 |
| 2부 | Spec Kit 시작하기 | specify 설치·init, Claude Code 연동, 프로젝트 구조 |
| 3부 | Constitution | 데이터 팀용 프로젝트 헌법 세우기 |
| 4부 | Specify & Clarify | 모니터링 서비스의 요구사항 명세·모호성 제거 |
| 5부 | Plan & Tasks | 아키텍처 설계와 작업 분해, 정합성 분석 |
| 6부 | Implement & Converge | 실제 구현, GitHub 이슈 연동, 완료 검증 |
| 7부 | 실전 회고 | 0→1 엔드투엔드 케이스 스터디와 함정 정리 |
마치며
바이브 코딩은 빠르지만, 빠른 만큼 빨리 길을 잃습니다. 길을 잃지 않는 비결은 더 똑똑한 AI가 아니라 AI와 사람이 공유하는 진실의 원천 — 검증 가능한 명세 — 를 갖는 것입니다. Spec-Driven Development는 그 명세를 워크플로의 중심에 두고, GitHub Spec Kit은 그 워크플로를 실제로 돌릴 수 있는 도구상자를 줍니다.
다음 2부에서는 말을 멈추고 손을 움직입니다. specify CLI를 설치하고 빈 프로젝트에 SDD 스캐폴딩을 깔아, Claude Code와 연동하는 데까지 5분 만에 가 보겠습니다.
참고 자료