Spec-Driven Development: AI-Generated Code에 골격을 부여하기

발행: 1개월 전 (2026년 3월 15일 오전 03:21 GMT+9)

10 분 소요

원문: Dev.to

Source: Dev.to

위에 제공된 소스 링크만으로는 번역할 본문이 포함되어 있지 않습니다. 번역이 필요한 전체 텍스트를 제공해 주시면, 요청하신 대로 마크다운 형식과 코드 블록, URL은 그대로 유지하면서 한국어로 번역해 드리겠습니다.

AI‑지원 개발 및 “바이브 코딩”의 부상

AI 코딩 도구 (Cursor, Copilot, Claude Code 등)는 소프트웨어를 구축하는 방식을 크게 바꾸었습니다. 이 도구들은 빠르고 유용하며 점점 더 강력해지고 있지만, 동시에 흔한 문제를 드러냅니다: “바이브 코딩.”

기능을 넓게 설명합니다.
AI가 그에 맞는 코드를 작성합니다.
모두가 결과가 실제 의도와 일치하기를 기대하며 진행합니다.

때로는 잘 작동하지만, 종종 생성된 코드에 누락된 엣지 케이스, 약한 계약, 일관성 없는 아키텍처, 혹은 문서화되지 않은 가정이 숨겨져 있습니다.

Spec‑Driven Development이란?

**Spec‑Driven Development (SDD)**는 AI에게 솔루션 구현을 요청하기 전에 구조화된 사양을 작성하는 것을 의미합니다. 사양은 의도, 동작, 제약 조건, 수용 기준을 포착하는 지속 가능한 아티팩트가 됩니다.

“진실의 원천”이 중요한 이유

사양 없이: 개발자와 AI가 기억, 가정, 부분적인 컨텍스트에 의존합니다.
사양과 함께: 두 사람 모두 동일한 아티팩트에 고정됩니다. 인간은 무엇을 만들어야 할지 합의하고, AI는 시스템이 어떻게 동작해야 하는지 구조화된 컨텍스트로 사용합니다.

간단히 생각해 보면:

Prompt‑only development:
idea → chat → code → patch bugs → explain later

Spec‑driven development:
idea → spec → design → tasks → code → tests

차이는 단순히 서류 작업이 아니라, 해결 비용이 아직 저렴할 때 모호성을 앞당겨 해결한다는 점입니다.

전통적인 개발 vs. 사양‑기반 개발

전통적인 (그리고 AI‑유혹에 빠지는) 흐름

Idea → Code → Docs

누군가 아이디어를 가지고 코딩을 시작한 뒤, 시간이 있으면 나중에 문서를 작성한다.
코드가 즉시 나타나면 계획을 건너뛰고 싶어지는 유혹이 커지고, 구현이 팀이 아닌 행동을 정의하게 된다.

사양‑기반 워크플로우

Idea → Spec → Code → Tests

또는, 더 성숙한 환경에서는:

Idea → Requirements → Design → Tasks → Implementation → Validation

사양부터 시작하면 코드 생성기가 하기 전에 중요한 질문에 답하게 된다:

우리가 해결하려는 문제는 무엇인가?
경계는 어디인가?
“완료”란 무엇을 의미하는가?
어떤 제약을 준수해야 하는가?
엣지 케이스에서는 무엇이 일어나야 하는가?

사양은 제품, 엔지니어링, 그리고 AI 도우미에게 공유된 지도를 제공하여 코드가 요구사항의 첫 번째 초안이 되는 가능성을 줄인다.

Source: …

스펙‑드리븐 워크플로우

다양한 도구가 SDD를 구현하는 방식은 다르지만, 워크플로우는 보통 네 가지 실용적인 단계로 진행됩니다.

1. 요구사항

행동 관점에서 기능을 정의합니다—클래스, 엔드포인트, 테이블보다 사용자 요구와 수용 기준에 집중합니다.

예시:

**Feature:** Export user data as CSV  
**User Story:** As a user, I want to download my account activity so I can analyze it offline.  
**Acceptance Criteria:**  
- The CSV includes columns: Date, Action, Amount.  
- Only data from the last 30 days is exported.  
- The file size does not exceed 5 MB.  
- Export fails gracefully with an error message if the query exceeds the size limit.

요구사항 1: 청구서를 PDF로 내보내기

회계 담당자로서,
청구서를 PDF로 내보내고 싶습니다,
그래서 고객에게 인쇄 가능한 버전을 보낼 수 있습니다.

수용 기준

GIVEN 유효한 청구서가 있을 때
WHEN “Export PDF” 버튼을 클릭하면
THEN 시스템이 PDF 파일을 다운로드합니다.
GIVEN 청구서에 세금이 포함되어 있을 때
WHEN PDF가 생성되면
THEN 세금 총액이 웹 화면과 일치해야 합니다.

2. 설계

이 단계에서는 팀이 무엇을 해야 하는지뿐만 아니라 어떻게 시스템이 사양을 만족시킬지를 결정합니다.

예시 흐름:

flowchart LR
    UI[UI Button] --> Service[Invoice Service]
    Service --> Generator[PDF Generator]
    Generator --> Storage[Storage/Download]

3. 작업

설계를 구체적인 작업 항목으로 나누면 사람과 AI 모두 넓은 의도를 구체적인 실행 단계로 전환하는 데 도움이 됩니다.

예시 작업 목록:

- [ ] Add PDF export endpoint
- [ ] Implement invoice‑to‑PDF transformer
- [ ] Add validation for missing invoice data
- [ ] Write integration tests for export flow
- [ ] Verify totals match rendered invoice

4. 구현

이전 단계가 명확해진 뒤에야 AI에게 코드를 생성하거나 수정하도록 요청해야 합니다. 여기서 스펙‑드리븐 개발(SDD)의 강력함이 발휘됩니다: 구현이 자유로운 추측이 아니라 가이드된 실행이 됩니다.

왜 스펙‑드리븐 개발이 AI와 잘 맞는가

AI 시스템은 인상적이지만 여전히 맥락을 많이 필요로 하는 패턴 매처입니다. 다음과 같은 상황에서 더 좋은 성과를 보입니다:

문제를 명확히 제시했을 때.
제약 조건이 명시적일 때.
원하는 동작이 구조화된 형태로 적혀 있을 때.

좋은 스펙은 모델에게 따라야 할 레일을 제공해 해결 공간을 좁히고 수용 기준을 명확히 합니다.

장점

팀 간 정렬 향상 – 구현 전에 공유된 이해 확보.
명확한 API 계약 – 검증이 쉬운 깔끔한 인터페이스.
문서화 개선 – 문서가 개발 프로세스의 일부가 됨.
AI‑생성 코드 신뢰성 향상 – 명시적인 의도가 더 일관된 결과를 도출.

도전 과제

초기 부담 – 요구사항, 설계 노트, 작업을 작성하는 데 시간 소요.
잘못된 스펙은 잘못된 시스템을 만든다 – 모호하거나 모순된 스펙은 잘못된 결과를 초래.
AI는 여전히 예측 불가능할 수 있다 – 모델이 지시를 놓치거나 계획에서 벗어날 수 있음.

목표는 사고를 스펙으로 대체하는 것이 아니라, 사고를 보이게 만드는 것입니다.

결론

AI가 소프트웨어 전달의 더 큰 부분이 되면서, 사양은 더 중요해질 것입니다, 덜 중요해지는 것이 아니라. 코드가 빠르게 생성될 수 있는 세상에서, 부족한 자원은 명확성이지, 타이핑 횟수가 아닙니다. 사양 기반 개발은 “어시스턴트가 어떤 코드를 만들었는가?”에서 “우리가 실제로 만들고자 하는 시스템은 무엇인가?”로 초점을 이동시킵니다. 사양은 방향을 제시하고; 코드는 그 결과물입니다.

참고문헌

(추가 참고문헌이 제공되지 않았습니다)