GitHub Spec Kit으로 Spec-Driven Development 시작하기

Yono·2026년 6월 23일
sdd
post-thumbnail

GitHub Spec Kit 분석: 왜 이제는 코드보다 Spec이 중요한가?

AI 코딩 시대가 오면서 개발자는 더 이상 코드를 직접 작성하는 사람이 아니라 AI에게 무엇을 만들어야 하는지 설명하는 사람이 되어가고 있다.

하지만 많은 개발자들이 경험했듯이 AI에게 설명하는 것은 생각보다 어렵다.

GitHub가 공개한 Spec Kit은 이러한 문제를 해결하기 위해 등장한 오픈소스 프로젝트다.

GitHub Spec Kit

GitHub가 공개한 AI 기반 Spec-Driven Development(SDD) 프레임워크

현재 Cursor, Claude Code, GitHub Copilot 등 AI 코딩 도구와 함께 활용할 수 있으며, "명세 → 계획 → 작업 분해 → 구현" 과정을 체계화하는 것을 목표로 한다.

AI 코딩의 현실

최근 Cursor, Claude Code, ChatGPT와 같은 AI 코딩 도구들이 빠르게 발전하면서 많은 개발자들이 AI 기반 개발을 경험하고 있다.

기존 개발 방식은 대략 다음과 같다.

요구사항
  ↓
Prompt 작성
  ↓
AI 코드 생성
  ↓
수정 반복

처음에는 생산성이 매우 높아 보인다.

하지만 프로젝트 규모가 커질수록 다음과 같은 문제가 발생한다.

  • 요구사항 누락
  • 기능 간 충돌
  • 일관성 없는 설계
  • AI의 임의적인 기술 선택
  • 유지보수 어려움
  • 컨텍스트 손실

특히 AI가 여러 차례의 대화를 거치면서 프로젝트 전체 맥락을 잃어버리는 경우가 많다.

결국 개발자는 AI가 생성한 코드를 검토하고 수정하는 데 많은 시간을 소비하게 된다.

GitHub Spec Kit이란?

GitHub Spec Kit은 GitHub에서 공개한 오픈소스 프로젝트로, AI 기반 개발 과정에 Spec-Driven Development(SDD) 를 적용하기 위한 프레임워크이다.

기존 방식이

Idea
 ↓
Prompt
 ↓
Code

였다면,

Spec Kit은 다음과 같은 과정을 거친다.

Idea
 ↓
Specification
 ↓
Planning
 ↓
Task Breakdown
 ↓
Implementation

즉, 코드를 생성하기 전에 먼저 명세(Specification)를 작성하는 방식이다.

왜 Spec이 중요한가?

AI는 매우 뛰어난 코드 생성 능력을 가지고 있다.

문제는 "무엇을 만들어야 하는지" 가 불명확한 경우다.

예를 들어 다음과 같은 요청을 한다고 가정해 보자.

회원가입 기능 만들어줘

AI는 여러 가지를 임의로 결정해야 한다.

- 이메일 인증을 할 것인가?
- 비밀번호 정책은?
- OAuth 로그인을 지원하는가?
- JWT를 사용하는가?
- 데이터베이스는 무엇인가?

질문 하나에 수십 개의 설계 결정이 숨어 있다.

결국 AI는 추측을 통해 구현하게 되고, 이는 프로젝트마다 다른 결과를 만들어낸다.

Spec Kit은 이러한 문제를 줄이기 위해 먼저 명세를 정의하도록 강제한다.

Spec Kit의 동작 방식

1. Specification 생성

/specify

사용자가 기능 요구사항을 입력하면 spec.md 파일이 생성된다.

예시:

# User Registration

## Goals

사용자는 이메일을 통해 회원가입할 수 있어야 한다.

## Requirements

- 이메일 인증 필수
- 비밀번호 최소 8자리
- 중복 이메일 허용 불가

2. Plan 생성

/plan

Spec를 기반으로 구현 계획을 생성한다.

예시:

# Architecture

- Spring Boot
- PostgreSQL
- JWT Authentication

# Components

- Auth Controller
- User Service
- Email Verification Service

3. Task 생성

/tasks

실제 개발 작업 단위로 분해한다.

예시:

- Create User Entity
- Implement Registration API
- Add Email Verification
- Add Integration Tests

4. 구현

/implement

생성된 계획을 기반으로 실제 코드를 작성한다.

즉,

Spec
 ↓
Plan
 ↓
Tasks
 ↓
Implementation

프로세스를 강제하는 것이다.

Constitution: Spec Kit의 핵심

Spec Kit에서 가장 흥미로운 개념은 Constitution 이다.

일종의 프로젝트 헌법(Project Constitution)이라고 볼 수 있다.

예시:

# Project Constitution

## Architecture

- Backend는 Spring Boot 사용
- Database는 PostgreSQL 사용

## Quality

- 테스트 커버리지 80% 이상
- API 문서 필수 작성

## Security

- JWT 기반 인증 사용
- 비밀번호 BCrypt 암호화

이 규칙은 이후 모든 기능 개발 과정에 적용된다.

즉 AI가 임의로 다른 기술 스택을 선택하거나 조직의 개발 표준을 무시하지 못하도록 만드는 장치다.

Cursor · Claude Code 사용자에게 의미하는 것

많은 개발자들이 현재 아래와 같은 방식으로 AI를 활용한다.

Cursor

"회원가입 기능 만들어줘"

그리고 생성된 결과를 수정한다.

하지만 프로젝트 규모가 커질수록

"지난번에 만들었던 로그인 로직과 맞춰서 수정해줘"

같은 요청이 반복된다.

Spec Kit은 이 과정을 구조화한다.

회원가입 기능 요청
 ↓
Spec 작성
 ↓
검토
 ↓
Plan 작성
 ↓
Task 생성
 ↓
구현

즉 AI에게 자유를 주는 대신, AI가 따라야 할 규칙을 먼저 정의하는 방식이다.

실제로 유용할까?

개인적으로는 다음과 같은 프로젝트에서 특히 효과가 클 것으로 보인다.

스타트업 초기 제품 개발

  • 빠른 기능 추가 필요
  • 요구사항 변경 빈번

기업 내부 시스템

  • 개발 표준 유지 필요
  • 여러 개발자가 협업

AI 기반 개발 조직

  • Cursor
  • Claude Code
  • GitHub Copilot

사용 비중이 높은 팀

반면 다음과 같은 경우에는 효과가 제한적일 수 있다.

  • 개인 토이 프로젝트
  • 단순 CRUD 예제
  • 하루 이틀 만에 끝나는 프로젝트

Spec 작성 비용 자체가 추가되기 때문이다.

마무리

GitHub Spec Kit은 단순한 코드 생성 도구가 아니다.

오히려 AI 시대에 맞는 새로운 개발 프로세스를 제안하는 프로젝트에 가깝다.

기존의 AI 개발이

Prompt → Code

였다면,

Spec Kit은

Spec → Plan → Tasks → Code

로 전환한다.

AI의 성능이 좋아질수록 중요한 것은 코드 작성 능력이 아니라,

"무엇을 만들어야 하는지 명확하게 정의하는 능력"

이 될 가능성이 높다.

GitHub Spec Kit은 바로 그 방향성을 보여주는 흥미로운 시도라고 생각한다.

profile
Yono
Java,Spring,JavaScript
이전 포스트

Saas 서비스 개발 회고록

0개의 댓글