SDD 명세 기반 개발이 AI 시대에 중요한 이유 2026 — 체크리스트 5가지

Posted on by

바이브 코딩으로 주말에 뚝딱 만들었습니다. 근데 월요일에 팀원이 코드를 봤을 때 “이게 뭐예요?”가 나왔습니다.

AI가 코드를 만들어줬는데, 왜 이렇게 설계했는지 아무도 모릅니다. 함수 이름도 제각각이고, 어디서 어디로 데이터가 흐르는지 추적이 안 됩니다. 다음 날 AI한테 “이어서 개발해줘”라고 했더니 어제랑 다른 방향으로 코드를 뽑아냅니다.

명세가 없었으니까요.

SDD 한 줄 정리: 코드를 짜기 전에 명세(spec)를 먼저 쓰고, 그 명세가 AI와 사람 모두의 개발 기준이 되는 방식입니다. AI 에이전트가 길을 잃지 않도록 지도를 먼저 그려두는 것입니다.

2026년 기준, AWS Kiro가 3개월 만에 개발자 25만 명을 모으고, GitHub Spec Kit이 출시 첫 주에 별 1만 6천 개를 받은 건 우연이 아닙니다. 개발자들이 명세 기반 개발의 필요성을 이미 체감하고 있다는 신호입니다.

왜 지금 SDD인가 — 바이브 코딩의 숨겨진 청구서

바이브 코딩이 나쁜 게 아닙니다. 빠르게 프로토타입 만들 때는 진짜 좋습니다. 문제는 그걸 그대로 프로덕션에 올리거나, 명세 없이 AI 에이전트한테 계속 개발을 이어가게 할 때 나옵니다.

CodeRabbit이 2025년 12월에 오픈소스 GitHub PR 470개를 분석한 결과가 있습니다. AI가 함께 작성한 코드는 사람이 단독으로 쓴 코드보다 “심각한” 이슈가 약 1.7배 많았고, 로직 오류는 75% 더 자주 발생했습니다. 명세 없이 “대충 이런 기능이야”라고만 던졌을 때 나오는 결과입니다.

보안 쪽은 더 심합니다. 2026년 초 기준으로 AI가 생성한 코드의 약 24.7%에 보안 취약점이 있다는 연구가 있습니다. Veracode의 GenAI Code Security Report에 따르면 AI 생성 코드 샘플의 약 45%가 보안 테스트를 통과하지 못하고 OWASP Top 10에 포함된 심각한 취약점을 포함하고 있었습니다.

2025년 7월엔 충격적인 사례도 있었습니다. 코딩 AI가 “변경하지 말라”는 명시적 지시를 무시하고 데이터베이스에 접근해서 완전히 날려버린 사건입니다. 명세가 없으면 AI는 그냥 자기 판단으로 움직입니다.

SDD는 이 문제를 구조적으로 막습니다. “무엇을 만들어야 하는지”를 먼저 문서로 고정해두면, AI가 매 세션마다 방향을 잃지 않습니다.

명세 없는 개발 vs. SDD — 현실 비교

실제로 AI 에이전트를 3일 이상 쓰면 이 차이가 체감됩니다.

상황 명세 없는 바이브 코딩 SDD
세션 재시작 AI가 이전 맥락을 모름 → 재설명 필요 명세 파일을 참조해 자동으로 맥락 복원
기능 추가 기존 코드와 충돌 가능 명세 범위 안에서만 확장
팀원 합류 코드 읽어야만 이해 가능 명세로 빠른 온보딩 가능
버그 추적 “왜 이렇게 됐지?” 파악 어려움 명세와 코드 비교로 의도 파악 가능
AI 판단 오류 재현/예방 어려움 DO NOT 리스트로 사전 차단

SDD가 실제로 어떻게 동작하나

전통적인 방식은 이렇습니다: 요구사항 → 개발 → 스펙 작성(가끔). 스펙은 나중에 쓰거나 아예 안 씁니다.

SDD는 이 순서를 뒤집습니다: 명세 → 리뷰 → 코드 생성.

AWS Kiro를 예로 들면, 기능 개발 시작 전에 세 가지 문서를 먼저 만들게 합니다.

  • requirements.md: 무엇을 만드는가, 왜 만드는가, 성공 기준은 무엇인가
  • design.md: 어떻게 만드는가, 기술 아키텍처와 통합 방식
  • tasks.md: 구체적으로 어떤 순서로 구현할 것인가

이 세 파일이 완성되고 사람이 리뷰한 뒤에야 AI가 실제 코드를 생성합니다. 코드는 명세의 출력물이지, 명세가 코드의 부산물이 아닙니다.

Claude Code에서는 CLAUDE.md가 비슷한 역할을 합니다. 프로젝트 전체에 적용될 규칙과 컨텍스트를 파일로 고정해두면, 에이전트가 세션이 바뀌어도 같은 방향으로 움직입니다. GitHub Spec Kit은 이 흐름을 Claude Code, Cursor, Copilot, Gemini CLI 등 여러 에이전트에 동일하게 적용할 수 있게 만든 오픈소스 CLI입니다.

SDD를 쓴 프로젝트는 스프린트 중간 방향 전환이 40% 줄고, 통합 재작업이 60% 감소한다는 보고가 있습니다.

2026년 주요 SDD 도구 비교

도구 운영사 특징 적합한 상황
AWS Kiro Amazon IDE 내장, requirements+design+tasks 자동 생성 엔터프라이즈, 대형 팀
GitHub Spec Kit GitHub 오픈소스 CLI, 다중 에이전트 지원 신규 프로젝트, 다양한 AI 사용 팀
cc-sdd 커뮤니티 Kiro 스타일 워크플로우를 Claude Code/Cursor에 적용 Claude Code 사용자
OpenSpec 오픈소스 기존 코드베이스 역분석에 강점 레거시 프로젝트
CLAUDE.md Anthropic 프로젝트 수준 명세, 에이전트 행동 제어 Claude Code 단독 사용

SDD 실전 체크리스트 5가지

이 체크리스트는 AI 에이전트를 본격적으로 쓰기 시작하는 개발자 기준입니다. “코드는 AI가 쓰고, 나는 방향만 잡는다”는 방식을 택했다면 이 5가지가 기준선입니다.

체크 1. “왜 만드는가”가 명세에 적혀 있는가

가장 먼저 확인할 것입니다. 명세에 기능 목록만 있고 “이걸 왜 만드는가”가 빠져 있으면 반쪽짜리입니다.

좋은 명세에는 이게 포함됩니다:

  • 누가 쓰는가 (사용자 페르소나)
  • 왜 필요한가 (해결하려는 문제)
  • 성공이 뭔지 어떻게 아는가 (수용 기준, acceptance criteria)

AI 에이전트는 “왜”를 알아야 엣지 케이스에서 올바른 판단을 합니다. “왜”가 없으면 AI가 자기 판단으로 채웁니다. 그 판단이 항상 여러분이 원하는 방향은 아닙니다.

나쁜 명세 예시:

기능: 사용자 알림 시스템
- 알림을 보낼 수 있어야 한다
- 사용자가 알림을 받을 수 있어야 한다

좋은 명세 예시:

기능: 사용자 알림 시스템
목적: 장바구니에 담고 24시간 이내 결제 미완료 사용자의 전환율 개선
대상 사용자: 회원 가입 완료, 장바구니에 1개 이상 상품 보유
수용 기준:
  - 24시간 후 미결제 시 이메일 + 앱 푸시 동시 발송
  - 알림 클릭 시 장바구니 화면으로 직접 이동
  - 사용자 당 동일 장바구니 기준 알림 최대 1회 발송
  - 알림 수신 거부 설정 반영 필수

실전 확인 방법: 명세를 처음 보는 팀원한테 보여줬을 때 추가 질문 없이 바로 개발 시작이 가능하면 합격입니다. 질문이 나오면 그게 명세에 들어가야 할 내용입니다.

체크 2. “하지 말아야 할 것”이 명시되어 있는가

DO NOT 리스트가 있는지 확인하세요.

AI 에이전트는 명시적으로 금지하지 않으면 모든 것을 시도합니다. 외부 API를 무단으로 호출하거나, 데이터베이스 스키마를 임의로 변경하거나, 로깅에 민감한 정보를 포함시킬 수 있습니다.

명세에 들어가야 할 DO NOT 예시:

## 제약 조건 (DO NOT)
- 사용자 비밀번호, 카드번호를 어떤 로그에도 출력하지 않는다
- 기존 테이블 스키마를 마이그레이션 없이 변경하지 않는다
- 외부 이메일 API는 SendGrid만 사용한다 (다른 API 추가 금지)
- 현재 MVP 범위 밖의 기능을 자체 판단으로 추가하지 않는다
- 알림 발송 전 opt-in 여부 확인 없이 진행하지 않는다

2025년 7월 데이터베이스가 날아간 사례가 바로 DO NOT이 없던 케이스입니다. 에이전트는 “더 효율적으로 최적화하겠다”는 자체 판단으로 DB를 건드렸고, 돌이킬 수 없게 됐습니다.

명세에 DO NOT이 없으면 AI는 좋은 의도로 나쁜 결과를 낼 수 있습니다.

CLAUDE.md에서 이 역할을 하는 섹션이 ## 절대 규칙 또는 ## 금지 사항입니다. 에이전트에게 “이것만은 절대 하지 마라”를 명시해두는 것이 SDD의 DO NOT 리스트와 같은 원리입니다.

체크 3. 명세가 테스트로 검증 가능한가

“사용자가 로그인할 수 있어야 한다”는 명세가 아닙니다. 요구사항입니다.

명세는 이렇게 써야 합니다:

검증 불가능한 명세 (요구사항 수준):
– “빠르게 응답해야 한다”
– “안전하게 저장해야 한다”
– “사용자 친화적이어야 한다”

검증 가능한 명세:
– “이메일과 비밀번호로 로그인 시 p95 기준 2초 이내에 응답한다”
– “비밀번호 5회 오류 시 15분 계정 잠금이 발생한다”
– “로그인 성공 후 JWT 토큰이 localStorage가 아닌 httpOnly 쿠키에 저장된다”
– “동시 접속 1000명 기준 에러율 1% 미만을 유지한다”

테스트로 검증할 수 없는 명세는 AI 에이전트가 구현 후에도 제대로 됐는지 알 방법이 없습니다.

실전 확인 방법: 명세의 각 항목마다 “이걸 어떻게 테스트하지?”라고 자문해보세요. 테스트 방법이 바로 떠오르지 않으면 명세를 더 구체화해야 합니다.

Thoughtworks는 이 원칙을 이렇게 요약했습니다: “테스트할 수 없는 명세는 구현할 준비가 안 된 명세다.”

이 방식을 일관되게 쓰면 TDD(테스트 주도 개발)와 자연스럽게 연결됩니다. 명세의 수용 기준이 곧 테스트 케이스가 됩니다. AI가 코드를 짜고 나서 자신이 작성한 코드가 명세를 충족하는지 스스로 검증까지 할 수 있게 됩니다.

체크 4. 명세가 코드와 함께 관리되고 있는가

명세를 노션이나 컨플루언스에만 올려두면 2주 후에 실제 코드와 달라집니다. 항상.

SDD의 핵심 원칙 중 하나는 명세가 코드 저장소 안에 있어야 한다는 것입니다. docs/specs/ 폴더나 각 기능 디렉토리 안에 spec.md로 관리하면 코드 변경과 명세 변경을 같은 PR에서 리뷰할 수 있습니다.

Claude Code에서 CLAUDE.md를 프로젝트 루트에 두고 Git으로 관리하는 방식이 이와 같습니다. 에이전트가 참조하는 명세가 코드와 함께 버전 관리됩니다.

권장 폴더 구조:

project/
├── CLAUDE.md                  ← 전체 원칙 (에이전트 행동 기준)
├── docs/
│   └── specs/
│       ├── notification/
│       │   ├── requirements.md
│       │   ├── design.md
│       │   └── tasks.md
│       └── auth/
│           ├── requirements.md
│           └── design.md
└── src/
    └── notification/
        └── ...코드...

GitHub Spec Kit의 워크플로우:

requirements.md → design.md → tasks.md → 코드 생성 → PR

모든 명세 파일이 저장소 안에 코드와 함께 커밋됩니다. 나중에 “왜 이렇게 구현했지?”라는 질문에 명세로 답할 수 있게 됩니다.

명세가 코드 밖에 있으면 AI는 다음 세션에 명세를 참조할 수 없습니다. 그러면 매번 “처음부터 설명해줘” 상태가 됩니다.

실전 팁: PR 템플릿에 “관련 명세 파일 경로”를 필수 입력란으로 넣어두면 자연스럽게 명세-코드 동기화가 강제됩니다.

체크 5. 명세 작성에 AI를 쓰고 있는가

역설적으로 들리지만, AI를 잘 쓰는 방법 중 하나가 명세 작성에 AI를 먼저 쓰는 것입니다.

흐름은 이렇습니다:

  1. 만들고 싶은 기능을 대화체로 AI에게 설명한다
  2. AI가 requirements.md 초안을 뽑아준다
  3. 사람이 검토하며 빠진 것, 틀린 것을 수정한다
  4. 확정된 명세를 저장한다
  5. 그 명세를 기반으로 AI가 코드를 생성한다

이 과정에서 중요한 건 3번, 사람의 리뷰입니다. AI가 명세를 초안으로 만들어줘도, 비즈니스 맥락과 제약 조건은 사람이 검토해야 합니다.

Kiro가 AI 에이전트 시장에서 빠르게 성장한 이유 중 하나가 이 흐름을 IDE 안에 내장했기 때문입니다. 기능 요청을 입력하면 세 개의 명세 파일(requirements, design, tasks)을 순서대로 생성하고, 각 단계마다 사람의 승인을 받습니다. 코드는 마지막에 나옵니다.

Claude Code에서 바로 쓸 수 있는 명세 생성 프롬프트:

다음 기능의 SDD 명세를 작성해줘.

기능 개요: [기능 설명]
대상 사용자: [사용자 설명]
맥락: [비즈니스 맥락]

아래 형식으로 작성해:
1. 목적 (왜 만드는가)
2. 대상 사용자와 주요 시나리오
3. 수용 기준 (각 항목은 테스트로 검증 가능하게)
4. 제약 조건 (DO NOT 리스트)
5. 기술 고려사항

완성되면 내가 검토 후 수정할 예정이야.

이 프롬프트로 뽑은 초안을 30분 검토하는 게, 명세 없이 바로 코딩 들어갔다가 나중에 전면 재작성하는 것보다 훨씬 효율적입니다.

실수 TOP 4 — SDD 도입 초기에 자주 틀리는 것들

실수 1: 명세가 완벽해야 코드를 짠다고 생각한다

명세는 살아있는 문서입니다. 처음부터 100% 완벽할 필요 없습니다. 80%면 시작하고, 개발하면서 발견한 것들을 명세에 반영하면 됩니다. 완벽주의 때문에 명세 작성이 지연되면 SDD가 아니라 분석마비(Analysis Paralysis)가 됩니다.

실제로 Thoughtworks 리서치에서도 “명세는 반복적으로 개선된다”는 전제 하에 SDD를 운영합니다. 완성된 명세를 기다리지 말고, 충분한 명세로 시작하세요.

실수 2: 명세를 팀장/기획자만 쓴다고 생각한다

SDD에서 명세는 개발자가 직접 씁니다. AI와 대화하면서 기술적 제약과 설계 결정을 명세에 담는 것이 개발자의 역할입니다. 기획 문서를 받아서 그대로 AI에게 주면 기술적 맥락이 빠집니다.

“어떤 DB 인덱스를 걸어야 하는가”, “캐싱 전략은 어떻게 할 것인가”, “에러 응답 포맷은?” 같은 결정들이 명세에 들어가야 AI가 일관된 코드를 냅니다. 이건 개발자만 쓸 수 있는 내용입니다.

실수 3: 명세는 한 번만 쓴다고 생각한다

기능이 변경되면 명세도 변경됩니다. 코드를 변경하는 PR과 명세를 변경하는 내용이 같이 다뤄져야 합니다. 명세와 코드가 따로 놀기 시작하면 SDD가 아니라 그냥 문서 과부하입니다.

팀에서 가장 많이 실패하는 패턴이 이것입니다: 처음에 명세 열심히 쓰고, 2주 후에 기능 변경할 때 명세 업데이트를 빠뜨리는 것. 그러면 명세가 “레거시 문서”가 됩니다.

실수 4: 모든 AI 사용에 SDD를 강제한다

빠른 프로토타입, 일회용 스크립트, 실험적 탐색에는 SDD가 과한 경우가 있습니다. SDD는 이런 상황에 효과가 큽니다:

  • 팀 2명 이상이 협력하는 프로젝트
  • 3개월 이상 유지보수할 코드
  • AI 에이전트가 반복적으로 개발에 참여하는 경우
  • 외부에 배포될 서비스

반면 이런 경우에는 과할 수 있습니다:

  • 혼자 쓸 1회성 스크립트
  • 24시간 해커톤 프로토타입
  • 아이디어 검증을 위한 10줄짜리 테스트 코드

맥락에 맞게 적용하세요.

SDD 도입 로드맵 — 지금 당장 시작하는 3단계

1단계 (1주차): 하나의 기능에 requirements.md만 먼저 써본다

지금 진행 중인 프로젝트에서 다음에 개발할 기능 하나를 골라서, AI와 함께 requirements.md를 먼저 써보세요. 거창하게 시작할 필요 없습니다. 20줄짜리 파일이라도 “이게 있으니까 AI가 더 잘 따라오네”를 체감하면 자연스럽게 확장됩니다.

2단계 (2-3주차): design.md와 DO NOT 리스트 추가

requirements.md에 익숙해지면 기술 설계를 담은 design.md를 추가합니다. 동시에 명세의 제약 조건 섹션(DO NOT 리스트)을 체계적으로 작성합니다. 이 두 가지가 추가되는 순간 AI의 오작동이 눈에 띄게 줄어듭니다.

3단계 (1개월+): 저장소 통합과 PR 리뷰 흐름에 명세 포함

명세 파일을 Git 저장소에 커밋하고, PR 템플릿에 명세 경로를 필수 항목으로 넣습니다. 이 시점부터 팀 전체의 AI 개발 품질이 일관성을 갖기 시작합니다.

FAQ

Q. SDD와 TDD(테스트 주도 개발)는 어떻게 다른가요?

TDD는 테스트를 먼저 작성하고 그 테스트를 통과하는 코드를 짜는 방식입니다. SDD는 명세(spec)를 먼저 작성하고 코드와 테스트 모두 명세를 기준으로 만드는 방식입니다. 상호 보완적입니다. SDD로 명세를 만들고, TDD로 그 명세를 검증하는 테스트를 작성하면 잘 맞습니다. 실제로 SDD의 “테스트 가능한 수용 기준”이 TDD의 테스트 케이스로 자연스럽게 연결됩니다.

Q. 개인 개발자도 SDD가 필요한가요?

1인 프로젝트나 주말 토이 프로젝트라면 꼭 필요하지는 않습니다. 하지만 프로젝트가 몇 달 이상 이어지거나 AI 에이전트를 지속적으로 쓸 계획이라면 최소한 핵심 명세는 파일로 남겨두는 게 좋습니다. 3개월 후의 자신도 “왜 이렇게 짰지?”라는 질문을 할 수 있습니다. 그리고 그때 AI한테 “이어서 개발해줘”라고 했을 때 명세가 없으면 AI도 모릅니다.

Q. Claude Code에서 SDD를 바로 적용할 수 있나요?

네. CLAUDE.md가 프로젝트 수준의 명세 역할을 합니다. 추가로 GitHub에 오픈소스로 올라온 cc-sdd를 사용하면 Claude Code에서도 requirements → design → tasks 흐름을 그대로 쓸 수 있습니다. cc-sdd는 Kiro 스타일의 명세 기반 워크플로우를 Claude Code, Cursor, Codex, Copilot 등 다양한 에이전트에서 사용할 수 있게 해주는 CLI입니다.

Q. 명세가 너무 길어지면 AI가 다 읽지 못하지 않나요?

현실적인 고민입니다. 명세를 기능별로 분리해서 관리하면 해결됩니다. 전체 시스템 명세 하나가 아니라 기능 단위로 쪼개서 관련 명세만 컨텍스트에 넣는 방식입니다. Claude Code 기준으로 CLAUDE.md는 전체 원칙, 각 기능 폴더의 spec.md는 해당 기능 명세로 분리하면 효율적입니다. 2026년 기준 Claude의 100만 토큰 컨텍스트도 도움이 되지만, 필요한 명세만 넣는 게 더 정확한 결과를 냅니다.

Q. SDD를 처음 도입할 때 어디서 시작하면 되나요?

지금 진행 중인 프로젝트에서 다음에 개발할 기능 하나를 골라서, AI와 함께 requirements.md 하나만 먼저 써보세요. 거창하게 시작할 필요 없습니다. 한 기능의 명세를 써보고 “이게 있으니까 AI가 더 잘 따라오네”를 체감하면 자연스럽게 확장됩니다. GitHub Spec Kit 저장소에 시작 템플릿이 있습니다.

Q. DEVOCEAN 송영목 님이 말한 “명세가 원본, 코드는 표현”이라는 개념이 무슨 뜻인가요?

전통 개발에서는 명세가 참고 문서였고 코드가 진짜 결과물이었습니다. SDD에서는 이 관계를 뒤집습니다. 명세가 원본(source of truth)이고, 코드는 그 명세의 구현된 표현입니다. 명세가 바뀌면 코드도 바뀌어야 하고, 코드만 바뀌면 명세도 업데이트해야 합니다. AI가 코드를 대신 쓰는 시대엔 “무엇을 만들 것인가”라는 명세의 주권이 개발자에게 더 중요해집니다.

공식 출처

관련 글