SDD(Spec-Driven Development) 방법론

[k9425mino]

📆 일자: 26년 7월 29일(수)

요즘 개발 트렌드는 AI 에이전트를 활용한 개발이 주를 이루고 있습니다. AI 에이전트는 개발 생산성을 크게 높여주지만, 프로젝트가 고도화될수록 무분별한 코드 생성과 환각 문제가 두드러진다는 한계도 있습니다. 이러한 상황에서 SDD는 명세를 팀의 단일 진실 공급원으로 삼아, 협업 과정에서의 일관성과 체계적이고 효율적인 개발을 가능하게 합니다. SDD는 비교적 최근 등장한 개념이라 아직 논란의 여지가 있을 수 있지만, 개발자의 역할이 '코드를 작성하는 사람'에서 '스펙을 검증하고 테스트를 설계하는 사람'으로 변화하는 흐름에 부합하는 방법론입니다. 이에 따라 이번 스터디에서는 SDD(Spec-Driven Development) 방법론에 대해 알아보고자 합니다.

🤔오늘의 질문

1. SDD의 정의와 등장 배경을 설명해주세요.
2. SDD의 핵심 원칙과 워크플로우를 설명해주세요.
3. SDD의 장점과 한계를 설명해주세요.
4. SDD 프레임워크 2~3개 정도를 간단하게 소개해주세요.

[9ga0]

SDD(Spec-Driven Development) 방법론 #21

1. SDD의 정의와 등장 배경을 설명해주세요.

Spec-Driven Development는 코드를 먼저 작성하기 보다, 명세(spec)를 작성하고 그 명세를 기준으로 설계, 구현, 테스트, 리뷰를 진행하는 개발 방법론입니다. 여기서 명세는 단순 요구사항 목록뿐만 아니라, 무엇을 만들지, 어떤 동작을 할지/하지말지, 예외 상황 어떻게 처리할지, 입출력, 완료 기준, 테스트 방법 등을 포함합니다.
소프트웨어 규모가 커지면서 사람과의 협업이나 ai와의 협업 시 개발 의도를 명확하게 전달하기 위해서 명확한 기준 문서의 필요해지게 되면서 SDD가 주목받게 되었습니다.

2. SDD의 핵심 원칙과 워크플로우를 설명해주세요.

핵심 원칙은 대표적으로 Spec First, Shared Source of Truth, Unambiguous Behavior, Testable Secification, Iterative Refinement, Boundary Clarity 로 6가지가 있습니다.

• Spec First : 구현 전에 명세를 먼저 작성한다.
• Shared Source of Truth : 명세를 기획자, 개발자, QA, AI 에이전트가 함께 보는 기준으로 삼는다.
• Unambiguous Behavior : "잘 동작해야 한다"가 아니라 구체적인 입력, 출력, 상태, 예외를 적는다.
• Testable Secification : 명세는 테스트 가능한 형태여야 한다.
• Iterative Refinement : 명세는 한 번에 완성하는 문서가 아니라 구현과 피드백을 거치며 갱신된다.
• Boundary Clarity : 이번 작업의 범위, 비범위, 의존성, 변경 금지 영역을 명확히 한다.

일반적인 워크플로우는 문제와 목표 정의, 명세 작성, 명세 리뷰, 테스트 기준화, 구현, 검증, 명세 갱신 순서를 따릅니다.

3. SDD의 장점과 한계를 설명해주세요.

장점)

• 요구사항 해석 차이를 줄인다.
• 개발 전에 누락된 조건과 모순을 발견할 수 있다.
• 테스트 기준이 명확해진다.
• 코드 리뷰가 "취향 논쟁"보다 "명세 충족 여부" 중심으로 바뀐다.
• 신규 개발자의 온보딩이 쉬워진다. (안내서 역할까지 가능)

  실제 회사에서는 신규 개발자가 입사하면 보통 이런 순서로 온보딩이 진행됩니다.
  1. 프로젝트 소개
  2. 개발 환경 설정
  3. SDD 또는 기술 문서 읽기
  5. 시스템 아키텍처 이해
  6. 작은 버그 수정
  7. 작은 기능 개발
  8. 큰 기능 개발
  이 과정을 통해 몇 주에서 몇 달에 걸쳐 프로젝트를 이해하게 됩니다.

• AI 코딩 도구에 더 정확한 작업 지시를 줄 수 있다.
• 큰 기능을 작은 명세 단위로 쪼개기 좋다.
• 유지보수 시 "왜 이렇게 만들었는가"를 추적하기 쉽다.

한계)

• 명세 작성 시간이 추가로 필요하다.
• 오래된 명세는 혼란을 만든다.
• 불확실성이 큰 초기 제품에서는 지나친 명세화가 개발 속도를 늦춘다.
• 모든 요구사항을 문서로 완벽하게 표현하기 어렵다.
• 팀이 명세를 읽고 갱신하는 습관이 없으면 형식적인 문서가 된다.
• 창의적 UI, 탐색적 프로토타입, 연구성 작업에는 유연한 접근이 더 적합할 수 있다.
  * 탐색적 프로토타입 : "무엇을 만들지 아직 확실하지 않은 상태"에서 빠르게 시제품을 만들어 아이디어를 검증하는 방식

4. SDD 프레임워크 2~3개 정도를 간단하게 소개해주세요.

SDD 프레임워크는 대표적으로 SpecDD, BDD, Specification by Example이 있습니다.

• SpecDD : Spec-Driven Development를 위해 .sdd 파일을 코드 가까이에 두는 방식의 프레임워크입니다. 각 기능이나 모듈 옆에 명세를 두고, 의도, 책임, 경계, 의존성, 완료 기준 등을 기록합니다. 특히 AI 에이전트와 사람이 같은 명세를 기준으로 작업하는 흐름에 잘 맞습니다. https://specdd.ai/
• BDD / Cucumber : Behavior-Driven Development로, 사용자의 행동과 시스템 반응을 예시 중심으로 명세화합니다. Cucumber는 Gherkin 문법을 사용해 Given, When, Then 형태로 실행 가능한 명세를 작성하게 해줍니다. SDD와 완전히 같은 것은 아니지만, “명세를 먼저 쓰고 구현과 테스트를 연결한다”는 점에서 매우 가까운 실천 방식입니다.
  https://cucumber.io/docs/bdd/
• Specification by Example : 추상적인 요구사항보다 구체적인 예시를 통해 명세를 만드는 방식입니다. 예를 들어 “할인을 적용한다”가 아니라 “VIP 사용자가 10만 원 이상 구매하면 15% 할인을 받는다”처럼 실제 사례를 기준으로 합의합니다. 이후 이 예시는 인수 테스트나 자동화 테스트로 연결될 수 있습니다.
  https://martinfowler.com/bliki/SpecificationByExample.html

AI 시대에는 “프롬프트를 잘 쓰는 것”보다 한 단계 더 나아가, 프로젝트 안에 지속 가능한 명세 체계를 두는 것이 중요해지고 있다.

[eunji719]

1. SDD란 코드가 아닌 문서화되고 버전 관리되는 명세를 프로젝트의 유일한 진실 공급원으로 삼는 개발 방법론이다. 먼저 시스템이 무엇을 해야 하는지 상세히 기술한 스펙을 작성하고, 구현 계획을 도출한 뒤 세부 작업으호 쪼개 코드를 생성한다. 요구사항이 바뀌면 코드를 고치는 것이 아닌 스펙을 수정하고 다시 코드를 생성하는 방식이다. 바이브코딩이 성장하면서 ai에게 막연한 목표를 던져주면 그럴듯하지만 제대로 작동하지 않는 코드를 만들어내는 문제가 반복됐고 원인은 ai모델 자체 한계보다는 ai를 검색엔진처럼 다루고 신중하지 못한 작업방식에 있었다. 이런 모호한 프롬프트가 신뢰할 수 없는 코드로 이어지는 문제를 해결하려는 흐름에서 등장하게 된 방법론이다.

---

2. SDD에서는 명세가 원본,코드는 파생물이라는 관점을 취하고, 개발의 중심을 ‘무엇을,왜’로 옮기며 의도 중심적인 개발을 원칙으로 하며, 한번 쓰고 끝나는게 아닌 변화에따라 함께 진화하는 살아있는 문서 스펙을 사용하며, 개발자가 코드를 직접 짜기보단 ai결과물이 명세,계획에 부합하는지 검증하는 역할을 한다.

---

3. Ai가 궤도를 벗어나지 않도록 로드맵 역할을 하며 스스로 검증할 수 있게 하여 요구사항 변경에 유연하게 대응할 수 있게 한다. 또한 비효울적으로 수천 줄을 한꺼번에 검토하는 대신 작업 단위별로 집중된 리뷰가 가능하다. 하지만 과도한 리뷰 부담과 통제감의 착각을 주면 환각현상이 발생할 수 있고, 과거의 개발자가 직접 개발하던 방식보다 비용이 크고 작은 작업에서는 오히려 오버헤드가 부담될 수 있다.

---

[JM-220]

SDD의 정의와 등장 배경을 설명해주세요.

spec driven development.
개발을 진행할 때, 어떤 기능을 구현하거나 수정했을 때, 구현을 먼저하고 문서화를 나중에 하면(swagger 나 postman 같은거 사용해서) 해당 기능 개발자를 제외한 나머지 작업에 병목이 생길 수 있다. 만약 문서화를 먼저 하고 합의가 된 후에 작업을 하면, 문서화가 끝난 후 동시 작업을 진행할 수 있기 때문에 효율적이다. sdd는 ai 기반 코드 작성이 늘면서 더 중요성이 커진 개발 방식인데, 단순 프롬프트로 개발을 하면 ai의 환각에 의한 결과물이 나올 수도 있다. 따라서 이런 명세를 자세하게 작성하여 ai에게 정확하고 일관된 코드의 작성을 유도할 수 있다.

SDD의 핵심 원칙과 워크플로우를 설명해주세요.

핵심 원칙

1. 명세가 기준점이다 : 요구사항, 설계, 구현, 테스트가 하나의 명세를 기준으로 정렬됨.
2. 의도를 구현보다 먼저 명확히 한다 : 무엇을 만들지뿐 아니라 범위, 제약, 예외, 성공 조건까지 정의한다.
3. 모호함을 코드 작성 전에 제거한다 : “빠르게”, “적절하게” 같은 표현을 측정 가능한 조건으로 바꾼다.
4. 작고 추적 가능한 단위로 작업한다 : 각 요구사항이 설계 결정, 코드 변경, 테스트 결과로 연결되어야 한다.
5. 검증 가능해야 한다 : 모든 중요 요구사항에는 대응하는 인수 조건이나 테스트가 있어야 한다.
6. 명세도 코드처럼 관리한다 : 버전 관리, 리뷰, 변경 이력, 영향 분석의 대상이다.
7. 구현과 명세의 불일치를 방치하지 않는다 : 요구가 바뀌면 명세부터 갱신하고 구현과 테스트를 동기화한다.

워크플로우

• 요구 확인
  • ㄴ> 명세 작성
    • ㄴ> 명세 검토·질문·합의
      • ㄴ> 기술 설계
        • ㄴ> 작업 단위로 분해
          • ㄴ> 테스트와 구현
            • ㄴ> 명세 기준 검증
              • ㄴ> 문서·명세 동기화

SDD의 장점과 한계를 설명해주세요.

장점

위의 sdd 의 특징에서 장점들을 생각해볼 수 있는데

• 요구사항의 모호함 감소
• 이해관계자 간 합의가 쉬움
• 구현 품질과 일관성 향상
• 테스트와 검증이 명확함
• ai 기반 개발에 효과적
• 인수인계와 유지보수에 유리

단점

단점은 장점보다 생각하기 어려울 것 같다

• 초기 작성 비용이 큼
• 잘못된 명세가 오류를 확대할 수 있음
• 변화가 잦은 환경에서는 유지 비용이 증가함
• 모든 상황을 사전에 정의하기 어려움(ex. UX)
• 명세와 코드가 달라질 수 있음

SDD 프레임워크 2~3개 정도를 간단하게 소개해주세요.

• GitHub Spec Kit
• OpenSpec
• Kiro Specs

[vvineey]

SDD는 무엇이며 어떻게 소프트웨어 개발을 명세 중심으로 바꾸는가?

SDD의 정의와 등장 배경

SDD란?

SDD(Spec-Driven Development)는 코드를 작성하기 전에 요구사항과 제약 조건을 명확한 명세로 만들고 그 명세를 기준으로 설계, 작업, 코드, 테스트를 생성하고 검증하는 개발 방식이다.

-> 일단 코드를 만들고 문서화하는게 아니라 쿠엇을 만들어햐 하는지 먼저 합의하고 그 명세에 따라 코드를 만드는 것이다. 전통적인 개발에서는 요구사항 문서가 구현을 위한 참고 자료로 사용되다가, 개발이 시작되면 코드가 사실상의 기준이 된느 경우가 많았다. SDD는 명세가 코드를 보조하는 것이 아니라 코드가 명세를 구현하는 방향이다.

등장 배경 1: 문서와 코드의 불일치

구현이 변경될 떄 문서가 함께 갱신되지 않으면 요구사항에는 있지만 코드에는 없는 문제, 코드에는 있지만 문서화되지 않은 동작, 변경된 요구사항이 테스트에 반영되지 않는 문제 등등이 발생힘 -> SDD는 일회성 문서가 아닌 지속적으로 관리하는 핵심 산출물로 취급하여 불일치를 줄인다.

등장 배경 2: 모호한 요구사항

기획자, 개발자, 사용자가 요구사항을 서로 다르게 이해하면 기술적으로 완성된 코드를 작성해도 잘못된 서비스가 만들어질 수 있다.
SDD는 구현을 시작하기 전에

• 기능의 범위
• 완료 조건
• 예외 상황
• 성능과 보안 요구사항
• 이번 작업에서 제외되는 범위 등
  을 명확하게 하고 수정 비용이 큰 구현 단계에 들어가기 전에 요구사항의 오류를 찾는 것이 목적이다.

등장 배경 3: AI 코딩 에이전트의 확산

AI에게 모호한 문장을 주고 코드를 작성하게 하면 AI는 누락된 내용을 스스로 추측한다.
따라서 SDD는 AI에게 단순한 채팅 기록 대신 구조화된 요구사항, 기술 설계, 작업 목록을 제공하므로서 AI를 단순한 코드 생성기가 아니라 명세를 분석하고 구현하는 협업 도구로 활용하게 한다.

SDD의 핵심 원칙과 워크플로우

핵심 워칙 1: 명세가 기준 정보이다.

SDD에서는 요구사항과 구현이 충돌할 때 판단이 되는 자료가 명세이다.
기능이 변경되면 코드만 수정하는게 아니라

1. 요구사항 명세를 수정함
2. 영향을 받는 기술 설계를 확인함
3. 구현 작업과 테스트를 수정함
4. 코드를 변경함
   의 순서로 변경한다.

핵심 원칙 2: 완료 조건을 검증할 수 있어야 한다.

명세에는 무엇을 만들 것인지뿐 아니라 언제 완성됐다고 판단할 것인지를 포함한다.
예를 들어 “검색이 빨라야 한다”는 요구사항은 검증하기 어렵다.
“상품 10만 건에서 검색 요청의 95%가 500ms 이내에 완료되어야 한다”처럼 작성해야 실제 테스트가 가능하다.

핵심 원칙 3: 요구사항부터 테스트까지 추적할 수 있어야 한다.

요구사항
  ↓
인수 조건
  ↓
기술 설계
  ↓
구현 작업
  ↓
코드와 테스트

특정 요구사항이 변경됐을 때 영향을 받는 설계, 작업, 코드와 테스트를 찾을 수 있어야 한다.
이러한 연결을 요구사항 추적성이라고 한다.

핵심 원칙 4: 명세와 구현을 반복적으로 개선하고 검증한다.

SDD는 처음부터 완벽한 문서를 작성하고 그대로 구현하는 폭포수 방식이 아니다. 구현 중 새로운 기술적 제약이 발견되거나 사용자 피드백이 들어오면 명세를 수정할 수 있다. 이때 변경 내용을 채팅이나 개인의 기억이만 남지기 않고 명세에도 반영해야 한다.
또한 코드 리뷰뿐 아니라 명세 리뷰를 통해 명세 자체에 누락, 모순이 없는지, 구현과 테스트가 실제 명세에 만족하는지 등을 검증해야 한다.

핵심 원칙 5: 중요한 판단은 사람이 승인한다.

• AI가 요구사항, 설계, 작업 목록을 생성하더라도 다음 항목은 사람이 검토해야 한다.
• 실제 사용자의 요구를 정확히 반영했는가?
• 보안과 개인정보 보호 조건이 충분한가?
• 아키텍처가 운영 환경에 적합한가?
• 생성된 테스트가 핵심 요구사항을 검증하는가?
• 명세 자체에 잘못된 가정이 없는가?

워크플로우

• 1단계: 문제와 의도 정의
• 2단계: 요구사항 명세 작성
• 3단계: 명세 검토와 명확화
• 4단계: 기술 설계 작성
• 5단계: 작업 분해
• 6단계: 구현과 테스트
• 7단계: 일관성 검증
• 8단계: 변경 관리

SDD의 장점과 한계

장점

장점	설명
요구사항 명확화	구현 전에 모호함, 충돌, 누락을 발견할 수 있다.
예측 가능한 AI 활용	AI가 추측하지 않고 구조화된 명세를 기준으로 작업한다.
추적성	요구사항이 어떤 설계, 작업, 코드와 테스트로 이어졌는지 확인할 수 있다.
검토 가능성	코드를 작성하기 전에 요구사항과 아키텍처를 팀이 검토할 수 있다.
컨텍스트 유지	대화나 담당자가 바뀌어도 명세를 통해 개발 의도를 전달할 수 있다.
유지보수성	기술 선택과 설계 이유가 남아 변경 영향 분석에 도움이 된다.
테스트 설계	구체적인 인수 조건을 테스트 케이스로 변환하기 쉽다.
협업	합의된 인터페이스와 작업 경계를 바탕으로 업무를 나눌 수 있다.

한계

한계	설명
초기 비용	코딩 전에 명세를 작성하고 검토하는 시간이 필요하다.
명세 품질 의존	잘못된 명세를 정확하게 구현하면 결과도 정확하게 잘못된다.
동기화 비용	코드 변경 시 명세를 함께 수정하지 않으면 다시 불일치가 발생한다.
과도한 형식화	모든 결정을 미리 고정하면 실험과 탐색이 어려워질 수 있다.
AI의 허위 완전성	AI가 만든 상세한 문서가 완전하고 정확하다는 착각을 줄 수 있다.
도구 종속성	특정 IDE, 명령어와 디렉터리 구조에 워크플로우가 묶일 수 있다.
검증의 어려움	성능과 보안 요구사항은 문서화만으로 보장되지 않는다.
기존 프로젝트 적용	레거시 시스템은 현재 동작을 명세로 복원하는 작업부터 필요하다.

대표적인 SDD 프레임 워크

1. GitHub Spec Kit

GitHub가 공개한 오픈소스 SDD 툴킷이다. 여러 AI 코딩 에이전트와 함께 사용할 수 있다.

2. Kiro Specs

Kiro는 AWS가 개발한 AI 개발 환경이다. IDE, CLI와 웹에서 명세 기반 개발 흐름을 제공한다.

3. OpenSpec

OpenSpec은 여러 AI 코딩 도구와 함께 사용할 수 있는 비교적 가벼운 오픈소스 SDD 프레임워크다.

비교

구분	GitHub Spec Kit	Kiro Specs	OpenSpec
형태	오픈소스 툴킷·CLI	통합 AI 개발 환경	경량 오픈소스 CLI
기본 흐름	Spec → Plan → Tasks → Implement	Requirements → Design → Tasks → Execute	Propose → Apply → Verify → Archive
핵심 특징	체계적인 단계와 프로젝트 원칙	계획부터 구현까지 개발 환경에 통합	변경 단위 관리와 유연한 반복
적합한 경우	명확한 절차와 거버넌스가 필요할 때	하나의 환경에서 전체 과정을 진행할 때	기존 도구를 유지하며 가볍게 도입할 때
주의점	작은 작업에는 무거울 수 있음	도구 종속성이 상대적으로 큼	팀별 규칙을 직접 정해야 함