04. Specification-Driven Development (SDD)

“Specification-Driven Development (SDD)”

• “코드 중심”에서 “명세 중심”으로 개발의 진실(Source of Truth)을 옮기는 선언문.
• 슬라이드 구성 포인트
  • 제목: Specification-Driven Development (SDD), 부제: 명세가 코드를 이끄는 개발 패러다임
  • 핵심 문장: Intent → Spec → Plan → Code
  • 오른쪽 그림: Software Architecture Blueprint (API Gateway–Microservices–DB/Integrations 흐름)
• 왜 중요하나
  • 이 한 장이 SDD의 세계관을 고정합니다. SDD는 “코드를 먼저 만들고 문서를 맞추는” 방식이 아니라, 의도/명세/계획이 먼저이고 코드는 결과물이라는 전제를 깔고 갑니다.
• 실무 적용 팁
  • 팀 합의 문장으로 “Intent → Spec → Plan → Code”를 박아두면, 구현 중 논쟁이 생겨도 기준점이 흔들리지 않습니다.

---

문제 제기 : “왜 또 다른 방법론인가?”

• 전통 개발은 “코드만 진짜”로 취급해 시간이 갈수록 문서-코드 괴리가 폭발한다.
• 슬라이드가 말하는 핵심
  • 전통 방식: 코드가 진실의 원천, PRD/설계 문서는 참고용 → 초기엔 빠르지만 장기적으로 붕괴
  • 대표 증상: 코드와 문서 불일치, 명세-구현 괴리, 낡은 문서 + 독자 진화하는 코드
  • 누적 문제: 온보딩 어려움, 변경 추적 어려움, 리팩터링 위험 증가, 인수인계 복잡, 기술부채 누적
• 왜 중요하나
  • SDD는 “문서 좀 더 쓰자”가 아니라, 불일치가 발생하는 구조 자체를 뒤집자는 제안입니다.
• 실무 적용 팁
  • 레거시가 클수록 SDD 효과가 큽니다. 특히 “문서 업데이트 안 됨”이 반복되는 팀에서 체감이 큽니다.

---

권력의 전환 : “코드에서 명세로”

• “왜 코드를 진실의 원천으로 둬야 하지?”라는 질문으로 시작한다.
• 슬라이드 핵심 메시지
  • 코드는 “구현의 한 형태”일 뿐, 유일한 진실일 필요는 없다.
  • 명세가 1차 산출물, 코드는 명세의 표현물(expression)이다.
  • 명세/계획이 실행 가능(executable)해지면, 코드 생성은 변환(transform) 문제로 수렴한다.
• 왜 중요하나
  • 여기서 말하는 “실행 가능한 명세”는 단순 문서가 아니라, 검증/생성/재생성을 전제로 한 구조화된 명세를 뜻합니다.
• 실무 적용 팁
  • “명세 = 문서”로 끝내지 말고, 명세로부터 plan/tasks/test/code가 자동 생성되는 흐름을 설계해야 SDD가 성립합니다.

---

SDD 한 줄 정의 — “명세가 곧 코드의 소스 코드”

• 데이터 모델·API·테스트·비즈니스 로직의 근원은 “코드”가 아니라 “명세”다.
• 슬라이드 구성
  • 명세가 곧: 데이터 모델/ API 설계/ 테스트 시나리오/ 비즈니스 로직의 근원
  • 코드는: 특정 언어로 변환된 결과물, 특정 프레임워크 구현체, 필요 시 재생성 가능, 명세에 종속된 표현 형태
• 왜 중요하나
  • “코드가 진짜”라는 관성을 버려야 재생성(Regeneration), 동기화 자동화가 가능해집니다.
• 실무 적용 팁
  • 팀 규칙을 “코드 수정”보다 “명세 수정 → 재생성”에 우선순위를 두도록 바꾸는 게 핵심입니다.

---

SDD에서 개발자의 역할

• 사람은 고차원 판단, AI는 반복·기계적 변환을 맡는다.
• 개발자가 집중할 영역(사람)
  • 문제 정의/도메인 이해
  • 요구사항·엣지 케이스 정교화
  • 비기능 요구사항 명시
  • 아키텍처 원칙/팀 규칙/조직 제약 정의
  • 비판적 사고와 최종 판단
• AI가 담당할 영역
  • 명세→코드 기계적 변환
  • 구현 계획 초안 생성
  • 테스트 케이스 생성
  • 리팩터링 제안
  • 일관성 검사/검증
• 왜 중요하나
  • SDD는 “AI가 코딩해준다”가 아니라 사람-기계 분업을 표준화하는 방법론입니다.
• 실무 적용 팁
  • 팀이 가장 먼저 합의해야 할 문장: “번역은 AI, 판단은 사람”

---

SDD 워크플로우 개요 (01~07)

• 아이디어→명세→리서치→계획→코드→피드백→반복의 전 과정을 한 파이프라인으로 묶는다.
• 단계별 의미
  1. 아이디어 단계: 대부분 모호한 상태에서 출발
  2. 명세 고도화: AI 대화로 PRD/명세를 정교화
  3. 리서치 단계: 관련 기술/제약 조사
  4. 구현 계획: 명세로부터 Implementation Plan 생성
  5. 코드 생성: 명세·계획이 안정되면 코드 생성
  6. 피드백 루프: 테스트/운영 데이터로 명세 업데이트
  7. 반복과 개선: 재생성, 리팩터링, 다른 구현 시도
• 왜 중요하나
  • SDD의 핵심은 “명세 작성”이 아니라 명세가 계속 살아서 업데이트되는 운영 구조입니다.
• 실무 적용 팁
  • 6번(피드백 루프)을 빼면 SDD가 아니라 “초반에 문서 좀 잘 쓴 프로젝트”로 끝납니다.

---

SDD vs 전통 개발

• 전통은 문서가 정적이고 수동 동기화, SDD는 명세가 살아있고 자동 동기화.
• 전통 개발
  • 초기 문서화에 집중 → 이후 방치
  • 정적인 명세
  • 코드 중심 진화(문서와 괴리)
  • 변경 반영 시 문서/코드 모두 수작업 수정
• SDD 방식
  • 요구/설계/명세는 생명주기 전체에서 지속 활동
  • 살아있는 명세(코드 생성의 직접 원천)
  • 명세 주도 진화(명세 변화에 따라 코드 진화)
  • 변경은 “명세 수정 + 재생성”으로 처리
• 실무 적용 팁
  • “문서 업데이트는 나중에”라는 습관을 깨고, 변경이 생기면 명세부터 고치는 규율이 필요합니다.

---

왜 지금 SDD인가? (1) AI 역량의 진화

• LLM 발전으로 “자연어 명세→동작 코드” 변환이 현실이 됐다(단, 템플릿/지침이 있을 때).
• 핵심 요지
  • LLM은 자연어를 코드로 변환 가능 수준에 도달
  • 단, 구조화된 템플릿 + 명확한 지침이 있으면 품질이 크게 상승
  • “아무 코드나”가 아니라 “이 템플릿/규칙에 맞는 명세·계획·코드”로 지시
  • 품질 제어 장치로 헌법(Constitution)이 가드레일 역할
• 실무 적용 팁
  • AI를 잘 쓰는 팀은 프롬프트가 아니라 템플릿·규칙(가드레일)을 먼저 만듭니다.

---

왜 지금 SDD인가? (2) 복잡성과 변화 속도

• 시스템이 복잡해지고 요구가 빨리 변하는 시대에, “명세 수정→재생성”이 가장 싸다.
• 슬라이드 핵심
  • 마이크로서비스/의존성 증가로 수작업 일관성 유지가 어렵다
  • 비즈니스 Pivot이 기본 모드가 됐다
  • A/B 테스트, 다양한 구현 방식 시도, 빠른 프로토타이핑 필요
  • SDD는 명세만 수정하고 재생성하면 변화 대응 비용이 크게 줄어든다
• 실무 적용 팁
  • “변경이 잦은 기능(가격정책/프로모션/추천/검색)”부터 SDD를 적용하면 효과가 빨리 납니다.

---

SDD 핵심 원칙 요약

• 명세를 공통 언어로 만들고, 실행 가능하게 유지하며, 지속적으로 정제한다.
• 6가지 원칙
  1. 명세=공통 언어(PM/디자이너/개발/QA의 Lingua Franca)
  2. 실행 가능한 명세(생성/테스트/검증 가능한 형식)
  3. 지속적 정제(프로젝트 내내 업데이트)
  4. 리서치 기반 컨텍스트(제약/라이브러리/보안/성능 조사)
  5. 양방향 피드백(운영 데이터가 명세로 환류)
  6. 분기와 실험(병렬 시도/비교 가능)
• 실무 적용 팁
  • “명세는 읽는 것”이 아니라 실행 가능한 시스템 입력이라는 관점을 팀에 주입해야 합니다.

---

SDD 실천 도구 스택

• SDD는 이론이 아니라, 지금 당장 조합 가능한 도구 체인이다.
• 도구 구성
  1. AI 어시스턴트(명세/계획/코드 생성)
  2. 리서치 에이전트(기술 선택/취약점/성능 조사)
  3. Codegen 도구(프롬프트 기반 일관 코드 생성)
  4. Git 버전 관리(명세·계획·코드 동시 버전 관리)
  5. Consistency Checker(모순/모호/누락 자동 검출)
• 실무 적용 팁
  • “명세 파일도 코드처럼 PR 리뷰” + “체커로 모순 감지”를 붙이면 SDD의 효과가 확 올라갑니다.

---

SDD를 현실로 만드는 3가지 명령어 (Speckit 스타일)

• SDD 흐름을 3개의 고정 명령으로 표준화한다.
• 3개 명령의 역할
  • /speckit.specify: 아이디어 → Feature 명세 + 브랜치 + 디렉터리 구조
  • /speckit.plan: 명세 → 구현 계획 + 리서치 + Data Model + Contracts
  • /speckit.tasks: 계획 → 실행 가능한 작업 목록(tasks.md)
• 왜 중요하나
  • “명세-계획-작업”이 사람 손에만 맡겨지면 품질이 들쑥날쑥해집니다. 명령어는 자동화와 표준화를 통해 일관성을 만듭니다.

---

/speckit.specify — 명세 생성

• 한 줄 기능 설명만으로도 “명세 패키지”를 표준 구조로 만든다.
• 입력
  • “짧은 기능 설명 한 줄”
• 하는 일(자동화)
  • 기존 스펙 번호 자동 스캔 → 순차 번호 부여(001, 002…)
  • 의미 있는 브랜치 이름 자동 생성
  • 명세 템플릿 복사 및 내용 채우기
  • 표준 디렉터리 구조 생성
• 출력 예시(폴더 구조)
  • specs/003-chat-system/ 아래 spec.md, plan.md, data-model.md, contracts/, research.md
• spec.md에 담기는 것
  • 사용자 스토리, 수용 기준, 비기능 요구사항, 제약사항, 엣지 케이스
• 실무 적용 팁
  • 이 단계에서 “빠진 요구사항”이 드러나게 설계하는 게 핵심입니다. 빈칸을 그냥 넘어가지 않는 템플릿이 SDD의 시작점입니다.

---

/speckit.plan — 구현 계획 생성

• 명세를 “기술적으로 어떻게 풀지”를 문서화된 청사진으로 바꾼다.
• 입력
  • spec.md(필수) + 선택 힌트(기술 스택/제약 등)
• 분석 과정
  • 기능/유스케이스/엣지케이스 이해
  • Constitution(헌법)과 정합성 체크
• 출력
  • plan.md, data-model.md, contracts/, quickstart.md, research.md
• 실무 적용 팁
  • plan은 “코드 작성 지시서”가 아니라 의사결정 기록입니다. 나중에 “왜 이렇게 설계했지?”가 plan에서 답이 나와야 합니다.

---

/speckit.tasks — 태스크 리스트 생성

• plan을 “지금 당장 실행 가능한 작업(Task)”으로 떨어뜨린다.
• 프로세스
  1. 입력 수집: plan.md(필수) + data-model.md/contracts//research.md(선택)
  2. 작업 추출: 구현 단위 식별
  3. 태스크 변환: API/엔티티/시나리오를 실행 가능한 작업으로
  4. 병렬성 표기: 독립 작업에 [P] 마커
  5. tasks.md 생성
• 실무 적용 팁
  • 여기서 목표는 “할 일 목록”이 아니라 작업 분배/병렬 처리/진척 추적이 가능한 수준의 granularity입니다.

---

템플릿이 중요한 이유 = 고급 프롬프트 엔지니어링

• 템플릿은 AI의 추측을 막고, 요구 완전성과 일관성을 강제한다.
• 4가지 이유
  1. WHAT/WHY vs HOW 분리: “무엇/왜”만 다루고 기술 스택·코드 구조 언급을 금지(초기 과잉 설계 방지)
  2. [NEEDS CLARIFICATION] 마커: 모호하면 추측하지 말고 질문으로 남기게 강제
  3. 체크리스트 기반 검토: 수용 기준/비기능 요구사항/테스트 가능성까지 확인
  4. 일관성 보장: 팀 전체가 동일 형식/수준의 명세 작성 → 코드 품질 일관성으로 연결
• 실무 적용 팁
  • 템플릿은 “양식”이 아니라 품질 관리 시스템입니다. (특히 [NEEDS CLARIFICATION]은 AI 코딩에서 치명적인 추측을 막는 장치입니다.)

---

SDD 헌법(Constitution) 개요

• 프로젝트 전체가 따라야 하는 “불변 원칙”을 최상위 규칙으로 고정한다.
• 헌법 파일
  • memory/constitution.md = 모든 명세/계획/코드가 따라야 하는 최상위 규칙
• 예시 조항
  • Article I: Library-First
  • Article II: CLI Interface Mandate
  • Article III: Test-First Imperative
  • Article VII: Simplicity
  • Article VIII: Anti-Abstraction
  • Article IX: Integration-First Testing
• 실무 적용 팁
  • 헌법은 “좋은 개발 습관”이 아니라 자동 생성의 안전장치(가드레일)입니다. 헌법이 없으면 자동화가 곧 무질서로 갑니다.

---

핵심 조항 예시 (1) Library-First

• 기능은 앱 코드에 바로 넣지 말고, 재사용 가능한 라이브러리로 먼저 만든다.
• 원칙
  • 모든 기능은 라이브러리로 시작 (앱 코드에 직접 구현 금지)
• 적용 예시
  • 인증 로직 → auth-lib
  • 데이터 검증 → validation-lib
  • 비즈니스 규칙 → domain-lib
• 기대 효과
  • 재사용성 극대화(여러 앱에서 동일 로직 재사용)
  • 책임 분리(도메인 로직 vs UI/프레임워크 분리)
  • 테스트 용이(라이브러리 단위 독립 테스트)
  • 다양한 컨텍스트(CLI/웹/모바일)에서 동일 라이브러리 활용
• 실무 적용 팁
  • “UI 먼저 만들고 로직 끌어오자”는 유혹을 끊는 조항입니다. 규모가 커질수록 이 원칙이 차이를 만듭니다.

---

핵심 조항 예시 (2) Test-First

• 테스트는 선택이 아니라 절대 양보 불가 조항이며, AI에게도 동일하게 강제한다.
• TDD 흐름
  • Red: 실패하는 테스트 작성(특히 Contract/Integration/E2E부터)
  • 확인: Red 상태 검증(테스트가 실제로 실패하는지 확인)
  • Green: 구현 작성(Red 확인 후에만 구현 가능)
• AI에도 동일 적용
  • “테스트 파일 먼저 생성 → 그 다음 구현 코드 생성” 순서를 강제
• 실무 적용 팁
  • AI 코딩에서 가장 흔한 사고가 “그럴듯한 코드지만 검증 없음”입니다. 이 조항이 그 문제를 구조적으로 차단합니다.

---

핵심 조항 예시 (3) Simplicity & Anti-Abstraction

• 초기 구현은 단순해야 하고, 불필요한 추상화/래핑을 금지한다.
• 초기 구현 제약
  • 프로젝트 수 ≤ 3개
  • 미래 대비 과잉 설계 금지
  • 프레임워크 기능 직접 사용(불필요 wrapper 금지)
  • 모델 표현은 가능한 한 단순하게
• 복잡성 추가 규칙
  • 복잡성이 필요하면:
    • Complexity Tracking에 이유 문서화
    • 대안 검토 및 기각 사유 명시
    • 복잡성 제거를 위한 향후 계획 수립
• 실무 적용 팁
  • SDD는 “명세가 왕”이지만, 그 명세가 곧바로 “복잡한 설계”를 정당화하면 망합니다. 그래서 복잡성 문서화 의무를 같이 둡니다.

---

SDD에서 디버깅

• 버그가 나면 코드부터 고치지 말고, 명세/계획/테스트/생성 과정의 결함을 먼저 의심한다.
• SDD 디버깅 질문 4개
  • 명세가 요구사항을 정확히 반영했는가?
  • 구현 계획에 논리적 오류가 있는가?
  • 테스트 시나리오가 충분했는가?
  • 코드 생성 과정에서 누락이 있었는가?
• 왜 중요하나
  • 전통 디버깅은 “증상(코드)”을 붙잡는 경향이 강합니다. SDD는 “원인(명세/계획)”을 고쳐 재발을 막는 방식입니다.
• 실무 적용 팁
  • 동일한 버그가 반복되면 대부분 “명세의 모호함”이나 “테스트 시나리오 누락” 문제일 가능성이 큽니다.

---

SDD에서 리팩터링

• 리팩터링은 코드가 아니라 명세 수준에서 시작하고, 병렬 실험→비교 평가→최선 선택으로 간다.
• 프로세스
  1. 명세 개선: 문제점 파악, 더 명확/효율적으로 정제(새 요구/제약 반영)
  2. 병렬 실험: 개선된 명세로 여러 구현 방식 병렬 시도(AI 에이전트 활용)
  3. 비교 평가: 성능/안정성/유지보수성 등 지표로 비교(테스트/벤치/시뮬)
  4. 최선 선택: 최적 구현을 프로덕션 적용, 나머지는 지식/학습 데이터로 축적
• 실무 적용 팁
  • “리팩터링 브랜치가 영원히 안 끝나는 문제”를 줄이는 핵심이 비교 기준(테스트/벤치)과 선택 프로세스입니다.

---

변경과 Pivot 시나리오

• 전통은 변경 때마다 문서/코드를 수작업으로 다 고치고, SDD는 명세 수정 후 재생성으로 대응한다.
• 전통 방식의 변경
  • 요구 변경 → 설계/문서/코드 모두 수작업 수정
  • 정합성 유지 어려움, 미반영은 기술 부채로 남음
• SDD 방식의 변경
  • PRD/명세 수정 → /speckit.plan, /speckit.tasks 재실행
  • 업데이트된 계획/작업 목록 확보
  • 필요 시 코드 재생성, 마이그레이션에 집중
• 슬라이드가 제시하는 효과(주장)
  • 80% 시간 절감 / 95% 일관성 유지 / 3x 실험 속도
• 실무 적용 팁
  • “요구가 자주 바뀌는 영역”에서 SDD의 비용 절감 효과가 가장 크게 드러납니다.

---

개발자 입장에서의 실질적 이득

• 온보딩, 정합성, 재시작, 의사결정 기록, 품질이 모두 좋아진다.
• 핵심 이득 5가지
  • 온보딩 가속화: 명세/계획이 최신이라 신규 팀원이 빨리 이해
  • 문서-코드 괴리 해소: 명세가 곧 코드 소스이기 때문
  • 쉬운 재시작: 실패해도 명세로 돌아가 다른 접근을 재시도
  • 의사결정 기록: “왜 이렇게 만들었지?”가 명세/계획/헌법에 남음
  • 품질 향상: 테스트/계약/도메인 용어가 자연스럽게 코드베이스에 스며듦
• 실무 적용 팁
  • “의사결정 기록”은 장기 운영에서 특히 강력합니다. 사람이 바뀌어도 이유가 남습니다.

---

SDD 도입 시 시작 포인트

• 혁명이 아니라 진화다. 작은 기능 하나로 끝까지 한 번 돌려보고, 최소 헌법으로 시작한다.
• 권장 도입 순서
  1. 작은 기능 선정: 실험하기 적당한 크기
  2. 명세 템플릿 작성: 모호성이 드러나는 과정 자체가 가치
  3. 전체 흐름 경험: “명세 → 계획 → 태스크”를 끝까지 돌리고 배포까지
  4. 최소 헌법 정의: 3~5개 핵심 원칙이면 충분
  5. 점진적 확장: 성공 사례 기반으로 범위 확대, 피드백 반영
• 핵심 목표(슬라이드 문장 요지)
  • “한 번에 팀 전체 전환”이 아니라 작고 명확한 성공 사례를 먼저 만든다.
• 실무 적용 팁
  • 첫 파일/첫 템플릿을 잘 만드는 것이 곧 SDD 도입 성공률을 결정합니다.

---

정리 : SDD가 가져오는 변화

• SDD는 방법론이 아니라 “무엇이 진실의 원천인가”를 재정의하는 패러다임이다.
• 슬라이드가 정리하는 변화
  • 명세가 진짜 소스: 명세가 코드의 진짜 소스가 되는 시대
  • 높은 수준의 사고: 개발자는 더 높은 레벨에서 사고/의사결정
  • AI의 역할: 기계적 번역/반복 작업 담당
  • 정상화된 변화: 변경/실험/Pivot이 “정상 동작”이 되는 문화
  • 간극의 제거: 의도(Intent)와 구현(Implementation) 간극을 구조적으로 제거
• 실무 적용 팁
  • SDD의 최종 목표는 “문서화 강화”가 아니라 의도→구현 간극을 시스템적으로 줄이는 것입니다.