Claude Code + Spec Kit으로 스펙 주도 개발(SDD) 시작하기

들어가며

요즘 AI 코딩 에이전트 뉘앙에 힙스되는 개발 스타일이 있습니다. 바로 "블라인드하게 코드를 짜다(vibe coding)". AI가 코드를 품품 내줘주니 빠르게 만들 수는 있지만, 스펙 없이 만들어진 코드는 나중에 센센이 엽혀 다시 짜는 상황이 생길 수 있습니다.

GitHub이 만든 오픈소스 툴킷인 Spec Kit은 이 문제를 다릅니다. 코드를 짜기 전에 뜻(스펙)을 먼저 정의하고, AI가 그를 실현하도로 유도하는 Spec-Driven Development(SDD) 방식을 지향합니다. Claude Code와 조합하면 몇 가지 커맨드만으로 스펙 작성부터 구현까지 일관된 플로우를 만들어낼 수 있습니다.

Spec Kit이란?

Spec Kit은 GitHub이 2025년에 공개한 오픈소스 툴킷으로, 스펙 주도 개발(Spec-Driven Development)을 실천하기 위한 도구입니다. specify라는 CLI 도구와 AI 코딩 에이전트에서 사용할 수 있는 슬래시 커맨드들을 제공합니다.

SDD의 핵심 아이디어는 단순합니다.

코드를 짜기 전에 무엇을(what) 만들지를 명확히 하라.
스펙이 코드를 영도하고, 코드는 스펙을 구현한다.

Claude Code, Gemini CLI, Cursor, Copilot 등 30개 이상의 AI 코딩 에이전트와 호환되며, 이 글에서는 Claude Code 기준으로 설명합니다.

설치 및 쓰이 환경 준비

1. Claude Code 설치

Node.js 18+이 설치되어 있어야 합니다.

npm install -g @anthropic-ai/claude-code
claude  # 실행 후 Anthropic API 키 입력

2. Spec Kit CLI(specify) 설치

공식 설치는 PyPI가 아닌 GitHub 레포 직접에서 해야 합니다.

# uv를 사용하는 경우 (권장)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# pipx를 사용하는 경우
pipx install git+https://github.com/github/spec-kit.git

# 설치 확인
specify version

SDD 워크플로우: 5단계

Spec Kit은 다음 5단계 플로우로 개발을 진행합니다.

STEP 0: 프로젝트 초기화

프로젝트 디렉토리를 만들고 specify init으로 템플릿을 초기화합니다.

# 신규 프로젝트
specify init MyApp
cd MyApp

# 기존 프로젝트에 적용
cd existing-project
specify init . --integration copilot
# Claude Code를 쓸 경우
specify init . --integration claude

완료되면 .specify/ 디렉토리와 CLAUDE.md가 생성됩니다. 또한 Claude Code에 /speckit.* 슬래시 커맨드들이 등록됩니다.

STEP 1: 원칙(Constitution) 수립

Claude Code를 실행한 뒤 /speckit.constitution 커맨드로 프로젝트의 개발 원칙을 수립합니다.

claude

# Claude Code 안에서
/speckit.constitution 코드 품질, 테스트 커버리지, 성능 등을 중심으로 한 개발 원칙을 수립해줘

이 커맨드는 .specify/memory/constitution.md 파일을 생성하며, 이후 모든 AI 응답의 기준이 됩니다.

STEP 2: 스펙(Spec) 작성

/speckit.specify로 만들 것에 대한 요구사항을 자연어로 작성합니다. 기술 스택은 여기서 언급하지 않는 게 포인트입니다.

/speckit.specify 사용자가 할 일 목록을 관리하는 앱을 만들어줘.
사용자는 할 일을 추가/삭제/완료 체크할 수 있고,
우선순위를 지정할 수 있어야 해.
날짜 기준으로 정렬하는 기능도 있었으면 좋겠어.

AI가 요구사항을 분석해 .specify/specs/001-todo-app/spec.md 파일을 생성합니다. User Story와 엑셍스 커버리지 충 등이 자동으로 정리됩니다.

STEP 3: 구현 계획(Plan) 생성

/speckit.plan에서 이제 기술 스택과 아키텐쳐를 알려줍니다.

/speckit.plan React + TypeScript를 사용해서 만들어줘.
상태 관리는 Zustand, 데이터 저장은 localStorage 사용.
UI는 Tailwind CSS로 슬림하게 만들어줘.

AI는 plan.md, data-model.md 등 세부 구현 문서를 생성합니다.

STEP 4: 태스크 분해

/speckit.tasks로 계획을 실행 가능한 태스크 단위로 취계합니다.

/speckit.tasks

tasks.md 파일이 생성되며, 병렬 실행 가능한 태스크는 [P] 표시로 마크됩니다. 의존성 순서를 지켜서 태스크가 나열돬으며, 각 User Story별로 묵여서 정리됩니다.

STEP 5: 구현

/speckit.implement으로 AI가 tasks.md를 읽고 실제 코드를 작성합니다.

/speckit.implement

Claude Code는 constitution → spec → plan → tasks 순서로 컨텍스트를 확인하면서 코드를 작성합니다. 실행에 필요한 CLI 도구(npm, git 등)도 직접 호출합니다.

유용한 추가 커맨드

Spec Kit은 코어 5단계 외에도 성능/품질 강화를 위한 선택적 커맨드를 제공합니다.

커맨드	설명
/speckit.clarify	스펙 작성 후 더 명확하게 요구사항을 정리
/speckit.analyze	태스크 생성 후 컨시스턴시 검사
/speckit.checklist	요구사항 완성도 체크리스트 생성

커뮤니티 익스텐션 활용

Spec Kit은 커뮤닄티가 만든 익스텐션을 specify extension add로 설치할 수 있습니다. 주목할 만한 것들로는:

• spec-kit-review: 구현 후 코드 리뷰를 자동화
• spec-kit-cleanup: 구현 후 리팩토링과 소리 로직 수정
• spec-kit-jira: Jira 연동으로 태스크 자동 생성
• spec-kit-pr-bridge: PR 설명을 스펙에서 자동 생성
• spec-kit-security-review: 보안 삐넓 자동 검사

# 익스텐션 검색
specify extension search

# 설치
specify extension add spec-kit-review

정리

Spec Kit + Claude Code 조합은 AI 코딩의 장점은 살리면서, 스펙 없이 코드를 짜는 단점을 보완하는 접근법입니다. 특히 팀에서 AI 코딩 에이전트를 사용할 때, 스펙이 있으면 AI가 일관성 있는 코드를 생성하는 데 큰 도움이 됩니다.

• 코드를 짜기 전에 뜻을 먼저 정의한다
• AI는 스펙을 구현한다
• 스펙은 프로젝트 전체의 진실의 원천(single source of truth)이 된다

이 세 원칙만 지켜도 AI 코딩의 편의성을 영리하지 않으면서도 훨씬 더 안정적인 개발을 할 수 있습니다.

---

실전 워크플로우: 내가 실제로 사용하는 방식

Spec Kit 공식 가이드의 5단계 흐름에 더해, 실제로 운용하면서 효과적이라고 확인한 구체적인 방식을 공유합니다.

1단계: Constitution — TDD 강제 + 금지 원칙 중심으로 수립

Constitution을 작성할 때 가장 중요하게 생각하는 두 가지 원칙이 있습니다.

TDD 강제: AI가 작성하는 모든 코드는 테스트 코드로 동작이 검증되고 명세될 수 있어야 합니다. 단순히 "테스트를 작성해줘"라고 하는 게 아니라, Constitution 수준에서 강제해야 AI가 구현 후 테스트를 붙이는 게 아니라 테스트를 명세로 먼저 정의하는 방향으로 작업합니다.

허가 원칙보다 금지 원칙: AI는 모호한 상황에서 "일단 해도 되겠지"라고 판단하는 경향이 있습니다. "이런 건 해도 된다"는 허가 목록보다, "이런 건 절대 하지 마라"는 금지 목록이 훨씬 효과적으로 작동합니다. 예를 들어 "도메인 로직을 UI 레이어에 작성하지 말 것", "테스트 없이 구현 PR을 올리지 말 것" 같은 식으로 구체적인 금지 지침을 명시합니다.

2단계: Specify — 요구사항을 최대한 구체적으로

/speckit.specify를 호출할 때 전달받은 요구사항이나 구현 목표를 최대한 상세하게 설명합니다. 명령 후 .specify/specs/ 하위에 작업 디렉토리가 생성되는 것을 확인할 수 있습니다.

3단계: Clarify 반복 — 기획 구체화의 핵심

이 단계가 전체 워크플로우에서 가장 공을 들이는 부분입니다. /speckit.clarify를 N번 반복 실행합니다.

실행할 때마다 두 가지 방식을 병행합니다.

• 능동적 구체화: 내가 직접 구체화가 필요한 지점을 명시해서 AI에게 인터뷰를 요청합니다.
• 수동적 검토: 작성된 spec을 바탕으로 AI가 스스로 모호하거나 구체화가 필요한 지점을 찾아 인터뷰를 진행합니다.

이 과정을 반복할수록 초기에는 보이지 않던 엣지 케이스, 정책 미결정 사항, 도메인 용어의 모호함 등이 드러납니다. clarify를 충분히 돌리고 나면 spec이 상당히 두꺼워지는데, 이게 나중에 plan과 tasks의 품질을 결정합니다.

4단계: Analyze — Plan 전 일관성 검사

plan을 수립하기 전에 /speckit.analyze를 실행해 spec 문서들 간의 일관성을 검사합니다. clarify를 여러 번 반복하다 보면 앞뒤가 맞지 않는 내용이 생길 수 있는데, 이 단계에서 미리 잡아두면 plan과 tasks 단계에서 AI가 엉뚱한 방향으로 작업하는 것을 막을 수 있습니다.

5단계: Plan — 구현 계획 수립

/speckit.plan으로 기술 스택과 아키텍처를 명시하여 구현 계획을 수립합니다. 앞 단계에서 spec이 충분히 구체화되어 있으면 plan의 완성도도 자연히 높아집니다.

6단계: Tasks — 원자적 단위로 분해

/speckit.tasks로 plan을 태스크 단위로 분해하는 단계입니다. 이 단계의 품질이 구현 결과를 좌우합니다.

태스크를 나눌 때 핵심 기준은 다음과 같습니다.

• 원자적 단위: 하나의 태스크는 하나의 책임만 가집니다.
• 도메인/계층 경계 존중: 도메인 경계나 계층 간 경계를 침범하지 않도록 분리합니다.
• 독립 실행 가능: 독립적인 에이전트가 혼자서 작업할 수 있는 수준으로 분해합니다.

이렇게 하면 두 가지 이점이 생깁니다. 개발자 입장에서 AI가 작업한 내용을 태스크 단위로 검토하기가 수월해지고, 기능 단위가 잘게 쪼개져 있어 추후 유지보수도 용이해집니다.

7단계: Implement — Task/Phase 단위 순차 검증

/speckit.implement로 구현을 진행할 때 전체를 한 번에 실행하기보다, 태스크 단위로 실행하고 검증하는 사이클을 반복합니다. 경험적으로 phase 단위로 구현 작업을 나눠도 문제없이 구현됨을 확인했습니다.

이 방식의 장점은 AI가 작업 중 방향을 이탈했을 때 조기에 발견하고 수정할 수 있다는 점입니다. 태스크가 원자적으로 잘 분해되어 있을수록 검증 사이클도 빠르게 돌아갑니다.

---

전체 흐름 요약

constitution (TDD 강제 + 금지 원칙)
    ↓
specify (요구사항 상세 전달)
    ↓
clarify × N (기획 구체화 반복 인터뷰)
    ↓
analyze (spec 일관성 검사)
    ↓
plan (기술 스택 + 구현 계획)
    ↓
tasks (원자적 단위 분해)
    ↓
implement (task/phase 단위 순차 실행 + 검증 반복)