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