AI는 코드를 빠르게 만들지만, 요구사항까지 자동으로 명확하게 만들어 주지는 않는다. SDD와 GitHub Spec Kit은 바이브 코딩의 속도를 유지하면서 프로젝트의 방향과 완료 기준을 관리하는 방법을 제공한다.
바이브 코딩에 명세가 필요한 이유
AI에게 “이런 앱을 만들어줘”라고 요청하면 몇 분 만에 화면과 코드가 만들어진다. 버튼을 추가하고 디자인을 바꾸고 오류를 고치는 일도 대화만으로 빠르게 진행할 수 있다. 이른바 바이브 코딩이다.
작은 프로토타입에서는 놀라울 정도로 효율적이다. 하지만 기능이 많아지고 대화가 길어지면 문제가 생기기 시작한다.
- 처음 요청한 조건이 어느 순간 사라진다.
- 새로운 기능을 추가하면서 기존 기능이 깨진다.
- AI가 정한 기술적 선택의 이유를 알기 어렵다.
- 구현된 범위와 남은 작업을 구분하기 어렵다.
- 새로운 채팅을 시작하면 프로젝트를 다시 설명해야 한다.
이러한 문제를 줄이기 위한 접근법이 SDD(Spec-Driven Development), 명세 주도 개발이다. GitHub Spec Kit은 SDD를 AI 코딩 과정에 적용할 수 있도록 만든 대표적인 오픈소스 도구다.
SDD란 무엇인가
SDD는 코드를 작성하기 전에 소프트웨어가 어떻게 동작해야 하는지 명세하고, 그 명세를 기준으로 설계·구현·검증하는 개발 방식이다.
일반적인 바이브 코딩은 다음과 같이 흘러간다.
아이디어
→ AI에게 구현 요청
→ 결과 확인
→ 추가 요청
→ 반복 수정
SDD에서는 구현 전에 몇 가지 단계를 추가한다.
아이디어
→ 요구사항 명세
→ 기술 설계
→ 작업 분해
→ 구현
→ 명세와 결과 비교
예를 들어 AI에게 “사용자가 할 일을 관리할 수 있는 앱을 만들어줘”라고 요청했다고 생각해 보자. 사람은 어느 정도 완성된 모습을 떠올릴 수 있지만, 개발에 필요한 정보는 충분하지 않다.
- 할 일을 수정하거나 삭제할 수 있는가?
- 완료한 할 일은 어디에 표시되는가?
- 새로고침해도 데이터가 유지되어야 하는가?
- 로그인이 필요한가?
- 여러 사용자가 데이터를 공유하는가?
- 모바일 화면을 지원해야 하는가?
AI는 빠진 내용을 질문하거나 임의로 결정할 수밖에 없다. 문제는 그 결정이 대화 속에 흩어지고, 프로젝트가 커질수록 서로 충돌할 수 있다는 점이다.
SDD에서는 먼저 다음처럼 기준을 만든다.
[목표]
사용자가 개인 할 일을 간단하게 관리할 수 있는 웹 앱을 만든다.
[기능 요구사항]
- 사용자는 할 일을 추가, 수정, 삭제할 수 있다.
- 사용자는 할 일을 완료 상태로 변경할 수 있다.
- 데이터는 새로고침 후에도 유지되어야 한다.
[제외 범위]
- 회원가입과 로그인
- 여러 사용자 간 공유
- 서버 데이터베이스
[완료 조건]
- 빈 내용은 등록할 수 없다.
- 변경 결과가 즉시 화면에 반영된다.
- 모바일에서도 주요 기능을 사용할 수 있다.
이 명세는 단순한 설명서가 아니다. AI가 무엇을 구현해야 하는지 판단하는 기준이자, 구현이 끝났는지 확인하는 기준이다.
GitHub Spec Kit은 무엇인가
GitHub Spec Kit은 AI 코딩 에이전트에 구조화된 SDD 작업 흐름을 추가하는 오픈소스 도구다.
Spec Kit 자체가 코드를 작성하는 AI 모델은 아니다. Codex, GitHub Copilot, Claude Code, Gemini CLI 같은 기존 코딩 에이전트가 일정한 절차를 따르도록 명령과 템플릿을 제공한다.
GitHub 공식 기록에 따르면 저장소의 최초 커밋은 2025년 8월 21일에 작성됐으며, 2026년 8월 21일에 1.0 버전이 출시됐다.
2026년 9월 기준 GitHub 저장소에는 약 13만 8천 개의 스타와 1만 2천 개 이상의 포크가 있다. 공식 문서는 38개의 AI 코딩 도구 연동과 157개의 커뮤니티 확장 기능을 안내한다. 스타 수가 실제 사용자 수를 의미하지는 않지만, SDD 도구 중 상당한 관심을 받고 있는 프로젝트다.
Spec Kit의 작업 흐름
Constitution
↓
Specify → Clarify
↓
Plan → Checklist
↓
Tasks → Analyze
↓
Implement ↔ Converge| 단계 | 핵심 질문 | 결과 |
| Constitution | 프로젝트가 항상 지킬 원칙은 무엇인가? | 프로젝트 공통 원칙 |
| Specify | 무엇을 왜 만들어야 하는가? | 기능 명세 |
| Clarify | 빠지거나 애매한 조건은 무엇인가? | 보완된 명세 |
| Plan | 어떤 기술과 구조로 구현할 것인가? | 기술 계획 |
| Checklist | 명세가 충분히 명확한가? | 품질 체크리스트 |
| Tasks | 어떤 순서로 구현할 것인가? | 작업 목록 |
| Analyze | 문서 사이에 충돌이나 누락이 있는가? | 분석 보고서 |
| Implement | 계획대로 코드를 어떻게 작성할 것인가? | 구현 결과 |
| Converge | 구현이 명세를 모두 만족하는가? | 검증 결과와 보완 작업 |
1. Constitution: 프로젝트 원칙 설정
Constitution은 프로젝트 전체에서 지켜야 할 규칙을 정의한다. 기능마다 만드는 것이 아니라 프로젝트를 시작할 때 한 번 작성하고, 원칙이 변경될 때 갱신한다.
- TypeScript strict 모드를 사용한다.
- 모든 사용자 입력을 검증한다.
- 기존 API 응답 형식을 유지한다.
- 핵심 비즈니스 로직에는 테스트를 작성한다.
- 민감한 정보를 코드와 로그에 저장하지 않는다.
이후 작성되는 명세와 계획은 이 원칙을 기준으로 평가된다.
2. Specify: 사용자 관점의 요구사항 작성
Specify 단계에서는 무엇을 만들고 왜 필요한지 정리한다.
이 단계에서는 “PostgreSQL 테이블을 만든다”보다 “사용자의 데이터가 다른 기기에서도 유지되어야 한다”처럼 원하는 동작을 먼저 정의한다. 기술 선택은 Plan 단계에서 다룬다.
결과는 사용자 시나리오, 기능 요구사항, 예외 상황과 완료 조건을 포함한 spec.md로 남는다.
3. Clarify: 애매한 부분 확인
Clarify 단계에서는 AI가 명세를 읽고 빠진 내용을 질문한다. 로그인 기능이라면 다음과 같은 질문이 나올 수 있다.
- 로그인 실패 횟수를 제한하는가?
- 세션은 언제 만료되는가?
- 탈퇴한 사용자의 이메일을 다시 사용할 수 있는가?
- 인증 이메일의 유효기간은 얼마인가?
- 이메일 발송에 실패하면 어떻게 알려주는가?
답변은 다시 spec.md에 반영된다. 모호한 요구사항을 바탕으로 잘못된 설계를 만드는 일을 구현 전에 줄일 수 있다.
4. Plan: 기술적인 구현 방법 설계
Plan 단계에서는 명세를 만족시키기 위한 기술 스택과 구조를 정한다.
- Next.js App Router를 사용한다.
- 인증은 Supabase Auth를 사용한다.
- 세션은 서버에서 검증한다.
- 인증 정보는 HttpOnly 쿠키로 관리한다.
- 기존 사용자 테이블 구조를 유지한다.Specify가 “무엇을 만들 것인가”를 다룬다면, Plan은 “어떻게 만들 것인가”를 다룬다. 결과는 plan.md와 데이터 모델, API 계약 등의 설계 자료로 남는다.
5. Checklist: 요구사항의 품질 검사
Checklist는 코드가 아니라 명세 자체를 검사한다. 공식 문서는 이를 “요구사항을 위한 단위 테스트”와 비슷하게 설명한다.
- [ ] 인증 링크의 만료 시간이 정의되어 있는가?
- [ ] 이미 사용된 링크의 처리 방법이 정의되어 있는가?
- [ ] 이메일 발송 실패 시 동작이 정의되어 있는가?
- [ ] 오류 메시지가 계정 존재 여부를 노출하지 않는가?부족한 부분이 발견되면 구현을 시작하기 전에 Specify 또는 Clarify로 돌아간다.
6. Tasks: 실행 가능한 작업으로 분해
Tasks 단계에서는 설계를 실제 구현 작업으로 나눈다.
## 기반 작업
- [ ] 인증 환경변수 구성
- [ ] 사용자 테이블 마이그레이션 작성
## 회원가입
- [ ] 회원가입 서버 함수 구현
- [ ] 입력값 검증 구현
- [ ] 회원가입 화면 구현
- [ ] 이메일 인증 처리 구현
## 검증
- [ ] 정상 회원가입 테스트
- [ ] 중복 이메일 테스트
- [ ] 만료된 인증 링크 테스트작업은 의존 관계에 따라 정렬된다. AI에게 전체 앱을 한 번에 만들게 했을 때 발생하기 쉬운 누락과 대규모 수정을 줄여준다.
7. Analyze: 문서 사이의 모순 찾기
Analyze는 spec.md, plan.md, tasks.md를 비교해 다음 문제를 찾는다.
- 명세에는 있지만 작업 목록에는 없는 기능
- 명세의 조건과 충돌하는 기술 설계
- 요구사항 없이 추가된 기능
- 완료 조건이 없는 작업
- 구현 대상으로 연결되지 않은 예외 상황
요구사항 문제는 Specify나 Clarify에서, 설계 문제는 Plan에서, 작업 분해 문제는 Tasks에서 수정한다.
8. Implement: 작업 목록에 따라 구현
Implement 단계에서 AI가 실제 코드를 작성한다. 작은 기능은 한 번에 구현할 수 있지만, 규모가 크다면 범위를 나누는 편이 좋다.
데이터 모델과 회원가입 서버 기능까지만 구현한다.
로그인 UI와 비밀번호 재설정은 다음 단계에서 진행한다.
완료된 작업은 tasks.md에 표시되므로 대화가 종료되거나 새로운 세션을 시작해도 진행 상황을 복원하기 쉽다.
9. Converge: 명세와 구현 결과 비교
Converge는 완성된 코드를 명세, 설계와 작업 목록에 다시 비교한다. 누락된 부분이 없다면 구현이 명세에 수렴했다는 결과를 반환한다. 빠진 기능이 있다면 tasks.md에 보완 작업을 추가한다.
Implement → Converge → Implement → Converge단순히 화면이 보이거나 빌드가 성공했다는 이유만으로 개발을 끝내지 않고, 처음 정한 요구사항을 만족하는지 확인하는 단계다.
명세는 쌓일까, 기존 내용이 바뀔까
Spec Kit에서는 일반적으로 현재 명세를 최신 상태로 수정하고 변경 이력은 Git으로 관리한다.
같은 기능이 변경될 때마다 spec-v1.md, spec-v2.md를 계속 만들기보다는 기존 spec.md, plan.md, tasks.md를 갱신한다. 이전 내용은 Git 커밋에서 확인한다.
새 기능은 별도 디렉터리로 관리할 수 있다.
specs/
├─ 001-user-login/
│ ├─ spec.md
│ ├─ plan.md
│ └─ tasks.md
├─ 002-shopping-cart/
│ ├─ spec.md
│ ├─ plan.md
│ └─ tasks.md
└─ 003-payment/
├─ spec.md
├─ plan.md
└─ tasks.md
현재 문서는 최신 상태를 나타내고, 기능별 자료와 Git 이력이 함께 축적되는 구조다.
기존 프로젝트에 도입하기
Spec Kit을 사용하려면 Python 3.11 이상과 uv, 그리고 지원되는 AI 코딩 도구가 필요하다. Windows에서는 PowerShell 스크립트도 지원한다.
uv tool install specify-cli
specify version
새 프로젝트를 Codex와 함께 시작한다면 다음과 같이 초기화할 수 있다.
specify init my-project --integration codex --script ps
cd my-project
기존 프로젝트에서는 먼저 작업 내용을 커밋하거나 별도 브랜치를 만든다.
git switch -c setup/spec-kit
specify init --here --force --integration codex --script ps
git status
git diff--force는 파일이 있는 디렉터리에서 초기화를 허용한다. 프로젝트 전체를 삭제하지는 않지만 Spec Kit이 관리하는 경로와 기존 파일이 겹칠 수 있으므로, 초기화 직후 변경 내용을 검토해야 한다.
Codex에서는 보통 다음과 같이 실행한다.
$speckit-constitution
$speckit-specify
$speckit-clarify
$speckit-plan
$speckit-checklist
$speckit-tasks
$speckit-analyze
$speckit-implement
$speckit-converge
에이전트에 따라 명령 표기는 /speckit-*, $speckit-*, /speckit.* 등으로 달라질 수 있다.
기존 프로젝트를 전부 명세화해야 할까
그럴 필요는 없다.
이미 운영 중인 프로젝트를 도입 첫날부터 모두 분석해 완전한 명세로 바꾸면 문서 작업만 커질 수 있다. 공식 가이드도 기존 시스템 전체를 다시 명세화하지 않고, 다음에 개발할 범위가 명확한 기능부터 적용하는 방식을 안내한다.
기존 쇼핑몰에 쿠폰 기능을 추가한다면 전체 쇼핑몰을 명세화하기보다 다음 범위부터 시작할 수 있다.
쿠폰 등록
→ 쿠폰 적용 조건
→ 할인 계산
→ 중복 사용 규칙
→ 주문 취소 시 복구효과가 확인되면 로그인, 주문, 결제 등 다른 영역으로 점차 확대하면 된다.
바이브 코딩에서 Spec Kit이 유용한 이유
Spec Kit의 가장 큰 장점은 AI에게 더 긴 프롬프트를 제공한다는 데 있지 않다. 의사결정이 저장되는 위치를 채팅에서 프로젝트 파일로 옮긴다는 데 있다.
채팅은 빠르지만 시간이 지나면 과거의 결정이 묻힌다. 반면 명세, 계획과 작업 목록은 프로젝트에 남아 사람이 검토하고 Git으로 추적할 수 있다.
- AI가 처음 요구사항을 잊는 문제를 줄인다.
- 새 세션에서도 목표와 진행 상황을 복원할 수 있다.
- AI가 임의로 정한 조건을 구현 전에 발견할 수 있다.
- 큰 기능을 검토 가능한 작은 작업으로 나눌 수 있다.
- 다른 AI 코딩 도구에서도 같은 명세를 활용할 수 있다.
- 구현 완료 여부를 명확한 기준으로 판단할 수 있다.
- 팀원이 코드뿐 아니라 요구사항과 설계도 리뷰할 수 있다.
특히 로그인, 권한, 결제, 데이터베이스처럼 여러 기능이 서로 영향을 주는 프로젝트에서 효과가 크다.
Spec Kit이 항상 필요한 것은 아니다
Spec Kit에도 비용이 있다. 명세와 설계 문서가 늘어나고 각 단계의 결과를 검토해야 한다. 작은 변경에도 전체 절차를 적용하면 개발보다 문서 검토에 더 많은 시간이 들 수 있다.
도입 효과가 작은 작업
- 버튼 색상 변경
- 간단한 랜딩 페이지
- 일회성 자동화 스크립트
- 버릴 것을 전제로 만든 짧은 프로토타입
- 원인이 명확한 작은 오류 수정
도입 효과가 큰 작업
- 화면과 기능이 여러 개 연결된 서비스
- 로그인·결제·권한처럼 예외가 많은 기능
- 여러 세션에 걸쳐 개발하는 프로젝트
- 개발자 여러 명이 참여하는 프로젝트
- AI가 반복해서 요구사항을 놓치는 프로젝트
- 프로토타입을 실제 운영 서비스로 발전시키는 작업
처음부터 모든 단계를 사용할 필요는 없다. 개인 프로젝트라면 다음 흐름으로 시작해도 충분하다.
Specify → Plan → Tasks → Implement → Converge
기능이 복잡하거나 실제 서비스에 배포해야 한다면 Clarify, Checklist와 Analyze를 품질 단계로 추가하면 된다.
기업에서도 사용할 수 있을까
Spec Kit은 사내 전용 템플릿과 확장 기능, 조직별 카탈로그, 폐쇄망 설치를 지원한다. 여러 팀이 동일한 개발 원칙을 적용하거나 보안·품질 조건을 명세에 포함하려는 경우 활용할 수 있다.
다만 기업에서는 다음 문제도 함께 해결해야 한다.
- 기존 Jira·Confluence·GitHub Issues 절차와의 중복
- 명세를 작성하고 승인할 책임자
- AI가 작성한 결과에 대한 검토 기준
- 토큰 비용과 모델 사용 정책
- 소스 코드와 개인정보의 외부 전송 정책
- 커뮤니티 확장 기능의 보안 검토
Spec Kit은 2025년에 등장한 비교적 새로운 도구다. 전체 조직에 곧바로 적용하기보다 작은 팀과 하나의 기능에서 시작해 효과와 비용을 측정하는 접근이 현실적이다.
명세는 바이브 코딩의 속도를 늦추는가
처음에는 느려 보일 수 있다. 바로 코드를 생성할 수 있는데 요구사항과 계획을 먼저 검토해야 하기 때문이다.
하지만 기능이 복잡해질수록 개발 시간의 상당 부분은 코드를 입력하는 데 쓰이지 않는다. 잘못 이해한 기능을 다시 만들고, 수정 과정에서 깨진 코드를 고치고, 이전 결정을 다시 찾는 데 쓰인다.
간단한 프로토타입에서는 자유로운 바이브 코딩이 더 빠를 수 있다. 그러나 프로젝트가 커지고 유지보수가 필요해지는 시점부터는 명세가 오히려 속도를 지켜준다.
마무리
바이브 코딩은 소프트웨어를 만드는 진입 장벽을 크게 낮췄다. 아이디어를 설명하는 것만으로도 실행 가능한 결과를 얻을 수 있게 됐다. 하지만 AI가 코드를 빠르게 작성한다고 해서 요구사항까지 자동으로 명확해지는 것은 아니다.
SDD는 개발 전에 모든 것을 완벽하게 예측하자는 방법이 아니다. 현재 알고 있는 목표, 제약과 완료 조건을 명시하고, 새로운 사실이 생기면 명세를 함께 갱신하자는 방식이다.
GitHub Spec Kit은 이 과정을 다음 흐름으로 구체화한다.
무엇을 만들지 정의한다.
→ 애매한 부분을 확인한다.
→ 구현 방법을 설계한다.
→ 작업을 나눈다.
→ 구현한다.
→ 처음 정한 기준과 결과를 비교한다.
바이브 코딩의 장점은 빠른 실행과 반복이다. SDD의 장점은 방향과 기준을 유지하는 것이다. 두 방식을 함께 사용하면 AI에게 단순히 코드를 많이 생성하게 하는 것을 넘어, 원하는 결과에 도달하도록 개발 과정을 관리할 수 있다.