GitHub Spec Kit 실전 가이드 — Spec-Driven Development 도구화
Vibe→Spec 철학의 도구화 공백을 메운다. GitHub Spec Kit의 Specify CLI 설치부터 커맨드 체인 4단계·보조 커맨드·Hooks·Subagent·Evals 워크플로우와의 결합 지점, 그리고 Spec Slop 함정과 constitution vs CLAUDE.md 책임 분리까지 정리했다.
들어가며
Vibe Coding에서 Spec-Driven Development로는 왜 스펙 중심으로 개발해야 하는지를 다뤘다. 이 글은 그다음 질문에 답한다: 어떻게 도구화하는가?
철학은 도구 없이 현장에 안착하지 않는다. GitHub의 Spec Kit은 SDD를 CLI 수준의 반복 가능한 워크플로우로 만들기 위한 도구다. 이 글은 Spec Kit README를 1차 자료로 삼아 Specify CLI의 설치·커맨드 체인·보조 커맨드를 정리하고, 이 블로그의 Hooks·Subagent·Evals 패턴과의 결합 지점을 제시한다.
1. SDD란 무엇인가 — Spec Kit의 정의
“Specifications Become Executable”
GitHub Spec Kit README의 핵심 명제는 하나다: specifications become executable.1 스펙은 문서가 아니라 에이전트가 실행하는 입력이 된다.
이 관점에서 SDD(Spec-Driven Development, 스펙 기반 개발)는 세 가지를 전제한다.
- Intent-driven(의도 중심): AI 에이전트에게 코드를 지시하는 것이 아니라, 의도(intent) 를 스펙으로 기술하고 에이전트가 그 스펙을 실행하도록 한다.
- Executable artifact(실행 가능한 산출물):
spec.md,plan.md,tasks.md는 에이전트가 파싱하고 실행 계획에 반영할 수 있는 구조화된 파일이다. - 30+ agent integrations: Spec Kit은 Claude Code, GitHub Copilot, Cursor 등 30개 이상의 AI 에이전트 통합 옵션을 제공한다. 어느 에이전트를 쓰더라도 동일한 스펙 구조가 입력으로 들어간다.1
Vibe→Spec 철학의 도구화 위치
Vibe→Spec 전환 가이드에서 SDD의 철학을 정리했다. Spec Kit은 그 철학의 실행 레이어다.
| 레이어 | 내용 | 담당 |
|---|---|---|
| 철학 | Intent-driven, Machine-readable spec | 개발자 판단 |
| 도구 | Specify CLI, slash commands, 산출물 4종 | Spec Kit |
| 실행 | AI 에이전트 구현 | Claude Code 등 |
Spec Kit은 “스펙을 어디에 어떻게 쓸 것인가”를 규격화한다. 스펙을 쓸지 말지는 여전히 개발자의 판단이다.
2. 설치와 초기화
요구사항 및 설치
Specify CLI는 Python 3.11 이상과 uv 도구가 필요하다. README가 제시하는 정확한 설치 명령은 다음과 같다.1
1
2
3
4
5
6
7
8
# Python 3.11+ 확인
python --version
# Specify CLI 설치 (vX.Y.Z는 최신 릴리스 태그로 교체)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
# 설치 확인
specify --version
pip install 대신 uv tool install을 사용하는 이유는, uv가 격리된 환경에 도구를 설치하여 프로젝트 Python 환경을 오염시키지 않기 때문이다.
프로젝트 초기화
1
2
3
4
5
# GitHub Copilot 통합 예시 (README 표기)
specify init my-project --integration copilot
# 현재 디렉토리에 초기화
specify init .
--integration <agent> 플래그가 핵심이다. README는 “30+ AI 코딩 에이전트 통합 지원” 을 명시하며, 실제 사용 가능한 에이전트 값은 최신 README의 통합 카탈로그에서 확인한다.1
출력 디렉토리 구조
specify init 실행 후 프로젝트 루트에 다음 구조가 생성된다.
1
2
3
4
5
6
7
8
my-project/
├── .specify/
│ └── constitution.md # 프로젝트 헌법
├── specs/
│ ├── spec.md # 기능 스펙
│ ├── plan.md # 구현 계획
│ └── tasks.md # 세분화된 태스크
└── ...
.specify/constitution.md는 프로젝트의 변하지 않는 규약이다. specs/ 하위 파일들은 기능별로 생성·갱신된다.
3. 커맨드 체인 4단계
Spec Kit의 핵심은 5개 핵심 슬래시 커맨드(slash command) 체인이다. 모든 단계는 CLI가 아닌 AI 에이전트와의 대화 안에서 호출하는 슬래시 커맨드 다 — specify CLI는 프로젝트 초기화(specify init)와 확장·프리셋 관리용이며, 스펙 생성·계획·태스크·구현은 모두 슬래시 커맨드로 진행한다.1
flowchart TD
A[요구사항 / GitHub Issue] --> B["/speckit.constitution\n에이전트 슬래시 커맨드"]
B --> B2["constitution.md\n프로젝트 헌법"]
B2 --> C["/speckit.specify\n에이전트 슬래시 커맨드"]
C --> C2["spec.md\n기능 스펙"]
C2 --> D["/speckit.plan\n에이전트 슬래시 커맨드"]
D --> D2["plan.md\n구현 계획"]
D2 --> E["/speckit.tasks\n에이전트 슬래시 커맨드"]
E --> E2["tasks.md\n세분화 태스크"]
E2 --> F["/speckit.implement\n에이전트 슬래시 커맨드"]
style B fill:#e3f2fd,stroke:#1565c0
style B2 fill:#bbdefb,stroke:#1565c0
style C fill:#e8f5e9,stroke:#2e7d32
style C2 fill:#c8e6c9,stroke:#2e7d32
style D fill:#fff3e0,stroke:#e65100
style D2 fill:#ffe0b2,stroke:#e65100
style E fill:#fce4ec,stroke:#c62828
style E2 fill:#f8bbd0,stroke:#c62828
style F fill:#4caf50,color:#fff
1단계: /speckit.constitution — 헌법 정의
AI 에이전트(Claude Code, Copilot 등)와의 대화에서 /speckit.constitution을 입력하면 에이전트가 프로젝트의 불변 규약을 작성한다.
constitution.md에는 다음이 포함된다:
- 프로젝트의 핵심 목적과 설계 원칙
- 코드 컨벤션과 아키텍처 제약
- 에이전트가 따라야 할 금지 패턴
2단계: /speckit.specify — 스펙 생성
에이전트 대화에서:
1
/speckit.specify 로그인 기능 구현
자연어 요구사항을 입력으로 받아 구조화된 spec.md를 생성한다. 스펙에는 완료 기준(Acceptance Criteria), 범위, 제약 조건이 포함된다. AI가 문서를 생성하므로 결과물은 반드시 사람이 검토·확정해야 한다.
3단계: /speckit.plan — 구현 계획
1
/speckit.plan
spec.md를 읽고 에이전트가 실행할 수 있는 plan.md를 생성한다. 어떤 파일을 어떤 순서로 수정할지, 어떤 판단을 내렸는지가 명시된다.
4단계: /speckit.tasks + /speckit.implement
1
2
/speckit.tasks
/speckit.implement
tasks.md는 plan.md를 에이전트가 체크오프할 수 있는 원자적(atomic) 태스크 목록으로 분해한다. /speckit.implement는 이 태스크 목록을 따라 구현을 진행한다. README는 추가로 /speckit.taskstoissues(tasks를 GitHub issue로 변환)도 핵심 커맨드로 제공한다.1
4개의 파일(constitution · spec · plan · tasks)이 모두 Git 이력에 남는다. “왜 이렇게 구현됐는가”를 추적할 수 있는 스펙 이력이 자동으로 형성된다.
4. 보조 커맨드
Spec Kit은 메인 체인 외에 3가지 보조 슬래시 커맨드를 제공한다.1 모두 AI 에이전트와의 대화 안에서 호출하는 slash command다.
/speckit.clarify — 명세 명확화
스펙의 모호한 부분을 에이전트가 질문 형식으로 되짚어 명확화한다. /speckit.specify 전에 사용하면 스펙 품질이 높아진다. 요구사항이 불명확할 때 먼저 /speckit.clarify를 호출하고, 명확화된 요구사항으로 /speckit.specify를 실행하는 것이 권장 순서다.
/speckit.analyze — 코드베이스 분석
/speckit.specify 전에 기존 코드베이스를 분석한다. 스펙이 현재 구조와 충돌하는 부분, 재사용 가능한 기존 컴포넌트를 사전에 파악한다. 신규 기능보다 기존 코드베이스에 기능을 추가하는 상황에서 특히 유용하다.
/speckit.checklist — 구현 완료 체크리스트
구현 후 spec.md의 완료 기준 대비 실제 구현을 항목별로 점검한다. 체크리스트가 통과되지 않으면 구현이 완료된 것으로 보지 않는다.
Plan Mode와의 비교
Plan Mode 가이드에서 ExitPlanMode가 세션 내 승인 게이트로 동작한다고 설명했다. Spec Kit의 커맨드 체인과는 성격이 다르다.
| 항목 | Spec Kit | Plan Mode |
|---|---|---|
| 산출물 위치 | 파일 시스템 (spec.md 등) | 세션 내 계획서 |
| 지속성 | Git 이력에 영구 보존 | 세션 종료 시 소멸 |
| 주요 목적 | 외부 명세 산출물 생성 | 세션 내 승인 게이트 |
| 활용 범위 | 에이전트 독립적 | Claude Code 전용 |
두 접근은 상호 보완적이다. Spec Kit으로 외부 산출물을 만들고, Plan Mode로 각 단계의 세션 내 승인을 받는 패턴을 조합하면 이중 게이트(dual gate)가 된다.
5. 우리 워크플로우와 결합
Hooks — Lifecycle 자동화 입력으로 spec 활용
Hooks 가이드에서 SessionStart 훅이 컨텍스트를 자동 주입한다고 다뤘다. spec.md와 tasks.md를 SessionStart 훅 입력으로 넣으면, 에이전트가 세션을 시작할 때마다 현재 스펙과 태스크 상태를 자동으로 인식한다.
1
2
3
4
5
6
7
{
"hooks": {
"SessionStart": [{
"command": "cat specs/spec.md specs/tasks.md"
}]
}
}
PostToolUse 훅을 활용하면 specify tasks가 실행된 직후 태스크 목록을 알림으로 전송하는 자동화도 가능하다. 스펙 산출물이 파일로 존재하기 때문에 훅의 입력으로 쉽게 참조할 수 있다는 것이 핵심이다.
Subagent 패턴 — specify implement에서 분기 재사용
서브에이전트 설계 패턴에서 Orchestrator-Worker 패턴을 다뤘다. tasks.md는 이 패턴의 자연스러운 입력이 된다.
tasks.md의 각 태스크를 독립적인 worker 에이전트에게 분배하고, orchestrator가 완료를 집계하는 구조다.
1
2
3
4
5
6
Orchestrator
└─ tasks.md 파싱
└─ Worker-1: 태스크 A (독립적)
└─ Worker-2: 태스크 B (독립적)
└─ Worker-3: 태스크 C (독립적)
└─ Verifier: 완료 기준 대비 검증 (/speckit.checklist)
specify implement의 내부 로직이 이 패턴을 구현한다. 자체 워크플로우에서도 tasks.md를 파싱하여 동일한 분기 패턴을 재사용할 수 있다.
Evals — golden set으로 spec 재활용
AI 코딩 Evals 가이드에서 골든셋(golden set) 설계를 다뤘다. spec.md의 완료 기준(Acceptance Criteria)은 eval의 골든셋 항목과 구조적으로 동일하다.
1
2
3
4
# spec.md의 완료 기준 → eval 골든셋으로 변환
golden_cases = parse_acceptance_criteria("specs/spec.md")
results = run_evals(agent, golden_cases)
assert results.pass_rate >= 0.95
스펙을 먼저 작성하면 eval 골든셋 작성 비용이 줄어든다. 스펙과 eval이 같은 소스에서 나오므로 기준의 일관성도 보장된다.
6. 한계와 함정
30+ 에이전트 통합의 일관성 미보장
Spec Kit이 30개 이상의 AI 에이전트를 지원한다는 것은 강점이지만, 동시에 함정이기도 하다. 도구마다 슬래시 커맨드 해석 방식, 파일 접근 권한, 컨텍스트 창 크기가 다르다. constitution.md에 동일한 규약을 써도 에이전트별로 해석이 달라질 수 있다.
실용적 대응: 팀에서 메인으로 쓰는 에이전트 1~2개를 정하고, 그 에이전트에서 검증된 패턴을 constitution.md에 고정한다. 모든 통합을 동시에 쓰려는 시도는 일관성 문제를 악화시킨다.
/speckit.specify의 환각 위험
specify specify가 생성하는 spec.md는 AI가 작성한 문서다. AI는 요구사항의 빈칸을 창의적으로 채운다. 이때 존재하지 않는 API, 잘못된 데이터 모델, 불가능한 성능 목표가 스펙에 포함될 수 있다.
생성된 spec.md는 반드시 사람이 검토한 후 확정한다. AI가 생성한 스펙을 검토 없이 다음 단계로 넘기는 것은 vibe coding과 다를 바 없다.
스펙 검토 게이트를 생략하면, “잘 구조화된 방식으로 틀린 일을 한다”는 역설이 생긴다.
명세 슬롭(Spec Slop) 위험과 Comprehension Debt
AI가 스펙을 생성한다는 것은 명세 슬롭(spec slop) 위험을 내포한다. 양은 많지만 실질적 정보 밀도가 낮은 스펙이 쌓이는 현상이다. AI 기술부채와 Comprehension Debt에서 코드 레벨의 동일한 문제를 다뤘다. 코드에서 Comprehension Debt가 쌓이듯, 스펙에서도 이해 없이 쌓이는 부채가 발생한다.
명세 슬롭의 징후:
spec.md가 100줄인데 완료 기준이 모호하다plan.md가 구현을 지시하지 않고 현황을 설명한다tasks.md에 체크오프 기준이 없는 태스크가 있다
명세 슬롭을 막는 방법은 단순하다: /speckit.checklist로 구현 완료 전에 반드시 기준 대비 점검한다. 체크리스트가 통과되지 않는 스펙은 스펙이 아니라 메모다.
7. 시작하기
최소 한 사이클 돌리기
Spec Kit의 가치는 설치보다 한 사이클을 완주해봐야 실감된다. 규모가 작고 독립적인 기능 하나를 골라 다음 순서로 진행한다.
터미널 (CLI):
1
2
3
# 1. 초기화 (사용 가능한 통합 값은 README 카탈로그 참조)
specify init my-feature --integration copilot
cd my-feature
에이전트 대화 (Claude Code / Copilot 등에서 슬래시 커맨드):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 2. 헌법 정의
/speckit.constitution
# 3. 요구사항 명확화 (선택)
/speckit.clarify
# 4. 스펙 생성
/speckit.specify 사용자 프로필 사진 업로드 기능
# 5. spec.md 검토 및 확정 (사람이 직접 확인·수정)
# 6. 계획 → 태스크 → 구현
/speckit.plan
/speckit.tasks
/speckit.implement
# 7. 완료 체크
/speckit.checklist
이 흐름을 한 번 완주하면 산출물 4종(constitution.md · spec.md · plan.md · tasks.md)이 Git 이력에 남는다.
PR에 산출물 4종 동봉하기
구현이 완료되면 PR에 스펙 산출물을 포함시킨다.
1
2
3
4
5
6
7
8
9
10
PR #123: 사용자 프로필 사진 업로드
변경 파일:
- src/upload.ts
- tests/upload.test.ts
첨부 스펙 산출물:
- specs/spec.md ← 완료 기준 확인용
- specs/plan.md ← 설계 판단 추적용
- specs/tasks.md ← 구현 범위 확인용
리뷰어는 스펙 산출물을 보고 “코드가 스펙대로 구현됐는가”를 기준으로 리뷰할 수 있다. AI 생성 코드에 대한 리뷰 기준이 생긴다.
Constitution vs CLAUDE.md — 책임 분리
CLAUDE.md · AGENTS.md 설계 패턴에서 CLAUDE.md의 역할을 다뤘다. Spec Kit의 constitution.md와 CLAUDE.md는 성격이 다르며, 혼용하면 에이전트가 어느 규약을 우선해야 하는지 모호해진다.
| 파일 | 범위 | 내용 | 변경 빈도 |
|---|---|---|---|
constitution.md | 기능/피처 단위 | 이 기능의 설계 원칙, 제약 | 기능마다 갱신 |
CLAUDE.md | 저장소 전체 | 코드 컨벤션, 금지 패턴, 범위 제한 | 드물게 변경 |
constitution.md는 스펙 사이클마다 새로 정의되는 기능별 헌법이고, CLAUDE.md는 저장소 전체에 적용되는 항구적 규약이다.
CLAUDE.md는 “이 저장소에서 항상 성립하는 것”을 담고,constitution.md는 “이 기능을 구현하는 동안 성립하는 것”을 담는다. 두 파일의 책임을 분리해두면 에이전트가 충돌 없이 두 규약을 동시에 적용할 수 있다.
마치며
GitHub Spec Kit은 SDD를 파일 시스템 수준의 반복 가능한 워크플로우로 만든다. 철학을 아는 것과 실제로 도구를 쓰는 것 사이의 간격을 좁히는 것이 이 글의 목적이었다.
설치하고 초기화하는 것보다 더 중요한 것이 있다. 생성된 스펙을 검토하는 인간 게이트, 명세 슬롭을 막는 /speckit.checklist, 그리고 constitution.md와 CLAUDE.md의 명확한 책임 분리다.
도구는 의도를 실행한다. 의도가 불명확하면 도구도 불명확하게 실행된다. Spec Kit을 최대한 활용하려면 명확한 의도를 스펙으로 먼저 작성하는 습관이 선행되어야 한다.
관련 글:
- Vibe Coding에서 Spec-Driven Development로 — 2026 실무 전환 가이드
- Claude Code Hooks 완전 가이드 — Lifecycle 이벤트와 자동화·보안 가드
- Claude Code 서브에이전트 설계 패턴 — 언제·어떻게 쪼갤 것인가
- Claude Code Plan Mode 실전 활용 — ExitPlanMode와 승인 게이트
- AI 코딩 에이전트 평가(Evals) — Anthropic Evals 프레임으로 회귀 잡기
- AI 기술부채 회수 전략 — Comprehension Debt 시대의 생존법
- CLAUDE.md · AGENTS.md 설계 패턴 — 200 라인 원칙과 모듈화