스펙 주도 개발 (SDD)¶

에이전트 시대의 개발 방식¶

2025년을 기점으로 소프트웨어 개발의 풍경이 달라졌습니다.
AI 코딩 에이전트가 실제 코드를 만들어주는 시대가 된 것입니다.

그런데 문제가 생겼습니다. 개발 속도는 빨라졌지만, 코드 품질은 오히려 들쭉날쭉해졌습니다.
이 현상에는 이름도 생겼습니다.

Vibe Coding — "대충 이런 거 만들어줘"식의 모호한 지시로 AI에게 코드를 생성시키는 방식

Vibe coding에는 세 가지 구조적 실패가 있습니다.

실패 유형	현상
표준화 부재	팀 내 여러 명이 같은 기능을 다른 방식으로 구현
컨텍스트 소실	"왜 이렇게 만들었는지"가 대화창에만 있다가 사라짐
컨텍스트 붕괴	AI는 무상태(stateless)라 창이 길어지면 앞의 결정을 잊음

이 문제를 해결하기 위해 등장한 것이 SDD입니다.

SDD란?¶

SDD = Spec-Driven Development — 스펙 주도 개발

SDD는 이렇게 정의됩니다.

"스펙을 1차 산출물로 삼고, 코드를 2차 산출물(생성되거나 검증되는 것)로 취급하는 개발 방식"

코드가 먼저가 아니라, 스펙이 먼저입니다.
AI가 코드를 생성하는 것은 스펙을 구현하는 과정일 뿐입니다.

TDD에서 SDD로¶

SDD는 완전히 새로운 개념이 아닙니다.
기존의 TDD(Test-Driven Development)에서 자연스럽게 진화한 것입니다.

TDD 복습¶

TDD 사이클:
실패하는 테스트 작성 → 코드 작성(테스트 통과) → 리팩터링

TDD에서 테스트는 마이크로 스펙입니다.
"이 함수가 이 입력을 받으면 이 결과를 내야 한다"는 것을 코드로 먼저 정의하는 것이죠.

TDD의 한계 — AI 에이전트 시대에서¶

TDD는 개발자가 직접 코드를 작성할 때 효과적인 방식입니다.
하지만 AI 에이전트가 코드를 작성하는 환경에서는 다른 문제가 생깁니다.

AI에게 모호한 지시를 주면:
"사진 공유 기능 추가해줘"
  ↓
AI가 임의로 가정을 채움
  ↓
개발자가 원한 것과 다른 코드가 나옴

"AI 모델은 패턴 완성에는 뛰어나지만 마음 읽기에는 서툴다."

TDD의 테스트 단위 스펙만으로는 AI 에이전트에게 충분한 컨텍스트를 전달할 수 없습니다.
아키텍처, 제약 조건, 비기능 요구사항까지 포함한 더 넓은 범위의 스펙이 필요합니다.

TDD vs SDD 비교¶

	TDD	SDD
1차 산출물	실패하는 테스트	스펙 문서
범위	함수/유닛 단위	시스템 전체
주도하는 주체	개발자	개발자 + AI 에이전트
코드 작성	개발자가 직접	AI가 생성, 개발자가 검토
목적	올바른 구현 보장	AI의 의도 이탈 방지

SDD는 TDD를 대체하는 것이 아닙니다.
SDD의 4단계 워크플로우 안에서 TDD는 검증(Validate) 단계의 도구로 계속 쓰입니다.

스펙의 3단계 엄밀성¶

스펙의 구속력 수준은 세 단계로 나뉩니다.

1단계: Spec-First (스펙 우선)¶

스펙 작성 → AI가 코드 생성 → 코드가 완성되면 스펙은 역할 종료

스펙이 초기 개발을 안내하지만, 이후 코드와 스펙이 따로 놀 수 있음
유지보수 부담이 낮음
적합한 경우: 프로토타입, 일회성 기능, 작은 프로젝트

2단계: Spec-Anchored (스펙 고정)¶

스펙 작성 → 구현 → 스펙과 코드를 함께 유지 관리
(기능이 바뀌면 스펙도 함께 수정)

스펙이 살아있는 문서(Living Documentation)로 유지됨
자동화 테스트가 스펙과 코드의 일치를 강제함
적합한 경우: 대부분의 실제 서비스 (기본값으로 권장)

3단계: Spec-as-Source (스펙이 소스)¶

스펙만 수정 → 코드는 스펙에서 자동 생성 → 코드를 직접 수정하지 않음

가장 엄격한 형태
코드는 직접 편집하지 않음 (스펙만 편집)
적합한 경우: 자동차 임베디드 시스템, Tessl 같은 완전 자동화 도구

우리 과정에서는 2단계 Spec-Anchored를 목표로 합니다.

SDD의 4단계 워크플로우¶

1. Specify (정의)
   무엇을 만들 것인가?
   사용자 스토리, 시나리오, 인수 조건
        ↓
2. Plan (계획)
   어떻게 만들 것인가?
   기술 스택, 아키텍처, API 설계, 데이터 모델
        ↓
3. Implement (구현)
   스펙을 코드로 옮긴다
   AI 에이전트가 스펙을 "슈퍼 프롬프트"로 사용해 구현
        ↓
4. Validate (검증)
   코드가 스펙을 만족하는가?
   자동화 테스트, 인수 조건 체크 (이 단계에서 TDD 활용)

스펙은 AI 에이전트에게 단순한 지시문이 아닙니다.
스펙은 "복잡한 문제를 에이전트의 컨텍스트 창에 맞는 모듈로 분해하는 슈퍼 프롬프트"입니다.

실제 효과¶

금융 서비스 사례 연구:

API 변경 사이클 타임 75% 단축 — 호환성 문제를 운영 환경이 아닌 스펙 리뷰 단계에서 조기 발견

명확한 스펙을 AI에 제공했을 때:

통제 실험에서 코드 오류 최대 50% 감소

스펙 주도 개발의 생태계¶

2025년 이후 주요 AI 코딩 도구들이 SDD를 기본 워크플로우로 채택했습니다.

도구	출시	특징
GitHub Spec Kit	2025년 9월	GitHub Copilot과 연동, 오픈소스
AWS Kiro	2025년 7월	스펙에서 코드 자동 생성
Tessl	2025년	Spec-as-Source 방식, 코드 직접 편집 불가
Claude Code	2025년	CLAUDE.md 기반 스펙 컨텍스트

SDD는 "2025년 핵심 AI 보조 엔지니어링 관행"으로 꼽힙니다.

"프롬프트 엔지니어링이 인간-LLM 상호작용을 최적화한다면,
컨텍스트 엔지니어링은 에이전트-LLM 상호작용을 최적화한다."

우리 과정에서의 SDD¶

이 과정에서 스펙은 Markdown 파일로 작성합니다.

프로젝트/
├── specs/
│   ├── api.md        ← API 스펙 (엔드포인트, 요청/응답, 오류)
│   ├── data.md       ← 데이터 스펙 (테이블, 필드, 제약)
│   └── behavior.md   ← 동작 스펙 (경계 상황, 비즈니스 규칙)
└── ...

이 스펙 파일들이 AI 에이전트(Claude Code 등)의 컨텍스트로 주입되어
일관된 구현이 가능해집니다.

API 스펙 예시¶

[POST /todos]
인증: Bearer Token 필요
요청: { "title": string, 필수, 1~100자 }

성공: 201 Created
     { "id": 1, "title": "운동하기", "is_done": false, "created_at": "..." }

오류:
  400 → title 없음 또는 빈 문자열
  400 → title 100자 초과
  401 → 인증 토큰 없음

동작 스펙 예시¶

[인증 규칙]
- 로그인 성공 시 JWT 발급, 유효기간 7일
- 비밀번호 5회 오류 시 10분 잠금
- 만료 토큰 요청 시 401 반환

[할 일 규칙]
- 자신의 할 일만 수정/삭제 가능 (타인 접근 시 403)
- 삭제된 항목은 복구 불가

실습 미션¶

미션 1: Vibe Coding 문제 분석¶

아래 AI 지시문에서 AI가 임의로 가정해야 하는 부분을 모두 찾으세요.

"쇼핑몰 장바구니 기능 만들어줘"

미션 2: 스펙으로 변환¶

미션 1의 지시문을 API 스펙 형식으로 변환하세요. (엔드포인트 3개 이상)

형식:
[메서드 /경로]
인증:
요청:
성공 응답:
오류 응답:

미션 3: 스펙 엄밀성 판단¶

아래 시나리오에서 어떤 단계(Spec-First / Spec-Anchored / Spec-as-Source)가 적절한지 고르고 이유를 설명하세요.

A. 해커톤 24시간 프로젝트 — 빠르게 프로토타입만 만들면 됨
B. 스타트업의 결제 API — 6개월 후에도 유지보수해야 함
C. 개인 포트폴리오 사이트 — 혼자, 한 번만 만들면 됨

미션 4 (심화): 내 서비스 스펙 파일 작성¶

4장 서비스의 스펙을 Markdown 파일로 작성하세요.

specs/api.md      — 엔드포인트 5개 이상
specs/data.md     — 테이블 2개 이상, 필드와 제약조건 포함
specs/behavior.md — 비즈니스 규칙 5개 이상

핵심 요약¶

개념	설명
Vibe Coding	모호한 지시로 AI에게 코드를 맡기는 방식 — 품질 저하 유발
SDD	스펙을 1차 산출물로, 코드를 2차 산출물로 취급하는 개발 방식
TDD와의 관계	TDD는 SDD의 Validate 단계에서 활용, 서로 대체 아닌 보완
Spec-First	스펙이 초기 안내, 이후 별도 관리 (프로토타입 적합)
Spec-Anchored	스펙과 코드를 함께 유지 (실제 서비스 권장)
Spec-as-Source	코드를 스펙에서 자동 생성, 직접 편집 불가
슈퍼 프롬프트	스펙이 AI 에이전트의 컨텍스트로 작동하는 방식
작성 순서	SRS(무엇을) → SDD 스펙(어떻게) → 구현 → 검증