스펙 기반 개발(Spec-Driven Development)이란 무엇인가? 스펙을 진리의 원천(Source of Truth)으로

사이드 문서가 아닌, 스펙을 단일 진실 공급원(Single Source of Truth)으로 활용하세요.

Page content

명세 기반 개발(Spec-Driven Development, 이하 SDD)은 소프트웨어 엔지니어들이 한때 시도했다가 노력이 보상으로 돌아오지 않자 접했던 아이디어 중 하나입니다.

2025년에 변한 것은 AI 코딩 에이전트의 등장으로 인해 명시적인 의도(intent)의 부재가 치명적인 비용으로 작용하게 되었다는 점입니다. 프롬프트는 일시적입니다. 에이전트 세션은 리셋됩니다. 코드는 변경되지만 그 뒤에 숨겨진 추론 과정은 사라집니다. 명세가 바로 이러한 상황을 방지하는 아티팩트(artifact)입니다.

What Is Spec-Driven Development – the spec as source of truth for AI coding

명세는 진실의 원천(Source of Truth)이 되고 있다

소프트웨어 개발 역사的大部分 동안 명세는 임시적인 계획 아티팩트이거나 사후thought(사후 고찰)에 불과했습니다. 요구사항은 티켓(ticket)에, 설계 결정은 채팅 스레드에 존재했으며, 코드가 곧 유일한 진실(ground truth)이었습니다. 문서화는 사후에 존재하는 시스템을 설명하는 역할을 했죠.

명세 기반 개발은 이러한 관계를 반전시킵니다. 명세가 주된 아티팩트가 됩니다. 코드는 명세에 따라 생성되거나 검증되는 대상이지, 그 반대는 아닙니다.

이는 새로운 아이디어가 아닙니다. 포멀 메서드(Formal Methods), 계약 중심 설계(Design-by-Contract), BDD(Behavior-Driven Development) 등에는 이와 유사한 버전들이 존재해 왔습니다. 새로운 것은 실용적인 동기입니다: AI 코딩 에이전트는 정확하고 일관된 출력을 생성하기 위해 명시적이고 지속 가능한 컨텍스트가 필요합니다. 프롬프트는 너무 일시적입니다. 명세만이 에이전트 세션, 팀원, 그리고 시간을 가로질러 의도를 전달할 수 있는 유일한 아티팩트입니다.

명세 기반 개발의 실제 의미

명세 기반 개발(SDD)은 버전 관리된 명세가 구현을 안내하거나 생성하는 워크플로우입니다. 에이전트가 코드를 작성하기 전에 명세가 작성되고 리뷰됩니다. 명세는 다음을 포착합니다:

  • 무엇을 구축할 것인가 – 사용자 문제, 목표, 비목표(non-goals)
  • 올바른 동작의 모습 – 수용 기준(acceptance criteria), 엣지 케이스, 에러 상태
  • 어떻게 구축할 것인가 – 아키텍처 결정, 데이터 모델, API 계약, 보안 제약 조건
  • 어떻게 검증할 것인가 – 테스트 전략, 유효성 검사 규칙, 요구사항으로의 추적 가능성

명세는 일회성 문서가 아닙니다. 현실이 설계와 다를 때 업데이트됩니다. 에이전트가 구현 과정에서 명세가 잘못 포착한 것을 발견하면, 계속 진행하기 전에 명세가 수정됩니다. 명세는 코드처럼 취급되어 진실성을 유지합니다.

최근 학술 연구는 이 프레임워크를 형식화합니다: 연구자들은 SDD를 명세를 진실의 원천으로, 코드를 이에 기반하여 생성되거나 검증되는 것으로 취급하는 방식이라고 설명합니다. 실용적인 해석은 명세가 인간이나 AI 도구가 읽고 신뢰할 수 있는 의도의 검증된, 내구성 있는 기록이라는 것입니다.

다음 세 가지 용어는 명세 사용 스펙트럼의 다양한 지점을 포착합니다:

**명세 우선(Spec-first)**은 구현이 시작되기 전에 전체 명세를 작성하는 것을 의미합니다. 이는 가장 엄격한 해석이며, 주의 깊게 수행되지 않으면 폭포수 모델(waterfall)에 가장 가깝습니다.

**명세 고정(Spec-anchored)**은 기능 라이프사이클 전반에 걸쳐 명세를 구현과 동기화하여 유지하는 것을 의미합니다. 결정이 변경될 때 명세가 업데이트됩니다. 이는 대부분의 팀에게 가장 실용적인 버전입니다.

**명세를 원천으로(Spec-as-source)**는 명세에서 구현을 생성하거나 검증하는 것을 의미하며, 이는 AI 에이전트 또는 코드를 명세 제약 조건에 대해 검사하는 도구화를 통해 이루어집니다. GitHub Spec Kit 및 Kiro와 같은 도구들이 나아가고 있는 방향입니다.

왜 지금 SDD가 중요한가

솔직한 답변은 SDD가 하루짜리 스크립트를 구축하는 솔로 개발자에게는 설득력이 없다는 것입니다. 오버헤드가 그만한 가치가 없습니다.

SDD는 세 가지 조건이 충족될 때 가치가 있습니다: 기능이 여러 세션에 걸쳐 충분히 큰 경우, 에이전트가 아키텍처에 영향을 미치는 결정을 내려야 하는 경우, 그리고 작업이 다른 사람에 의해 리뷰되거나 계속될 경우입니다.

이 세 가지 조건은 AI 지원 개발에서 점점 더 흔해지고 있습니다.

LLM은 프롬프트가 아닌 컨텍스트가 필요합니다. 모호한 프롬프트를 받는 모델은 모호한 결정을 내립니다. 명시적인 제약 조건, 비목표, 수용 기준이 포함된 검증된 명세를 받는 모델은 더 나은 결정을 내리며, 이탈 시 수정하기가 더 쉽습니다. 이는 검색과 표현이 작동하는 방식과 연결됩니다: 에이전트에 버전 관리된 명세를 제공하는 것은 프로젝트 의도의 구조화된 검색 형태입니다.

코드 생성은 저렴하지만, 무엇을 구축할지 결정하는 것은 여전히 어렵습니다. AI 지원 개발의 병목 현상은 더 이상 타이핑이 아닙니다. 무엇을 구축해야 하는지, 에이전트를 어떻게 제한해야 하는지를 아는 것입니다. SDD는 노력이 중요한 곳으로 이동을 합니다: 생성이 시작되기 전에 의도를 명확하게 명시하는 것입니다.

프롬프트는 일시적입니다. 에이전트는 마지막 세션에서 알려준 것을 기억하지 못합니다. 저장소에 저장된 버전 관리된 명세는 기억합니다. 각 새 세션은 동일한 명세를 읽고 컨텍스트를 처음부터 재설정하지 않고 동일한 의도에 따라 구현할 수 있습니다.

바이브 코딩은 작동하다가 멈춥니다. 프로토타입과 일회성 작업의 경우, 즉흥적인 프롬프팅이 더 빠르고 적절합니다. 그러나 기능이 보안 제약 조건, 다중 파일 아키텍처 결정, 또는 팀 인계(handoff)를 필요로 하는 순간, 명세의 부재가 이탈과 결함의 주요 원인이 됩니다. 각 접근 방식이 적용되는 시기에 대해서는 SDD vs 바이브 코딩의 비교를 참조하십시오.

핵심 아티팩트

실용적인 SDD 워크플로우는 네 가지 주요 아티팩트를 생성합니다. 각각은 에이전트가 처리하기 전에 특정 유형의 모호성을 줄입니다.

요구사항 명세. 문제 진술, 영향받는 사용자, 목표, 명시적인 비목표, 그리고 수용 기준을 포함합니다. 비목표는 목표만큼 중요합니다 – 이는 에이전트가 무엇을 구축하지 않아야 하는지를 알려주고 범위 팽창(scope creep)을 방지합니다. 수용 기준은 각 기준이 적어도 하나의 테스트로 매핑될 만큼 정확해야 합니다.

설계 명세. 이 기능과 관련된 아키텍처 결정: 영향받는 모듈, 데이터 모델 변경, API 계약, 마이그레이션, 보안 제약 조건, 관측 가능성 요구사항, 그리고 알려진 실패 모드를 포함합니다. 이는 전체 시스템 설계 문서가 아닙니다 – 이 기능을 올바르게 구현하는 데 필요한 아키텍처 결정의 하위 집합입니다.

태스크 계획. 명시적인 의존성, 예상 파일 변경 사항, 검증 기준을 가진 작은 구현 태스크의 시퀀스입니다. 태스크는 단일 에이전트 세션에서 구현하고 집중된 diff로 검증할 수 있을 만큼 작아야 합니다. 각 태스크에는 인간 리뷰 체크포인트가 있습니다.

추적 가능성 기록(Traceability record). 수용 기준에서 테스트로, 설계 결정에서 영향받는 파일로, 그리고 태스크에서 커밋으로의 매핑입니다. 이는 SDD를陈腐해지(documentation that becomes stale)는 문서화에서 구분하는 것입니다. 추적 가능성은 명세가 단순히 작성된 것을 넘어 실제로 구현되었음을 검증할 수 있게 해줍니다.

이러한 아티팩트는 무거울 필요가 없습니다. 간단한 기능은 네 가지 영역을 모두 다루는 단 하나의 2페이지 마크다운 문서를 생성할 수 있습니다. 형식보다 구현이 시작되기 전에 의도를 작성하는 습관이 더 중요합니다.

SDD와 문서화의 차이

가장 흔한 오해는 SDD 아티팩트를 문서화로 취급하는 것입니다. 그것들은 전통적인 의미의 문서화가 아닙니다.

문서화는 설명합니다. 시스템이 무엇을 하는지, 어떻게 사용하는지, 무엇을 포함하는지 알려줍니다. 사후에 작성되며 시스템이 변경될 때 업데이트됩니다.

명세는 제약합니다. 명세는 에이전트가 구축할 수 있는 것과 할 수 없는 것을 알려줍니다. 구현 시작 전에 권위 있습니다. 구현 완료 후 검증됩니다. 실제로 구축된 것을 설명하는 명세 – 구축되어야 할 것을 제약하는 것이 아닌 – 는 이미 그 목적을 실패한 것입니다.

실행 가능한 명세는 생성과 검증을 안내합니다. 최고의 SDD 명세는 에이전트가 이에 따라 구현하고 테스트 스위트가 검증할 수 있을 만큼 기계 판독 가능(machine-readable)에 가깝습니다. “엔드포인트는 인증되지 않은 요청을 401 응답으로 거부해야 한다"는 수용 기준은 실행 가능한 명세입니다. 반면 “엔드포인트는 보안이 적용되어 있다"는 것은 문서화입니다.

결정 기록 – ADR, PDR, DDR – 은 SDD 아티팩트와 보완적이지만 다른 목적을 수행합니다. 결정 기록은 왜 선택이 이루어졌고 무엇이 거부되었는지를 포착합니다. SDD 명세는 무엇을 구축할지와 어떻게 검증할지를 포착합니다. 둘 다 저장소에 속합니다. 함께 사용하면 AI 에이전트는 현재 의도와 그 뒤에 숨겨진 추론 과정을 완전히 파악할 수 있습니다.

SDD와 TDD의 차이

테스트 주도 개발(TDD)과 명세 기반 개발(SDD)은 둘 다 코드가 존재하기 전에 명시적인 아티팩트를 생성하기 때문에 종종 혼동됩니다. 차이점은 시작점입니다.

TDD는 테스트로 시작합니다. 원하는 동작을 설명하는 실패하는 테스트를 작성한 다음, 이를 통과하기 위한 최소한의 코드를 작성합니다. TDD는 유닛 레벨에서의 피드백 루프입니다. 이는 좋은 테스트를 생성하지만, 올바른 것을 구축하고 있는지에 대한 질문에 답하지는 않습니다.

SDD는 의도로 시작합니다. 테스트가 존재하기 전, 아키텍처가 결정되기 전, 명세가 다음을 답합니다: 누구에게 이 문제가 있는지, 올바른 동작의 모습은 무엇인지, 명시적으로 범위 밖인 것은 무엇인지. 명세는 어떤 테스트를 작성할지 알려주기 때문에, 좋은 SDD와 좋은 TDD는 경쟁 관계가 아니라 보완 관계입니다.

이를 실용적으로 생각하는 방법: SDD가 TDD를 주도합니다. 명세의 수용 기준이 테스트 시나리오가 됩니다. 설계 명세는 계약 테스트가 필요한 통합 경계를 식별합니다. 태스크 계획은 에이전트가 구현하기 전에 테스트 커버리지가 필요한 유닛 동작을 식별합니다.

SDD와 BDD의 차이

행위 기반 개발(BDD)은 자연어 시나리오 – 일반적으로 Gherkin 형식 – 를 사용하여 사용자 관점에서 예상되는 동작을 설명합니다. 이러한 시나리오는 비즈니스 의도와 기술적 구현 사이의 격차를 해소합니다.

SDD는 더 광범위합니다. 행위 설명(BDD 스타일 언어 또는 일반 산문을 사용 가능)을 포함하지만, 아키텍처 결정, 데이터 모델, 보안 제약 조건, 태스크 계획, 추적 가능성도 다룹니다. BDD는 SDD 요구사항 명세 내에서 수용 기준을 작성하는 유용한 형식이 될 수 있습니다. 명세는 컨테이너이며, BDD 시나리오는 그 안에 들어가는 것을 작성하는 한 가지 방식입니다.

이 구분은 실습에서 중요합니다: BDD 도구는 시나리오를 실행 가능하게 만드는 데 초점을 맞춥니다. SDD 관행은 도구, 세션, 팀원을 가로질러 의도를 내구성 있게 만드는 데 초점을 맞춥니다.

SDD와 포멀 메서드의 차이

포멀 메서드는 수학적 표기법과 자동화된 검증을 사용하여 소프트웨어 시스템의 속성을 증명합니다. 이는 매우 엄격하며 대부분의 프로덕션 개발 환경에서는 매우 비용이 많이 듭니다.

SDD는 형식적 표기법을 요구하지 않습니다. 수용 기준과 아키텍처 결정이 포함된 마크다운 파일도 명세입니다. 이는 수학적으로 형식적이지는 않지만 제약합니다. 엄격성의 수준은 위험도에 비례합니다: 청구 서비스(billing service)의 명세는 문서화 페이지의 명세보다 더 정확하고 신중하게 검토되어야 합니다.

관계는 스펙트럼입니다:

  • 비공식적 산문 명세(최소 생존 SDD)
  • 수용 기준과 비목표가 있는 구조화된 마크다운
  • 스키마 유효성 검사가 있는 기계 판독 가능 명세
  • 명세에서 직접 파생된 계약 테스트
  • 자동화된 증명이 있는 형식적 명세

대부분의 팀은 이 스펙트럼의 중간에서 운영됩니다. 목표는 수학적 엄격성이 아닙니다 – AI 에이전트가 이에 따라 구현하고 인간 리뷰어가 결과를 검증할 수 있을 만큼 의도를 명시적으로 만드는 것입니다.

명세 기반 개발의 이점

의도 이탈 감소. 명세가 기준입니다. 에이전트가 이탈할 때 – 그리고 이탈할 것입니다 – 리뷰어는 구현을 비교할 기준이 있습니다. 명세가 없으면 이탈은 무언가가 깨질 때까지 보이지 않습니다.

더 나은 AI 출력. 명시적인 제약 조건, 비목표, 수용 기준을 주어진 에이전트는 의도대로 더 가까운 구현을 생성하며, 놓쳤을 때 수정하기 쉽습니다. 컨텍스트 품질이 출력 품질을 직접 결정합니다.

쉬운 리뷰. 명세에 연결된 풀 리퀘스트는 코드에서 의도를 재구성해야 하는 풀 리퀘스트보다 리뷰하기 쉽습니다. 명세가 리뷰 체크리스트입니다.

팀 정렬. 여러 사람 또는 에이전트가 동일한 기능에 작업할 때, 명세가 공유 계약입니다. 없으면 각 기여자가 로컬로 최적화하고 조각들이 맞지 않을 수 있습니다.

더 나은 테스트 계획. 명세의 수용 기준은 테스트 케이스로 직접 매핑됩니다. 테스트 커버리지는 명세 커버리지 질문이 됩니다: 모든 수용 기준이 적어도 하나의 테스트로 커버되고 있는가?

내구성 있는 인계. 기능이 인계될 때 – 엔지니어 사이, 에이전트 세션 사이, 스프린트 사이 – 명세가 인계 아티팩트입니다. 이는 결정된 것, 범위 밖인 것, 그리고 검증되어야 하는 것을 포착합니다.

명세 기반 개발의 비용

선행 노력. 어떤 코드도 작성하기 전에 좋은 명세를 작성하는 데 시간이 걸립니다. 작은 기능의 경우, 이 오버헤드는 현실적이며 때로는 그만한 가치가 없을 수 있습니다.

거짓 자신감. 존재하지만 구현에 대해 검증되지 않은 명세는 잘못된 정확성에 대한 느낌을 줍니다.陈腐한 명세는 때로는 명세가 없는 것보다 더 나쁩니다: 리뷰어와 이를 읽는 에이전트를 오도합니다.

陈腐한 명세. 팀이 명세를 계획 아티팩트而非 living document로 취급할 때 명세는 이탈합니다. 구현이 설계와 다를 때 명세를 업데이트하는 것은 선택 사항이 아닙니다 – 이는 SDD를陈腐해지고 썩는 문서화에서 구분하는 것입니다.

생성된 관료제. AI 에이전트는 포괄적인 태스크 목록과 장황한 명세를 빠르게 생성할 수 있습니다. 30초 만에 생성된 200개 태스크 명세는 유용한 명세가 아닙니다 – 이는 관료제 생성기입니다. 좋은 SDD는 무엇을 명시할지와 무엇을 암묵적으로 남길지에 대한 판단이 필요합니다.

도구 잠금. 일부 SDD 도구는 형식, 파일 구조, 워크플로우에 대해 의견이 있습니다. 독점적 형식으로 작성된 명세는 명확한 헤더와 수용 기준이 있는 마크다운 파일보다 도구 간 이동이 어렵습니다.

결론

명세 기반 개발은 새로운 방법론이 아닙니다. 이는 AI 생성 코드에서 암묵적 의도의 비용이 이제 가시화되었기 때문에 실용적이 된 오래된 дисциплина입니다.

이 дисциплина는 간단합니다: 에이전트가 구축하기 전에 구축하려는 의도를 작성하고, 검증하고, 버전 관리하십시오. 현실이 다를 때 이를 업데이트하여 기록의 진실성을 유지하십시오. 이를 리뷰, 테스트, 인계를 위한 기준으로 사용하십시오.

명세는 마법이 아닙니다. 검증되지 않은 명세는 가장 비용이 많이 드는 유형의 문서화가 됩니다: 자신감 있게 오도하는 문서화. 좋은 SDD는 명세를 진실하게 유지하는 관행입니다 – 유지할 수 있을 만큼 작고, 제약할 수 있을 만큼 정확하며, 단일 에이전트 세션을 넘어서 지속될 수 있을 만큼 내구성 있는.

SDD는 문서화 관행, 테스트 아키텍처, 코드 설계의 교차점에 위치하며 – 이는 결정 기록, API 설계, 데이터 접근 패턴과 함께 프로덕션에서의 앱 아키텍처 클러스터에서 다뤄집니다.

유용한 링크

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.