2025년 9월 GitHub은 Spec Kit이라는 새로운 개발 방식을 발표했다.
핵심은 단순하다:
“코드를 먼저 짜고 거기에 의미를 붙이는 게 아니라,
스펙을 먼저 명확히 정의하고, 그 스펙을 기반으로 AI 에이전트가 코드를 생성하는 방식으로 전환하자.”
AI 기반 코딩이 보편화되면서 생기는 문맥(shared context) 문제를 해결하려는 시도이며, GitHub Spec Kit은 이를 실무에서 일관되게 적용할 수 있는 툴킷이다.
1. 왜 Spec-Driven Development(SDD)가 필요한가?
■ 1) AI 코딩이 실패하는 이유: “문맥 부족”
AI 에이전트는 코드를 잘 짜지만, 다음 문제를 자주 만든다:
- 개발자·PM·디자이너가 각기 다른 가정을 전제로 작업
- 기능 요구사항이 코드 곳곳에 암묵적으로 흩어져 유지보수 난이도 급증
- 코드 자체가 스펙이 되면서, 문제 정의가 뒤늦게 나타남
- 변경 비용이 커지고 팀의 사고가 코드에 갇힘(lock-in)
즉, “무엇을 만들고 왜 만드는가”가 명확하지 않으면
AI는 문제를 더 심각하게 악화시킨다.
■ 2) 코드 → 스펙이 아니라
스펙 → 코드 로 방향을 바꿔야 한다
코드는 한번 작성되면 강력한 제약이 된다.
그래서 스펙 없이 바로 코드부터 작성하면:
- 기능 정의의 오해가 뒤늦게 발견됨
- 아키텍처 변경 비용이 폭증
- 여러 사람·여러 AI 에이전트가 들어오면 혼란 가중
→ 즉, 코드를 기반으로 협업·의사결정하는 방식은 한계
SDD는 이 문제를 해결하기 위한 개발 문화이다.
2. Spec-Driven Development(SDD)란 무엇인가?
잘못된 오해 3가지
SDD는 다음과 다르다:
- ❌ “문서만 잔뜩 쓰는 워터폴 방식”
- ❌ “상세 스펙 200페이지 만들기”
- ❌ “팀 속도 늦추는 관료주의”
SDD의 실제 목적
기술적 결정의 ‘이유’를 명확하게 만들고,
이를 살아있는(living) 문서로 유지하는 것.
SDD는 다음을 해결한다:
- 팀 전체의 공유 문맥 정렬(shared context alignment)
- “왜 이런 구조인가?”를 문서 기반으로 바로 이해
- 의사결정 과정이 명확해져 유지보수 비용 감소
- 다양한 AI 에이전트가 일관된 기준으로 작업 가능
3. GitHub Spec Kit이 제공하는 기능
Spec Kit은 SDD를 실제로 실천하게 해주는 도구이며 구성은 두 가지:
3.1 Specify CLI
프로젝트를 SDD 구조로 자동 셋업해주는 CLI
설치 예시:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>실행 후 선택하게 되는 항목:
- 사용할 AI 에이전트(Copilot, Claude, Cursor 등)
- 플랫폼에 맞는 템플릿 자동 구성
CLI가 하는 일:
.specify/폴더 생성.github/prompts/(에이전트별 프롬프트 생성)- 스펙/플랜/태스크 템플릿 다운로드
- Git 저장소 자동 초기화
3.2 템플릿 & 스크립트
Spec Kit은 아래 구조를 생성한다:
.github/
prompts/
plan.prompt.md
specify.prompt.md
tasks.prompt.md
.specify/
memory/
constitution.md
constitution_update_checklist.md
scripts/
powershell/
check-task-prerequisites.ps1
...
templates/
spec-template.md
plan-template.md
tasks-template.md
agent-file-template.md핵심 파일 설명
✔ spec-template.md
→ "무엇을 만들 것인가" 정의 (기능 요구사항 중심)
✔ plan-template.md
→ "어떻게 만들 것인가" 정의 (기술 스택, 구조, 데이터 계약)
✔ tasks-template.md
→ 계획을 실행 가능한 작업 단위로 분해
✔ constitution.md
→ 프로젝트의 불변 원칙(Non-negotiable rules)
(예: 테스트 커버리지 규칙, CLI 우선 규칙 등)
SDD의 핵심은 “의사결정의 기준”을 명문화하고
AI 에이전트가 이를 준수하도록 만드는 것.
4. Slash Commands – SDD 흐름의 핵심
GitHub Spec Kit은 에이전트가 직접 프롬프트를 만들어두었기 때문에
다음 세 가지 명령어만 사용하면 된다.
4.1 /specify
무엇을 만들까? 왜 필요한가?
- PRD 초안 생성
- 기능의 목적과 사용 사례
- 사용자 경험 요구사항
- 제약조건 명시
기술적 구현 내용은 배제됨
(기술 선택은 /plan 단계)
4.2 /plan
기능을 어떻게 만들 것인가?
- 기술 스택, 프레임워크
- API/DB 구조
- 연구 자료(Research)
- 데이터 계약(Data Contract)
- Quickstart
이 단계는 constitution.md를 기반으로 제한된다.
예:
"프론트는 React만 사용한다"
"테스트는 Vitest로 작성해야 한다"
4.3 /tasks
계획을 작업 단위로 분해
- Phase별 태스크 나누기
- 에이전트가 직접 구현할 작업 목록 생성
- 의존성/순서 정의
- 커밋 전략까지 자동화 가능
5. 전체 흐름 예시
Step 1. /specify 실행 → 스펙 파일 생성
→ 리뷰 및 수정
Step 2. /plan 실행 → 기술 계획 파일 생성
→ 리뷰 및 수정
Step 3. /tasks 실행 → 실행 가능한 태스크 목록 생성
→ 리뷰 후 에이전트에게 구현 요청
이후:
- 에이전트가 각 태스크별로 브랜치·파일 생성
- Git 상태 관리 자동화
- 스펙과 계획은 계속 수정·조정 가능(living docs)
6. 왜 SDD가 AI 시대에 중요한가?
✔ AI는 코드만 바탕으로 이해하기엔 너무 비싸다
코드 기반 컨텍스트 제공만으로는 모델 비용 폭발 → 비효율
✔ 스펙은 가장 강력한 컨텍스트 입력
에이전트는 markdown 기반 구조적 문서 입력을 잘 처리함
✔ 여러 AI 에이전트가 동시에 움직여도 통일성 유지됨
✔ A/B 아키텍처 실험도 쉬워진다
예:
“동일 스펙으로 Rust 버전 + Go 버전 2가지 만들어줘”
✔ 모호한 요구사항으로 인한 팀 파편화 줄어듦
(SDD의 핵심 가치)
7. 결론 — 이제 “코드가 스펙”인 시대는 끝났다
GitHub Spec Kit은 단순한 템플릿 툴이 아니다.
“AI 기반 개발 시대에 필요한 팀 공유 컨텍스트 관리 방식”을 정착시키는 도구이다.
새로운 기능 하나 만들 때도,
버그를 수정할 때도,
코드보다 스펙이 먼저여야 한다.
Spec Kit은 이 원칙을
VSCode, GitHub, AI 에이전트 환경에 직접 녹여낸 SDD 실천 도구이다.
