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

 

 

깃허브가 만든 오픈소스 도구라고 할 수 있다.
회사에서 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

 

 

명세서가 코드를 섬기는 것이 아니라, 코드가 명세서를 섬깁니다. PRD는 구현을 위한 가이드가 아닌, 이를 보고 구현을 하는 원천입니다.

따라서 무엇이 개발을 주도하는가에 대한 근본적인 재 해석입니다.

코드에 맞추어 명세를 작성하는 것이 아닌 명세를 코드로 변환(Transformation)이 그들이 제시한 비전이다.

예시)

• 전통적 방식: 약 12시간의 문서 작업 (PRD 작성, 설계 문서, 프로젝트 세팅, 기술 명세, 테스트 계획 등)
• 명령어를 사용한 SDD 방식:
  1. /speckit.specify: "메시지 기록과 사용자 상태가 있는 실시간 채팅 시스템" (5분) -> 명세서 생성
  2. /speckit.plan: "실시간 메시징용 웹소켓, 기록용 PostgreSQL, 상태용 Redis" (5분) -> 구현 계획 생성
  3. /speckit.tasks: (5분) -> 실행 가능한 작업 목록 생성

15분 만에 다음을 얻습니다: 사용자 스토리, 기술적 선택과 근거가 담긴 구현 계획, API 계약, 데이터 모델, 포괄적 테스트 시나리오, 버전 관리된 문서들.

구조화된 자동화의 힘

이 명령어들은 단순히 시간을 절약하는 것이 아니라 일관성과 완전성을 강제합니다:

1. 누락된 세부 사항 없음: 템플릿이 비기능 요구사항부터 에러 처리까지 모든 측면을 고려하게 함
2. 추적 가능한 결정: 모든 기술적 선택이 특정 요구사항으로 연결됨
3. 살아있는 문서: 명세서가 코드를 생성하기 때문에 코드와 동기화가 유지됨
4. 빠른 반복: 요구사항을 변경하고 며칠이 아닌 몇 분 만에 계획을 재생성

따라서 그들의 궁극적인 목표는 "AI라는 무한한 노동력을 이용해 코딩(구현)의 고통은 제거하고, 개발자는 순수한 "설계 와 논리"의 영역으로 넘어가는 그 과정 중의 하나"라고 느꼈습니다.

---

사용 준비

필수 도구: Python 3.11+, Git, uv (파이썬 패키지 매니저)

AI 에이전트: Claude Code, GitHub Copilot CLI, Cursor 등

먼저 SpecKit CLI를 설치하고 프로젝트를 세팅해야합니다.

1. UV를 이용해서 설치

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

2. 프로젝트 생성

# 새 프로젝트 생성 (예: my-app) 및 AI 에이전트 선택 (예: claude)
specify init my-app --ai claude

# 또는 현재 폴더에서 시작
specify init . --ai claude

이런 식으로

 

이 과정을 거치면 프로젝트 폴더에. specify 디렉터리가 생성되고 각종 템플릿이 다운로드된다.

이후 원하는 AI 명령어에 이런 식으로 목록이 뜹니다.

3. 헌법(Constitution) 제정

프로젝트의 '대원칙'을 세우는 단계입니다. AI가 내 마음대로 코드를 짜지 않도록 규칙을 정합니다.

여기에는 프로젝트의 컨벤션이나, 코드스타일, 아키택쳐 등등 AI가 마음대로 코드를 짜지 않게 선언을 해줍니다.
프로젝트에서 한 번만 실행해도 되나 컨벤션이 바뀌면 수정해 달라고 수행하면 됩니다.

 

사용처: AI 에이전트 채팅창 (터미널 아님)

명령어: /speckit.constitution 

 

예시 프롬프트: " 아키텍처는 MVC아키텍처를 따를 거고 Kotlin스러운 문법으로 작성해 줘, 각각의 함수는 모듈화를 거칠 거고 서비스는 서비스 폴더에 컨트롤러는 컨트롤러 폴더에 컨트롤러 폴더 안에 도메인 별로 각각 폴더를 만들고 그 안에 한파일에는 꼭 하나의 API가 선언이 되어야 해 이는 서비스도 마찬가지야 작명은 RESTful에 맞춰주고 폴더는 카멜케이스 파일은 스네이크 케이스를 따라줘 네가 판단해서 재사용될 가능성이 높은 함수들은 Common에 따로 모아주고 DB에 접근하는 코드(ORM)는 레포지토리에 모아줘 등.."

 

---

실제 사용

 

1. 스펙 작성

"무엇(What)을 만들지 정의합니다."
여기서는 기획자/사용자가 되어 사용자가 격을 경험과 기능적 요구사항을 구체적으로 묘사해야 한다.
따라서 자연어로 어떤 기능을 만들고 싶은지 자세히 작성한다.

 

명령어: /speckit.specify 

 

 

❌ 나쁜 예 (기술 스택을 미리 정해버림)
"React랑 Tailwind CSS 써서 투두리스트 만들어줘. 상태 관리는 Redux로 하고 DB는 Firebase 붙여줘."

👉 문제점: plan 단계에서 해야 할 기술적 결정을 미리 해버리면, AI가 더 나은 아키텍처를 제안할 기회를 잃고 스펙 문서가 기술에 종속됩니다.

 

 

⭕ 좋은 예 : 팀 프로젝트용 칸반 보드 (중급용)

복잡한 로직과 사용자 인터랙션을 묘사합니다.

 

 

/speckit.specify "소규모 팀을 위한 프로젝트 관리 도구인 'Taskify'를 만들 거야.

주요 기능:

보드 구성: 기본적으로 '할 일', '진행 중', '완료' 3개의 칼럼을 가진다.

드래그 앤 드롭: 카드를 마우스로 잡아서 다른 칼럼으로 옮기면 상태가 변경되어야 한다.

카드 상세: 카드를 클릭하면 상세 모달이 뜨고, 제목/설명/담당자를 지정할 수 있다.

사용자: 별도 로그인 없이, 앱 실행 시 '기획자', '개발자', '디자이너' 중 하나를 선택해서 입장한다.

제약 사항: 완료된 카드는 수정할 수 없다."

 

그럼 이런 식으로

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

 

이런 식으로 어떤 기능을 할지 문서화가 된다.

 

 

2. 명확화 (Clarification) - 선택이지만 강력 추천

AI가 스펙의 구멍을 찾아내 질문을 던집니다.

 

명령어: /speckit.clarify 

 

이걸 하면 AI 가 질문을 던집니다. 모호한 요구사항을 제거하여 구현 단계의 삽질을 방지합니다.

예: "삭제 기능을 만드신다고 했는데, 실수로 삭제했을 때 복구 기능이 필요한가요, 아니면 영구 삭제인가요?", "사용자 이름에 특수문자 입력을 허용할까요?"

 

사용자는 자연어로 답변을 함. -> 이를 토대로 spec.md수정

 

 

3. 구현 계획 수립

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 예시)

4. 작업 분해

명령어: /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] 마크가 붙은 작업은 동시에 진행해도 된다는 것을 알려줍니다.

 

 

5. 구현(Implement)

명령어: /speckit.implement

AI 가 Task에 따라 코드를 구현합니다!

---

직접 써보고 느낀 SpecKit 리얼 후기

 

1. 토큰 비용 vs 개발 비용 (ROI의 관점)
   솔직히 말하면 토큰 소모량이 상당합니다. 스펙을 상세하게 작성하고, 이를 기반으로 계획을 짜는 과정에서 생각보다 많은 토큰이 증발하는 것을 보며 흠칫할 수 있습니다. 하지만 결론적으로는 "오히려 비용이 절약되는 느낌"을 받았습니다.

기존 방식: 대충 짜고 -> 에러 나고 -> 디버깅하고 -> 다시 짜는 무한 루프 (시간과 정신력 소모)

SpecKit 방식: 초반에 토큰을 태워서 스펙을 완벽히 잡음 -> 거의 정확한 코드가 한 번에 나옴

결국 '디버깅 시간'과 '스트레스'를 토큰 값으로 샀다고 생각하면, 충분히 남는 장사입니다.

 

 

2. DB 설계는 여전히 '휴먼 터치'가 필요하다
   AI가 data-model.md를 통해 DB 구조를 제안해 주지만, 이 부분을 100% 신뢰하고 바로 적용하기엔 무리가 있습니다. 특히 RDB(관계형 데이터베이스) 구조는 서비스의 특성이나 개발자의 의도에 따라 정규화/비정규화 전략이 달라져야 합니다. AI가 제안한 구조를 베이스로 하되, 반드시 개발자가 개입하여 검수하고 최적화하는 과정을 거친 뒤 백엔드와 연결하시길 권장합니다.
3. 개발자의 미래: '코더(Coder)'의 종말과 '아키텍트'의 부상
   SpecKit을 쓰면서 확신이 들었습니다. 이제 단순히 문법을 외워 코드를 타이핑하는 '코더'로서의 경쟁력은 끝났습니다. 그동안은 '구현 능력' 하나로도 먹고살 수 있었지만, 앞으로 필요한 역량은 완전히 달라질 것입니다.

설계 역량: 무엇을 만들지 명확하게 정의하는 능력

검증 역량: AI가 짜준 코드가 비즈니스 로직에 맞는지, 아키텍처가 올바른지 판단하는 능력

이제 우리는 코드를 직접 짜는 사람이 아니라, AI라는 유능한 시공사를 감독하는 '현장 소장'이나 '아키텍트'가 되어야 합니다.

4. 꿀팁: 유연한 툴 스위칭 (Claude Code ↔ Cursor)
   작업하다가 Claude Code의 토큰이나 할당량을 다 썼다고 당황하지 마세요. 작업하던 폴더 그대로 Cursor(커서) 같은 다른 AI 에디터로 넘어가서 작업을 이어갈 수 있습니다.

 

주의할 점: 툴을 옮길 때 Constitution(헌법/원칙) 컨텍스트가 끊길 수 있습니다.

해결법:. spec 폴더 내의 메모리 파일도 있지만, 가장 확실한 건 기존. claude 설정 파일에 있는 내용을 참고하라고 던져주거나, Constitution 내용을 복사해서 프롬프트에 한 번 입력해 주는 것입니다. 이렇게만 해주면 AI가 찰떡같이 알아듣고 작업을 이어갑니다.