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

(github.com/github)

54P by xguru 1달전 | ★ favorite | 댓글 9개

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 중 선택

▲

heycalmdown 1달전 [-]

컨셉에 무척 공감을 해서 신규 프로젝트로 주말에 테스트를 좀 해봤는데, 생각만큼 잘 되지는 않네요. 아직 많은 개선이 필요한 것 같습니다. 일단 대략적인 동작은 여러번 소개됐듯이 다음과 같습니다:
헌법 작성 → 스펙 작성 → 태스크 작성 → 구현

문제는

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은 안 쓰는 게 낫겠다

답변달기

▲

xguru 1달전 [-]

글 중간에 SDD 상세 소개 링크가 내용이 좋네요. 아래는 AI로 요약해 본 겁니다.

명세 주도 개발(Specification-Driven Development, SDD)

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에 명시 근거를 기록함
개정 절차를 통해 원칙의 적용 방식은 진화 가능하되 핵심 철학은 유지함