사양 기반 개발 (Spec Driven Development)
한 줄 정의
일회성 프롬프팅에 의존하는 개발 방식에서 벗어나, 기술 스택을 배제하고 요구사항만 담은 ‘살아있는 사양서(spec)‘를 구축하고 AI 에이전트를 코드 렌더러로 삼아 구현을 완성해 나가는 구조화된 에이전틱 개발 패러다임이다. (출처: 바이브 코딩의 종말-ko)
핵심 요지
- 코드가 사양을 지배: 사양(Source of Truth)이 단순히 개발 전 초안이 아닌 최상위 설계도로 작동한다. 기획 의도와 핵심 내용(What & Why)을 기재한 뒤 에이전트가 그에 맞춰 코드를 유도해 내는 구조다.
- 에이전트 도구 종속성 해소: 명세서 파일이 IDE나 AI 코딩 에디터(Cursor, Claude Code 등) 바깥에 온전히 존재하며 Git으로 버전 관리되므로, 개발 도구를 전환하더라도 변치 않는 규약(Contract) 역할을 한다.
- 오작동 표면 최소화: ‘느낌 코딩(Vibe Coding)‘의 고질병인 잘못 지은 변수명, edge case 누락, 잘못 전제된 조건들을 엄격한 자연어 사양서와 아키텍처 헌법으로 통제한다.
- 유기적인 활성 문서: 한 번 쓰고 방치하는 문서가 아니라, 제품 사정 변경에 맞춰 지속적으로 업데이트하고 Git으로 버전 변동을 관리하는 살아있는 문서로 기능해야 한다.
상세
1. 사양 기반 개발의 6단계 실행 템플릿 (Implementation Cycle)
SDD 워크플로우는 전형적인 선형 인과 관계에 따라 움직이며, 각 단계는 이전 단계의 산출물을 입력으로 받아 실행된다.
- 헌장 (Constitution): 프로젝트 전반에 걸친 아키텍처 규칙 및 코드 스타일, 테스트 가이드라인 등 양보할 수 없는 지배 원칙(
.specify/memory/constitution.md)을 확립한다. - 사양 (Spec): 구체적인 기술 스택과 구현 세부사항은 철저히 배제하고, 구현하고자 하는 비즈니스 목표와 기획 요구사항(What & Why)만을 작성한 사양서(
.specify/specs/*/spec.md)를 작성한다. 이와 동시에 작업을 격리할 Git 기능 브랜치가 생성된다. - 명확화 및 체크리스트 (Clarify & Checklist): 에이전트와 수동/자동 질의응답을 거쳐 사양서의 모호함을 걷어내고, 사양의 완전성을 검증할 맞춤형 품질 체크리스트를 도출한다. 이는 자연어로 작성된 명세에 대한 ‘자연어 유닛 테스트’로 작동한다.
- 계획 (Plan): 채택할 구체적인 기술 스택을 바탕으로 구현 설계서(
plan.md), 데이터베이스 데이터 모델(data-model.md), 최신 정보 및 패키지 버전을 조사한 리서치 로그(research.md), 로컬 빌드 가이드(quickstart.md)의 4대 아키텍처 문서를 생성한다. - 작업 및 분석 (Tasks & Analyze): 기술 구현 계획을 의존성에 맞게 정렬한 세부 작업 목록(
tasks.md)을 도출하고, 최초 사양과 구현 설계, 작업 간에 누락이나 오차가 없는지 정적 분석을 거쳐 무결성을 입증한다. 병렬 처리가 가능한 작업은[P]마커가 붙고, 각 작업 끝에는 기능 동작을 검증할 체크포인트가 마련된다. - 구현 (Implement): 설정된 모든 명세, 설계서, 작업 목록 및 헌장을 바탕으로 에이전트가 로컬 컴파일러와 패키지 도구들을 구동해 실제 기능 코드를 완성하고, 테스트 및 빌드 오류를 실시간으로 처리한다.
2. 컴파일러 방식의 닮은꼴 구조와 렌더러화
SDD는 사람이 고수준 언어로 구현하면 컴파일러가 이를 기계어로 변환하는 흐름과 닮아 있다. 자연어로 작성된 명세와 헌법이 최상위 언어(Source of truth)라면, 에이전트가 출력해 내는 소스 코드는 하위 산출물에 불과하다. 이로 인해 개발자는 사용하는 도구(Cursor, Claude Code, Gemini CLI 등)에 구속되지 않고, 도구를 언제든지 교환할 수 있는 독립성을 얻는다. 에이전트는 단지 명세라는 표준 설계도를 해석해 기계적으로 결과물을 내놓는 ‘코드 렌더러’로만 작동하기 때문이다.
3. 경직성 경계와 고이코 아지치(Gojko Adzic)의 지적
애자일 방법론 전문가 고이코 아지치는 한 번 결정된 기획 사양을 경직되게 고수할 경우, 과거 수십 년간 극복하려 했던 ‘문서화 우선의 폭포수(Waterfall) 모델’의 폐해를 재부활시킬 위험이 있다고 경고한다. 따라서 사양서는 유기적으로 살아있는 생명체처럼 다루어야 한다. 개발 과정의 피드백이나 비즈니스 변동에 따라 사양서를 유연하게 편집하고, 변경 이력을 Git으로 추적하며, 헌법 조항들도 점진적으로 업데이트해 나가는 유연한 애자일식 운영이 병행되어야 한다.
4. 시나리오별 개발 환경 대응 패턴
- 그린필드 (Greenfield - 신규): 백지상태에서 대원칙(헌법)과 기능 명세를 먼저 수립하고, 에이전트를 통해 초기 뼈대 및 구조적 소스 코드를 충돌 없이 고속 구현한다.
- 브라운필드 (Brownfield - 점진 개선): 기존 아키텍처와 헌법 규칙을 보존한 상태에서 신규 기능에 대해서만
specs/하위 폴더에 사양을 작성하고, Git 브랜치를 분리해 기존 코드를 깨뜨리지 않는 안전한 병렬 추가를 진행한다. - 레거시 현대화 (Modernization - 리팩토링): 기술 부채가 누적되고 분석이 어려운 레거시 코드에서 비즈니스 로직(What & Why)만 사양서로 도출한다. 이후 최신 아키텍처 설계를 적용하여 에이전트가 이전의 낡은 코드를 걷어내고 바닥부터 깨끗한 스택으로 재구축하도록 함으로써 부채의 연쇄 상속을 막는다.
5. 헌장(Constitution)과 FAA-style 10,000피트 규칙의 아키텍처 DNA
SDD 파이프라인의 중심을 관통하는 헌장(.specify/memory/constitution.md)은 미 민간항공국(FAA)이 수립한 **10,000피트 규칙(Sterile Cockpit Rule)**에서 파생된 **0-1 모드(이진법적 규칙)**와 설계 철학을 공유한다. 10,000피트 이하의 중요한 비행 단계에서 안전에 필수적이지 않은 모든 활동과 사담을 금지하듯, 에이전트가 코드를 짤 때 아키텍처 규칙이나 공통 디자인 시스템 표준을 위반하는 모든 타협적 시도를 사전에 전면 배제한다. 이로써 에이전트는 기분이나 문맥에 흔들리지 않고 불변의 아키텍처 DNA 범위 안에서만 작동한다. (출처: 10,000피트 규칙 (10,000-Foot Rule))
6. Pull Request 제출에서의 에이전트 정직성(Fidelity) 검증 원칙
구현을 마친 후 작업 내용을 리포지토리에 반영하기 위해 Pull Request(PR)를 작성할 때, 에이전트와 기여자 간의 엄격한 상호 검증과 정직성이 요구된다.
- 거짓 진술 거부: 실제 로컬 테스트를 실행해 보고 검증되지 않은 정보나 허위 사실을 PR 설명서에 기재하라는 사용자의 부적절한 지시를 에이전트가 스스로 거절(Opt-out)하는 안전제어(Fidelity boundary)가 작동해야 한다.
- 투명한 데이터 기록: 통과한 테스트 케이스뿐 아니라 기존 메인 브랜치에서 재현되던 내재적 실패 결함(예: 47개 성공, 4개 실패 등)까지 있는 그대로 기술하여, 기만 없이 신뢰할 수 있는 데이터를 바탕으로 PR을 전송하는 정직한 검증 프로토콜을 성립시킨다. (출처: 케이브맨)
예시
- 드래그 앤 드롭이 포함된 사진 앨범 앱을 구축할 때, 기술 스택을 적지 않고 “앨범 내 개별 사진 삭제는 불가하지만 앨범 자체는 삭제 및 수정 가능” 등의 비즈니스 요구사항만 명문화하여 사양서(
spec.md)로 에이전트에 공급하는 과정.
충돌
- 사소한 버그 패치에서의 비효율: 설계 및 문서화 파이프라인이 촘촘한 특성상 코드 한두 줄 수정 등 사소한 패치 작업에서는 배보다 배꼽이 더 큰 오버헤드(overkill)가 될 수 있다. 이 경우 SDD 파이프라인을 우회하여 디버깅하는 것이 합리적이다. (출처: 바이브 코딩의 종말-ko)