명세 기반 개발 (Spec-Driven Development): 구조가 도움이 될 때와 세금이 될 때

Tisha Chawla · Microsoft 소프트웨어 엔지니어

1. 모호성의 세금 (The Ambiguity Tax)

AI 보조 엔지니어링 (AI-assisted engineering)의 병목 현상은 더 이상 코드 생성 (code generation)이 아닙니다. 그것은 바로 의도 보존 (intent preservation)입니다.

인간 엔지니어는 제품 맥락 (product context), 팀의 기억, 아키텍처적 취향, 그리고 축적된 판단력을 사용하여 모호함을 해결할 수 있습니다. 코딩 에이전트 (coding agent)는 의도가 어딘가 영구적인 곳에 기록되어 있지 않는 한, 그러한 맥락을 가정할 수 없습니다. 의도가 오직 채팅 기록 (chat history)에만 존재할 때, 모델은 그 공백을 그럴듯한 가정 (assumptions)으로 채웁니다. 어떤 가정은 해롭지 않지만, 어떤 가정은 그것이 잘못되었다는 것을 아무도 알아차리기 전에 아키텍처를 형성해 버립니다.

나는 이것을 **모호성의 세금 (ambiguity tax)**이라고 부릅니다. 이는 모호한 요구사항이 자동화된 코딩 루프 (automated coding loop)에 진입할 때 발생하는 재작업 (rework), 맥락 드리프트 (context drift), 그리고 아키텍처 파편화 (architectural fragmentation)를 의미합니다. IBM은 생성된 코드가 완전한 시스템 맥락 (system context)을 결여했을 때 발생하는 맥락 드리프트와 파편화를 포함하여, AI 보조 개발에서의 유사한 실패 모드 (failure modes)를 설명합니다. GitHub Blog 또한 에이전트 측면에서 동일한 근본적인 논점을 제시합니다. 즉, 코딩 에이전트는 검색 엔진처럼 다루는 것이 아니라, 명확한 지침이 필요한 글자 그대로의 의미를 따르는 페어 프로그래머 (pair programmers)처럼 다루어야 한다는 것입니다.

명세 기반 개발 (Spec-Driven Development), 또는 SDD는 이러한 실패 모드에 대한 대응책입니다. 이는 엔지니어링 의도를 일시적인 채팅 기록에서 분리하여, 버전 관리(versioned)가 가능하고 검토 가능한 산출물 (reviewable artifacts)로 옮깁니다.

2. 먼저, 산출물을 정의하라

**명세 (spec)**라는 단어는 너무 많은 의미를 담고 있습니다. 만약 우리가 이를 정의하지 않는다면, 나머지 논의는 무너질 것입니다.

**명세 (spec)**란 시스템이나 기능이 무엇을 해야 하는지를 설명하고, AI 코딩 에이전트가 작업을 계획, 구현 및 검증할 수 있도록 충분한 맥락을 제공하는, 주로 자연어로 작성된 구조화되고 동작 중심적인 산출물 (behavior-oriented artifact)입니다. Birgitta Böckeler는 Martin Fowler의 사이트에 게재된 Kiro, Spec Kit, Tessl에 대한 자신의 분석에서 이러한 프레임워크를 사용합니다.

명세(Spec)는 프롬프트(Prompt)가 아닙니다. 프롬프트는 대화적이고 일시적입니다. 명세는 지속적이며 검토 가능합니다.

명세는 PRD(제품 요구사항 문서)가 아닙니다. PRD는 주로 비즈니스 이해관계자들의 의견을 조율합니다. 엔지니어링 명세(Engineering spec)는 코드 생성(Code generation), 구현 선택, 그리고 검증(Verification)을 안내할 수 있을 만큼 충분히 정밀해야 합니다.

명세는 테스트 스위트(Test suite)가 아닙니다. 테스트는 구현 중 또는 구현 후에 동작을 검증합니다. 명세는 구현 전에 기대되는 동작을 정의합니다. 가장 뛰어난 SDD 워크플로우는 이 둘을 연결하지만, 두 가지가 동일한 산출물(Artifact)은 아닙니다.

명세는 길기 때문에 유용한 것이 아닙니다. 유용한 명세는 불확실성을 줄여줍니다. 나쁜 명세는 단순히 모호함을 채팅창에서 마크다운(Markdown)으로 옮겨 놓을 뿐입니다.

3. SDD의 실제 의미

명세 기반 개발(Spec-Driven Development, SDD)은 코드와 명세 사이의 전통적인 관계를 뒤집습니다.

전통적인 라이프사이클:
    코드 (진실의 원천, Source of truth) → 문서 (오래된 산출물)

...

Spec Kit의 문서는 이러한 변화를 명세를 코딩이 시작되면 버려지는 비계(Scaffolding)로 취급하는 것이 아니라, 실행 가능한(Executable) 것으로 만드는 것이라고 설명합니다. 이것은 폭포수(Waterfall) 모델로의 회귀가 아닙니다. SDD의 가장 강력한 형태는 "완벽한 문서를 작성한 다음 코드를 짜는 것"이 아닙니다. 그것은 "의도를 명확히 하고, 이를 검토하며, 에이전트(Agent)가 이를 바탕으로 작동하게 한 뒤, 이해도가 변함에 따라 명세를 진화시키는 것"입니다. GitHub 블로그는 명세를 프로젝트와 함께 진화하며 공유된 진실의 원천(Shared source of truth)이 되는 살아있는 산출물로 설명합니다.

실무적인 엔지니어링 질문은 결코 "문서를 작성해야 하는가?"가 아닙니다. 질문은 다음과 같습니다: 이 특정 변경 사항에 대해, 어느 정도의 구조가 그 유지보수 비용을 정당화할 수 있는가?

4. 핵심 트레이드오프 (Tradeoff)

SDD는 생산성을 높이는 묘수가 아닙니다. 그것은 트레이드오프(Tradeoff)입니다.

구현 전에 더 많은 노력을 들임으로써, 구현 중에 에이전트가 추측하는 데 드는 노력을 줄이는 것입니다. 이 트레이드오프는 모호함의 비용이 높을 때 효과적입니다. 하지만 절차(Ceremony)의 비용이 코드 작성 비용보다 더 클 때는 실패합니다.

실수는 SDD를 사용하지 않는 것이 아닙니다. 모든 변경 사항에 대해 동일한 양의 SDD를 사용하는 것이 실수입니다.

5. 분류 체계 (The Taxonomy): SDD의 세 가지 수준

Böckeler의 가장 유용한 기여는 SDD의 세 가지 수준으로 이루어진 분류 체계 (taxonomy)입니다. 이는 흔히 하나의 라벨 아래 혼동되어 사용되는 관행들을 분리합니다.

SDD 수준	진실의 원천 (Source of Truth)	코드베이스와의 관계	가장 적합한 경우	주요 리스크
Spec-first	작업의 생명주기 동안의 명세 (Spec)	명세가 구현을 가이드한 후, 역사적 유물 (historical artifact)이 됨	오늘날 SDD를 도입하는 대부분의 팀	병합 후 명세가 보관만 된 채 잊혀짐
...

대부분의 프로덕션 팀은 Spec-first로 시작해야 합니다. Spec-anchored는 매력적이지만, 유지보수 의무를 생성합니다. 만약 병합 후에 아무도 명세를 관리하지 않는다면, 해당 유물은 문서 부채 (documentation debt)가 됩니다. Spec-as-source는 가장 야심 차지만 가장 취약합니다. Tessl은 이 방향을 탐구하고 있으며, Böckeler는 이 야심을 모델 주도 개발 (Model-Driven Development, MDD)과 명시적으로 비교하며, MDD 스타일의 경직성과 LLM의 비결정성 (non-determinism)이 결합될 위험이 있다고 경고합니다.

이 분류 체계는 팀이 도입을 결정할 수 있는 언어를 제공합니다. 반드시 "명세 기반이 되어야" 하는 것은 아닙니다. 작업의 성격에 따라 어떤 수준이 정당한지를 선택하는 것입니다.

6. 표준 생명주기 루프 (The Canonical Lifecycle Loop)

대부분의 SDD 도구들은 다음과 같은 유사한 루프로 수렴합니다:

탐색 (Explore) → 명세 (Specify) → 계획 (Plan) → 작업 (Tasks) → 구현 (Implement) → 검증 (Verify)

단계	목적	전형적인 산출물
탐색 (Explore)	문제 공간, 기존 시스템, 제약 조건 및 숨겨진 의존성 이해	노트, 조사 내용, 질문
...

Spec Kit은 Constitution (헌법), Specify (명세), Plan (계획), Tasks (작업), Implement (구현)를 통해 이를 공식화합니다. 이 프로젝트의 README는 사용자에게 명세 (spec) 단계에서는 '무엇을(what)'과 '왜(why)'에 집중하고, 계획 (plan) 단계에서 기술 및 아키텍처 선택을 수행하도록 명시적으로 지시합니다. Kiro의 공식 문서는 명세를 requirements.md 또는 bugfix.md, design.md, tasks.md라는 세 가지 핵심 파일을 생성하는 구조화된 산출물로 설명합니다. OpenSpec은 각 변경 사항에 대해 제안 (proposal), 명세 (specs), 설계 (design), 작업 (tasks)을 사용하며, 더 가볍고 반복적인 프로세스를 채택합니다.

명령어 이름은 서로 다릅니다. 하지만 형태는 동일합니다. 즉, 에이전트에게 코드베이스 수정을 요청하기 전에 모호함을 줄이는 것입니다.

7. 아키텍처로 재구성한 생태계

Star(별) 개수는 트렌드를 감지하는 데 유용합니다. 하지만 그것이 기술적인 평가 지표는 아닙니다. 더 나은 질문은 다음과 같습니다: 해당 도구가 어떤 아키텍처 계층 (architectural layer)에서 작동하는가?

7.1 의도 계층 (Intent Layer)

우리는 무엇을 만들고 있으며, 완료(done)란 무엇을 의미하는가?

도구	아키텍처적 의도	최적의 용도	주요 실패 모드
Spec Kit	명세, 계획, 작업, 확장 기능 및 프로젝트 원칙을 포함하는 저장소 네이티브 SDD (명세 기반 개발)	여러 코딩 에이전트에 걸쳐 명시적인 거버넌스 (governance)를 원하는 팀	Markdown 및 리뷰 오버헤드
...

7.2 실행 계층 (Execution Layer)

에이전트가 작업을 수행하는 동안 어떻게 행동하는가?

도구	아키텍처 의도 (Architectural Intent)	최적의 활용 사례 (Best Fit)	주요 실패 모드 (Primary Failure Mode)
Superpowers	계획 (Planning), TDD, 디버깅 (Debugging), 리뷰 (Review), 검증 (Verification)을 위한 필수적인 조합 가능한 기술 (Composable skills)	기본적으로 규율을 갖추고자 하는 개인 개발자 및 소규모 포드 (Pods)	워크플로우가 작업과 일치하지 않을 때 지나치게 주관적(Opinionated)이라고 느껴질 수 있음
...

HVE Core의 RPI 워크플로우는 연구 (Research), 계획 (Plan), 구현 (Implement), 리뷰 (Review)를 분리합니다. 해당 문서에서는 RPI를 다음과 같은 변환 파이프라인 (Transformation pipeline)으로 설명합니다: 불확실성 (Uncertainty) → 지식 (Knowledge) → 전략 (Strategy) → 작동하는 코드 (Working Code) → 검증된 코드 (Validated Code).

7.3 오케스트레이션 계층 (Orchestration Layer)

누가 작업을 수행하며, 에이전트들은 어떻게 협업하는가?

도구	아키텍처 의도 (Architectural Intent)	최적의 활용 사례 (Best Fit)	주요 실패 모드 (Primary Failure Mode)
Squad	지속적인 의사결정을 보유한 저장소 네이티브 (Repository-native) 멀티 에이전트 팀	프론트엔드 (Frontend), 백엔드 (Backend), 테스트 (Tests), 문서화 (Documentation) 전반의 병렬 작업	작은 작업에서의 조정 오버헤드 (Coordination overhead)
BMAD-METHOD	개발 생명주기 전반에 걸친 멀티 에이전트 프로세스 오케스트레이션 (Orchestration)	대규모의 구조화된 워크플로우	프로세스 복잡성

GitHub 블로그의 Squad 심층 분석에서는 작업을 라우팅하고, 저장소 컨텍스트 (Repository context)를 로드하며, 작업별 지침을 가진 전문가 (Specialists)를 생성하는 코디네이터 에이전트 (Coordinator agent)를 설명합니다.

이 생태계는 하나의 사다리가 아닙니다. 하나의 스택 (Stack)입니다. 의도 (Intent)를 위해서는 Spec Kit을, 실행 규율 (Execution discipline)을 위해서는 HVE Core를, 오케스트레이션 (Orchestration)을 위해서는 Squad를 사용할 수 있습니다. 또는 주관적인 개인 워크플로우를 위해 Superpowers만 단독으로 사용할 수도 있습니다. 올바른 선택은 당신이 줄이고자 하는 실패 모드 (Failure mode)에 달려 있습니다.

8. 결정 필터: 언제 SDD를 실행할 것인가

모호함 (Ambiguity)의 비용이 명세 (Specification)의 비용보다 높을 때 SDD를 사용하십시오.

신호 (Signal)	SDD 건너뛰기 (Skip SDD)	SDD 사용 (Use SDD)
모호함 (Ambiguity)	하나의 명확한 구현 경로	여러 가지 그럴듯한 해석 가능성
...

세 개 이상의 신호가 오른쪽 열에 해당한다면, SDD를 시도해 볼 가치가 있습니다. 대부분이 왼쪽 열에 해당한다면, 테스트를 동반한 일반적인 AI 보조 코딩 (AI-assisted coding)을 사용하십시오.

Böckeler의 분석은 부정적인 사례를 통해 이러한 필터링을 뒷받침합니다. 그녀는 Kiro가 작은 버그 하나를 네 개의 사용자 스토리 (User stories)와 열여섯 개의 수락 기준 (Acceptance criteria)으로 변질시켰으며, Spec Kit은 기존 코드베이스의 중간 규모 기능을 구현하기에는 너무 무겁게 느껴졌다는 점을 발견했습니다. 그녀의 결론은 SDD가 쓸모없다는 것이 아니었습니다. SDD 도구는 문제의 규모에 적합해야 한다는 것이었습니다.

방법론을 채택하지 마십시오. 필터를 적용하십시오.

9. 과잉 구조의 법칙 (The Law of Surplus Structure)

모든 추가적인 규칙은 추론 예산 (Reasoning budget)을 소비합니다. 만약 그 규칙이 불확실성을 줄여준다면 그것은 구조 (Structure)입니다. 그렇지 않다면 그것은 세금 (Tax)입니다.

나는 이것을 **과잉 구조의 법칙 (Law of Surplus Structure)**이라고 부릅니다.

이것은 나의 프레임워크이지만, 두 가지 데이터 포인트에 근거하고 있습니다.

토큰 인플레이션 벤치마크 (The token inflation benchmark). Jamie Telin은 동일한 구현 작업, 즉 AI 채팅 애플리케이션에 스트리밍 및 세션 지원을 추가하는 작업에 대해 OpenSpec과 Spec Kit을 직접 비교하여 발표했습니다.

보고된 실행 (Reported Run)	OpenSpec	Spec Kit	차이 (Difference)
테스트 1 총 토큰 (Test 1 total tokens)	~57,740	~120,947	+109%
...

Telin은 OpenSpec이 더 적은 어시스턴트 턴 (Assistant turns)과 도구 호출 (Tool calls)을 필요로 하면서도 더 높은 작업 성공률을 달성했다고 보고했습니다. 더 많은 구조가 결과물을 개선하지 못한 채 비용만 증가시킨 것입니다.

준수 루프의 함정 (The compliance loop trap). ETH Zurich의 논문 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"에 따르면, 저장소 수준의 컨텍스트 파일 (repository-level context files)은 컨텍스트가 없는 경우와 비교했을 때 작업 성공률을 낮추는 경향이 있는 반면, 추론 비용 (inference cost)은 20% 이상 증가시키는 것으로 나타났습니다. 논문은 에이전트 (agents)가 컨텍스트 파일을 무시하는 것이 아니라고 보고합니다. 그들은 컨텍스트를 따릅니다. 그들은 더 넓게 탐색하고, 더 많은 파일을 가로지르며, 더 많은 도구 호출 (tool calls)을 실행하고, 더 많은 추론 토큰 (reasoning tokens)을 소비하지만, 솔루션에 도달하기 위한 단계 (steps)는 유의미하게 줄어들지 않습니다.

에이전트가 반드시 거버넌스 (governance)를 무시해서 실패하는 것은 아닙니다. 거버넌스를 너무 광범위하게 준수하기 때문에 실패할 수도 있습니다. 거버넌스를 추가하면 모델은 거버넌스를 충족하는 데 노력을 할당합니다. 만약 그 거버넌스가 중복되거나, 모호하거나, 현재 작업과 관련이 없다면, 신뢰성을 개선한 것이 아닙니다. 지능을 문제로부터 멀어지게 재지정했을 뿐입니다.

이것이 "구조를 피하라"는 뜻은 아닙니다. 구조는 그 자리를 증명해야 한다는 뜻입니다. 좋은 헌법은 자유도를 제거합니다. 나쁜 헌법은 형식적인 절차 (ceremony)를 만듭니다. 좋은 명세 (spec)는 동작을 좁힙니다. 나쁜 명세는 컨텍스트를 팽창시킵니다. 좋은 워크플로 (workflow)는 탐색을 줄입니다. 나쁜 워크플로는 준수 루프 (compliance loops)를 만듭니다.

10. 토큰 경제학은 곧 아키텍처다

토큰 비용은 청구서의 각주가 아닙니다. 그것은 아키텍처적 속성 (architectural property)입니다. 워크플로가 더 많은 산출물 (artifacts)을 요구할수록, 더 많은 컨텍스트를 읽고, 요약하고, 확인하고, 조정해야 합니다. 그 비용은 지연 시간 (latency), 도구 호출 (tool calls), 추론 토큰 (reasoning tokens), 검토 시간 (review time), 그리고 비용으로 나타납니다.

spec-kit-cost 확장 프로그램 문서에는 총 $13.3983에 달하는 샘플 기능 보고서가 포함되어 있으며, 이 예시에서 구현 단계 (implementation phase)가 $11.64를 차지합니다. 이것은 평균적인 벤치마크가 아니라, 왜 단계별 비용 가시성 (phase-level cost visibility)이 중요한지를 보여주는 사례입니다.

해결책은 추상적으로 "토큰을 적게 사용하라"는 것이 아닙니다. 그것은 아키텍처의 문제입니다.