SpecKit 완벽 가이드 - AI와 함께하는 스펙 주도 개발(SDD)
SpecKit

SpecKit
https://github.com/github/spec-kit
[GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development
💫 Toolkit to help you get started with Spec-Driven Development - github/spec-kit
github.com](https://github.com/github/spec-kit)
깃허브가 만든 오픈소스 도구라고 할 수 있다.
회사에서 AI를 이용한 바이브코딩을 애용하고 있는데 이때마다 내가 원하는 기능이 만들어지지 않아 함수단위로 쪼개서 개발하거나,
Cursor Plan Mode 등 여러 가지 방법을 사용하다가 SDD란 방법론을 찾았다.
스팩주도 개발이란(Spec-Driven Development)
개발 자체를 스팩(명세?, 확실한 기능)을 먼저 하고 개발에 들어가는 방식이다.
원래는 DDD 도메인 주도 개발이나, TDD테스트 주도 개발 등 여러 방법론이 있었고 그 이전에는 Waterfall 방식의 방법론이 있었다.
워터폴은 문서를 통해 완벽하게 설계를 하고 개발에 들어가는 방식인데 안 하는 이유는
애자일 (Agile) 방법론에 밀렸고(빠르게 개발하고 시장의 반응을 봐야하는데 설계하는데 시간이 많이 들어감)
설계를 완벽하게 해도 오류나 구멍이 있었고, 문서를 쓰는게 너무 어렵고
이를 코드와 동기화 시키키도 어렵다는 이유 때문에 안 쓰이고 있었다.
근데 LLM이 등장하면서 상황이 바뀌었다.
-> 문서를 쓰는 데에 노력이 매우 낮아졌고, 자연어로 이런 기능 만들고 싶어 하면 AI 가 대신 작성해 주는 경지까지 이르렀다.
또한 바이브 코딩을 해보니 확실한 프롬프트 엔지니어링 기술이 필요해졌다.
AI는 명확하게 설명하면 잘 수행하지만 추상적으로 설명하면 추상적으로 구현한다. (자기 마음대로)
따라서 개발자들은 바이브 코딩을 하기전에 상세한 스펙을 미리 AI와 함께 작성하고 그 스펙을 계속해서 참고하게 instruction으로 주었다.
이러한 방법론이 널리 퍼져서 지금에 이르러 SDD 가 되었다.
SpecKit에서의 SDD
SpecKit은 SDD를 GitHub Next 팀에서 해석한 결과물이라고 볼 수 있다.
여기 그들의 생각을 직접 정리해놓은 문서다.
https://github.com/github/spec-kit/blob/main/spec-driven.md
[spec-kit/spec-driven.md at main · github/spec-kit
💫 Toolkit to help you get started with Spec-Driven Development - github/spec-kit
github.com](https://github.com/github/spec-kit/blob/main/spec-driven.md)
명세서가 코드를 섬기는 것이 아니라, 코드가 명세서를 섬깁니다. PRD는 구현을 위한 가이드가 아닌, 이를 보고 구현을 하는 원천입니다.
따라서 무엇이 개발을 주도하는가에 대한 근본적인 재 해석입니다.
코드에 맞추어 명세를 작성하는 것이 아닌 명세를 코드로 변환(Transformation)이 그들이 제시한 비전이다.
예시)
- 전통적 방식: 약 12시간의 문서 작업 (PRD 작성, 설계 문서, 프로젝트 세팅, 기술 명세, 테스트 계획 등)
- 명령어를 사용한 SDD 방식:
- /speckit.specify: “메시지 기록과 사용자 상태가 있는 실시간 채팅 시스템” (5분) -> 명세서 생성
- /speckit.plan: “실시간 메시징용 웹소켓, 기록용 PostgreSQL, 상태용 Redis” (5분) -> 구현 계획 생성
- /speckit.tasks: (5분) -> 실행 가능한 작업 목록 생성
15분 만에 다음을 얻습니다: 사용자 스토리, 기술적 선택과 근거가 담긴 구현 계획, API 계약, 데이터 모델, 포괄적 테스트 시나리오, 버전 관리된 문서들.
구조화된 자동화의 힘
이 명령어들은 단순히 시간을 절약하는 것이 아니라 일관성과 완전성을 강제합니다:
- 누락된 세부 사항 없음: 템플릿이 비기능 요구사항부터 에러 처리까지 모든 측면을 고려하게 함
- 추적 가능한 결정: 모든 기술적 선택이 특정 요구사항으로 연결됨
- 살아있는 문서: 명세서가 코드를 생성하기 때문에 코드와 동기화가 유지됨
- 빠른 반복: 요구사항을 변경하고 며칠이 아닌 몇 분 만에 계획을 재생성
따라서 그들의 궁극적인 목표는 “AI라는 무한한 노동력을 이용해 코딩(구현)의 고통은 제거하고, 개발자는 순수한 “설계 와 논리”의 영역으로 넘어가는 그 과정 중의 하나“라고 느꼈습니다.
사용 준비
필수 도구: Python 3.11+, Git, uv (파이썬 패키지 매니저)
AI 에이전트: Claude Code, GitHub Copilot CLI, Cursor 등
먼저 SpecKit CLI를 설치하고 프로젝트를 세팅해야합니다.
- UV를 이용해서 설치
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
- 프로젝트 생성
# 새 프로젝트 생성 (예: my-app) 및 AI 에이전트 선택 (예: claude)
specify init my-app --ai claude
# 또는 현재 폴더에서 시작
specify init . --ai claude
이런 식으로
이 과정을 거치면 프로젝트 폴더에. specify 디렉터리가 생성되고 각종 템플릿이 다운로드된다.
이후 원하는 AI 명령어에 이런 식으로 목록이 뜹니다.

- 헌법(Constitution) 제정
프로젝트의 ’대원칙’을 세우는 단계입니다. AI가 내 마음대로 코드를 짜지 않도록 규칙을 정합니다.
여기에는 프로젝트의 컨벤션이나, 코드스타일, 아키택쳐 등등 AI가 마음대로 코드를 짜지 않게 선언을 해줍니다.
프로젝트에서 한 번만 실행해도 되나 컨벤션이 바뀌면 수정해 달라고 수행하면 됩니다.
사용처: AI 에이전트 채팅창 (터미널 아님)
명령어: /speckit.constitution
예시 프롬프트: “ 아키텍처는 MVC아키텍처를 따를 거고 Kotlin스러운 문법으로 작성해 줘, 각각의 함수는 모듈화를 거칠 거고 서비스는 서비스 폴더에 컨트롤러는 컨트롤러 폴더에 컨트롤러 폴더 안에 도메인 별로 각각 폴더를 만들고 그 안에 한파일에는 꼭 하나의 API가 선언이 되어야 해 이는 서비스도 마찬가지야 작명은 RESTful에 맞춰주고 폴더는 카멜케이스 파일은 스네이크 케이스를 따라줘 네가 판단해서 재사용될 가능성이 높은 함수들은 Common에 따로 모아주고 DB에 접근하는 코드(ORM)는 레포지토리에 모아줘 등..”
실제 사용
- 스펙 작성
“무엇(What)을 만들지 정의합니다.”
여기서는 기획자/사용자가 되어 사용자가 격을 경험과 기능적 요구사항을 구체적으로 묘사해야 한다.
따라서 자연어로 어떤 기능을 만들고 싶은지 자세히 작성한다.
명령어: /speckit.specify
❌ 나쁜 예 (기술 스택을 미리 정해버림)
“React랑 Tailwind CSS 써서 투두리스트 만들어줘. 상태 관리는 Redux로 하고 DB는 Firebase 붙여줘.”
👉 문제점: plan 단계에서 해야 할 기술적 결정을 미리 해버리면, AI가 더 나은 아키텍처를 제안할 기회를 잃고 스펙 문서가 기술에 종속됩니다.
⭕ 좋은 예 : 팀 프로젝트용 칸반 보드 (중급용)
복잡한 로직과 사용자 인터랙션을 묘사합니다.
/speckit.specify “소규모 팀을 위한 프로젝트 관리 도구인 ’Taskify’를 만들 거야.
주요 기능:
보드 구성: 기본적으로 ‘할 일’, ‘진행 중’, ‘완료’ 3개의 칼럼을 가진다.
드래그 앤 드롭: 카드를 마우스로 잡아서 다른 칼럼으로 옮기면 상태가 변경되어야 한다.
카드 상세: 카드를 클릭하면 상세 모달이 뜨고, 제목/설명/담당자를 지정할 수 있다.
사용자: 별도 로그인 없이, 앱 실행 시 ‘기획자’, ‘개발자’, ‘디자이너’ 중 하나를 선택해서 입장한다.
제약 사항: 완료된 카드는 수정할 수 없다.”
그럼 이런 식으로

spec.md 문서가 생기는데 여기에는

이런 식으로 어떤 기능을 할지 문서화가 된다.
- 명확화 (Clarification) - 선택이지만 강력 추천
AI가 스펙의 구멍을 찾아내 질문을 던집니다.
명령어: /speckit.clarify
이걸 하면 AI 가 질문을 던집니다. 모호한 요구사항을 제거하여 구현 단계의 삽질을 방지합니다.
예: “삭제 기능을 만드신다고 했는데, 실수로 삭제했을 때 복구 기능이 필요한가요, 아니면 영구 삭제인가요?”, “사용자 이름에 특수문자 입력을 허용할까요?”
사용자는 자연어로 답변을 함. -> 이를 토대로 spec.md수정
- 구현 계획 수립
AI의 동작 (The Action):
AI가 ’솔루션 아키텍트(Architect)’가 됩니다.
완성된 스펙(What)과 사용자가 지정한 기술 스택(How)을 결합하여 전체 시스템 설계도를 그립니다.
프로젝트의 ’헌법(Constitution)’을 위반하지 않는지 검사합니다. (예: “헌법에 외부 라이브러리 최소화가 있는데, 여기서 Lodash를 쓰는 건 불필요해 보입니다”라고 판단)
명령어: /speckit.plan (뒤에 기술 스택 프롬프트 추가)
프롬프트:
/speckit.plan “이 앱은 웹 브라우저에서 동작해야 해.
- Frontend: React와 Vite를 사용하고, 스타일링은 Tailwind CSS로 해줘. 상태 관리는 Context API면 충분해.
- Backend: Node.js와 Express를 사용해 줘.
- Database: 로컬 개발용으로 SQLite를 사용하고, ORM은 Prisma를 써줘.”
결과물
data-model.md: 데이터베이스 스키마(ERD), 테이블 구조, 필드 타입 정의.
contracts/ 폴더: 프론트엔드와 백엔드가 소통할 API 명세서(JSON/Markdown). 어떤 URL로 요청하면 어떤 JSON을 응답하는지 미리 정의됩니다.
research.md: 왜 이 기술을 선택했는지에 대한 기술적 근거와 분석 내용.
아래는 data-model.md 예시)

- 작업 분해
명령어: /speckit.tasks
🤖 AI의 동작 (The Action):
AI가 ’프로젝트 매니저(PM)’가 됩니다.
거대한 계획(plan.md)을 실제로 코딩 가능한 **아주 작은 단위(Unit)**로 잘게 쪼갭니다.
의존성(Dependency) 관리: “DB 테이블을 먼저 만들어야 API를 짤 수 있지”와 같이 작업 순서를 논리적으로 정렬합니다.
TDD 적용: 구현 코드보다 테스트 코드를 먼저 작성하도록 작업을 배치합니다.
📄 결과물 (The Output):
tasks.md: 실행 가능한 체크리스트 파일.
작업 내용 예시:
[ ] 1.1: 사용자(User) 데이터 모델(Schema) 파일 생성
[ ] 1.2: 사용자 생성 API에 대한 단위 테스트 코드 작성
[ ] 1.3: 사용자 생성 API 실제 구현
병렬 표시: [P] 마크가 붙은 작업은 동시에 진행해도 된다는 것을 알려줍니다.
- 구현(Implement)
명령어: /speckit.implement
AI 가 Task에 따라 코드를 구현합니다!
직접 써보고 느낀 SpecKit 리얼 후기
- 토큰 비용 vs 개발 비용 (ROI의 관점)
솔직히 말하면 토큰 소모량이 상당합니다. 스펙을 상세하게 작성하고, 이를 기반으로 계획을 짜는 과정에서 생각보다 많은 토큰이 증발하는 것을 보며 흠칫할 수 있습니다. 하지만 결론적으로는 **“오히려 비용이 절약되는 느낌”**을 받았습니다.
기존 방식: 대충 짜고 -> 에러 나고 -> 디버깅하고 -> 다시 짜는 무한 루프 (시간과 정신력 소모)
SpecKit 방식: 초반에 토큰을 태워서 스펙을 완벽히 잡음 -> 거의 정확한 코드가 한 번에 나옴
결국 ’디버깅 시간’과 ’스트레스’를 토큰 값으로 샀다고 생각하면, 충분히 남는 장사입니다.
- DB 설계는 여전히 ’휴먼 터치’가 필요하다
AI가 data-model.md를 통해 DB 구조를 제안해 주지만, 이 부분을 100% 신뢰하고 바로 적용하기엔 무리가 있습니다. 특히 RDB(관계형 데이터베이스) 구조는 서비스의 특성이나 개발자의 의도에 따라 정규화/비정규화 전략이 달라져야 합니다. AI가 제안한 구조를 베이스로 하되, 반드시 개발자가 개입하여 검수하고 최적화하는 과정을 거친 뒤 백엔드와 연결하시길 권장합니다. - 개발자의 미래: ’코더(Coder)’의 종말과 ’아키텍트’의 부상
SpecKit을 쓰면서 확신이 들었습니다. 이제 단순히 문법을 외워 코드를 타이핑하는 ’코더’로서의 경쟁력은 끝났습니다. 그동안은 ‘구현 능력’ 하나로도 먹고살 수 있었지만, 앞으로 필요한 역량은 완전히 달라질 것입니다.
설계 역량: 무엇을 만들지 명확하게 정의하는 능력
검증 역량: AI가 짜준 코드가 비즈니스 로직에 맞는지, 아키텍처가 올바른지 판단하는 능력
이제 우리는 코드를 직접 짜는 사람이 아니라, **AI라는 유능한 시공사를 감독하는 ’현장 소장’이나 ‘아키텍트’**가 되어야 합니다.
- 꿀팁: 유연한 툴 스위칭 (Claude Code ↔ Cursor)
작업하다가 Claude Code의 토큰이나 할당량을 다 썼다고 당황하지 마세요. 작업하던 폴더 그대로 Cursor(커서) 같은 다른 AI 에디터로 넘어가서 작업을 이어갈 수 있습니다.
주의할 점: 툴을 옮길 때 Constitution(헌법/원칙) 컨텍스트가 끊길 수 있습니다.
해결법:. spec 폴더 내의 메모리 파일도 있지만, 가장 확실한 건 기존. claude 설정 파일에 있는 내용을 참고하라고 던져주거나, Constitution 내용을 복사해서 프롬프트에 한 번 입력해 주는 것입니다. 이렇게만 해주면 AI가 찰떡같이 알아듣고 작업을 이어갑니다.