스펙 기반 개발이란? 단일 정보원으로서의 스펙

사이드 문서가 아닌, 단일 진실 공급원으로서의 스펙

Page content

스펙 기반 개발(Spec-Driven Development)은 소프트웨어 엔지니어들이 과거에 시도했다가 노력이 더 이상 보상을 주지 못할 때 제쳐두었던 아이디어 중 하나입니다.

2025년에 변한 점은 AI 코딩 에이전트의 등장으로 인해 명시적인 의도의 부재가 비싸게 다가오게 되었다는 것입니다. 프롬프트는 일시적입니다. 에이전트 세션은 초기화됩니다. 코드는 변경되지만 그 이면의 추론은 사라집니다. 스펙은 이러한 일이 일어나지 않도록 막아주는 산출물입니다.

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

스펙은 진실의 원천이 되고 있다

소프트웨어 개발 역사 대부분에서 스펙은 일시적인 계획 산출물이거나 사후적으로 덧붙여진 것이었습니다. 요구사항은 티켓에, 설계 결정은 채팅 스레드에 존재했으며, 코드가 유일한 진실이었습니다. 문서화는 사후적으로 기존에 존재하는 것을 설명하는 역할을 했죠.

스펙 기반 개발(SDD)은 이 관계를 뒤집습니다. 스펙이 1차 산출물이 됩니다. 코드는 스펙에 따라 생성되거나 검증되는 대상이지, 그 반대는 아닙니다.

이것은 새로운 아이디어가 아닙니다. 형식 방법론(Formal methods), 계약에 의한 설계(Design-by-Contract), BDD(행위 주도 개발) 모두 이 개념의 변형을 포함하고 있습니다. 새로운 것은 실용적인 동기입니다: AI 코딩 에이전트는 정확하고 일관된 출력을 생성하기 위해 명시적이고 지속적인 컨텍스트가 필요합니다. 프롬프트는 너무 일시적입니다. 스펙은 에이전트 세션을 넘어, 팀원을 넘어, 시간을 넘어 의도를 전달할 수 있는 유일한 산출물입니다.

스펙 기반 개발이 실제로 의미하는 것

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

  • 무엇을 만들 것인가 – 사용자 문제, 목표, 비목표(non-goals)
  • 올바른 행동이 무엇인지 – 수용 기준, 예외 케이스, 오류 상태
  • 어떻게 만들 것인가 – 아키텍처 결정, 데이터 모델, API 계약, 보안 제약
  • 어떻게 검증할 것인가 – 테스트 전략, 검증 규칙, 요구사항으로의 추적성(Traceability)

마지막 항목은 쓰기에는 쉽지만 실제에서는 쉽게 건너뛸 수 있습니다. AI 개발에서 스펙, 테스트, 코드 동기화 유지하기는 요구사항으로의 추적성이 데이터로서 실제로 어떻게 보이는지(요구사항 ID, 설계 결정 ID, 구현된 풀 리퀘스트와 연결된 테스트)를 다룹니다.

스펙은 일회성 문서가 아닙니다. 현실이 설계와 다르면 업데이트됩니다. 에이전트가 구현 과정에서 스펙의 오류를 발견하면, 계속하기 전에 스펙이 수정됩니다. 스펙은 코드처럼 취급되기 때문에 항상 정확한 상태를 유지합니다.

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

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

Spec-first는 어떤 구현이 시작되기 전에 전체 스펙을 작성하는 것을 의미합니다. 이는 가장 엄격한 해석이며, 조심하지 않으면 폭포 방식(Waterfall)에 가장 가깝습니다.

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

Spec-as-source는 AI 에이전트를 통해 또는 코드가 스펙 제약 조건과 일치하는지 확인하는 도구를 통해 스펙으로부터 구현을 생성하거나 검증하는 것을 의미합니다. GitHub Spec Kit과 Kiro와 같은 도구가 이 방향으로 나아가고 있으며, 각각은 이식성과 통합 IDE 가이드 사이의 트레이드오프가 다릅니다. Superpowers와 같은 스킬 패키지는 스펙-앵커링(spec-anchored) 쪽에 더 가깝습니다 – 코드를 직접 생성하는 대신 검토 규율을 자동으로 강제합니다.

왜 지금 SDD가 중요한가

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

SDD는 세 가지 조건이 충족될 때 가치를 발휘합니다: 기능이 여러 세션을 아우를 정도로 충분히 크고, 에이전트가 아키텍처에 영향을 미치는 결정을 내려야 하며, 작업이 다른 사람에 의해 검토되거나 계속될 때입니다.

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

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

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

프롬프트는 일시적입니다. 에이전트는 이전 세션에서 무엇을 말했는지 기억하지 못합니다. 저장소에 저장된 버전 관리된 스펙은 기억합니다. 모든 새로운 세션은 컨텍스트를 처음부터 다시 설정하지 않고도 동일한 스펙을 읽고 동일한 의도에 따라 구현할 수 있습니다.

**바이브 코딩(Vibe coding)은 일회성 작업에 더 빠릅니다; SDD vs 바이브 코딩은 언제 스펙을 추가하고 언제 자유롭게 프롬프트를 이어야 하는지 다룹니다.

핵심 산출물

SDD는 네 가지 유형의 산출물을 생성합니다. 각 산출물은 에이전트가 코드에 손을 대기 전에 다른 종류의 모호성을 줄입니다:

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

이를 단계별로 작성하고 검토하는 방법 – 지정(specify), 계획(plan), 작업(tasks), 구현(implement), 검증(validate) – 은 요구사항에서 코드로의 스펙 기반 개발 워크플로우에서 다룹니다. 단순한 기능은 짧은 마크다운 파일로 네 가지 영역을 모두 커버할 수 있습니다. 형식보다 습관이 더 중요합니다.

SDD가 문서화와 다른 점

가장 흔한 혼동은 SDD 산출물을 문서화로 취급하는 것입니다. 이들은 전통적인 의미의 문서화가 아닙니다.

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

스펙은 제약한다. 스펙은 에이전트에게 무엇을 만들 수 있고 무엇을 하면 안 되는지 알려줍니다. 구현이 시작되기 전에 권위가 있으며, 구현이 완료된 후 검증됩니다. 실제로 무엇을 만들었는지 설명하는 스펙(만들어야 할 것을 제약하는 것이 아니라)은 이미 그 목적을 실패한 것입니다.

실행 가능한 스펙은 생성과 검증을 안내합니다. 최고의 SDD 스펙은 에이전트가 그에 따라 구현하고 테스트 스위트가 이를 검증할 수 있을 정도로 기계가 읽을 수 있는 형태에 가깝습니다. “엔드포인트는 인증되지 않은 요청을 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는 형식 표기를 요구하지 않습니다. 수용 기준과 아키텍처 결정을 가진 마크다운 파일은 스펙입니다. 수학적으로 형식적이지 않으면서도 제약을 가합니다. 엄밀성의 수준은 베팅 규모에 따라 달라집니다: 청구 서비스의 스펙은 문서 페이지의 스펙보다 더 정확하고 신중하게 검토되어야 합니다.

관계는 스펙트럼입니다:

  • 비공식 산문 스펙(최소 실행 가능한 SDD)
  • 수용 기준과 비목표가 있는 구조화된 마크다운
  • 스키마 검증을 가진 기계가 읽을 수 있는 스펙
  • 스펙에서 직접 파생된 계약 테스트
  • 자동 증명을 가진 형식 스펙

대부분의 팀은 이 스펙트럼의 중간에서 작동합니다. 목표는 수학적 엄밀성이 아닙니다 – AI 에이전트가 그에 따라 구현하고 인간 검토자가 결과를 검증할 수 있을 정도로 의도를 명시화하는 것입니다.

스펙 기반 개발의 이점

의도 дрей프(Intent drift) 감소. 스펙은 기준입니다. 에이전트가 어긋날 때 – 그럴 것입니다 – 검토자는 구현을 비교할 기준이 있습니다. 스펙이 없으면, 무언가가 깨질 때까지 드리프트는 보이지 않습니다.

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

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

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

더 나은 테스트 계획. 스펙의 수용 기준은 테스트 케이스로 직접 매핑됩니다. 테스트 커버리지는 스펙 커버리지 문제가 됩니다: 모든 수용 기준이 최소 하나의 테스트에 의해 커버되는가?

지속 가능한 인수인계. 기능이 손을 바꿀 때 – 엔지니어 사이, 에이전트 세션 사이, 스프린트 사이 – 스펙은 인수인계 산출물입니다. 무엇이 결정되었는지, 무엇이 범위 밖이었는지, 무엇이 검증되어야 하는지를 포착합니다.

스펙 기반 개발의 비용

사전 노력. 코드를 작성하기 전에 좋은 스펙을 작성하는 데 시간이 걸립니다. 작은 기능의 경우, 이 오버헤드는 실제로 존재하며 때로는 가치가 없을 수 있습니다.

거짓된 자신감. 존재하지만 구현과 검증되지 않은 스펙은 잘못된 정확성의 느낌을 줍니다. 오래된 스펙은 스펙이 없는 것보다 더 나쁠 수 있습니다: 그것을 읽는 검토자와 에이전트를 오도하기 때문입니다.

오래된 스펙. 팀이 스펙을 계획 산출물이 아니라 살아있는 문서로 취급하지 않을 때 스펙은 드리프트됩니다. 구현이 설계와 다르면 스펙을 업데이트하는 것은 선택이 아닙니다 – SDD를 축적되고 썩는 문서화와 구분하는 것이 바로 이것입니다.

생성된 관료주의. AI 에이전트는 방대한 작업 목록과 장황한 스펙을 빠르게 생성할 수 있습니다. 30초 만에 생성된 200개 작업의 스펙은 유용한 스펙이 아닙니다 – 관료주의 생성기입니다. 좋은 SDD는 무엇을 명시하고 무엇을 암묵적으로 둘 것인지에 대한 판단을 요구합니다.

도구 잠금(Tool lock-in). 일부 SDD 도구는 형식, 파일 구조, 워크플로우에 대해 의견이 많습니다. 독점 형식으로 작성된 스펙은 명확한 헤더와 수용 기준을 가진 마크다운 파일보다 도구 간 이식이 어렵습니다.

결론

스펙 기반 개발은 새로운 방법론이 아닙니다. 이는 암시적 의도의 비용이 이제 AI 생성 코드에서 가시화되었기 때문에 다시 실용적이 되고 있는 오래된 규율입니다.

이 규율은 단순합니다: 에이전트가 그것을 만들기 전에, 작성하고 검토하며 버전 관리된 의도를 문서로 남기십시오. 현실이 다르면 기록을 업데이트하여 정확성을 유지하십시오. 검토, 테스트, 인수인계의 기준으로 사용하십시오.

스펙은 마법이 아닙니다. 검증되지 않은 스펙은 가장 비용이 높은 종류의 문서가 됩니다: 자신감 있게 오도하는 문서. 좋은 SDD는 스펙을 정직하게 유지하는 실천입니다 – 유지보수하기 충분히 작고, 제약하기 충분히 정확하며, 단일 에이전트 세션보다 오래 지속될 정도로 지속 가능한.

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

유용한 링크

구독하기

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