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

(github.com/github)

28P by xguru 21시간전 | ★ favorite | 댓글 4개

Spec-Driven Development: 전통적 개발에서 보조 수단이던 명세(Spec) 를 실행 가능한 명세로 승격해, 명세로부터 직접 동작하는 구현을 생성하려는 접근
- 코드가 중심이던 관행을 전환해 무엇과 왜를 먼저 정의하고 이후에 어떻게를 구체화하는 의도 중심 개발을 강조
- 핵심 아이디어는 명세를 통해 일관된 산출물을 만들고, 반복 작업을 자동화해 개발자가 제품 문제에 집중하도록 지원함
Spec Kit은 이렇게 명세를 실행 가능 산출물로 전환해 구현을 자동화하는데 도움을 주는 도구 모음
설치후 /specify로 무엇/왜를 기술하고, /plan으로 스택/아키텍처를 선언하며, /tasks로 작업 단위를 생성
목표는 조직이 차별화되지 않은 공통 코드 작성에서 벗어나 제품 시나리오에 집중하도록 돕는 것으로, 명세 주도 방식을 통해 품질과 속도 모두를 끌어올리려는 실험적 프레임워크

핵심 철학: Core philosophy

의도 중심 개발로 무엇을 앞세우고 어떻게는 이후에 구체화하는 명세 우선 사고방식
가드레일과 조직적 원칙을 갖춘 풍부한 명세를 작성하고, 일회성 코드 생성이 아닌 다단계 정제 과정을 거침
고급 AI 모델의 해석 능력에 적극 의존해 명세를 실행 가능한 결과로 변환하는 활용법 지향

개발 단계: Development phases

0-to-1(그린필드) 단계 : 고수준 요구사항을 기반으로 명세 생성 → 계획 수립 → 프로덕션급 앱 생성 흐름 지원
창의적 탐색 단계 : 다양한 스택/아키텍처와 UX 패턴을 평행 구현으로 실험하는 프로세스 강조
점진적 개선(브라운필드) 단계 : 기능 추가, 레거시 현대화, 프로세스 적응을 반복하는 진화형 개발

Prerequisites

Linux/macOS 또는 Windows의 WSL2 필요
AI 에이전트로 Claude Code, GitHub Copilot, Gemini CLI, Cursor 중 선택

▲

xguru 21시간전 [-]

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