GitHub Spec Kit 딥다이브
— "스펙 먼저, 코드는 나중" SDD 방법론을 21개 이상 AI 에이전트에 적용하는 GitHub 공식 툴킷

1프로젝트 한줄 요약

Spec Kit은 GitHub이 만든 "Spec-Driven Development(SDD)" 도구로, 스펙(사양서)을 먼저 작성하면 AI가 자동으로 구현 코드를 생성하는 개발 방법론 + CLI 툴킷이다. specify init my-project --ai claude 한 줄로 프로젝트를 초기화하면, Claude Code/Cursor/Copilot 등 AI 에이전트가 바로 사용할 수 있는 슬래시 커맨드와 헌법(constitution)이 자동으로 생성된다.

2왜 주목받는가

경쟁 도구 비교

GitHub 공식 프로젝트라는 신뢰도, 21개 이상 AI 에이전트 지원, 106,332 스타로 폭발적 성장 중. "스펙이 왕, 코드는 스펙의 출력물"이라는 패러다임 전환이 개발자 커뮤니티에서 뜨거운 토론을 일으키고 있다.

3기술 스택 전체 지도

언어 및 런타임

핵심 Python 의존성

템플릿 시스템

인프라 / DevOps

4아키텍처 심화 분석

SDD 워크플로 파이프라인

시스템 구조도

설계 패턴 ①: Template Method

설계 패턴 ②: Strategy (에이전트 어댑터)

CommandRegistrar 클래스가 21개 이상 AI 에이전트를 통일된 인터페이스로 관리한다. 에이전트별로 디렉토리 경로, 파일 포맷, 플레이스홀더 문법이 달라도 동일한 커맨드 등록 로직을 공유한다.

# 에이전트별 설정 구조 (개념)
AGENT_CONFIG = {
    "claude": {
        "dir": ".claude/commands",
        "format": "markdown",
        "placeholder": "$ARGUMENTS"
    },
    "cursor": {
        "dir": ".cursor/commands",
        "format": "markdown",
        "placeholder": "$ARGUMENTS"
    },
    "copilot": {
        "dir": ".github/agents",
        "format": "markdown",
        "placeholder": "$ARGUMENTS"
    }
    # ... 18개 이상
}

설계 패턴 ③: Layered Override (4단계 우선순위)

설계 패턴 ④: Constitution (아키텍처 거버넌스)

프로젝트 "헌법"이 AI의 코드 생성을 제약한다. 9개 조항으로 구성:

5디렉토리 구조 해부

Spec Kit 레포 자체 구조

생성되는 프로젝트 구조 (specify init my-app --ai claude)

6학습 포인트 (기술별)

6-1. Spec-Driven Development (SDD) 방법론

배울 것: "코드 우선" 사고에서 "스펙 우선" 사고로의 전환. 실행 가능한 명세(Executable Specification)의 개념. AI 시대의 소프트웨어 개발 프로세스 재설계.

실습: 자신의 사이드 프로젝트에 SDD 워크플로를 적용. 동일한 스펙으로 Claude Code vs Cursor에서 생성 결과 비교.

6-2. CLI 도구 설계 (Python/Typer)

배울 것: typer + rich 조합으로 현대적 CLI 구축, 화살표 키 내비게이션 등 인터랙티브 터미널 UI 구현 (readchar), httpx로 비동기 HTTP + SOCKS 프록시 지원, platformdirs로 OS 독립적 경로 관리.

6-3. 다중 에이전트 어댑터 패턴

배울 것: 21개 이상 AI 에이전트를 하나의 인터페이스로 통합하는 아키텍처. 설정 기반 코드 생성 (설정 딕셔너리를 읽어 에이전트별 파일 생성). Markdown/TOML 간 포맷 변환.

실습: agents.py의 AGENT_CONFIG 구조를 분석하고, 새로운 에이전트 추가해보기.

6-4. 템플릿 기반 LLM 제어

배울 것: 마크다운 템플릿으로 LLM 출력을 구조화하는 기법. [NEEDS CLARIFICATION] 마커로 LLM의 "추측" 방지. 체크리스트를 통한 자기 검증 메커니즘. Constitution(헌법)으로 아키텍처 일관성 강제.

6-5. Layered Override 시스템

배울 것: CSS의 cascade와 유사한 4단계 우선순위 시스템. 조직 표준(프리셋) → 프로젝트 커스텀(오버라이드)의 계층적 설정 관리. 확장 포인트 설계로 서드파티 생태계 지원.

6-6. Git 기반 피처 관리

배울 것: 피처 번호 자동 부여 (001-feature-name, 002-next-feature), 브랜치명 자동 생성 및 시맨틱 네이밍, SPECIFY_FEATURE 환경 변수를 통한 비-Git 환경 지원.

7하드웨어 / 시스템 요구사항

에어갭(Air-Gapped) 환경: --offline 모드 + 번들 core_pack 에셋으로 네트워크 없이도 사용 가능. PyPI/GitHub 차단 환경을 위한 portable wheel 번들 가이드 별도 제공.

8직접 해볼 수 있는 실습 과제

# 1. Spec Kit 설치
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.3.2

# 2. 새 프로젝트 초기화 (Claude Code 사용)
specify init todo-app --ai claude

# 3. 헌법 작성
cd todo-app && claude "/speckit.constitution"

# 4. 첫 번째 스펙 작성
claude "/speckit.specify 간단한 할일 목록 CRUD 앱"

# 5. 계획 → 태스크 → 구현까지 완주
claude "/speckit.plan"
claude "/speckit.tasks"
claude "/speckit.implement"

# 기존 프로젝트 디렉토리에서
specify init . --ai claude --here

# 기존 코드베이스를 분석하여 헌법 작성
claude "/speckit.constitution"

# 새 기능을 SDD 방식으로 추가
claude "/speckit.specify 사용자 인증 기능 추가"

9관련 기술 심화 학습 로드맵

1주차: SDD 기초 + CLI 도구

2주차: 템플릿 시스템 + 프롬프트 엔지니어링

3주차: 아키텍처 패턴 + 에이전트 어댑터

4주차: 실전 프로젝트 + 기여

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — github/spec-kit
• SDD 심화 가이드 (spec-driven.md)
• AGENTS.md (에이전트 통합 문서)
• 설치 가이드
• CHANGELOG
• Python Typer 문서
• Rich 라이브러리 문서
• uv 패키지 매니저
• TrendShift 페이지