스펙 주도 개발(Spec-Driven Development, SDD)은 AI 코딩 에이전트에게 “무엇을 원하는지”를 말하기 전에 입력·출력·제약·엣지 케이스를 구조화된 명세(specification)로 먼저 정의하는 개발 방법론이다. 프롬프트 재시도 루프(Prompt → Retry → Guess)를 명세 기반 검증 루프(Spec → Generate → Validate)로 전환해 일관성과 예측 가능성을 높인다.
배경: 프롬프트 반복 루프의 한계
많은 개발자가 AI 코딩 도구로 경험하는 전형적인 패턴:
- 원하는 것을 설명하는 프롬프트 작성
- 생성된 출력 검토
- 프롬프트 조정
- 받아들일 수 있을 때까지 반복
단순한 태스크에서는 잘 동작하지만, 복수 입력·제약·엣지 케이스가 있는 복잡한 태스크에서는 산출물이 일관되지 않고 반복 주기가 길어진다. 문제는 모델이 아니라 문제를 구조화하는 방식의 부재에 있다.
핵심 아이디어: 명세가 실행을 생성한다
SDD는 전통적 소프트웨어 개발을 뒤집는다. 코드가 아닌 명세(spec)가 중심이 되고, 명세에서 구현이 생성된다:
구조화된 명세 → AI 에이전트 → 검증 가능한 구현명세는 긴 문서가 아니다. 다음 네 요소를 구조적으로 기술하는 것이다:
| 요소 | 설명 |
|---|---|
| 입력(Inputs) | 시스템이 받는 데이터와 파라미터 |
| 출력(Outputs) | 예상 응답 형식과 필드 |
| 제약(Constraints) | 기본값, 한도, 불변식 |
| 엣지 케이스(Edge Cases) | 예외 상황 처리 방법 |
비교: 프롬프트 vs. 명세
예시: 주문 API
프롬프트 방식:
“사용자의 주문 상세 정보를 반환하는 API를 작성해.”
결과: 필드명 불일치, 페이지네이션 누락, 엣지 케이스 미처리, 반복 호출마다 다른 구조
명세 방식:
입력: userId, page, pageSize
출력: userId, orders[](orderId, totalAmount, orderDate),
pagination(page, pageSize, totalRecords)
제약: 기본 pageSize=10, 주문 없으면 빈 리스트 반환,
대용량 데이터셋 효율적 처리결과: 일관된 필드명, 페이지네이션 포함, 엣지 케이스 처리
SDD 워크플로우 5단계
- Ask — 문제를 설명(프롬프트, 토론, 메모)
- Write a Spec — 입력·출력·제약 정의
- Refine — 모호성 제거
- Generate — 명세를 입력으로 에이전트 실행
- Validate — 출력을 명세와 비교
이 워크플로우는 앞단 투자 비용이 있지만, 이후 반복을 줄여 전체 사이클을 단축한다.
spec-kit: GitHub의 SDD 공식 툴킷
spec-kit은 GitHub이 공개한 SDD 실천 도구로, specify CLI를 제공하고 Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot 등 주요 에이전트 플랫폼을 지원한다.
핵심 명령어
| 명령어 | 역할 |
|---|---|
/speckit.constitution | 프로젝트 원칙 및 개발 가이드라인 수립 |
/speckit.specify | 기능 명세 작성 (무엇을, 왜 빌드할지) |
/speckit.plan | 기술 구현 계획 수립 (기술 스택 및 아키텍처) |
/speckit.build | 명세와 계획 기반 구현 |
/speckit.test | 명세 대비 테스트 |
/speckit.review | 코드 리뷰 및 품질 게이트 |
/speckit.ship | 프로덕션 배포 |
설치
# uv로 영구 설치 (권장)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 또는 일회성 실행
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>핵심 철학
spec-kit은 코드 중심에서 명세 중심으로 패러다임을 전환한다:
- 코드는 명세의 구현물: 명세가 진실의 원천
- 스펙은 실행 가능: 명세에서 직접 구현이 생성됨
- 스펙은 진화: 처음부터 완벽할 필요 없음, 이해가 깊어지면 스펙도 개선됨
SDD를 지원하는 에코시스템
| 도구/프로젝트 | SDD 지원 방식 |
|---|---|
| spec-kit | GitHub 공식 SDD 툴킷, specify CLI |
| Kiro IDE | SDD를 네이티브 핵심 워크플로우로 채택한 AI 코딩 에이전트 IDE |
| addyosmani/agent-skills | spec-driven-development 스킬 포함, 에이전트에 SDD 내재화 |
| ACAI | feature.yaml 기반 스펙 주도 소프트웨어 개발 툴킷 |
SDD가 잘 맞는 케이스
- 복수 입력과 정의된 계약이 있는 API 설계
- 스키마 주도 시스템 (데이터베이스, GraphQL, OpenAPI)
- 일관성이 중요한 기존 코드 리팩토링
- 멀티 에이전트 워크플로우 (각 에이전트의 인터페이스 명세화)
SDD가 불필요한 케이스
- 소규모 스크립트, 간단한 UI 수정
- 빠른 실험과 프로토타입
- 이미 잘 이해된 반복 작업
관련 도구
- agent-skills — 에이전트 스킬 시스템 개요 (spec-driven-development 스킬 포함)
- acai — feature.yaml 기반 스펙 주도 소프트웨어 개발 툴킷
참고 자료
- Moving Beyond Prompts: A Practical Introduction to Spec-Driven Development — Microsoft Tech Community (2026-05-05)
- github/spec-kit — GitHub 공식 저장소