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

사이드 문서가 아닌, 명세를 진실의 원천으로

Page content

스펙 주도 개발(Spec-Driven Development, SDD)은 소프트웨어 엔지니어들이 과거에 시도했다가 노력 대비 효과가 떨어지자 포기했던 아이디어들 중 하나입니다.

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

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

스펙이 진실의 원천(Source of Truth)이 되고 있다

소프트웨어 개발 역사의 대부분에서 스펙은 일시적인 계획 아티팩트이거나 사후에 고려되는 요소에 불과했습니다. 요구사항은 티켓(tickets)에, 설계 결정은 채팅 스레드에 존재했으며, 코드가 그라운드 트루(ground truth)였습니다. 문서화는 사후에 존재하는 시스템을 설명하는 역할만 했죠.

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

이는 새로운 아이디어가 아닙니다. 형식적 방법(formal methods), 계약 설계(design-by-contract), BDD(behavior-driven development) 모두 이와 유사한 개념을 포함하고 있습니다. 새로운 점은 실용적인 동기입니다: AI 코딩 에이전트는 정확하고 일관된 출력을 생성하기 위해 명시적이고 지속 가능한 컨텍스트가 필요합니다. 프롬프트는 너무 일시적입니다. 스펙은 에이전트 세션, 팀원, 그리고 시간을 가로질러 의도를 전달할 수 있는 유일한 아티팩트입니다.

스펙 주도 개발의 실제 의미

보통 SDD로 약칭되는 스펙 주도 개발은 버전 관리된 스펙이 구현을 안내하거나 생성하는 워크플로우입니다. 에이전트가 코드를 작성하기 전에 스펙이 작성되고 리뷰됩니다. 스펙은 다음을 포착합니다:

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

마지막 항목은 쓰기 쉽지만 실제에서는 쉽게 건너뛰기 쉽습니다. AI 개발에서 스펙, 테스트, 코드의 동기화 유지는 요구사항으로의 추적 가능성이 데이터로 어떤 의미를 갖는지 설명합니다: 요구사항 ID, 설계 결정 ID, 그리고 구현한 풀 리퀘스트(pull requests)와 연결된 테스트들.

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

최근 학술 연구는 이 프레임워크를 공식화했습니다: 연구자들은 SDD를 스펙을 진실의 원천으로 취급하고 코드를 이에 대해 생성하거나 검증하는 방법으로 설명합니다. 실용적인 해석은 스펙이 인간이나 AI 도구가 읽고 신뢰할 수 있는 의도의 검토된, 지속 가능한 기록이라는 것입니다.

세 가지 용어가 스펙 사용 스펙트럼의 다른 지점을 포착합니다:

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

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

**Spec-as-source(스펙 원천)**는 스펙에서 구현을 생성하거나 검증하는 것을 의미하며, 이는 AI 에이전트나 스펙 제약 조건에 대해 코드를 확인하는 툴링을 통해 이루어집니다. 이는 GitHub Spec Kit 및 Kiro와 같은 툴들이 이동하고 있는 방향이며, 각 툴은 포터성과 통합 IDE 가이드 사이의 상충 관계(tradeoff)가 다릅니다.

왜 지금 SDD가 중요한가

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

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

이 세 가지 조건은 AI 보조 개발 환경에서 점점 더 일반화되고 있습니다.

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

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

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

**Vibe 코딩은 버려도 되는 작업에는 더 빠릅니다; SDD vs Vibe 코딩은 언제 스펙을 추가하고 언제 자유롭게 프롬프팅을 유지해야 하는지 다룹니다.

핵심 아티팩트

SDD는 네 가지 아티팩트 유형을 생성합니다. 각각은 에이전트가 코드에 접근하기 전에 다른 유형의 모호성을 줄입니다:

  • 요구사항 스펙 – 문제, 사용자, 목표, 비목표, 수용 기준
  • 설계 스펙 – 이 기능의 아키텍처, 데이터 모델, API 계약, 보안 제약
  • 작업 계획 – 종속성과 검증 기준이 있는 작은 구현 조각들
  • 추적 가능성 기록 – 수용 기준에서 테스트로, 설계 결정에서 파일로, 작업에서 커밋으로 매핑

이를 단계별로(스펙 작성, 계획, 작업, 구현, 검증) 어떻게 생성하고 리뷰할지는 요구사항에서 코드로의 스펙 주도 개발 워크플로우에서 다룹니다. 간단한 기능은 짧은 마크다운 파일에서 네 가지 영역을 모두 다룰 수 있습니다. 형식보다 습관이 더 중요합니다.

SDD가 문서화와 어떻게 다른가

가장 흔한 오해는 SDD 아티팩트를 문서화로 취급하는 것입니다. 이는 일반적인 의미의 문서화가 아닙니다.

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

스펙은 제약합니다. 스펙은 에이전트가 빌드할 수 있는 것과 할 수 없는 것을 알려줍니다. 구현 시작 전에 권위 있으며, 구현 완료 후 검증됩니다. 실제로 빌드된 것을 설명하는 스펙(빌드해야 할 것을 제약하는 것이 아닌)은 이미 그 목적을 실패한 것입니다.

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

결정 기록 – ADR, PDR, DDR – 은 SDD 아티팩트와 보완적이지만 다른 목적을 수행합니다. 결정 기록은 왜 특정 선택이 이루어졌고 무엇을 거부했는지를 포착합니다. SDD 스펙은 무엇을 빌드할지, 어떻게 검증할지를 포착합니다. 둘 다 저장소에 포함되어야 합니다. 함께 사용되면 AI 에이전트는 현재 의도와 그背後의 추론을 모두 제공합니다.

SDD가 TDD와 어떻게 다른가

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

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

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

실용적인 사고 방식: SDD가 TDD를 주도합니다. 스펙의 수용 기준이 테스트 시나리오가 됩니다. 설계 스펙은 계약 테스트가 필요한 통합 경계를 식별합니다. 작업 계획은 에이전트가 구현하기 전에 테스트 커버지가 필요한 유닛 동작을 식별합니다.

SDD가 BDD와 어떻게 다른가

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

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

이 구별은 실제에서 중요합니다: BDD 툴링은 시나리오를 실행 가능하게 만드는 데 초점을 맞춥니다. SDD 관행은 의도를 지속 가능하게 만드는 데 초점을 맞춥니다 – 툴을 넘어, 세션을 넘어, 팀원을 넘어.

SDD가 형식적 방법(Formal Methods)과 어떻게 다른가

형식적 방법은 수학적 표기법과 자동 검증을 사용하여 소프트웨어 시스템의 속성을 증명합니다. 이는 매우 엄격하며 대부분의 프로덕션 개발 컨텍스트에서 매우 비용이 많이 듭니다.

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

관계는 스펙트럼입니다:

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

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

스펙 주도 개발의 이점

의도 이탈(Intent drift) 감소. 스펙이 기준(reference)입니다. 에이전트가 이탈하면 – 그리고 이탈할 것입니다 – 리뷰어는 구현을 비교할什么东西가 있습니다. 스펙이 없으면, 무언가가 깨질 때까지 이탈은 눈에 띄지 않습니다.

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

더 쉬운 리뷰. 스펙에 첨부된 풀 리퀘스트는 코드에서 의도를 재구성해야 하는 풀 리퀘스트보다 리뷰하기 쉽습니다. 슐이 리뷰 체크리스트입니다.

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

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

지속 가능한 인계(Handoff). 기능이 인계될 때 – 엔지니어 사이, 에이전트 세션 사이, 스프린트 사이 – 슐이 인계 아티팩트입니다. 무엇을 결정했는지, 무엇이 범위 밖이었는지, 무엇이 아직 검증되어야 하는지를 포착합니다.

슐 주도 개발의 비용

초기 노력. 어떤 코드도 작성하기 전에 좋은 슐을 작성하는 데 시간이 걸립니다. 작은 기능의 경우, 이 오버헤드는 실제이며 때로는 가치 있지 않을 수 있습니다.

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

오래된 슐. 팀이 슐을 계획 아티팩트而非 living document로 취급할 때 슐은 이탈합니다. 구현이 설계와 다를 때 슐을 업데이트하는 것은 선택 사항이 아닙니다 – 이것이 SDD를 축적되고 썩어가는 문서화에서 구별하는 것입니다.

생성된 관료제. AI 에이전트는 철저한 작업 목록과 장황한 슐을 빠르게 생성할 수 있습니다. 30초 만에 생성된 200개 작업 슐은 유용한 슐이 아닙니다 – 그것은 관료제 생성기입니다. 좋은 SDD는 무엇을 슐로 정의하고 무엇을 암시적으로 남길지에 대한 판단이 필요합니다.

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

결론

스펙 주도 개발은 새로운 방법론이 아닙니다. AI 생성 코드에서 암묵적 의도의 비용이 이제 가시화되면서 실용적이 된 오래된 규율입니다.

규율은 간단합니다: 에이전트가 빌드하기 전에 빌드하려는 것을 기록하고, 검토하고, 버전 관리하십시오. 현실이 다를 때 이를 업데이트하여 그 기록의 정직성을 유지하십시오. 이를 리뷰, 테스트, 인계의 기준으로 사용하십시오.

스펙은 마법이 아닙니다. 검증되지 않은 슐은 가장 비싼 종류의 문서화가 됩니다: 확신에 차서 오도하는 것. 좋은 SDD는 슐을 정직하게 유지하는 관행입니다 – 유지하기에 충분히 작고, 제약하기에 충분히 정확하며, 단일 에이전트 세션을 넘겨 지속하기에 충분히 견고해야 합니다.

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

유용한 링크

구독하기

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