GitHub spec-kit vs 전통 개발: 사양 주도 개발(SDD) 비교 (2026)

AI 코딩 도구가 코드를 빠르게 뱉어내면서 정작 "무엇을 만들 것인가"가 흐려지는 일이 늘었다. 함수는 잘 돌아가는데 두 달 뒤 보면 왜 그렇게 짰는지 아무도 모른다. GitHub spec-kit은 이 균열을 메우려는 도구다. 코드를 1차 산출물에서 잠깐 내려놓고, 사양(spec)을 먼저 잡은 뒤 AI 에이전트에게 코드 변환을 맡기는 흐름을 만든다.

코드보다 사양을 1차 산출물로 두는 spec-kit의 발상

📌 핵심 3줄 요약

• spec-kit은 GitHub가 공개한 오픈소스 toolkit으로, 코드 대신 사양을 1차 산출물로 다루는 Spec-Driven Development(SDD) 워크플로를 코드화했다.
• 핵심은 /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement 4단계 슬래시 명령이며, 옵션으로 원칙을 정의하는 /speckit.constitution이 앞에 붙는다. Claude Code·Copilot·Cursor 같은 AI 에이전트와 연동된다.
• TDD가 "코드 전에 테스트"라면 SDD는 "코드와 테스트 전에 사양"이라는 한 단계 앞쪽을 채우는 접근이다.

1. 사양 주도 개발(SDD)이 등장한 배경

지난 1~2년간 Claude Code, Copilot, Cursor 같은 AI 코딩 에이전트가 보편화되면서 "생산성"은 분명 올랐다. 다만 부작용도 또렷하다. PR이 하루 수십 개씩 들어오는데 의도 문서는 비어 있고, 6개월 된 리포지토리에선 누가 어떤 결정을 왜 했는지 추적이 불가능해진다. 코드는 결과물일 뿐 의도(intent)를 담기엔 부족한 매체라는 자각이 늘어난 셈이다.

Spec-Driven Development(이하 SDD)는 이 문제에 대한 응답이다. 명세 자체를 가장 신뢰할 수 있는 단일 진실(single source of truth)로 두고, 코드는 명세에서 파생되는 부산물로 다룬다는 발상이다. 살아 있는 spec(living spec)을 단계적으로 정제한 뒤 AI에게 구현을 위임하는 구조라 한국 개발자에게는 다소 생소하다.

2. GitHub spec-kit이 풀어내는 4단계 워크플로

spec-kit은 GitHub가 공개한 오픈소스 toolkit이다(저장소: github.com/github/spec-kit). Python·uv 기반이며, 공식 Quickstart(2026년 5월 기준)는 일회성 실행으로 uvx --from git+https://github.com/github/spec-kit.git specify init <project-name>을 권장한다. 영구 설치는 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git 형태다. Claude Code, GitHub Copilot, Cursor 등 다중 AI 에이전트와 호환된다는 점이 특징이다.

specify → plan → tasks → implement 단계별 산출물 흐름

핵심은 4개의 슬래시 명령으로 구성된 워크플로이며, 모든 명령은 /speckit. 네임스페이스 prefix를 가진다(다른 도구의 슬래시 명령과 충돌을 피하기 위함).

• /speckit.specify — 사용자가 자연어로 무엇을 만들지 서술. 이 단계에서 결과물은 spec 문서.
• /speckit.plan — spec을 기술 스택·아키텍처 결정을 포함한 설계 문서로 확장.
• /speckit.tasks — plan을 작은 작업 단위로 쪼개 체크리스트로 분해.
• /speckit.implement — 위 산출물을 입력 삼아 AI 에이전트가 실제 코드를 생성.

이 외에 원칙을 명시하는 /speckit.constitution, 모호한 spec을 다듬는 /speckit.clarify, 산출물을 점검하는 /speckit.analyze, 작업 점검표를 만드는 /speckit.checklist 같은 옵션 명령도 존재한다.

흥미로운 점은 각 단계가 별도 파일로 누적된다는 것이다. spec/plan/tasks가 모두 마크다운으로 리포지토리에 남기 때문에 코드 리뷰 대상이 코드뿐 아니라 의도까지 확장된다.

3. SDD vs TDD vs 전통 개발: 한눈에 🆚 비교

세 방법론을 같은 잣대로 정리하면 다음과 같다.

1차 산출물·검증 방법·AI 활용도를 한 화면에 정리

항목	spec-kit (SDD)	TDD (테스트 주도)	전통 코드 우선
1차 산출물	사양 문서(spec.md)	실패하는 테스트	동작하는 코드
검증 방법	사양·계획·태스크 일관성	테스트 통과 여부	동작·리뷰 의존
AI 활용도	매우 높음 (전 단계 위임)	보조 수준	보조 도구로 부분 사용
학습 곡선	중간 (워크플로 익히기)	높음 (테스트 설계)	낮음
적합 팀	AI 에이전트 적극 도입 팀	안정성 중시 백엔드	소규모·프로토타입
약점	한국어 자료·사례 부족	도입·유지 비용	의도 손실, 부채 누적

TDD가 "코드 전에 테스트"라면 SDD는 "코드와 테스트 전에 사양"이라는 한 단계 앞쪽을 채우는 셈이다. 둘은 배타적이지 않다. spec-kit으로 만든 plan에 테스트 전략을 명시하고 implement 단계에서 TDD를 결합하는 식의 혼합도 충분히 가능하다.

4. 🙋 어떤 팀에 어울리는가

💡 도입 판단 체크리스트

• 잘 맞는 팀 — 이미 Claude Code·Copilot으로 큰 비중의 코드를 생성하는 팀, PR 의도가 자주 휘발되는 중규모 조직, 기획·디자인 산출물을 깃 리포지토리에서 함께 추적하고 싶은 팀.
• 신중해야 할 팀 — 변경이 잦은 초기 프로토타입(spec 갱신 비용이 더 큼), 도메인이 좁은 1인 사이드 프로젝트, 사내 LLM 도입이 제한된 환경.

도입 결정은 결국 "spec 문서를 유지보수할 의지가 있는가"로 압축된다. spec이 한 번 만들어진 뒤 방치되면 SDD의 강점이 그대로 약점이 된다.

5. ⚠️ 직접 돌려보며 느낀 한계와 장점

필자가 spec-kit으로 여러 시나리오에서 명세를 시도해 본 결과는 절반의 성공이다. 작은 CLI 도구를 만드는 시나리오에서는 /speckit.specify 한 번에 나온 spec.md가 의외로 충실해서, 곧장 /speckit.plan을 돌려도 큰 모순 없이 이어졌다. 반면 외부 API 의존이 많은 웹 서비스 시나리오에선 plan 단계에서 가정이 어긋나는 일이 잦았고, tasks를 두 번 재생성해야 했다.

장점이 분명한 지점은 두 곳이다. 첫째, 의도 기록이 자동으로 남는다는 점. 둘째, AI 에이전트가 헛다리를 짚을 때 spec.md를 가리키며 교정 지시를 내릴 수 있다는 점이다. 한계로는 한국어 자료가 거의 없고, /speckit.implement 산출물 품질이 사용하는 AI 모델 성능에 그대로 좌우된다는 점을 꼽고 싶다.

🔗 참고 자료

• GitHub 공식 저장소: github.com/github/spec-kit
• spec-kit 공식 Quickstart: github.github.com/spec-kit/quickstart.html (2026년 5월 기준)
• Claude Code 공식 문서: docs.anthropic.com/claude-code

🚀 지금 바로 할 일

1. 로컬에 uvx --from git+https://github.com/github/spec-kit.git specify init <project-name>으로 spec-kit 초기화하기.
2. 작은 사이드 프로젝트에 /speckit.specify를 돌려 spec.md 한 번 만들어 보기.
3. 같은 주제로 Claude Code에 직접 코드를 요청한 결과와 spec-kit 산출물을 비교해 보기.

💬 의견

SDD를 직접 적용해 본 적이 있다면 어느 단계가 가장 까다로웠는지 댓글로 공유 부탁드립니다. 다음 글에서는 spec-kit과 Claude Code를 묶어 작은 웹 앱을 처음부터 끝까지 만들어 보는 핸즈온 튜토리얼을 다룰 예정입니다.

---

작성자: AI·개발자 도구를 다년간 추적해 온 필자가 GitHub spec-kit 공식 저장소와 직접 실행 경험을 바탕으로 정리했습니다. 2026년 5월 기준이며 도구 업데이트에 따라 일부 명령·옵션이 달라질 수 있습니다.