# GitHub의 Spec Kit - 고품질 소프트웨어를 더 빠르게 개발하기

> Clean Markdown view of GeekNews topic #23074. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=23074](https://news.hada.io/topic?id=23074)
- GeekNews Markdown: [https://news.hada.io/topic/23074.md](https://news.hada.io/topic/23074.md)
- Type: news
- Author: [xguru](https://news.hada.io/@xguru)
- Published: 2025-09-15T09:46:02+09:00
- Updated: 2025-09-15T09:46:02+09:00
- Original source: [github.com/github](https://github.com/github/spec-kit)
- Points: 54
- Comments: 9

## Summary

**명세 주도 개발(spec-driven development)** 을 통해 **무엇을 개발하고 왜 개발하는지**를 우선적으로 정의하고, 이후에 구체적인 **구현**을 자동화하는 새로운 접근법을 제시합니다. Spec-Kit의 핵심 구성은 **specify CLI**와 각 에이전트용 **프로젝트 템플릿**, 그리고 프로젝트내의 협상 불가능한 원칙을 담는 **Constitution** 문서로, 이를 통해서 스펙→플랜→태스크→구현의 단계적 산출물을 생성합니다. **Copilot/Claude/Cursor/Gemini** 등을 지원하며, Linux/macOS 또는 Windows의 WSL2 등에서 사용 가능한 스크립트를 제공해서 OS와 상관없이 이용가능합니다.

## Topic Body

- **Spec-Driven Development**: 전통적 개발에서 보조 수단이던 **명세(Spec)** 를 **실행 가능한 명세**로 승격해, 명세로부터 직접 **동작하는 구현**을 생성하려는 접근  
  - 코드가 중심이던 관행을 전환해 **무엇과 왜**를 먼저 정의하고 이후에 **어떻게**를 구체화하는 **의도 중심 개발**을 강조  
  - 핵심 아이디어는 명세를 통해 일관된 산출물을 만들고, 반복 작업을 **자동화**해 개발자가 제품 문제에 집중하도록 지원함  
- Spec Kit은 이렇게 **명세**를 **실행 가능 산출물**로 전환해 구현을 자동화하는데 도움을 주는 도구 모음  
- 설치후 `/specify`로 **무엇/왜**를 기술하고, `/plan`으로 **스택/아키텍처**를 선언하며, `/tasks`로 **작업 단위**를 생성  
- 목표는 조직이 **차별화되지 않은 공통 코드** 작성에서 벗어나 **제품 시나리오**에 집중하도록 돕는 것으로, 명세 주도 방식을 통해 품질과 속도 모두를 끌어올리려는 실험적 프레임워크  
  
### 핵심 철학: Core philosophy  
- **의도 중심 개발**로 **무엇**을 앞세우고 **어떻게**는 이후에 구체화하는 **명세 우선** 사고방식  
- **가드레일**과 조직적 원칙을 갖춘 **풍부한 명세**를 작성하고, **일회성 코드 생성**이 아닌 **다단계 정제** 과정을 거침  
- **고급 AI 모델**의 해석 능력에 **적극 의존**해 명세를 실행 가능한 결과로 변환하는 활용법 지향  
  
### Spec Kit을 사용한 스펙 주도 프로세스  
- **Spec Kit**은 스펙을 엔지니어링 프로세스의 중심으로 만들어 구현, 체크리스트, 작업 분해를 주도하며, 개발자는 주로 지시 역할을 수행  
  - 코딩 에이전트가 대부분의 작성 작업을 담당  
- 프로세스는 **4단계**로 구성되어 각 단계에 명확한 체크포인트가 있으며, 현재 작업이 완전히 검증될 때까지 다음 단계로 이동하지 않음  
- **Specify 단계**: 고수준 설명을 제공하면 코딩 에이전트가 상세 스펙을 생성하며, 이는 기술 스택이 아닌 사용자 여정, 경험, 성공 지표에 초점  
  - 사용자가 누구인지, 어떤 문제를 해결하는지, 상호작용 방식, 중요한 결과 등을 매핑  
  - 이는 사용자 학습에 따라 진화하는 **살아 있는 아티팩트** 형태  
- **Plan 단계**: 원하는 스택, 아키텍처, 제약 조건을 제공하면 코딩 에이전트가 포괄적인 기술 계획을 생성  
  - 회사 표준 기술, 레거시 시스템 통합, 규정 준수, 성능 목표 등을 포함  
  - 여러 계획 변형을 요청하여 비교 가능하며, 내부 문서를 제공하면 아키텍처 패턴을 직접 통합  
- **Tasks 단계**: 스펙과 계획을 바탕으로 코딩 에이전트가 작업을 작은, 검토 가능한 청크로 분해  
  - 각 작업은 독립적으로 구현 및 테스트 가능하며, AI가 작업을 검증하고 추적할 수 있도록 설계  
  - 예를 들어 "인증 구축" 대신 "이메일 형식 검증을 하는 사용자 등록 엔드포인트 생성"처럼 구체적  
- **Implement 단계**: 코딩 에이전트가 작업을 하나씩 또는 병렬로 처리하며, 개발자는 집중된 변경 사항을 검토  
  - 스펙이 무엇을 구축할지, 계획이 어떻게 구축할지, 작업이 무엇을 작업할지 알려줌  
- 각 단계에서 개발자는 반성하고 정제하며, 스펙이 의도를 포착하는지, 계획이 실제 제약을 고려하는지, 누락이나 에지 케이스를 확인하는 **검증 역할** 수행  
  
### 에이전틱 워크플로에서 Spec Kit 사용 방법  
- Spec Kit은 **GitHub Copilot, Claude Code, Gemini CLI** 같은 코딩 에이전트와 작동하며, 간단한 명령어 시리즈를 통해 에이전트를 지시하고 아티팩트를 생성  
  - 이는 모호한 프롬프트를 명확한 의도로 변환하여 신뢰성 있게 실행  
- 프로젝트 초기화 후 /specify 명령으로 고수준 프롬프트를 제공하면 코딩 에이전트가 전체 스펙을 생성하며, 프로젝트의 "무엇"과 "왜"에 초점  
- /plan 명령으로 고수준 기술 방향을 제공하면 코딩 에이전트가 아키텍처와 제약을 존중하는 상세 계획 생성  
- /tasks 명령으로 스펙과 계획을 실행 가능한 작업 목록으로 분해하며, 코딩 에이전트가 이를 바탕으로 프로젝트 요구사항 구현  
  
### 개발 단계: Development phases  
- **0-to-1(그린필드)** 단계 : 고수준 요구사항을 기반으로 **명세 생성 → 계획 수립 → 프로덕션급 앱** 생성 흐름 지원  
- **창의적 탐색** 단계 : **다양한 스택/아키텍처**와 **UX 패턴**을 **평행 구현**으로 실험하는 프로세스 강조  
- **점진적 개선(브라운필드)** 단계 : **기능 추가**, **레거시 현대화**, **프로세스 적응**을 반복하는 **진화형 개발**  
  
### 이 접근법이 잘 작동하는 3가지 시나리오  
- **그린필드(zero-to-one)** : 새로운 프로젝트 시작 시 코딩을 바로 하지 않고 스펙과 계획을 미리 만들어 AI가 의도된 것을 구축하도록 보장하며, 일반 패턴 기반의 일반적 솔루션 대신 맞춤형 결과 제공  
- **기존 시스템의 기능 작업(N-to-N+1)** : 복잡한 코드베이스에 기능을 추가할 때 스펙으로 새로운 기능의 기존 시스템 상호작용을 명확히 하고, 계획으로 아키텍처 제약을 인코딩하여 네이티브처럼 느껴지는 코드 생성  
  - 이는 지속 개발을 더 빠르고 안전하게 하며, 고급 컨텍스트 엔지니어링 기법이 필요할 수 있음  
- **레거시 현대화**: 레거시 시스템 재구축 시 원래 의도가 상실된 경우, Spec Kit 프로세스로 필수 비즈니스 로직을 현대 스펙에 포착하고 신선한 아키텍처를 계획하여 AI가 기술 부채 없이 재구축  
  
### Prerequisites  
- **Linux/macOS** 또는 **Windows의 WSL2** 필요  
- AI 에이전트로 **Claude Code**, **GitHub Copilot**, **Gemini CLI**, **Cursor** 중 선택

## Comments



### Comment 44052

- Author: edunga1
- Created: 2025-09-18T20:10:05+09:00
- Points: 1

copilot workspace가 생각나네요.

### Comment 43878

- Author: cocofather
- Created: 2025-09-16T07:41:10+09:00
- Points: 1

자연어기반 AI 프로그래밍의 토대가 될거같네요

### Comment 43853

- Author: tested
- Created: 2025-09-15T11:02:47+09:00
- Points: 1

GitHub의 Spec Kit의 장점은 GitHub Copilot에서도 쓸 수 있습니다.  
GitHub에서 만들었으니 당연?하겠지만 다른 도구들은 Claude 기반인 게 많았죠.

### Comment 43848

- Author: skageektp
- Created: 2025-09-15T10:34:10+09:00
- Points: 1

Kiro IDE가 생각나네요

### Comment 43836

- Author: kandk
- Created: 2025-09-15T10:12:09+09:00
- Points: 1

재밌네요. 말이 되기도 하고

### Comment 43825

- Author: xguru
- Created: 2025-09-15T09:47:01+09:00
- Points: 2

글 중간에 SDD 상세 소개 링크가 내용이 좋네요. 아래는 AI로 요약해 본 겁니다.   
  
[명세 주도 개발(Specification-Driven Development, SDD)](https://github.com/github/spec-kit/blob/main/spec-driven.md)  
  
### The Power Inversion  
- 코드를 중심으로 PRD·디자인 문서가 보조하던 흐름을 뒤집어, **명세가 원본**이고 코드는 **표현물**로서 특정 언어·프레임워크에 구현됨  
  - 명세와 구현 사이의 **영구적 간극**을 문서 보강이나 절차 강화로는 해소하기 어려웠다는 진단 제시  
  - **실행 가능한 명세**와 **구현 계획**이 코드를 생성하면 간극은 사라지고 **변환만 존재**함  
- AI는 복잡한 명세 해석과 구현 계획 수립을 가능케 하나, **구조 없는 생성은 혼란**을 초래하므로 SDD는 **정밀한 구조·가드레일**로 품질을 확보함  
- 유지보수는 명세 진화 행위이며, 개발 의도는 **자연어·디자인 자산·핵심 원칙**으로 표현되고 코드는 **라스트 마일** 위치를 점함  
- 디버깅은 잘못된 코드 수정보다 **명세·구현 계획 수정**을 우선하며, 리팩터링은 **명료성 재구성** 의미로 재정의됨  
  
### The SDD Workflow in Practice  
- 아이디어를 AI와의 **대화적 상호작용**으로 PRD로 정련하고, AI는 **질문·엣지 케이스·수용 기준**을 구체화함  
  - 요구·설계를 **연속 활동**으로 전환해 팀 단위 **브랜치 기반 명세 작업**과 리뷰·버저닝을 지원함  
- **리서치 에이전트**가 라이브러리 호환성, 성능, 보안, **조직 제약**(DB 표준·인증·배포 정책)을 탐색해 명세에 자동 반영함  
- PRD에서 **구현 계획**을 생성해 요구와 기술 결정을 **추적 가능**하게 매핑하고, AI가 **모순·애매성·누락**을 지속 검증함  
- 명세·계획이 충분히 안정되면 **코드 생성**을 시작하되, 초기에는 **탐색적 생성**으로 실현 가능성을 검증함  
  - 도메인 개념은 **데이터 모델**, 유저 스토리는 **API 엔드포인트**, 수용 시나리오는 **테스트**로 전환됨  
- 운영 단계의 **메트릭·인시던트**는 명세를 갱신하여 다음 재생성에 반영되고, 성능 병목은 **비기능 요구**, 취약점은 **전역 제약**으로 승격됨  
  
### Why SDD Matters Now  
- **AI 역량 임계점**: 자연어 명세에서 **동작 코드**를 신뢰성 있게 생성 가능하며, 구현 번역의 **기계적 부분 자동화**로 **탐색·창의성 증폭** 지원임  
- **복잡성 폭증**: 다수 서비스·프레임워크·의존성으로 **의도-구현 정합성** 유지가 어려워 SDD의 **명세 구동 정렬**이 필요함  
- **변화 가속**: 빈번한 피벗 상황에서 SDD는 변경을 **문서-디자인-코드 수작업 전파** 대신 **체계적 재생성**으로 처리함  
  - 예시적으로 **what-if 시뮬레이션**과 병행 구현을 가능하게 하여 **의사결정 민첩성**을 제공함  
  
### Core Principles  
- **명세=공용어**: 명세가 1급 산출물, 코드는 특정 스택의 **표현**이며 유지보수는 **명세 진화** 행위임  
- **실행 가능한 명세**: **정확·완결·비모호** 수준의 명세로 **작동 시스템**을 생성함  
- **지속 정련**: 일회성 게이트가 아닌 **상시 일관성 검증**을 수행함  
- **리서치 기반 맥락**: 성능·보안·조직 제약을 **연속적으로 수집**해 명세에 주입함  
- **양방향 피드백**: 운영 현실이 **명세 업데이트 입력**이 됨  
- **탐색을 위한 브랜칭**: 동일 명세에서 **성능·유지보수성·UX·비용** 등 최적화 목표별 **복수 구현** 생성 지원임  
  
### Implementation Approaches  
- 오늘의 실천은 기존 도구 조합과 **규율 유지**가 핵심이며, 다음 요소로 구현 가능함  
  - 명세 반복 정련용 **AI 어시스턴트**  
  - 기술 맥락 수집용 **리서치 에이전트**  
  - 명세→구현 변환용 **코드 생성 도구**  
  - **명세 우선** 워크플로에 맞춘 **버전 관리**  
  - 명세 문서 **AI 일관성 분석** 기반 체킹  
- 공통 원칙은 **명세를 단일 진실원**으로 두고, 코드를 **명세가 요구하는 산출물**로 취급하는 태도임  
  
### Streamlining SDD with Commands  
- **`/specify`**: 기능 설명을 구조화된 **명세**로 변환하고 **자동 번호 부여**, **브랜치 생성**, **템플릿 기반 디렉터리** 구성을 자동화함  
- **`/plan`**: 명세 분석 → **헌법 준수** 검토 → **기술 번역** → **데이터 모델·API 계약·테스트 시나리오** 문서화 → **퀵스타트 검증**을 생성함  
- **`/tasks`**: `plan.md`와 관련 설계를 읽어 **실행 가능한 태스크 리스트**를 산출하고, **병렬 가능 태스크 표시**와 안전 병렬 그룹화를 제공함  
- **예시: 채팅 기능**  
  - 전통 접근의 ~12시간 문서 작업을 **명세·계획·태스크** 자동화로 약 **15분 구성**으로 단축하는 흐름 예시 제시  
  - 산출물에는 **명세**, **구현 계획과 근거**, **API 계약·데이터 모델**, **퀵스타트 시나리오**, **tasks.md**가 **브랜치에 버전 관리**됨  
  
### The Power of Structured Automation  
- **빠진 항목 방지**: 템플릿이 **비기능 요구·에러 처리**까지 포괄함  
- **결정 추적성**: 모든 기술 선택이 **구체 요구와 연결**됨  
- **살아 있는 문서**: 명세가 **코드를 생성**하므로 **동기화 유지**가 용이함  
- **신속 반복**: 요구 변경 시 **계획 재생성**으로 분·시간 단위 대응 가능함  
  
### Template-Driven Quality  
- **구현 세부의 성급한 침투 방지**: WHAT/WHY 집중, HOW 배제 규칙으로 **추상화 레벨 유지** 유도함  
- **불확실성 표식 강제**: `[NEEDS CLARIFICATION]` 마커로 **추측 금지**와 **명시적 질문**을 유도함  
- **체크리스트 기반 자가 검수**: **완전성·명확성·측정 가능 수용 기준** 확인으로 **품질 게이트** 구현함  
- **헌법 게이트**: **단순성 게이트(≤3 프로젝트)**, **반추상화 게이트(프레임워크 직접 사용)**, **통합 우선 게이트(계약·계약 테스트 선행)** 등 **사전 단계(-1)** 체크 적용함  
- **계층화된 세부 관리**: 과도한 코드·세부는 `implementation-details/`로 분리해 **가독성 유지**함  
- **테스트 우선성**: **계약→통합→E2E→단위** 순서의 **파일 생성·테스트 우선** 규칙으로 **검증 가능성** 확보함  
- **가정·추측 기능 억제**: **추측적 기능 금지**와 **단계별 선행조건** 명시로 **범위 관리** 강화함  
  
### The Constitutional Foundation  
- `memory/constitution.md`의 **불변 원칙**으로 모든 구현을 **일관·단순·고품질**로 유지하는 **개발 헌법**을 채택함  
  - **Article I: Library-First** — 모든 기능은 **독립 라이브러리**로 시작해 **모듈성** 확보  
  - **Article II: CLI Mandate** — 모든 라이브러리는 **텍스트 입출력·JSON**을 지원하는 **CLI 인터페이스**를 노출해 **관측 가능성**과 **테스트 용이성** 보장  
  - **Article III: Test-First** — **테스트 승인·실패(red) 확인 전 구현 금지**, **행동 정의 우선** 원칙 적용  
  - **Articles VII & VIII: 단순성·반추상화** — **프로젝트 수 최소화**와 **프레임워크 직접 신뢰**로 **과공학 억제**  
  - **Article IX: 통합 우선 테스트** — **실환경 근접** 테스트를 선호하고 **계약 테스트**를 구현 선행으로 강제  
- 템플릿의 **Phase -1 게이트**로 헌법 준수를 **체크리스트화**하고, 예외는 **Complexity Tracking**에 **명시 근거**를 기록함  
- **개정 절차**를 통해 원칙의 **적용 방식**은 진화 가능하되 **핵심 철학**은 유지함  
  
### The Transformation  
- 목표는 개발자 대체가 아니라 **기계적 번역 자동화**로 **인간 능력 증폭**과 **의도-구현 정합성 유지**임  
- SDD는 명세가 코드를 **생성**하도록 하여, **명세·리서치·코드**가 **타이트한 피드백 루프**로 동반 진화하는 **연속적 변형**을 실천함

### Comment 43944

- Author: amoplan
- Created: 2025-09-17T04:58:10+09:00
- Points: 1
- Parent comment: 43825
- Depth: 1

어떤 ai로 정리하셨을까요?

### Comment 43950

- Author: xguru
- Created: 2025-09-17T09:35:44+09:00
- Points: 1
- Parent comment: 43944
- Depth: 2

GPT-5 로 했고요. 제가 요약용으로 정리한 꽤 긴 프롬프트를 사용합니다.

### Comment 44144

- Author: heycalmdown
- Created: 2025-09-22T10:16:10+09:00
- Points: 3

컨셉에 무척 공감을 해서 신규 프로젝트로 주말에 테스트를 좀 해봤는데, 생각만큼 잘 되지는 않네요. 아직 많은 개선이 필요한 것 같습니다. 일단 대략적인 동작은 여러번 소개됐듯이 다음과 같습니다:   
헌법 작성 → 스펙 작성 → 태스크 작성 → 구현  
  
문제는  
- constitution.md 파일은 "어떻게 개발할 것인가"에 대한 핵심 가이드이지만 "이 앱이 최종적으로 무엇이 될 것인가"는 담고 있지 않습니다  
- spec.md는 하나의 기능을 설명하는 문서입니다  
- "이 앱은 무엇인가"에 대한 마스터 문서는 없습니다  
- 깃헙에서 이뤄지고 있는 토론을 읽어보니까, chain of specs가 결국 source of truth가 될 것이다 - 라는 것 같습니다. 갸웃거려지지만 얼추 이해는 할 수 있었습니다.  
- `/specify`와 `/tasaks` 커맨드를 통해 많은 문서를 산출물로 생성하는데(원했던 결과), 그래서 그런지 컨텍스트를 빠르게 소모합니다(Claude Code 사용중)  
- 일단 구현에 들어가면 Spec Kit과는 잠시 멀어지고 평소처럼 Claude Code와 대화를 통해 구현을 마무리하게 됩니다  
- 컨텍스트를 다 소모하고 compaction 하거나 새로 세션을 시작하면 Spec Kit이 생성한 문서의 존재를 잊어버립니다  
- tasks.md에 정의된 작업을 진행하다 보면 앞에 제대로 만들었던 것을 덮어 쓰기도 하고 버그를 수정하는 과정에서 새로운 기능을 만들기도 하는데 tasks.md와 점점 거리가 멀어집니다. tasks.md를 영구 보관할 의미를 모르겠습니다.  
  
일단 제가 내린 결론은 다음과 같습니다  
  
- 최초 생각한 것과 다른 결과가 나오더라도 일단 스펙을 마무리 하고 새로운 스펙을 만들어서 조금씩 고쳐 나가야 한다  
- 최초 스펙은 커질 수밖에 없는데 앱의 기능에 대해서는 아예 설명하지 말고 보일러플레이트만 만드는 게 낫겠다  
- PoC 수준으로 만들 때는 Spec Kit은 안 쓰는 게 낫겠다