AI 에이전트(AI agents)를 통한 소프트웨어 구축 방식을 재편하고 있는 실무 가이드.

요약 (TL;DR) — 명세 기반 개발 (Spec-Driven Development, SDD)은 **정확하고 실행 가능한 명세 (precise, executable specification)**를 신뢰할 수 있는 단일 원천(source of truth)으로 만들며, 코드를 생성되고 검증 가능한 산출물로 취급합니다. 명세는 **의도 (intent)**를 선언하고, 코드는 이를 **구현 (realizes)**합니다. 2026년 현재, AI 에이전트가 코드를 작성하는 데는 뛰어나지만 사용자의 의도를 추측하는 데는 서툴기 때문에 SDD는 주류가 되었습니다.

바로가기: 왜 지금인가 · 명세 vs 실행 가능한 명세 · 성숙도 모델 · 워크플로 · 도구 · EARS · 실제 사례 · 주의사항 · 결론

왜 지금인가? "바이브 코딩 (vibe coding)"에 대한 반작용

이 움직임은 **"바이브 코딩 (vibe coding)"**에 반대하며 정의됩니다. 이는 Andrej Karpathy가 2025년 초에 대중화한 용어로, AI에게 느슨하게 프롬프트를 입력하고 결과물이 무엇이든 그대로 배포하는 방식을 의미합니다. 바이브 코딩은 일회성 프로토타입을 만드는 데는 훌륭하지만, 유지보수가 필요한 모든 작업에는 최악입니다.

SDD는 규율 있는 대항마입니다. AI가 대부분의 코드를 작성한다면, 명세 (specification)는 인간이 생산하는 가장 레버리지가 높은 산출물이 됩니다. 중요한 기술은 _구현 코드를 타이핑하는 것_에서 _기계가 틀릴 수 없을 정도로 의도를 정밀하게 정의하는 것_으로 이동합니다.

일반 명세 vs 실행 가능한 명세

이것은 이 주제 전체에서 가장 중요한 차이점이며, 대부분의 "SDD 설명글"들이 생략하는 부분입니다.

	전통적인 설계 문서 (Traditional design docs)	SDD 명세 (SDD specs)
읽는 주체	인간	인간 및 에이전트
...

"전통적인 명세는 인간이 읽지만, SDD 명세는 BDD 시나리오, API 계약 테스트(API contract tests), 또는 모델 시뮬레이션으로 실행됩니다."
— Deepak Babu Piskala, Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants (arXiv, 2026년 1월)

[2602.00180] Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants

AI 코딩 어시스턴트 (AI coding assistants)의 부상은 오래된 아이디어에 다시 불을 지폈습니다. 만약 코드가 아닌 명세(specifications)가 소프트웨어 개발의 주요 산출물이라면 어떻게 될까요? 명세 기반 개발 (Spec-driven development, SDD)은 명세를 신뢰할 수 있는 단일 원천 (source of truth)으로 취급하고, 코드를 생성되었거나 검증된 이차적 산출물로 취급함으로써 전통적인 워크플로를 뒤집습니다. 본 논문은 실무자들에게 SDD의 원칙, 워크플로 패턴 및 지원 도구를 아우르는 포괄적인 가이드를 제공합니다. 우리는 명세의 엄격함에 따라 spec-first, spec-anchored, spec-as-source의 세 가지 수준을 제시하며, 각 수준이 언제 적용되는지에 대한 명확한 지침을 제공합니다. 행동 주도 개발 (Behavior-Driven Development, BDD) 프레임워크부터 GitHub Spec Kit과 같은 현대적인 AI 지원 툴킷에 이르기까지 다양한 도구 분석을 통해, spec-first 철학이 실제 구현에 어떻게 매핑되는지 보여줍니다. 또한 API 개발, 엔터프라이즈 시스템, 임베디드 소프트웨어의 사례 연구를 통해 서로 다른 도메인이 SDD를 어떻게 적용하는지 설명합니다. 마지막으로 실무자들이 SDD가 가치를 제공하는 시점과 더 단순한 접근 방식이 충분한 시점을 결정하는 데 도움이 되는 의사결정 프레임워크를 제시하며 결론을 맺습니다.

arxiv.org

성숙도 모델: 세 가지 수준

2026년의 거의 모든 진지한 출처들은 동일한 단계(ladder)로 수렴합니다. 가장 공격적인 단계가 아니라, 실제로 필요한 단계를 선택하십시오.

1. Spec-First — 명세가 초기 생성을 유도하며, 이후 코드는 드리프트 (drift, 괴리)가 발생할 수 있습니다. AI 지원 기능 및 프로토타입에 적합합니다. 오버헤드가 낮지만, 장기적인 보장은 없습니다.
2. Spec-Anchored — 명세와 코드가 살아있는 문서 (living documentation)로서 함께 진화하며, 자동화된 테스트가 정렬 상태를 강제합니다. Piskala의 논문은 이를 **"대부분의 프로덕션 시스템을 위한 최적의 지점 (the sweet spot)"**이라고 부릅니다.
3. Spec-as-Source — 인간은 오직 명세만을 수정하며, 코드는 완전히 생성되고 수동으로 편집되지 않습니다. 설계 단계부터 드리프트를 제거하지만, 성숙하고 신뢰할 수 있는 생성 도구가 필요합니다. 여전히 대부분의 팀에게는 지향점 (aspirational) 단계입니다.

flowchart TD
  A["<b>Spec-First (명세 우선)</b><br/>명세가 생성의 씨앗이 됨,<br/>코드는 드리프트(drift)가 발생할 수 있음"]
  B["<b>Spec-Anchored (명세 고정)</b> 🎯<br/>명세와 코드가 함께 진화함,<br/>테스트가 정렬(alignment)을 강제함"]
...

🎯 권장 사항: spec-anchored를 목표로 하세요. Spec-as-source는 기대감(hype)이 모이는 곳이지만, spec-anchored는 오늘날 실제 가치가 창출되는 곳입니다.

표준 워크플로우 (The canonical workflow)

모든 주요 도구는 대략적으로 동일한 파이프라인을 구현하며, 드리프트가 누적되기 전에 차단하기 위해 **각 단계의 경계마다 인간의 검토 게이트(human review gate)**를 둡니다.

flowchart LR
  C[constitution (헌법)] --> S[specify (명세)] --> CL[clarify (명확화)] --> P[plan (계획)] --> T[tasks (작업)] --> I[implement (구현)] --> A[analyze (분석)]

단계	수행 내용
Constitution (헌법)	에이전트가 항상 준수해야 하는 프로젝트 전반의 규칙 (언어, 프레임워크, 테스트, 의존성)
...

⚠️ 황금률 (Golden rule): 명세에서 코드로 바로 건너뛰지 마세요. 작업 분해(task decomposition) 전에 계획을 검토하고, 구현(implementation) 전에 작업을 검토하세요.

도구 생태계 (2026년)

도구	강점	최적의 용도
GitHub Spec Kit	오픈 소스, 모델 불가지론적 (model-agnostic), 참조 구현체	벤더 종속(vendor lock-in)을 피하려는 팀
...
모두가 벤치마킹의 기준으로 삼는 오픈 소스 참조 구현체:

github / spec-kit

💫 명세 기반 개발 (Spec-Driven Development)을 시작할 수 있도록 돕는 툴킷

🌱 Spec Kit

<div class="markdown-heading" dir="auto">

고품질 소프트웨어를 더 빠르게 구축하세요.

모든 조각을 처음부터 '바이브 코딩 (vibe coding)' 하는 대신, 제품 시나리오와 예측 가능한 결과에 집중할 수 있게 해주는 오픈 소스 툴킷입니다.

목차 (Table of Contents)

목차 (Table of Contents)

• 🤔 Spec 기반 개발(Spec-Driven Development)이란 무엇인가?
• ⚡ 시작하기
• 📽️ 비디오 개요
• 🌍 커뮤니티
• 🤖 지원되는 AI 코딩 에이전트 통합 기능
• 🔧 Specify CLI 참고 자료
• 🧩 Spec Kit을 나만의 것으로 만들기: 확장 기능 및 프리셋
• 📚 핵심 철학
• 🌟 개발 단계
• 🎯 실험 목표
• 🔧 필수 조건
• 📖 더 알아보기
• 📋 상세 프로세스
• 💬 지원(Support)
• 🙏 감사의 말
• 📄 라이선스

🤔 Spec 기반 개발(Spec-Driven Development)이란 무엇인가?

Spec 기반 개발은 전통적인 소프트웨어 개발 방식을 뒤집습니다. 수십 년 동안 코드가 왕이었으며, 명세는 실제 코딩 작업이 시작되면 우리가 만들고 버리는 단순한 발판에 불과했습니다. Spec 기반 개발은 이를 바꿉니다: 명세가 실행 가능해져서, 단순히 가이드하는 것을 넘어 작동하는 구현체를 직접 생성합니다.

⚡ 시작하기

1. Specify CLI 설치

**uv**가 필요합니다...

GitHub에서 보기

AI 물결 이전에 존재했지만 SDD를 구동하는 표준 및 프레임워크 지원

• BDD (Behavior-Driven Development): Cucumber, SpecFlow, Behave (Gherkin / Given-When-Then)
• API contracts (API 계약): OpenAPI/Swagger, GraphQL SDL, Protocol Buffers, AsyncAPI
• Contract testing (계약 테스트): Pact, Specmatic
• Model-based design (모델 기반 설계): Simulink, SCADE

이 중 새로운 것은 없습니다. SDD의 기여는 이들을 사후에 작성하는 문서가 아니라, AI 에이전트가 생성하는 주요 (primary) 산출물로서 서로 연결하는 데 있습니다.

30초 도구 선택 가이드라인

• 이미 Claude Code를 사용 중인가요? → Spec Kit + cc-sdd 기술
• Cursor를 사용 중인가요? → Plan Mode + AGENTS.md + MCP를 통한 Spec Kit
• AWS 환경인가요? → Kiro
• 규제(Regulated) 산업인가요? → Tessl
• 최소한의 절차를 원하시나요? → OpenSpec

EARS: LLM이 오독할 수 없는 명세 작성법

EARS (Easy Approach to Requirements Syntax)는 인간과 모델 모두에게 모호하지 않은 수용 기준 (acceptance criteria)을 위한 사실상의 표준 (de facto standard)입니다. 다섯 가지 패턴이 거의 모든 것을 다룹니다:

패턴	템플릿	예시
Ubiquitous (편재적)	시스템은 ~해야 한다 (shall) …	시스템은 모든 인증 시도를 로그로 남겨야 한다 (shall log every auth attempt).
...

결과적으로: 이런 방식으로 작성된 기준은 테스트 케이스와 거의 1:1로 매핑됩니다. 이것이 바로 명세를 단순한 권고 사항이 아닌 실행 가능한 (executable) 것으로 만드는 핵심입니다.

실제 사례: "매직 링크 로그인 (magic-link login)"

말은 쉽습니다. 산출물이 구체적일 수 있도록 (축약된) 엔드 투 엔드 (end-to-end) 단면을 보여드리겠습니다.

📄 spec.md (발췌)

## Feature: Passwordless magic-link login

### Acceptance criteria (EARS)
...

🏗️ plan.md (발췌)

## Stack
- Node 22 + Fastify, Postgres 16, Redis for token TTL.

...

✅ tasks.md (발췌)

- [ ] T1  migration: magic_tokens table
- [ ] T2  POST /auth/magic-link  (issue + email)   refs spec §1, §3
- [ ] T3  GET  /auth/verify      (consume + session) refs spec §2
...

연결 고리를 주목하세요: 각 작업은 **자신이 충족하는 명세 조항을 인용(cite)**합니다. 이러한 추적 가능성 (traceability)이 핵심입니다. 테스트가 실패했을 때, 어떤 의도가 깨졌는지 알 수 있기 때문입니다.

권장 사항 및 모범 사례

헌법적 토대 (Constitutional foundations)

• 첫 번째 명세 (spec)를 작성하기 전에 AGENTS.md 또는 .specify/memory/constitution.md를 커밋(Commit)하세요.
• 프로젝트 전반의 결정 사항을 도처에 존재하는 EARS 문장(ubiquitous EARS statements)으로 성문화하세요: "시스템은 TypeScript strict mode를 사용해야 한다(The system shall use TypeScript strict mode)."

명세 규율 (Specification discipline)

• 하나의 기능 = 하나의 명세 디렉토리 (specs/NNN-feature-name/).
• 명세는 1~3페이지 이내로 유지하세요. 분량이 더 많아지면 분할하세요.
• 에이전트(agent)의 탐색 범위를 제한하기 위해 명시적인 "범위 외 (out of scope)" 섹션을 사용하세요.
• 구현 세부 사항이 아닌 도메인 언어 (domain language) (비즈니스 의도)로 작성하세요.

단계 경계 (Phase boundaries)

• 명세에서 코드로 절대 바로 건너뛰지 마세요. 계획(plan)을 검토한 다음, 작업(tasks)을 검토하세요.

문서화 및 추적성 (Documentation & traceability)

• 커밋(commit) 시 명세를 인용하세요: feat(auth): magic link, refs specs/004-magic-link/spec.md.
• 명세를 영구적인 것으로 취급하세요. 명세는 생성된 코드보다 더 오래 지속됩니다.
• 보안, 접근성, 관찰 가능성(observability)을 위해 사전 점검 단계인 /checklist 패스를 실행하세요.

솔직한 주의 사항

SDD에는 실제 회의론자들이 존재하며, 이들은 과장된 홍보보다 더 가치 있는 의견을 제공합니다: