github/spec-kit View GitHub Homepage for Latest Official Releases

GitHub 오픈 소스 규격 기반 개발 툴킷으로, 구조화된 규격 및 계획을 통해 AI 코딩 도우미가 고품질 코드를 생성하도록 안내합니다.

MITShellspec-kitgithub 42.4k Last Updated: October 23, 2025

GitHub Spec Kit 프로젝트 상세 소개

프로젝트 개요

GitHub Spec Kit은 GitHub이 오픈 소스로 공개한 사양 주도 개발(Spec-Driven Development, SDD) 툴킷입니다. 이 툴킷은 AI 코딩 어시스턴트에게 구조화된 작업 흐름을 제공하여, 상세한 사양을 먼저 작성한 후 코드를 생성하는 방식으로 기존의 "선 코딩 후 문서화" 개발 방식을 변화시킵니다.

프로젝트 주소: https://github.com/github/spec-kit

핵심 개념

사양 주도 개발(Spec-Driven Development)이란?

사양 주도 개발은 사양(Specification)을 핵심으로 하는 소프트웨어 개발 방법론으로, 그 핵심 사상은 다음과 같습니다:

사양 우선: 코딩 전에 상세한 제품 요구 사항 문서(PRD)와 기술 구현 계획을 먼저 작성합니다.
사양이 곧 진실: 사양은 프로젝트의 단일 진실 공급원(Single Source of Truth)이 됩니다.
동적 진화: 사양은 정적인 문서가 아니라 프로젝트의 진화에 따라 함께 발전하는 "살아있는 문서"입니다.

Spec Kit이 필요한 이유?

AI 코딩 어시스턴트(예: Claude Code, GitHub Copilot, Gemini CLI)를 사용할 때 흔히 발생하는 문제점은 다음과 같습니다:

모호한 입력으로 인한 잘못된 출력: AI 어시스턴트는 프롬프트에 따라서만 코드를 생성하며, 프로젝트 전체에 대한 이해가 부족합니다.
가정 기반 코딩: AI가 실제 요구 사항과 일치하지 않는 가정을 할 수 있습니다.
아키텍처 제약 부족: 생성된 코드가 기존 시스템 아키텍처와 일치하지 않을 수 있습니다.
일관성 없는 품질: 통일된 기준이 없어 코드 품질이 들쭉날쭉합니다.

Spec Kit은 구조화된 프레임워크를 제공하여 이러한 문제를 해결하고, AI 어시스턴트가 프로젝트 의도를 정확히 이해하고 고품질 코드를 생성하도록 보장합니다.

핵심 구성 요소

1. Specify CLI

Specify CLI는 Python 기반의 명령줄 도구로, 프로젝트의 SDD 스캐폴딩을 빠르게 초기화하는 데 사용됩니다.

설치 방법:

# uvx를 사용하여 설치(권장)
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

주요 기능:

설치된 도구(git, claude, gemini, code, cursor-agent 등) 확인
적합한 템플릿 파일 자동 다운로드
프로젝트의 SDD 구조 초기화
다양한 AI 코딩 어시스턴트 지원

사용 예시:

# 새 프로젝트 초기화 및 AI 어시스턴트 지정
specify init my-project --ai claude
specify init my-project --ai copilot
specify init my-project --ai gemini

# 현재 디렉터리에 초기화
specify init . --ai claude
specify init --here --ai copilot

# 비어 있지 않은 디렉터리에 강제 병합
specify init . --force --ai claude

# git 초기화 건너뛰기
specify init my-project --ai gemini --no-git

2. 템플릿 및 보조 스크립트

Spec Kit은 다음을 포함하는 완전한 템플릿 시스템을 제공합니다:

Constitution.md (프로젝트 헌장)

프로젝트의 기본 원칙과 협상 불가능한 지침, 예를 들어:

테스트 방법 요구 사항
아키텍처 규칙
코드 스타일 가이드
기술 스택 선택

이는 조직이 "주관 있는 기술 스택"을 구축하는 데 도움이 되는 강력한 도구입니다.

사양 템플릿

사양 문서가 포함해야 할 내용 구조를 정의합니다.

기술 계획 템플릿

기술 구현 계획의 형식과 필수 요소를 규정합니다.

작업 분해 템플릿

대규모 기능을 실행 가능한 작은 작업으로 분해합니다.

보조 스크립트

powershell 또는 bash 폴더에 위치하며, SDD 스캐폴딩의 일관된 적용을 보장합니다.

작업 흐름

Spec Kit은 4단계 개발 프로세스를 따릅니다:

1단계: 사양 정의 (/specify)

/specify 명령을 사용하여 높은 수준의 프로젝트 설명을 제공하며, 기술적 세부 사항보다는 "무엇을 할 것인가"와 "왜 하는가"에 중점을 둡니다.

예시:

/specify 
사용자 인증, 실시간 협업, 모바일 지원, 프로젝트 생성 및 작업 할당, 칸반 보드를 통한 진행 상황 추적을 지원하는 작업 관리 애플리케이션 Taskify를 구축합니다.

AI 코딩 어시스턴트는 다음을 포함하는 완전한 제품 사양 문서(PRD)를 생성합니다:

프로젝트 동기 및 목표
핵심 기능 설명
사용자 스토리
비기능적 요구 사항
승인 기준

2단계: 기술 계획 수립 (/plan)

/plan 명령을 사용하여 높은 수준의 기술 방향을 제공하면, AI가 상세한 기술 구현 계획을 생성합니다.

예시:

/plan
React + TypeScript 프런트엔드
Node.js 백엔드
PostgreSQL 데이터베이스 사용

생성된 기술 계획에는 다음이 포함됩니다:

시스템 아키텍처 설계
기술 스택 선택 이유
데이터 모델 설계
API 설계
보안 고려 사항
성능 최적화 전략

3단계: 작업 분해 (/tasks)

/tasks

기술 계획을 실행 가능한 작은 작업으로 분해하며, 각 작업에는 다음이 포함됩니다:

작업 설명
의존성
예상 산출물
승인 조건

4단계: 구현 (/implement)

/implement

AI 코딩 어시스턴트는 사양, 계획 및 작업 목록에 따라 코드를 생성하고, 테스트 주도 개발(TDD) 원칙을 따릅니다.

핵심 기능

1. 다양한 AI 어시스턴트 호환

Spec Kit은 여러 주요 AI 코딩 어시스턴트를 지원합니다:

Claude Code (Anthropic)
GitHub Copilot
Cursor
Gemini CLI (Google)
Windsurf
Qwen Code
OpenCode
Codex
그 외 다수...

2. 테스트 주도 개발(TDD) 통합

내장된 TDD 지원은 다음을 보장합니다:

모든 기능에 해당하는 테스트가 존재합니다.
Mock 대신 실제 환경 테스트를 우선적으로 사용합니다.
계약 테스트(Contract Tests)는 구현 전에 완료되어야 합니다.

3. 검토 및 승인 체크리스트

각 단계에는 다음과 같은 명확한 승인 기준이 있습니다:

사양이 완전한가?
기술 계획이 실현 가능한가?
작업이 독립적으로 실행 가능한가?
코드가 모든 테스트를 통과했는가?

4. 반복적 최적화 메커니즘

어떤 단계에서든 수정 사항을 되돌릴 수 있도록 지원합니다:

사양이 불분명한가? 사양을 업데이트합니다.
아키텍처 조정이 필요한가? 기술 계획을 수정합니다.
작업이 너무 큰가? 다시 분해합니다.

적용 시나리오

1. 그린필드 프로젝트 (Zero-to-One)

처음부터 시작하는 새 프로젝트의 경우, AI가 일반적인 솔루션을 생성하는 것을 방지하기 위해 미리 계획을 세웁니다.

2. 기능 확장 (N-to-N+1)

기존의 복잡한 시스템에 새 기능을 추가하는 경우, Spec Kit의 가장 강력한 적용 시나리오입니다:

새 기능과 기존 시스템의 상호 작용 방식을 명확히 합니다.
코딩 아키텍처 제약을 통해 코드 스타일의 일관성을 보장합니다.
새 코드가 "패치"가 아닌 네이티브 기능처럼 느껴지도록 합니다.

3. 레거시 시스템 현대화

레거시 시스템을 리팩토링할 때:

현대적인 사양에 핵심 비즈니스 로직을 담습니다.
새로운 아키텍처를 설계합니다.
AI가 기술 부채 없이 시스템을 처음부터 재구축하도록 합니다.

프로젝트 구조 예시

Specify CLI로 초기화된 프로젝트 구조:

my-project/
├── .specify/              # Spec Kit 설정 및 템플릿
│   ├── templates/         # 사양, 계획, 작업 템플릿
│   ├── scripts/           # 보조 스크립트
│   └── config.json        # 구성 파일
├── constitution.md        # 프로젝트 헌장
├── spec.md                # 제품 사양 문서
├── plan.md                # 기술 구현 계획
├── tasks/                 # 작업 목록
│   ├── task-001.md
│   ├── task-002.md
│   └── ...
└── src/                   # 소스 코드 디렉터리

실제 사례: Taskify 프로젝트

Spec Kit 공식 웹사이트는 칸반 스타일의 프로젝트 관리 도구를 사양 주도 개발로 구축하는 방법을 보여주는 완전한 예시 프로젝트 Taskify를 제공합니다.

기능 특성:

5개의 사전 설정 사용자, 비밀번호 없이 로그인
다중 프로젝트 관리
칸반 보드 뷰
드래그 앤 드롭 방식의 작업 관리
작업 할당 및 상태 추적
댓글 기능(자신이 작성한 댓글만 편집/삭제 가능)
현재 사용자 작업 하이라이트 표시

개발 흐름:

/specify 명령을 사용하여 Taskify의 요구 사항을 설명합니다.
AI가 상세한 제품 사양을 생성합니다.
/speckit.clarify를 사용하여 세부 사항을 명확히 합니다.
/plan을 사용하여 기술 구현 계획을 생성합니다.
검증 검토 및 승인 체크리스트를 확인합니다.
작업을 생성하고 실행합니다.

장점 및 가치

개발자를 위한 가치

추측 감소: 명확한 사양으로 모호성 제거
품질 향상: 구조화된 프로세스로 코드 품질 보장
협업 용이: 사양이 팀 커뮤니케이션의 공통 언어 역할
유지보수 용이: 문서와 코드가 동기화되어 진화

팀을 위한 가치

통일된 표준: Constitution을 통해 팀 사양 구축
지식 축적: 사양과 계획이 재사용 가능한 자산이 됨
재작업 감소: 사전 계획으로 구현 단계의 문제 감소
추적 가능성: 명확한 의사 결정 기록

AI 어시스턴트를 위한 가치

컨텍스트 이해: 완전한 사양이 충분한 컨텍스트 제공
제약 조건 안내: 기술 계획이 아키텍처 제약 조건 제공
작업 집중: 작은 단위의 작업으로 AI가 더 집중할 수 있도록 함
품질 보증: 내장된 승인 기준이 코드 생성 안내

한계 및 주의사항

1. 학습 곡선

작고 간단한 프로젝트에는 과도하게 복잡하게 느껴질 수 있으며, 투입 대비 산출을 고려해야 합니다.

2. 실험적 성격

Spec Kit은 여전히 실험 단계에 있으며, GitHub 팀은 아직 해결해야 할 많은 문제가 있다고 명확히 밝히고 있습니다.

3. 템플릿 유연성

내장된 템플릿은 GitHub 팀의 모범 사례를 기반으로 하지만, 조직의 요구 사항에 따라 조정이 필요할 수 있습니다.

4. 기존 프로젝트 통합

현재는 주로 새 프로젝트를 대상으로 하며, 기존 프로젝트에 대한 지원은 아직 탐색 중입니다.

커뮤니티 및 생태계

커뮤니티 피드백

Spec Kit에 대한 커뮤니티의 주요 논의점:

표준화 요구: 사용자들은 AI 보조 개발의 파편화를 피하기 위해 공유 프레임워크 구축을 희망합니다.
팀 간 협업: 저장소 간 사양 및 산출물 공유 지원을 제안합니다.
자동 생성: 기존 코드베이스에서 Constitution을 자동으로 생성할 수 있기를 희망합니다.
기존 프로젝트 지원: 이미 개발된 프로젝트의 통합 지원을 요청합니다.

지원 받기

GitHub Issues: https://github.com/github/spec-kit/issues
문서: https://speckit.org/
블로그 게시물: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
지원 페이지: https://support.claude.com (Claude 관련 문제)

요약

GitHub Spec Kit은 AI 보조 소프트웨어 개발의 중요한 방향을 제시합니다: "즉흥 코딩"(Vibe Coding)에서 "계획적인 구축"으로의 전환입니다. 구조화된 사양 주도 개발 프레임워크를 제공함으로써, 개발자와 AI 어시스턴트 간에 더 효과적인 협업 모델을 구축하는 데 도움을 줍니다.

아직 실험 단계에 있지만, Spec Kit은 복잡한 프로젝트 개발에서 그 가치를 이미 입증했습니다. 도구의 지속적인 개선과 커뮤니티의 기여를 통해 사양 주도 개발은 AI 시대 소프트웨어 엔지니어링의 중요한 실천 방법이 될 것으로 기대됩니다.

라이선스: MIT License

최신 버전: 최신 릴리스 버전은 https://github.com/github/spec-kit/releases 에서 확인하세요.