GitHub Spec Kit 완전 가이드 — 9만 스타, AI 에이전트에게 코드 대신 스펙을 던지는 법

AI 에이전트한테 기능 만들어달라고 했더니 돌아가긴 하는데 의도한 게 아닌 코드가 나옵니다. 다시 프롬프트 씁니다. 또 틀립니다. Vibe Coding의 끝이 이렇습니다. GitHub Spec Kit은 이 루프를 끊습니다.

[핵심 요약]
→ 정체: GitHub 공식 오픈소스, Spec-Driven Development(SDD) 툴킷
→ GitHub 스타: 90,000+ / 포크: 8,000+ (2026년 5월 기준)
→ 라이선스: MIT — 상업 이용 무료
→ 핵심: 코드가 아닌 스펙이 소스 오브 트루스
→ 4단계 워크플로우: Specify → Plan → Tasks → Implement
→ 7개 슬래시 커맨드로 전 과정 진행
→ 지원 에이전트: Claude Code, Copilot, Gemini CLI, Codex, Kiro, Cursor 등 30개+
→ 특이사항: 에이전트 락인 없음 — 한 커맨드로 에이전트 전환 가능

---

Vibe Coding vs Spec-Driven Development

Vibe Coding (기존):
→ "로그인 기능 만들어줘" → AI가 코드 생성
→ 돌아가긴 함 → 의도한 게 아님
→ 다시 프롬프트 → 또 어긋남
→ 500줄 넘어가면 에이전트가 컨텍스트 잃음
→ 1달 후 아무도 왜 이렇게 짰는지 모름

Spec-Driven Development (SDD):
→ 스펙 먼저 작성 (무엇을 / 왜 / 어떻게)
→ 스펙 → 설계 → 태스크 → 코드 순서
→ AI는 스펙을 보고 코드 생성
→ 스펙이 바뀌면 코드 재생성
→ 코드가 아닌 인텐트가 소스 오브 트루스

GitHub은 내부 프로젝트에 Spec Kit 적용 후 "처음부터 다시 짜야 하는 사이클"이 10배 감소했다고 밝혔습니다. AWS Kiro 사례에서는 40시간짜리 기능을 사람 작업 시간 8시간 이내에 완료했습니다.

---

실전 1 — 설치 및 프로젝트 초기화

# UV 먼저 설치 (Python 패키지 매니저)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 방법 1: 영구 설치 (추천)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 방법 2: 설치 없이 바로 실행
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

# 프로젝트 초기화 (Claude Code 연동)
specify init my-project --integration claude

# 현재 디렉토리에 초기화
specify init . --integration claude

# 지원 에이전트 목록 확인
specify integration list

초기화하면 .specify/ 디렉토리가 생성됩니다.

my-project/
├── .specify/
│   ├── constitution.md      # 프로젝트 헌법 (영구 규칙)
│   ├── spec.md              # 기능 스펙 (what & why)
│   ├── plan.md              # 기술 설계 (how)
│   └── tasks.md             # 구현 체크리스트
├── src/
└── ...

[초기화 시 생성되는 것들]
→ constitution.md: 프로젝트 원칙, 코딩 표준, 아키텍처 결정
→ 에이전트별 슬래시 커맨드 파일 (Claude용 /spec, /plan 등)
→ 컨텍스트 규칙 파일 (에이전트가 항상 참조)
→ .gitignore 자동 업데이트

---

실전 2 — 4단계 워크플로우 실전

1단계: /spec — 스펙 작성

에이전트 채팅에서 슬래시 커맨드를 입력합니다.

# Claude Code에서
/spec 사용자 프로필 이미지 업로드 기능

# 에이전트가 인터뷰 모드로 질문함
에이전트: 이미지 크기 제한이 있나요?
나: 최대 5MB, JPEG/PNG만 허용

에이전트: 이미지를 어디에 저장하나요?
나: S3, 업로드 후 CloudFront URL 반환

에이전트: 기존 이미지가 있을 때 어떻게 처리하나요?
나: 덮어쓰기, 이전 이미지 S3에서 삭제

자동으로 spec.md가 생성됩니다.

# spec.md (자동 생성)

## 기능: 사용자 프로필 이미지 업로드

### 목적
사용자가 프로필 이미지를 업로드하고 관리할 수 있게 한다.

### 사용자 스토리
- 사용자로서, 프로필 이미지를 업로드하여 계정을 개인화하고 싶다
- 사용자로서, 기존 이미지를 새 이미지로 교체하고 싶다

### 수락 기준 (EARS 표기법)
- WHEN 유효한 JPEG/PNG 파일(≤5MB)을 업로드하면
  THEN S3에 저장하고 CloudFront URL을 반환한다
- WHEN 이미 프로필 이미지가 있을 때 새 이미지를 업로드하면
  THEN 기존 이미지를 S3에서 삭제하고 새 이미지로 교체한다
- WHEN 5MB 초과 파일을 업로드하면
  THEN 400 에러와 명확한 에러 메시지를 반환한다
- WHEN JPEG/PNG 외 파일을 업로드하면
  THEN 415 Unsupported Media Type을 반환한다

2단계: /plan — 기술 설계

/plan

# plan.md (자동 생성)

## 기술 설계

### 아키텍처
- Presigned URL 방식 (서버 부하 최소화)
- 클라이언트 → S3 직접 업로드 → 서버에 완료 통보

### 컴포넌트
1. UploadController: Presigned URL 발급 엔드포인트
2. S3Service: Presigned URL 생성, 기존 파일 삭제
3. UserService: 프로필 URL 업데이트

### API 설계
POST /api/users/avatar/presigned
  → {presigned_url, key, expires_in}

POST /api/users/avatar/confirm
  → {avatar_url}

### 기술 스택
- AWS S3 + CloudFront
- Sharp: 이미지 리사이징 (업로드 후 처리)
- Multer: 파일 검증 미들웨어

3단계: /tasks — 구현 체크리스트

/tasks

# tasks.md (자동 생성)

## 구현 태스크

- [ ] 1. S3Service 구현
  - [ ] 1.1 Presigned URL 생성 함수
  - [ ] 1.2 파일 삭제 함수
  - [ ] 1.3 단위 테스트

- [ ] 2. UploadController 구현
  - [ ] 2.1 POST /presigned 엔드포인트
  - [ ] 2.2 POST /confirm 엔드포인트
  - [ ] 2.3 입력 검증 (파일 타입, 크기)

- [ ] 3. UserService 업데이트
  - [ ] 3.1 avatar_url 필드 추가 (DB 마이그레이션)
  - [ ] 3.2 updateAvatar() 메서드 구현

- [ ] 4. 통합 테스트 작성
- [ ] 5. CloudFront 캐시 무효화 처리

4단계: /implement — 코드 생성

/implement 1.1

에이전트가 tasks.md의 1.1 항목을 스펙과 플랜을 참조해서 구현합니다.

[4단계 워크플로우 핵심]
→ Specify: 무엇을 왜 만드는지 (비즈니스 로직)
→ Plan: 어떻게 만드는지 (기술 설계)
→ Tasks: 순서대로 뭘 해야 하는지 (체크리스트)
→ Implement: 실제 코드 생성 (에이전트가 스펙 기반으로)
→ 스펙 변경 시: /spec 업데이트 → /plan 재생성 → /implement 재실행

---

실전 3 — Constitution 파일 설정

Constitution은 Spec Kit의 "프로젝트 헌법"입니다. 모든 슬래시 커맨드가 이 파일을 참조합니다.

# .specify/constitution.md

## 프로젝트 원칙

### 기술 스택
- 언어: TypeScript strict mode
- 백엔드: NestJS + Prisma + PostgreSQL
- 인프라: AWS (Lambda, S3, RDS)
- 테스트: Jest (커버리지 80% 이상 필수)

### 코딩 표준
- 모든 함수는 단일 책임 원칙
- 에러는 Result 타입 패턴으로 처리
- API 응답: { data, error, meta } 구조 통일
- 환경변수 하드코딩 절대 금지

### 보안 정책
- 모든 엔드포인트 인증 필수 (public은 명시적 표기)
- SQL은 Prisma ORM만 사용
- 입력 검증은 zod 필수

### 금지 사항
- any 타입 사용 금지
- console.log 프로덕션 코드 금지
- 동기 파일 I/O 금지

[Constitution vs Steering(Kiro) vs CLAUDE.md 비교]
→ 공통: 영구 컨텍스트, 매 세션 자동 참조
→ Constitution: 에이전트 중립 (Claude/Copilot/Gemini 전부 읽음)
→ Steering: Kiro 전용, 여러 파일로 분리 가능
→ CLAUDE.md: Claude Code 전용
→ Spec Kit 장점: 어떤 에이전트 써도 같은 Constitution 적용

---

실전 4 — 에이전트 전환 및 Preset 활용

에이전트 전환 (락인 없음)

# Claude Code → Gemini CLI로 전환
specify integration switch gemini

# 현재 에이전트 확인
specify integration current

# 지원 에이전트 전체 목록
specify integration list
# → copilot, claude, gemini, codex, kiro,
#    cursor, windsurf, forge, amp ... (30개+)

Preset으로 워크플로우 커스터마이즈

# 사용 가능한 Preset 검색
specify preset search

# Agile 방법론 Preset 설치
specify preset add agile-workflow

# 보안 게이트 강제 Preset
specify preset add security-gates

# 한국어 로컬라이즈 Preset
specify preset add korean

# 설치된 Preset 확인
specify preset list

[Preset 활용 예시]
→ agile-workflow: 스프린트 기반 태스크 분리, 스토리포인트 추가
→ security-gates: 각 단계마다 보안 체크리스트 강제
→ regulatory: 규제 요구사항 추적 (의료/금융 등)
→ tdd-first: 테스트 먼저 작성하도록 tasks 순서 변경
→ domain-driven: DDD 패턴으로 스펙 구조 변경

---

마무리

✅ Spec Kit이 빛나는 상황
→ 그린필드 프로젝트 시작 (처음부터 스펙 주도로)
→ 레거시 재구축 (기존 의도를 스펙으로 복원 후 AI 재구현)
→ 팀 협업 (스펙 파일이 공통 언어 역할)
→ 여러 에이전트 번갈아 쓰는 팀 (에이전트 락인 없음)
→ 문서화 + 코드 일관성이 중요한 프로덕션 프로젝트

❌ Spec Kit이 맞지 않는 상황
→ 30분 안에 빠른 프로토타입 (스펙 작성 오버헤드)
→ 요구사항이 하루에도 열 번 바뀌는 초기 탐색 단계
→ 혼자서 작은 스크립트 짜는 경우
→ 이미 완성된 코드베이스에 기능 하나 추가하는 경우

---

관련 글

• Spec-Driven Development — Vibe Coding 다음 단계, AI 에이전트 개발 방법론
• AWS Kiro 완전 가이드 — Amazon Q Developer가 죽고 Spec-Driven IDE가 왔다
• Claude Code Agent Teams 실전 가이드 — 병렬 에이전트 설정부터 실전 시나리오까지
• CLAUDE.md 잘 쓰는 법 — 세션마다 시니어 개발자를 고용하는 효과
• Vibe Coding은 끝났다 — Karpathy가 선언한 Agentic Engineering 시대