Claude Code나 Cursor를 쓰다 보면 이런 경험이 한 번씩 있을 것이다. 원하는 걸 설명했고, 에이전트가 뚝딱 코드를 짜줬는데 — 컴파일도 되고, 언뜻 봐도 그럴싸한데 — 막상 돌려보면 내가 원했던 게 아니다. 그렇다고 에이전트가 못 만든 게 아니다. 내가 원하는 게 뭔지 제대로 알려주지 않은 거다.
GitHub에서 이 문제를 정면으로 다룬 오픈소스 툴킷을 내놨다. 이름은 spec-kit이다.
spec-kit이 말하는 문제: "바이브 코딩"의 한계
GitHub은 이 문제를 꽤 직접적으로 표현한다.
"우리는 AI 코딩 에이전트를 검색 엔진처럼 쓰고 있다. 그런데 에이전트는 검색 엔진이 아니라, 패턴 인식은 잘하지만 모호한 지시에는 취약한 '글자 그대로 받아들이는 페어 프로그래머'에 가깝다."
그래서 나온 개념이 Spec-Driven Development(SDD), 즉 스펙 주도 개발이다. 핵심 철학은 단순하다:
"스펙이 코드를 섬기는 게 아니라, 코드가 스펙을 섬긴다."
PRD나 스펙 문서를 구현의 참고 자료가 아니라, 구현을 생성하는 소스로 삼는다는 뜻이다.
spec-kit이란 뭔가
spec-kit은 두 가지로 구성된다:
- Specify CLI — 프로젝트를 SDD 방식으로 부트스트랩해주는 커맨드라인 툴
- 템플릿 + 슬래시 커맨드 — AI 에이전트가 실행할 수 있는 스펙 구조, 기술 계획, 태스크 분해 방식을 정의한 파일들
Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI 등 30개 이상의 AI 코딩 에이전트를 지원한다.
설치 방법
Python 3.11 이상이 필요하다. uv로 설치하는 게 공식 권장 방법이다.
# uv 설치 (없으면)
curl -LsSf https://astral.sh/uv/install.sh | sh
# specify CLI 설치
uv tool install specify-cli --from git+https://github.com/github/spec-kit
# 프로젝트 초기화
specify init
초기화하면 선택한 AI 에이전트와 플랫폼에 맞는 템플릿이 프로젝트 안에 생성된다.
핵심 워크플로: 4단계 슬래시 커맨드
spec-kit의 워크플로는 순서대로 실행하는 슬래시 커맨드로 구성된다.
1단계: /speckit.constitution
프로젝트의 불변 원칙을 세운다. 아키텍처 결정, 코딩 컨벤션, 보안 요구사항 같은 "무슨 일이 있어도 바꾸지 않을 것들"을 명문화한다.
2단계: /speckit.specify
무엇을(what) 만들 것인지, 왜(why) 만드는 건지를 기술한다. 이 단계에서는 기술 스택을 결정하지 않는다. 요구사항에 집중한다.
3단계: /speckit.plan
기술 계획을 세운다. 여기서 스택, 아키텍처, 구현 방향을 결정한다. specify에서 나온 "what"을 기반으로 "how"를 설계한다.
4단계: /speckit.tasks → /speckit.implement
계획을 AI 에이전트가 하나씩 실행할 수 있는 작은 태스크 단위로 쪼갠다. 그리고 에이전트가 태스크를 순서대로 구현한다.
이게 기존 방식과 뭐가 다른가
구분 기존 방식 (바이브 코딩) spec-kit (SDD)
| 시작점 | 프롬프트 | 스펙 문서 |
| 에이전트 역할 | 프롬프트 해석 | 스펙 실행 |
| 오류 원인 | 의도 전달 실패 | 스펙 불일치 |
| 변경 비용 | 높음 (맥락 재설명) | 낮음 (스펙 수정) |
특히 유용한 시나리오는 세 가지라고 GitHub이 강조한다:
- 그린필드 프로젝트: 처음부터 SDD로 시작하면 방향이 흔들리지 않는다
- 기존 시스템의 새 기능 추가: 기존 코드베이스의 맥락을 스펙에 담아 에이전트에게 전달한다
- 레거시 현대화: 기존 코드가 "무엇을 해야 하는지"를 스펙으로 먼저 정리한 뒤 마이그레이션
실제로 써보니
솔직히 처음엔 "그냥 문서 잘 쓰라는 거 아닌가?" 싶었다. 그런데 써보면 미묘하게 다르다.
기존에 Claude Code에 "이런 앱 만들어줘"라고 하면 에이전트가 스스로 가정을 채운다. 내가 생각하는 아키텍처가 아닐 수도 있고, 내가 원하는 라이브러리를 안 쓸 수도 있다.
spec-kit 방식은 먼저 스펙을 내가 직접 정의하고, 에이전트는 그 스펙 안에서만 움직인다. "무엇을 만들지"가 명확하게 고정되니 에이전트가 엉뚱한 방향으로 가는 일이 줄어든다. 태스크 단위로 나눠서 하나씩 구현하는 것도, 긴 컨텍스트에서 에이전트가 길을 잃는 걸 방지하는 데 효과적이다.
참고
- GitHub 레포: github/spec-kit
- 공식 블로그: Spec-driven development with AI
- 현재 GitHub 스타 111k+, 릴리즈 55회 이상 (2026년 6월 기준)