GitHub, 스펙 기반 개발(Spec-Driven Development)를 위한 실험적 프레임워크 Spec Kit 공개

9bow · 9월 6, 2025, 8:00오전

Spec Kit 소개

Spec Kit은 GitHub이 최근 공개한 오픈소스 도구로, 스펙 기반 개발(Spec-Driven Development, 이하 SDD) 을 실천하기 위한 실험적 프레임워크입니다. 전통적인 소프트웨어 개발은 언제나 코드가 중심이었습니다. 요구사항 문서, 설계 문서, 아키텍처 다이어그램 등은 시간이 지나면서 코드와 동기화되지 못해 버려지고, 개발자는 “코드만 보면 된다”는 태도에 익숙해졌습니다.

Spec Kit은 이러한 구조를 뒤집는 도구입니다. 코드가 스펙을 따르는 것이 아니라, 스펙이 코드의 원천이 됩니다. 스펙은 단순한 가이드가 아니라 실행 가능한 명세로 다뤄지며, 여기에 기반한 구체적인 구현 계획이 만들어지고, 최종적으로 코드가 생성됩니다.

Spec Kit을 활용하면 개발팀은 더 이상 “코드 짜기”라는 반복적이고 차별화되지 않은 작업에 묶이지 않고, 제품 시나리오와 사용자 가치 창출에 집중할 수 있습니다. 특히 빠른 프로토타이핑, 병렬 실험, 기존 시스템의 점진적 현대화 같은 상황에서 강력한 효과를 발휘합니다.

Spec Kit 시작하기

Spec Kit은 specify라는 CLI 도구를 중심으로 동작하며, 다음과 같은 사전 요구사항을 만족해야 합니다:

Linux/macOS (또는 Windows WSL2)
Python 3.11 이상, Git, uv 필요
AI 코딩 에이전트: Claude Code, GitHub Copilot, Gemini CLI 중 선택

specify_cli

Spec Kit의 사용 방법은 다음과 같습니다:

설치: 다음과 같은 명령어로 사용 중인 코딩 에이전트에 따른 프로젝트 초기화를 진행합니다:
```
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
```
스펙 작성: /specify 명령어를 사용하여 구축하고자 하는 내용을 설명합니다. 이 단계에서는 기술 스택에 신경 쓰지 않고, **무엇을 만들고자 하는지(What), 왜 필요한지(Why)**만 정의합니다:
```
/specify Build an application that helps me organize photos into albums...
```
구현 계획 수립: /plan 명령어를 사용하여 기술 스택 및 아키텍처 선택 사항 등을 구체적으로 지정합니다:
```
/plan Use Vite with vanilla JS, CSS, SQLite...
```
작업 분해 및 실행: /tasks 명령어를 사용하여 실행 가능한 작업 목록을 생성한 후, 에이전트에게 해당 기능을 구현하도록 합니다:
```
/tasks
```

SDD(스펙 기반 개발(Spec-Driven Development) 방법론 소개

스펙 기반 개발(Spec-Driven Development, 이하 SDD)은 기존 소프트웨어 개발의 중심축을 코드에서 스펙으로 전환하는 새로운 방법론입니다. 전통적으로 소프트웨어 개발에서 스펙은 부차적인 존재였습니다. 제품 요구사항 문서(PRD), 설계 문서, 다이어그램은 코드를 작성하기 위한 도구였을 뿐, 시간이 지나면 코드와 따로 놀게 되었고 결국 버려지곤 했습니다.

하지만 SDD에서는 코드가 스펙을 따르며, 스펙이 코드의 원천이 됩니다. 스펙은 단순한 설명서가 아니라 실행 가능한 아티팩트이며, 이를 통해 구체적인 구현 계획과 코드가 자동 생성됩니다. 즉, 코드가 중심이 아니라, 스펙이 진실의 원천이 되는 패러다임 전환입니다.

이러한 접근은 최근 AI 기술의 도약 덕분에 가능해졌습니다. AI는 복잡한 스펙을 이해하고 이를 기반으로 상세한 구현 계획을 생성할 수 있으며, 실행 가능한 코드를 만들어낼 수 있습니다. 다만 AI 단독으로는 혼란이 발생하기 쉬우므로, SDD는 명확하고 구조화된 스펙과 계획을 통해 AI의 출력을 제약하면서 품질을 보장합니다.

이러한 SDD는 기존의 개발 방법론과 유사한 점이 있지만, 핵심적인 차이가 존재합니다:

TDD(Test-Driven Development): 테스트 코드를 먼저 작성하고 이를 만족하는 코드를 작성합니다. 품질을 보장하지만, 여전히 코드가 중심입니다.
BDD(Behavior-Driven Development): 사용자 행동을 중심으로 시나리오를 작성하고 이를 구현합니다. 그러나 스펙이 코드로 직접 변환되는 것은 아닙니다.
SDD(Spec-Driven Development): 명세 그 자체를 실행 가능한 산출물로 취급합니다. 스펙에서 곧바로 코드와 테스트가 생성되며, 개발자는 명세의 풍부함과 정확성에 집중합니다.

즉, TDD와 BDD가 코드 품질 보장 방법론이라면, SDD는 아예 개발의 중심축을 코드에서 스펙으로 옮기는 패러다임 전환이라 할 수 있습니다.

SDD(Spec-Driven Development)의 핵심 철학

의도 중심 개발: 개발은 “무엇을” 만드는지에서 시작합니다.
풍부한 명세 작성: Guardrail과 템플릿으로 일관되고 완전한 스펙을 작성합니다.
다단계 정제: 단일 프롬프트에서 코드가 나오는 것이 아니라, 스펙 → 계획 → 코드로 점진적으로 발전합니다.
AI 해석 활용: 최신 AI 모델이 스펙을 읽고 코드와 테스트를 생성합니다.

이러한 핵심 철학에 따라, 다음과 같은 주요 원칙들이 탄생했습니다:

실행 가능한 스펙: 명확하고 완전해야 코드와 테스트로 변환 가능
지속적 정제: 모호성·모순을 AI가 지속적으로 검증
리서치 에이전트 활용: 보안·성능·호환성 맥락 자동 수집
양방향 피드백: 운영 데이터가 다시 스펙을 개선
브랜치 기반 탐색: 동일 스펙에서 다양한 구현을 병렬 탐색

SDD 방법론의 작업 흐름(Workflow)

아이디어 도출 모호한 아이디어를 AI와 대화하며 점차 구체적인 스펙(PRD)으로 발전시킵니다.
스펙 작성 제품 매니저와 팀원은 AI와 협업해 구체적인 사용자 스토리, 수용 기준을 포함한 명세를 작성합니다.
구현 계획 생성 AI는 스펙을 해석하여 기술적 선택과 아키텍처 결정을 담은 구현 계획을 만듭니다. 모든 선택은 스펙과 직접 연결되며, 일관성 검증이 지속적으로 이루어집니다.
코드 및 테스트 생성 스펙과 계획이 안정화되면 코드가 생성됩니다. 사용자 스토리는 API 엔드포인트로, 수용 기준은 테스트 시나리오로 변환됩니다.
운영 피드백 통합 운영 중 발생한 성능 문제, 보안 취약점, 장애 정보는 다시 스펙에 반영되어 차기 버전 구현에서 자동으로 적용됩니다.

SDD의 개발 단계

스펙 기반 개발(SDD)은 전통적인 SDLC(Software Development Life Cycle)와는 조금 다른 흐름을 제시합니다. 단순히 “요구사항 → 설계 → 구현 → 테스트”의 직선적 과정이 아니라, 스펙을 중심으로 한 반복적이고 유연한 사이클로 진행됩니다. Spec Kit에서는 이를 아래와 같은 세 가지 대표적인 단계로 구분하고 있습니다:

단계(Phase)	초점(Focus)	주요 활동(Key Activities)
0-to-1 개발(Development) (“그린필드(Greenfield)”)	처음부터 생성(Generate from scratch)	고수준 요구사항(high-level requirements)에서 시작명세(specifications) 생성구현 단계 계획프로덕션 준비가 완료된 애플리케이션 빌드
창의적 탐색(Creative Exploration)	병렬 구현(Parallel implementations)	다양한 솔루션 탐색여러 기술 스택 및 아키텍처 지원UX 패턴 실험
반복적 개선(Iterative Enhancement) (“브라운필드(Brownfield)”)	브라운필드 현대화(Brownfield modernization)	기능을 반복적으로 추가레거시 시스템 현대화프로세스 적응

SDD 방법론에 대한 더 자세한 내용은 Spec Kit 저장소에 공개된 문서를 참고해주세요.

라이선스

GitHub이 공개한 Spec Kit 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다. 상업적 사용 및 수정이 자유롭습니다.

Spec Kit 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~