포스트

Spec Driven Development (SDD) 완전 해설 가이드

게시 업데이트
By BLUEBUG
32 분읽는 시간
Spec Driven Development (SDD) 완전 해설 가이드

출처: Julian De Angelis의 아티클 “The Spec Is the New Code: A Guide to Spec Driven Development”
작성일: 2026년 3월
요약: AI 코딩 에이전트 시대에 프로덕션 수준의 소프트웨어를 만들기 위한 새로운 개발 방법론

목차

  1. 개요: 왜 AI 코딩 에이전트는 실패하는가
  2. 진짜 병목: 모델이 아닌 인간의 지시 방식
  3. 생태계의 수렴 현상: 모두가 같은 해결책으로
  4. Spec Driven Development란 무엇인가
  5. SDD의 성숙도 3단계
  6. SDD 4단계 프로세스 상세 분석
  7. SDD의 트레이드오프: 단점과 한계
  8. 실제 도입 사례: MercadoLibre의 20,000명 규모 롤아웃
  9. 생태계의 주요 SDD 도구들
  10. SDD vs 기존 방법론 비교
  11. 어디서부터 시작할 것인가
  12. 결론: Vibe Coding vs SDD

1. 개요: 왜 AI 코딩 에이전트는 실패하는가

AI 코딩 에이전트가 실패하는 이유는 흔히 모델 성능이나 컨텍스트 윈도우 크기, 혹은 도구의 문제라고 생각하기 쉽다. 그러나 저자는 이 통념을 정면으로 반박하면서 글을 시작한다. 진짜 문제는 지시 내용이 모호하고, 에이전트를 감싸는 구조(harness)가 너무 취약하다는 데 있다.

이 글은 저자가 이전 아티클 “The Coding Agent Harness”에서 소개한 “Spec Driven Development(명세 주도 개발)”를 보다 깊이 파고드는 후속편이다. SDD는 단순한 도구가 아니라 AI 코딩 시대에 프로덕션 수준의 소프트웨어를 안정적으로 만들기 위한 방법론 전체를 가리킨다.

2. 진짜 병목: 모델이 아닌 인간의 지시 방식

전형적인 실패 시나리오

저자는 AI 코딩 에이전트를 처음 사용하는 사람들이 겪는 전형적인 패턴을 이렇게 묘사한다.

“백오피스에서 아이템을 관리하는 기능을 추가해줘.”

에이전트는 코드베이스를 읽고, 패턴을 하나 선택하고, 기능을 작성한다. 처음에는 잘 동작하는 것처럼 보인다. 그런데 “아이템 추가” 버튼을 다시 누르면 같은 아이템이 두 번 삽입된다.

이 순간 비로소 개발자가 당연히 여겼던 모든 가정들이 수면 위로 드러난다.

  • 이 작업은 멱등성(idempotent) 이 보장되어야 한다.
  • 관리자만 이 작업을 수행할 수 있어야 한다.
  • “백오피스”는 판매자용이 아니라 내부 백오피스를 의미한다.

이 중 어느 것도 프롬프트에 명시되지 않았다. 에이전트는 스스로 추측해야 했다. 어떤 백오피스인지, 어떤 API 계약인지, 어떤 스토리지 레이어인지, 어떤 인가 모델인지, 어떤 오류 처리 전략인지. 각각의 결정은 침묵 속에서 내려진다. 어떤 추측은 맞고, 어떤 추측은 틀린다. 그리고 복잡성이 증가할수록, 개발자가 의도한 것과 에이전트가 실제로 만든 것 사이의 간극도 커진다.

이것이 모호성 문제(ambiguity problem) 다. 에이전트의 잘못이 아니다. 이것은 커뮤니케이션의 실패다.

3. 생태계의 수렴 현상: 모두가 같은 해결책으로

흥미로운 점은 전혀 다른 철학과 아키텍처를 가진 도구들이 독립적으로 동일한 결론에 도달하고 있다는 사실이다.

GitHub Spec Kit (77,000+ 스타)

GitHub가 공개한 오픈소스 SDD 툴킷으로, 에이전트에 구애받지 않고 Claude Code, Cursor 등 다양한 환경에서 동작한다. spec → plan → task → implement의 4단계 사이클을 구조화하며, Constitution(헌법) 이라는 핵심 개념을 도입한다. 이 Constitution은 프로젝트의 모든 변경사항에 항상 적용되어야 하는 불변의 고수준 원칙들을 담는 강력한 규칙 파일이다.

OpenAI의 Symphony

이슈 트래커를 모니터링하다가 이슈별로 자율 에이전트를 실행하는 시스템으로, SPEC.md를 계약서로 요구한다. 에이전트가 작업을 시작하기 전에 반드시 명세서가 존재해야 한다는 철학을 구현한다.

The Ralph Loop

PRD(제품 요구사항 문서)를 에이전트 루프에 넣어 무한 반복시키는 방식이다. 진행 상태는 컨텍스트 윈도우가 아닌 파일과 git에 영속적으로 저장된다. 모델의 단기 기억이 아닌 실제 파일 시스템을 상태 저장소로 활용한다는 점이 핵심이다.

네이티브 코딩 에이전트들의 변화

Claude Code와 Cursor의 Plan 모드도 본질적으로 가벼운 spec-and-plan 단계다. 대부분의 에이전트 루프에는 이미 태스크 분해 기능이 내장되어 있다. 아키텍처와 철학이 달라도, 이 모든 도구는 코드를 작성하기 전에 원하는 것을 정의하고, 구조화된 명세서로부터 에이전트가 구현하도록 한다는 핵심 아이디어를 공유한다.

4. Spec Driven Development란 무엇인가

Spec Driven Development(SDD)는 도구가 아니라 방법론이다. 네 단계로 이루어진 단순하지만 강력한 프로세스다.

1
2
3
4

1. Specify  →  무엇을 만들지 명세화한다
2. Plan     →  기술적으로 어떻게 만들지 계획한다
3. Tasks    →  작고 순서 있는 태스크들로 분해한다
4. Implement→  에이전트와 함께 하나씩 구현한다

각 단계는 모호성을 줄이는 역할을 한다. 에이전트가 코드를 작성하기 시작할 때쯤이면, 에이전트는 필요한 모든 것을 갖추게 된다: 기능이 무엇을 하는지, 어떻게 통합되는지, 엣지 케이스가 무엇인지, 테스트가 무엇을 검증해야 하는지, 어떤 아키텍처를 따라야 하는지.

에이전트는 더 이상 추측할 필요가 없다.

잘 작성된 spec과 plan을 에이전트에게 전달하면, 에이전트의 전체 컨텍스트 윈도우를 한 번에 엔지니어링하는 것과 같다. 아키텍처 결정, 단계별 가이드, 인수 기준이 모두 하나의 아티팩트 세트에 담긴다.

가장 좋은 점은 spec 자체를 에이전트가 작성하도록 시킬 수 있다는 것이다. spec을 처음부터 작성하는 것보다 수정하는 것이 훨씬 쉽다. 또한 에이전트에게 같은 spec에서 모호한 부분을 찾아달라고 요청할 수도 있다.

5. SDD의 성숙도 3단계

Birgitta Böckeler(ThoughtWorks, Martin Fowler 블로그 기고자)는 SDD 구현의 성숙도를 세 가지 레벨로 분류한다.

Level 1: Spec-First (명세 우선)

코딩 전에 spec을 작성하지만, 개발 완료 후에는 폐기한다. 대부분의 팀이 이 단계에서 시작한다. 이것만으로도 해당 개발 사이클의 모호성 문제를 상당히 해결할 수 있다. 가장 접근하기 쉬운 진입점이다.

Level 2: Spec-Anchored (명세 고정)

spec이 코드와 함께 저장소에 살아숨쉬며 함께 진화한다. spec이 팀을 위한 살아있는 문서(living documentation) 가 된다. 새로운 팀원 온보딩, 레거시 코드 이해, 아키텍처 의사결정 추적 등에 큰 가치를 발휘한다.

Level 3: Spec-as-Source (명세가 곧 소스)

spec이 주(primary) 아티팩트가 된다. spec을 수정하면 코드가 재생성되어 이에 맞춰진다. 아직 완전히 실현된 수준은 아니지만, 기술 발전의 궤적이 향하는 방향이다. GitHub Spec Kit의 철학 문서는 이 단계를 이렇게 표현한다: “소프트웨어를 유지보수한다는 것은 명세서를 발전시키는 것을 의미하게 된다. 개발팀의 의도는 자연어로 표현되고, 코드는 마지막 마일(last-mile) 접근 방식이 된다.”

SDD는 이분법적이지 않다. 진보적인 방법론이다. 1단계에서 시작해서 가치를 얻고, 그 다음 더 깊이 들어가야 하는지 결정한다.

6. SDD 4단계 프로세스 상세 분석

Step 1: Spec — 무엇을 만들 것인가

Spec은 기능적 레이어(functional layer) 다. 기능이 무엇을 하는지를 기술하며, 어떻게 구현될지는 다루지 않는다. 의도적으로 기술 중립적(technology-agnostic)이다.

좋은 spec은 비기술적 언어로 기능의 목적, 사용 사례, 요구사항, 엣지 케이스, 성공 기준을 정의한다.

핵심 통찰: 기능적 요구사항과 기술적 요구사항을 분리하면 LLM의 불확실성이 줄어든다.

“사용자가 Google과 GitHub로 인증할 수 있다”와 “JWT 전략을 사용한 NextAuth.js를 사용하고 세션을 Redis에 저장한다”를 섞으면, 에이전트가 두 가지 다른 관심사를 동시에 다뤄야 한다. 기능적 요구사항은 명확할 수 있지만, 기술적 결정이 복잡성을 가중시켜 분기 경로가 복합적으로 증가한다.

spec을 순수하게 기능적으로 유지함으로써, 에이전트에게 조기의 구현 결정으로 오염되지 않은 명확한 목표를 제공한다.

인수 기준(Acceptance Criteria)의 중요성

Given/When/Then 형식으로 검증을 모호하지 않게 만든다. 예시:

1
2
3
4
5
6
7

Given 신규 사용자가 있을 때,
When 그들이 "Google로 로그인" 버튼을 클릭하고 앱을 승인하면,
Then 유효한 세션이 있는 상태로 대시보드로 리디렉션된다.

Given Google 계정을 가진 사용자가 있을 때,
When 그들이 동일한 이메일로 GitHub로 로그인을 시도하면,
Then 계정들이 연결되고 동일한 프로필에 접근한다.

이것들은 단순한 문서가 아니다. 테스트 계획이 된다. 에이전트는 이 기준들을 토대로 자신의 구현을 스스로 검증할 수 있다.

Step 2: Plan — 어떻게 만들 것인가

Plan은 기술적 레이어(technical layer) 다. 에이전트를 위한 구현 가이드이며, spec에서 설명한 모든 것을 어떻게 달성할지를 담는다.

여기가 개발자의 전문성이 가장 중요한 순간이다. 코드를 직접 작성하는 것이 아니라, 아키텍처 의사결정을 내리는 것이다.

Plan에 포함되는 내용들:

항목예시
아키텍처 및 기술 결정“App Router가 있는 NextJS를 사용한다. @auth-rules의 기존 인증 패턴을 따른다.”
데이터 모델 및 계약“기존 User 엔티티를 사용한다. provider 필드를 추가한다.”
테스트 전략“단위 테스트는 인증 흐름의 90%를 커버해야 한다.”
성능 제약“로그인 엔드포인트의 응답 시간은 100ms 미만이어야 한다.”

Plan은 또한 커스텀 규칙 참조, 코드베이스의 기존 패턴 지정, 에이전트가 사용해야 할 MCP 지정, 기술적 제약 설정의 공간이다. 추상적인 spec을 구체적이고 경계가 있는 구현 가이드로 변환한다.

Plan이 특히 잘 작동하는 이유: Spec Kit의 /plan 명령어와 같은 도구들은 기술 계획을 생성하기 전에 실제 코드베이스를 읽는다. 현재 구조를 분석하고, 패턴과 관례를 식별하며, 이미 존재하는 것과 일관된 아키텍처를 제안한다.

Step 3: Tasks — 작게 쪼개기

Plan은 작고 순서 있는 태스크들로 분해된다. 각 태스크는 단일 에이전트 세션에서 완료 가능해야 하고, 테스트와 함께 검증 가능한 변경 사항을 만들어야 한다.

핵심 원칙: 모든 태스크는 자기 완결적이고 모호함이 없어야 한다. 에이전트가 가정을 하거나 누락된 컨텍스트를 찾아야 한다면, 그 태스크는 아직 준비되지 않은 것이다.

또한 이 단계는 개발자가 접근 방식을 검토하는 시간이기도 하다. 스스로에게 질문해야 한다: “이 태스크 목록이 솔루션을 과도하게 엔지니어링하고 있지는 않은가? 7개의 태스크가 정말 필요한가, 아니면 3개로 충분한가? 에이전트가 불필요한 추상화를 만들고 있지는 않은가?” 코드 작성 전 마지막 체크포인트이므로, 계획이 실용적인지 확인하는 시간을 갖는 것이 가치 있다.

태스크 분해가 열어주는 두 가지 강력한 능력:

  1. 병렬 실행(Parallelism): 독립적인 태스크들은 여러 에이전트가 동시에 실행할 수 있다.
  2. 에이전트 독립성(Agent Agnosticism): 태스크들은 자기 완결적이며 모든 컨텍스트가 내장되어 있기 때문에, 에이전트를 완전히 교체할 수 있다. Claude Code로 시작하고, Cursor로 태스크를 이어받고, 다른 것은 Codex로 마무리할 수 있다. Spec Kit과 같은 프레임워크를 사용하면, spec과 plan이 에이전트가 아닌 태스크와 함께 이동한다.

Step 4: Implement — 하나씩 실행

에이전트가 완전히 준비된 상태에서 코드를 작성한다. 각 태스크는 명확한 컨텍스트, 아키텍처 가이드, 검증 가능한 인수 기준을 갖추고 있다. 에이전트는 추측 없이 구현에만 집중할 수 있다.

7. SDD의 트레이드오프: 단점과 한계

SDD는 공짜가 아니다. 솔직하게 단점도 살펴봐야 한다.

토큰 비용

spec-plan-task 사이클은 많은 토큰을 소비한다. 전체 SDD 세션은 에이전트에게 직접 프롬프트하는 것보다 2~3배 이상의 토큰을 사용할 수 있다. 이것이 트레이드오프다: 앞에서 더 많이 투자하는 대신 극적으로 더 나은 결과를 얻는다.

모든 상황에 적합하지 않다

SDD는 모든 것에 맞지 않는다. 작은 변경사항, 빠른 버그 수정, 설정 업데이트 같은 것들은 전체 spec이 필요 없다. 이런 경우에는 Plan 모드를 사용하거나 직접 프롬프트하면 된다.

SDD가 빛을 발하는 때는 모호성이 에이전트를 잘못된 방향으로 이끌 만큼 기능이 복잡할 때다: 여러 파일 변경, 여러 도메인에 영향을 미치는 기능, 레거시 저장소, “명백한” 비즈니스 로직이 전혀 명백하지 않은 모든 상황.

학습 곡선

개발자들은 “내가 원하는 코드를 설명하는 것”에서 “내가 필요한 동작을 설명하는 것”으로 전환해야 한다. 이것은 마인드셋의 변화다. 구현이 아닌 동작과 요구사항에 집중하는 새로운 사고방식이 필요하다.

8. 실제 도입 사례: MercadoLibre의 20,000명 규모 롤아웃

저자가 재직 중인 라틴아메리카 최대 이커머스 기업 MercadoLibre는 약 20,000명의 개발자에게 SDD를 도입하고 있다. 이 규모의 롤아웃에서 두 가지 큰 도전이 있었다.

첫 번째 도전: 습관의 변화

개발자들은 곧바로 코드로 뛰어드는 것에 익숙해져 있다. 코딩 전에 spec을 먼저 작성하는 것은 결과를 보기 전까지는 오버헤드처럼 느껴진다. MercadoLibre는 이 가치를 설명하는 것이 아니라 실습을 통해 가르치는 방식을 선택했다. 5,000명 이상의 개발자가 참석한 실습 워크숍을 전면적으로 진행했다. 개발자들은 단일 세션에서 spec 작성, plan 생성, 태스크 분해, 에이전트와의 구현을 모두 경험한다. 이 경험이 채택을 이끈다.

두 번째 도전: 방법론 주변의 컨텍스트

SDD만으로는 충분하지 않다. 에이전트는 또한 내부 도구, SDK, 플랫폼 관례에 대한 컨텍스트가 필요하다. 이것이 저자가 이전 포스트에서 설명한 에이전트 하네스(agent harness) 다: 표준을 인코딩하는 커스텀 규칙, 도메인 지식을 번들링하는 스킬, 내부 시스템에 연결하는 MCP들.

방법론은 무엇을 만들지를 정의한다. 하네스는 에이전트에게 올바르게 만들 수 있는 내부 컨텍스트를 제공한다.

9. 생태계의 주요 SDD 도구들

GitHub Spec Kit

GitHub의 공식 SDD 구현체. CLI 도구로 배포되며, Claude Code, Cursor 등 다양한 코딩 어시스턴트와 통합된다. Constitution → Specify → Plan → Tasks의 워크플로우를 따른다.

1
2
3
4
5

# 새 프로젝트 생성
specify init <PROJECT_NAME>

# 기존 프로젝트에서 초기화
specify init .

Kiro (AWS)

AWS가 최근 공개한 IDE로, SDD를 네이티브로 지원한다. “Spec-first” 철학을 중심으로 설계되었다. 단, 작은 버그 수정과 같은 단순한 작업에는 과도하게 상세한 명세를 생성하는 경향이 있다는 비판도 있다.

Tessl

“명세가 주 아티팩트인 개발 접근 방식. 명세는 구조화된 테스트 가능한 언어로 의도를 설명하며, 에이전트가 코드를 생성한다”는 철학을 가진다.

OpenAI Symphony

이슈 트래커 모니터링 → SPEC.md 계약 생성 → 이슈별 자율 에이전트 실행의 파이프라인을 구현한다.

10. SDD vs 기존 방법론 비교

SDD는 기존의 TDD, BDD와 어떻게 다른가?

방법론초점SDD와의 관계
TDD (테스트 주도 개발)구현 수준에서의 정확성; 테스트가 인터페이스 설계를 주도SDD는 아키텍처 제약을 보장; TDD는 개별 단위의 올바른 동작을 보장. 상호 보완적
BDD (행동 주도 개발)사용자 직면 시나리오; Given/When/Then 형식SDD는 BDD 시나리오를 포함할 수 있지만, 핵심 차이는 실행 가능성. BDD는 종종 참조용 문서로 존재하지만, SDD는 그 시나리오들을 실행 가능한 검증 게이트로 변환한다
Vibe Coding자연어 프롬프트만으로 빠른 생성프로토타입과 MVP에 적합. SDD는 프로덕션 시스템에 적합
Waterfall사전에 모든 것을 계획SDD는 경량이며 반복적. 과도한 관료주의를 추구하지 않음

11. 어디서부터 시작할 것인가

저자가 제안하는 진입점은 명확하다.

1단계: Plan 모드 시도하기

Claude Code나 Cursor의 Plan 모드가 SDD에 대한 가장 접근하기 쉬운 진입점이다. 전체 절차 없이도 대부분의 이점(모호성 감소, 기술적 개요, 더 명확한 의도)을 얻을 수 있다.

2단계: 전용 SDD 프레임워크 도입하기

더 나아갈 준비가 되면, GitHub Spec Kit과 같은 전용 SDD 프레임워크를 채택한다. 구조화된 spec, plan, task 흐름을 제공하고, 구현이 커질수록 임시방편 프롬프팅보다 훨씬 잘 확장된다.

시작 전 알아야 할 것: SDD의 가치는 실습을 통해 복리로 쌓인다. 처음 작성하는 spec은 느리고 불완전하게 느껴질 것이다. 하지만 반복할수록, 무엇을 명세화해야 하는지, 언제 spec을 과도하게 엔지니어링하고 있는지, 에이전트가 올바르게 동작하기 위해 실제로 무엇이 필요한지에 대한 직관이 쌓인다. 그 기술은 매번의 반복을 통해 만들어진다.

12. 결론: Vibe Coding vs SDD

이 글의 핵심 대비는 간결하게 요약된다.

Vibe coding은 데모와 MVP를 만든다. Spec Driven Development는 프로덕션 시스템을 만든다.

AI 에이전트를 실제 코드베이스, 실제 제약 조건, 실제 결과가 있는 환경에서 진지하게 확장하려는 모든 조직에게 이것이 기준이 되고 있다.

소프트웨어 개발의 패러다임이 바뀌고 있다. 수십 년간 코드가 왕이었고, 명세서는 실제 작업이 시작되면 버려지는 발판에 불과했다. SDD는 이 권력 구조를 뒤집는다. 명세서가 코드를 섬기는 것이 아니라, 코드가 명세서를 섬긴다.

개발자의 역할 역시 변한다. 코드를 작성하는 사람에서 의도를 구조화하는 사람, 아키텍처 결정을 내리는 사람, 에이전트가 올바른 방향으로 나아갈 수 있도록 맥락을 엔지니어링하는 사람으로.

명세서는 새로운 코드다.

이 문서는 Julian De Angelis의 “The Spec Is the New Code: A Guide to Spec Driven Development”와 관련 생태계 자료(GitHub Spec Kit, Birgitta Böckeler의 ThoughtWorks/Martin Fowler 블로그 기고문, Wikipedia, Augment Code 가이드 등)를 종합하여 작성되었습니다.

AI, Vibe Coding
AI coding-agents SDD spec-driven-development agent-agnosticism Parallelism Harness spec-first MartinFowler Claude.write
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.