GitHub Spec Kit 완벽 가이드: 바이브 코딩 끝, 명세 기반 개발 시작 (2026)

"Claude Code한테 시켰는데 왜 매번 다른 코드가 나오죠?" — 요즘 가장 자주 듣는 질문이다.

문제는 모델이 아니라 명세 없이 분위기로 던지는 프롬프트에 있다. GitHub가 9월 공개한 Spec Kit은 이 "바이브 코딩"의 한계를 정면으로 겨냥한 공식 툴킷이다. 이 글에서는 specify CLI 설치부터 /specify /plan /tasks /implement 4단 워크플로우, Windows 환경 트러블슈팅까지 한 번에 정리한다.

📌 핵심 3줄 요약

• Spec Kit은 의도 → 명세 → 계획 → 작업 → 구현으로 단계를 쪼개 AI 에이전트가 코드를 만들기 전에 "무엇을 만들지" 합의하게 만든다.
• specify init 한 줄로 Claude Code, Copilot, Cursor, Gemini CLI 중 원하는 에이전트와 즉시 연동된다.
• Windows는 Python 3.11 이상 + Git Bash가 사실상 필수다. PATH·uv 설치만 잡으면 30분이면 첫 스펙을 돌릴 수 있다.

1. Spec-Driven Development가 바이브 코딩과 다른 점

바이브 코딩(vibe coding)은 자연어 한 줄로 결과물을 즉석에서 뽑아내는 방식이다. 빠르지만 같은 프롬프트에서 다른 결과가 나오고, 두 번째 기능을 붙이는 순간 첫 번째 코드가 뒤집힌다.

Spec-Driven Development(SDD)는 그 사이에 명세 산출물 3종(spec, plan, tasks)을 끼워 넣는다. 명세가 1급 산출물이고 코드는 그것의 표현이라는 관점이다.

항목	바이브 코딩	Spec-Driven Development
입력	즉흥 프롬프트 1줄	/specify로 작성한 사용자 시나리오
중간 산출물	없음 (코드로 직행)	spec.md → plan.md → tasks.md
재현성	모델 온도에 좌우	동일 spec → 동일 task 트리
기능 추가	컨텍스트 누락 빈번	기존 spec에 변경 분기 추가
적합 상황	1회용 스크립트, 프로토타입	그린필드, 레거시 현대화, 병렬 구현 비교

💡 핵심 한 줄

핵심 차이는 모델 교체 비용이다. spec.md가 남아 있으면 다음 분기에 Gemini로 바꾸든, 같은 코드를 Rust로 다시 짜든 출발점이 동일하다.

2. 설치 — specify init으로 5분 안에 끝내기

공식 요구사항은 Linux/macOS 또는 Windows + WSL2, Python 3.11+, uv 패키지 매니저, Git, 그리고 지원 AI 에이전트 중 하나다. 가장 깔끔한 단축키는 uv tool 한 줄이다.

terminal · bash

# uv 설치 (없다면)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Spec Kit 초기화 (현재 폴더에 .specify/ 생성)
uvx --from git+https://github.com/github/spec-kit.git specify init --here

처음 실행하면 어떤 AI 에이전트를 쓸지 묻는다. 화살표로 고르면 끝.

specify init · 콘솔 출력

$ uvx --from git+https://github.com/github/spec-kit.git specify init --here
Specify CLI v0.0.45

? Which AI agent do you want to use?
  > Claude Code
    GitHub Copilot
    Cursor
    Gemini CLI
    Qwen Code

? Which script style?
  > sh (POSIX shell)
    ps (PowerShell)

✓ Created .specify/memory/constitution.md
✓ Created .specify/templates/spec-template.md
✓ Created .specify/templates/plan-template.md
✓ Created .specify/scripts/sh/* (8 scripts)
✓ Registered slash commands: /constitution /specify /clarify /plan /tasks /analyze /implement

Run 'specify check' to verify your environment.

설치 검증은 specify check로 한다. 누락된 도구가 있으면 색깔로 알려준다.

specify check · 콘솔 출력

$ specify check
✓ git              2.45.0
✓ python           3.12.3
✓ uv               0.5.11
✓ claude (CLI)     1.0.20
✗ gh (optional)    not found  → install for PR automation

3. Windows 환경 트러블슈팅 표

WSL2를 쓰면 사실 별 문제 없지만, 네이티브 Windows + Git Bash 조합으로도 돌릴 수 있다. 다만 막히는 지점이 정해져 있다.

증상	원인	해결
specify: command not found	uv tool bin 경로 PATH 미등록	$env:Path += ";$HOME\.local\bin" 후 PowerShell 재시작
Python 3.11+ required	시스템 Python 3.10 이하	uv python install 3.12로 격리 설치 후 자동 인식
'specify' is not a git command	슬래시 명령이 Claude Code에 등록 안 됨	프로젝트 루트에서 specify init --here 재실행
.specify/scripts/sh/*.sh 실행 실패	sh 스크립트인데 PowerShell에서 호출	init 시 script style을 ps로 선택, 또는 Git Bash 사용
한글 spec.md 인코딩 깨짐	Windows 콘솔 CP949 기본	chcp 65001 또는 PowerShell에서 [Console]::OutputEncoding을 UTF-8로
/specify 호출 후 응답 없음	Claude Code가 .specify/templates 인식 못함	Claude Code 재시작, --ignore-agent-tools 없이 init했는지 확인

⚠️ 흔한 실수

5번 인코딩 이슈는 한국어 spec을 처음 작성할 때 거의 반드시 만난다. 미리 콘솔 코드페이지를 UTF-8로 바꿔두면 시간을 절약한다.

4. 첫 워크플로우 — /specify → /plan → /tasks → /implement

Claude Code를 열고 .specify가 있는 폴더에서 시작한다. 4개 슬래시 명령이 순서대로 호출된다.

Claude Code · /specify 호출 결과

> /specify

사용자 스토리를 자연어로 입력하세요 (구현 디테일은 빼고):
> 사내 위키 검색 API. 사용자가 키워드 입력 시 제목·본문에서 매칭되는 문서 상위 10건 반환.
  답변 시간 300ms 이하. 한국어 토크나이저 필수.

✓ Branch '001-wiki-search' created
✓ Generated specs/001-wiki-search/spec.md
  - 5 user stories
  - 12 functional requirements
  - 3 [NEEDS CLARIFICATION] markers

spec.md가 생기면 즉시 열어 [NEEDS CLARIFICATION] 마커를 채운다. 비워두면 /plan 단계에서 막힌다. 그다음:

• /clarify — 모호한 요구사항을 대화형으로 확정 (선택)
• /plan — 기술 스택과 아키텍처 결정. "FastAPI + Elasticsearch + 한국어 nori 토크나이저" 같은 구현 방향을 여기서 명시
• /tasks — plan.md를 읽어 의존성 순서로 정렬된 작업 트리 생성
• /implement — 첫 작업부터 차례로 실행. 각 단계에서 테스트가 통과해야 다음으로 넘어간다

이 흐름의 가장 큰 이득은 /plan까지 끝낸 명세를 그대로 다른 에이전트에 던질 수 있다는 점이다. 같은 spec을 Copilot으로 한 번, Cursor로 한 번 구현시켜 비교하는 "병렬 구현"이 공식 가이드에 명시된 사용 사례다.

⚠️ 직접 써보고 느낀 한계와 주의점

장점만 있는 도구는 없다. SDD를 며칠 굴려보면 다음 지점에서 마찰이 생긴다.

• 초기 스펙 작성 비용: 30분짜리 스크립트도 spec → plan → tasks 거치면 1시간이 된다. 1회용 작업엔 과한 의식이다.
• 모호한 요구사항을 잘 잡지 못함: /specify는 사용자가 빠뜨린 비기능 요구(성능·보안)를 알아서 추가해주지 않는다. constitution.md에 팀 규칙을 미리 박아두는 게 사실상 필수다.
• 레거시 통합은 별도 작업: 기존 코드베이스에 --here 옵션으로 붙일 수는 있지만, 기존 아키텍처와 spec이 충돌하면 /plan이 엉뚱한 방향으로 간다. 사전에 "현재 시스템 요약" 문서를 한 장 만들어두는 게 안전하다.
• 버전 변화 속도: 0.0.x 단계라 슬래시 명령 이름이 자주 바뀐다. 9월 초기 버전엔 /clarify가 없었고, /analyze는 최근 추가됐다. 팀 위키에 박제하면 곧 어긋난다.

이런 한계를 알고 쓰면 "AI가 짠 코드를 PR에서 검토 못 하겠다"는 흔한 고민의 절반은 해결된다.

✅ 핵심 정리

• Spec Kit은 spec → plan → tasks → implement 4단계로 AI 에이전트의 코드 생성 전 단계를 명세화한다.
• uvx specify init --here 한 줄이면 Claude Code · Copilot · Cursor 등과 즉시 붙는다.
• Windows는 Python 3.11+, PATH, UTF-8 콘솔 인코딩 3가지만 잡으면 네이티브에서도 무리 없다.
• spec.md가 남기 때문에 같은 명세를 여러 에이전트로 병렬 구현해 비교할 수 있다.

🚀 지금 바로 할 일

1. Python 3.11 이상이 있는 환경에서 uv tool install 또는 uvx 한 줄로 spec-kit 설치
2. 작은 기능 1개(예: TODO 리스트 REST API) 골라 /specify → /plan → /tasks까지만 돌려보기
3. 생성된 spec.md plan.md를 팀에 공유하고 PR 리뷰 방식이 어떻게 바뀌는지 확인

💬 의견

바이브 코딩 워크플로우와 비교했을 때 가장 큰 변화가 느껴진 지점이 어디였는지 댓글로 공유 부탁한다. spec 단계에서 막혔던 경험도 환영.

🔗 참고 자료

• GitHub 공식 spec-kit 저장소: https://github.com/github/spec-kit
• spec-driven.md (Spec-Driven Development 개념 정리): https://github.com/github/spec-kit/blob/main/spec-driven.md
• uv (Python 패키지 매니저): https://github.com/astral-sh/uv

---

작성자: AI 개발 워크플로우를 매일 굴리는 한국어 기술 블로거. 직접 시도해본 환경은 Windows 11 + WSL2 Ubuntu 24.04 / Python 3.12.3 / uv 0.5.11 / Claude Code 1.0.20 / spec-kit v0.0.45. 같은 spec을 네이티브 PowerShell에서도 재현해 트러블슈팅 표를 작성했다.