Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 18. 03:40

명세 기반 개발 (Spec-Driven Development): 실제 사례를 통해 명세가 코드를 주도하게 하라

요약

AI 코딩 에이전트의 모호한 입력을 해결하기 위해 명세(Specification)를 중심으로 개발하는 '명세 기반 개발(SDD)' 방법론을 소개합니다. 명세를 단일 진실 공급원으로 삼아 Spec, Plan, Tasks, Implement 단계로 이어지는 체계적인 워크플로우를 제안합니다.

핵심 포인트

  • AI 에이전트의 성능은 모호한 입력이 아닌 명확한 명세에 달려 있음
  • SDD는 Spec → Plan → Tasks → Implement의 구조적 단계를 따름
  • 명세는 코드가 아닌 프로젝트의 중심이 되는 '살아있는 산출물'이어야 함
  • 명세가 단일 진실 공급원(SSOT)이 되어 코드와 테스트를 주도해야 함

Sergio Colque Ponce 작성 — 소프트웨어 엔지니어링, Universidad Privada de Tacna.
전체 소스 코드: github.com/srg-cp/spec-driven-development

만약 여러분이 AI 코딩 에이전트(AI coding agent)인 Copilot, Claude Code, Gemini CLI 등을 사용해 보았다면, 아마 이런 순간을 경험했을 것입니다. 여러분이 기능을 설명하면, 에이전트는 컴파일이 되고 올바르게 보이는 코드를 생성하지만, 정작 실행하면 조용히 잘못된 동작을 수행하는 상황 말입니다. 에이전트가 약한 것이 아닙니다. **입력 (input)**이 모호했던 것입니다. 우리는 코딩 에이전트를 검색 엔진처럼 취급해 왔지만, 사실 그들은 매우 문자 그대로 실행하는 페어 프로그래머 (pair programmer)에 더 가깝게 동작합니다.

**명세 기반 개발 (Spec-Driven Development, SDD)**은 그 문제에 대한 해답입니다. 코드로 바로 뛰어드는 대신, 여러분이 무엇을 원하는지 그리고 왜 원하는지를 적고, 이를 다듬은 다음, 구현 (implementation)이 뒤따라오게 하는 것입니다. 코드가 아닌 명세 (specification)가 프로젝트의 중심이 됩니다.

명세 기반 개발 (Spec-Driven Development)이란 실제로 무엇인가

이 아이디어는 오래된 것이지만 (제품 요구 사항 문서 (Product Requirements Document)를 작성해 본 사람이라면 누구나 알아볼 것입니다), GitHub의 오픈 소스인 Spec Kit과 같은 도구 덕분에 다시 실용적으로 변했습니다. Spec Kit은 작업을 작은 마크다운 (Markdown) 산출물 세트로 구성하며, 각 산출물은 다음 단계의 입력이 됩니다:

  1. Constitution (헌법) — 프로젝트의 타협할 수 없는 원칙 (보안 규칙, 코딩 표준, 아키텍처 제약 조건).
  2. Spec (명세) — 구현 세부 사항 없이, 여러분이 무엇을 만들고 있고 왜 만드는지에 대한 내용.
  3. Plan (계획) — 명세로부터 도출된 기술적 청사진 (스택, 구조, 결정 사항).
  4. Tasks (작업) — 계획을 작고, 순서가 있으며, 검증 가능한 단계로 나눈 것.
  5. Implement (구현) — 에이전트(또는 사용자)가 이전 산출물들을 구조화된 컨텍스트 (context)로 사용하여 작업을 수행함.

이 워크플로우는 보통 Spec → Plan → Tasks → Implement로 요약되며, 동일한 프로세스는 언어, 프레임워크, 또는 지원되는 30개 이상의 에이전트 중 무엇을 사용하든 상관없이 작동하도록 설계되었습니다.

진정한 변화는 "더 많은 문서"를 만드는 것이 아닙니다. 그것은 바로 이것입니다: 요구사항이 변경될 때, 코드를 패치하며 의도가 유지되기를 바라는 대신, 명세(spec)를 업데이트하고, 계획(plan)을 재생성하며, 구현(implementation)이 이를 따르도록 하는 것입니다. 명세는 아무도 열어보지 않는 먼지 쌓인 Word 파일이 아니라, 살아있는(living) 산출물입니다.

도구의 이면에 있는 원칙

SDD를 실천하기 위해 반드시 Spec Kit이 필요한 것은 아닙니다. 그 근저에 깔린 원칙은 단순하며 도구에 구애받지 않습니다:

명세는 단일 진실 공급원(Single Source of Truth)입니다. 코드와 테스트는 명세로부터 파생됩니다. 그 반대는 결코 일어나서는 안 됩니다.

이 원칙의 가장 강력한 형태는 **실행 가능한 명세 (executable specification)**입니다. 이는 테스트와 CI(지속적 통합)가 구현 내용을 자동으로 검증할 수 있는, 기계가 읽을 수 있는 계약(contract)입니다. 만약 코드가 명세에서 벗어나면 빌드는 실패합니다. 이것이 바로 명세를 단순한 문서에서 가드레일(guardrail)로 바꾸는 핵심입니다.

여러분이 직접 실행해 볼 수 있는 작고 실제적인 프로젝트를 통해 이를 정확히 보여드리겠습니다.

실제 사례: URL 단축기 (URL shortener)

우리는 /shorten 엔드포인트를 원합니다: 긴 URL을 보내면 짧은 코드를 돌려받는 기능입니다. SDD 방식의 핵심은 어떤 로직을 작성하기 전에 계약(contract)을 먼저 작성하는 것입니다. 여기 OpenAPI 문서(spec/openapi.yaml)로 작성된 계약이 있습니다:

components:
  schemas:
    ShortenRequest:
...

성공의 _형태(shape)_를 이미 결정했다는 점에 주목하세요: 응답은 반드시 original_url과 정확히 7자리의 16진수 문자로 구성된 short_code를 포함해야 합니다. 아직 존재하는 코드는 없지만, 규칙은 명확합니다.

2단계: 명세에 따른 구현

이제 코드는 단순히 계약을 준수하기만 하면 됩니다. 코드의 역할은 자신만의 형식을 만들어내는 것이 아니라, ShortenResponse를 충족시키는 것입니다:

import hashlib

class InvalidURLError(ValueError):
...

3단계: 명세가 테스트를 주도함

이 지점에서 SDD는 단순한 슬로건을 넘어섭니다. 테스트는 명세를 로드하여 구현이 명세와 일치하는지 검증합니다. 단언문(assertion)은 코드에서 수동으로 복사해 온 것이 아니라, 계약으로부터 직접 가져옵니다:

import yaml, jsonschema
from openapi_spec_validator import validate as validate_openapi
from shortener import shorten, InvalidURLError
...

만약 나중에 누군가가 shorten()이 예를 들어 8자리의 코드를 반환하도록 변경한다면, 명세(spec)의 pattern이 더 이상 일치하지 않게 되어 test_response_conforms_to_the_spec 테스트가 즉시 실패합니다. 이제 명세가 _강제(enforced)_되는 것입니다.

4단계: 자동화로 루프를 완성합니다

작은 GitHub Actions 워크플로우가 계약(contract)을 검증하고 모든 푸시(push) 시 테스트를 실행합니다. 명세는 기계에 의해, 모든 변경 사항에 대해, 영원히 체크됩니다:

name: CI
on: [push, pull_request]
jobs:
...

로컬에서 테스트 스위트(suite)를 실행하는 것도 마찬가지로 정직합니다:

tests/test_contract.py::test_spec_is_a_valid_openapi_document PASSED
tests/test_contract.py::test_response_conforms_to_the_spec PASSED
tests/test_contract.py::test_short_code_matches_the_specified_pattern PASSED
...

SDD가 가치를 발휘하는 순간

명세 기반 개발 (Spec-Driven Development, SDD)은 그린필드 (greenfield) 작업(그냥 코딩을 시작하고 싶은 유혹이 드는, 아무것도 없는 상태에서 시작하는 작업), "맞아 보인다"는 것만으로는 충분하지 않은 **실질적인 결과 (real consequences)**가 따르는 기능, 그리고 모호한 프롬프트(prompt)보다는 명확한 의도가 필요한 AI 에이전트에게 전달되는 모든 프로젝트에서 빛을 발합니다. 일회성 스크립트에는 과할 수 있지만, 유지보수해야 하는 모든 것이라면 요구사항이 변경되는 첫 순간에 명세는 그 가치를 스스로 증명합니다.

한 가지 솔직한 주의사항을 덧붙이자면, 인간을 루프 안에 유지 (keep a human in the loop) 하십시오. AI와 함께하는 SDD가 맹목적인 신뢰를 의미하지는 않습니다. 당신은 여전히 중요한 단계에서 명세, 계획, 그리고 생성된 코드를 검토해야 합니다.

결론

명세 기반 개발 (Spec-Driven Development)은 특정 도구에 관한 것이라기보다, 일반적인 순서를 뒤집는 것에 가깝습니다. 무엇이 올바른지 결정하고, 기계가 확인할 수 있는 곳에 기록하며, 코드와 테스트가 그 뒤를 따르게 하는 것입니다. Spec Kit을 사용하여 전체적인 Spec → Plan → Tasks → Implement 워크플로우를 채택하든, 아니면 단순히 CI가 강제하는 OpenAPI 계약을 유지하든, 그 보상은 동일합니다. 당신의 소프트웨어가 실제로 의도한 대로 동작하며, 다음 변경 사항 이후에도 그 동작을 유지하게 됩니다.

전체 실행 가능한 프로젝트는 여기에 있습니다: github.com/srg-cp/spec-driven-development. 프로젝트를 클론(Clone)한 뒤, 명세(spec) 내의 short_code 패턴을 변경하고 테스트를 실행해 보세요. 계약(contract)이 당신의 실수를 잡아내는 것을 확인할 수 있습니다.

읽어주셔서 감사합니다!

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0