#개발방법론#AI#GitHub#생산성#Tools

Jan 23, 2025

GitHub Spec Kit 완벽 가이드: Spec-Driven Development로 개발 효율성 극대화하기

Spec Kit이란?

Spec Kit은 GitHub에서 오픈소스로 공개한 Spec-Driven Development(명세 기반 개발) 툴킷입니다. 기존의 “코드부터 작성하는” 방식에서 벗어나, **실행 가능한 명세(Executable Specifications)**를 우선 작성하고 이를 바탕으로 구현을 생성하는 혁신적인 개발 방법론을 제공합니다.

공식 리포지토리의 설명에 따르면:

“제품 시나리오와 예측 가능한 결과에 집중할 수 있게 해주며, 매번 처음부터 코딩하는 대신 체계적인 접근을 가능하게 합니다.”

기존 개발 방식 vs Spec-Driven Development

전통적인 개발 방식:

아이디어 → 코드 작성 → 문서화(선택적) → 테스트

Spec-Driven Development:

아이디어 → 명세 작성 → 계획 수립 → 구현 → 검증

Spec Kit은 명세를 단순한 참고 문서가 아닌 **일급 개발 산출물(First-class Artifact)**로 취급하며, 이로부터 직접 작동하는 구현을 생성합니다.

왜 Spec Kit을 사용해야 할까?

1. AI 코딩 에이전트와의 완벽한 통합

Spec Kit은 다음과 같은 주요 AI 코딩 어시스턴트들과 통합됩니다:

Claude Code (Anthropic)
GitHub Copilot
Cursor
Windsurf
Gemini CLI
Qwen Code
opencode
기타 다양한 AI 에이전트

2. 체계적인 개발 프로세스

명세 기반 개발은 다음과 같은 이점을 제공합니다:

명확한 의도 전달: 무엇을 만들어야 하는지 명확하게 정의
일관성 유지: 프로젝트 전반에 걸친 일관된 아키텍처와 설계
검증 가능성: 명세와 구현의 일치 여부를 자동으로 검증
효율적인 협업: 팀원 간 명확한 커뮤니케이션 기반 마련

3. 다양한 개발 시나리오 지원

Spec Kit은 세 가지 주요 개발 시나리오를 지원합니다:

Greenfield Development: 처음부터 새로 만드는 프로젝트
Creative Exploration: 여러 구현 방식을 병렬로 실험
Brownfield Modernization: 기존 시스템의 점진적 개선

핵심 구성 요소

Spec Kit의 주요 명령어

Spec Kit은 슬래시 커맨드 형태로 8가지 핵심 기능을 제공합니다:

1. `/speckit.constitution` - 프로젝트 헌법 수립

프로젝트의 거버넌스 원칙과 기본 규칙을 정의합니다.

예시:

## 프로젝트 원칙
- 모든 API는 RESTful 설계를 따른다
- 테스트 커버리지는 최소 80% 이상 유지
- 코드 리뷰 없이 main 브랜치에 머지 불가

2. `/speckit.specify` - 요구사항 및 사용자 스토리 정의

구체적인 기능 요구사항과 사용자 스토리를 작성합니다.

예시:

## 사용자 인증 기능

### 사용자 스토리
사용자로서, 이메일과 비밀번호로 로그인할 수 있어야 한다.

### 수락 기준
- 유효한 이메일 형식 검증
- 비밀번호는 최소 8자 이상
- 로그인 실패 시 명확한 에러 메시지

3. `/speckit.plan` - 기술 구현 전략 수립

요구사항을 바탕으로 구체적인 기술 구현 계획을 생성합니다.

4. `/speckit.tasks` - 실행 가능한 태스크 리스트 생성

구현 계획을 실제로 수행할 수 있는 작은 단위의 태스크로 분해합니다.

5. `/speckit.implement` - 태스크 실행 및 기능 구현

정의된 태스크를 실제로 구현하는 단계입니다.

6. `/speckit.clarify` - 불명확한 부분 해결

명세나 요구사항 중 불명확하거나 모호한 부분을 식별하고 명확화합니다.

7. `/speckit.analyze` - 아티팩트 간 일관성 검증

명세, 계획, 구현 간의 일관성을 검증하고 불일치를 찾아냅니다.

8. `/speckit.checklist` - 품질 검증 체크리스트 생성

구현 품질을 검증하기 위한 체크리스트를 자동으로 생성합니다.

설치 방법

필수 요구사항

Spec Kit을 사용하기 위해서는 다음이 필요합니다:

운영체제: Linux, macOS, 또는 Windows
Python: 3.11 이상
Git
uv: Python 패키지 매니저
AI 코딩 에이전트: Claude Code, Copilot 등

uv 패키지 매니저로 설치

가장 권장되는 설치 방법입니다:

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

설치 없이 바로 실행

설치 없이 바로 사용하고 싶다면:

# 프로젝트 초기화 (설치 없이)
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

실전 사용 가이드

기본 워크플로우

Spec Kit을 사용한 전형적인 개발 프로세스는 다음과 같습니다:

1단계: 프로젝트 초기화

# AI 에이전트 지정하여 프로젝트 초기화
specify init my-awesome-project --ai claude

이 명령어는 프로젝트 구조를 생성하고 필요한 설정 파일들을 준비합니다.

2단계: 프로젝트 원칙 수립

AI 에이전트에서 다음 명령어를 실행합니다:

/speckit.constitution

프로젝트의 핵심 원칙, 코딩 스타일, 아키텍처 가이드라인 등을 정의합니다.

3단계: 명세 작성

/speckit.specify

구현하고자 하는 기능의 요구사항과 사용자 스토리를 상세히 작성합니다.

예시 - Todo 앱 명세:

## 할일 관리 기능

### 기능 개요
사용자가 할일을 추가, 조회, 수정, 삭제할 수 있는 기능

### 주요 요구사항
1. 할일 추가
   - 제목 (필수, 최대 200자)
   - 설명 (선택, 최대 1000자)
   - 마감일 (선택)
   - 우선순위 (낮음/보통/높음)

2. 할일 조회
   - 전체 목록 조회
   - 완료/미완료 필터링
   - 우선순위별 정렬

3. 할일 수정
   - 모든 필드 수정 가능
   - 완료 상태 토글

4. 할일 삭제
   - 확인 메시지 표시 후 삭제

4단계: 기술 계획 수립

/speckit.plan

명세를 기반으로 구체적인 기술 스택, 아키텍처, 데이터 모델 등을 계획합니다.

5단계: 태스크 생성

/speckit.tasks

계획을 실행 가능한 작은 태스크로 분해합니다.

생성된 태스크 예시:

1. [ ] 데이터베이스 스키마 설계 및 생성
2. [ ] Todo 모델 클래스 구현
3. [ ] CRUD API 엔드포인트 구현
4. [ ] 입력 유효성 검증 로직 추가
5. [ ] 단위 테스트 작성
6. [ ] 통합 테스트 작성

6단계: 구현

/speckit.implement

AI 에이전트가 태스크를 순차적으로 구현합니다.

7단계: 검증 및 개선

명세와 구현이 일치하는지 확인:

/speckit.analyze

불명확한 부분이 있다면:

/speckit.clarify

최종 품질 체크:

/speckit.checklist

실전 활용 시나리오

시나리오 1: 새로운 마이크로서비스 구축

# 1. 프로젝트 초기화
specify init payment-service --ai claude

# 2. AI 에이전트에서 순차적으로 실행
/speckit.constitution
  → 서비스 원칙: 멱등성, 장애 격리, 이벤트 기반 설계

/speckit.specify
  → 결제 처리, 환불, 결제 내역 조회 기능 명세

/speckit.plan
  → 기술 스택: Node.js, Express, PostgreSQL, Redis
  → 아키텍처: 레이어드 아키텍처

/speckit.tasks
  → 30개 태스크 생성

/speckit.implement
  → 순차적 구현 시작

시나리오 2: 레거시 코드 리팩토링

# 1. 기존 프로젝트에 Spec Kit 적용
cd legacy-project
specify init . --ai copilot

# 2. 현재 상태 분석
/speckit.analyze
  → 불일치 사항 식별: 문서화되지 않은 API 엔드포인트 발견

# 3. 명세 작성
/speckit.specify
  → 기존 기능의 동작을 명세로 문서화

# 4. 개선 계획
/speckit.plan
  → 점진적 리팩토링 전략 수립

# 5. 실행
/speckit.implement
  → 하나씩 개선

시나리오 3: API 설계 및 구현

# 1. API 명세 작성
/speckit.specify

## RESTful API 명세

### GET /api/users
- 설명: 사용자 목록 조회
- 쿼리 파라미터:
  - page: 페이지 번호 (기본값: 1)
  - limit: 페이지당 항목 수 (기본값: 20)
  - sort: 정렬 기준 (name, created_at)
- 응답: 200 OK
  ```json
  {
    "users": [...],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20
    }
  }


```bash
# 2. 구현 계획
/speckit.plan
  → 라우터 설계, 컨트롤러 구조, 미들웨어 체인

# 3. 검증 체크리스트 생성
/speckit.checklist
  → API 문서 완성도, 에러 처리, 보안 검증 등

Spec-Driven Development의 핵심 철학

Spec Kit이 지향하는 개발 철학은 다음과 같습니다:

1. 의도 중심 개발 (Intent-Driven Development)

“어떻게”보다 “무엇을” 먼저 정의합니다. 구현 세부사항보다 의도와 목표에 집중합니다.

2. 풍부한 명세 작성

단순한 주석이나 TODO가 아닌, 조직의 원칙과 비즈니스 로직이 담긴 상세한 명세를 작성합니다.

3. 다단계 정제 프로세스

한 번에 완벽한 결과를 만들려 하지 않고, 명세 → 계획 → 태스크 → 구현 → 검증의 단계를 거치며 점진적으로 개선합니다.

4. AI 모델의 해석 능력 활용

최신 대규모 언어 모델의 강력한 자연어 이해 능력을 활용하여 명세로부터 구현을 생성합니다.

모범 사례 (Best Practices)

1. 명확하고 구체적인 명세 작성

❌ 나쁜 예:

사용자 로그인 기능을 만든다.

✅ 좋은 예:

## 사용자 로그인 기능

### 입력
- 이메일: RFC 5322 형식
- 비밀번호: 최소 8자, 대소문자+숫자+특수문자 포함

### 처리
1. 이메일 형식 검증
2. DB에서 사용자 조회
3. bcrypt로 비밀번호 검증
4. 성공 시 JWT 토큰 발급 (유효기간 24시간)
5. 실패 시 에러 코드 반환

### 출력
- 성공: { token, user: { id, email, name } }
- 실패: { error: "INVALID_CREDENTIALS" }

### 보안
- 비밀번호 오류 시 사용자 존재 여부 노출 금지
- Rate limiting: 5분 내 5회 실패 시 계정 임시 잠금

2. Constitution을 먼저 확립

프로젝트 시작 시 반드시 헌법(Constitution)을 먼저 작성하세요. 이는 모든 결정의 기준이 됩니다.

## 아키텍처 원칙
1. 단일 책임 원칙 준수
2. 의존성 주입 패턴 사용
3. 모든 외부 API 호출에 Circuit Breaker 적용

## 코드 품질
1. 함수는 20줄 이하로 제한
2. 순환 복잡도 10 이하 유지
3. 모든 public 메서드에 JSDoc 주석

## 테스트 전략
1. 단위 테스트 커버리지 80% 이상
2. 중요 비즈니스 로직은 100% 커버
3. E2E 테스트로 주요 사용자 시나리오 검증

3. 작은 단위로 반복

한 번에 큰 기능을 구현하려 하지 말고, 작은 단위로 나누어 반복적으로 개선하세요.

4. analyze로 주기적 검증

구현 중간중간 /speckit.analyze를 실행하여 명세와 구현의 일치성을 확인하세요.

5. clarify로 애매모호함 제거

명세 작성 후 /speckit.clarify를 실행하여 불명확한 부분을 미리 해결하세요.

AI 코딩 에이전트별 활용 팁

Claude Code 사용 시

Claude Code는 장문의 컨텍스트를 잘 이해하므로 상세한 명세를 작성하면 효과적입니다.

specify init my-project --ai claude

GitHub Copilot 사용 시

Copilot은 코드 자동완성에 특화되어 있으므로 /speckit.implement 단계에서 강력합니다.

Cursor 사용 시

Cursor의 멀티파일 편집 기능을 활용하여 여러 파일을 동시에 리팩토링할 때 유용합니다.

주의사항 및 제한사항

1. AI 모델의 한계 인지

AI가 생성한 코드는 반드시 검토가 필요합니다. 특히 보안, 성능과 관련된 부분은 주의 깊게 확인하세요.

2. 과도한 의존 방지

Spec Kit은 도구일 뿐입니다. 개발자의 판단과 경험을 대체할 수 없습니다.

3. 팀 컨벤션 우선

Spec Kit의 제안과 팀의 기존 컨벤션이 충돌할 경우, 팀 컨벤션을 우선하세요.

4. 점진적 도입

기존 프로젝트에 Spec Kit을 도입할 때는 작은 부분부터 시작하여 점진적으로 확대하세요.

결론

GitHub Spec Kit은 단순한 코드 생성 도구를 넘어, 개발 프로세스 자체를 재구성하는 패러다임 전환을 제공합니다. 명세 기반 개발을 통해:

✅ 더 명확한 요구사항 정의
✅ 팀 간 원활한 커뮤니케이션
✅ 일관성 있는 코드베이스
✅ 검증 가능한 구현
✅ AI의 효과적인 활용

을 달성할 수 있습니다.

특히 AI 코딩 에이전트와 결합했을 때, Spec Kit은 개발 생산성을 극적으로 향상시킬 수 있는 강력한 도구입니다. 처음에는 낯설 수 있지만, 명세 작성 습관이 몸에 배면 “왜 진작 사용하지 않았을까?”라는 생각이 들 것입니다.

지금 바로 시작해보세요:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-first-spec-project --ai claude

추가 자료

명세 기반 개발로 더 나은 소프트웨어를 만들어보세요!