스펙 주도 개발(SDD): 워터폴의 귀환

 (marmelab.com)
20P by GN⁺ | ★ favorite | 댓글 1개
  • Spec-Driven Development(SDD) 는 코딩 전 방대한 문서를 작성하는 워터폴식 접근을 부활시킨 방식으로, AI 코딩 보조 도구를 위한 구조화를 목표로 하지만 민첩성을 저해할 위험이 있음
  • 오픈소스 커뮤니티는 초기 프롬프트와 지침을 기반으로 명세서·구현 계획·작업 목록을 자동 생성하는 도구들을 개발했으며, 대표적으로 Spec-Kit, Kiro, Tessl, BMad Method가 있음
  • 그러나 실제 사용 시 맥락 인식 부족, 과도한 문서화, 이중 코드 리뷰, 허위 안정감 등 여러 한계가 드러나며, 대규모 코드베이스에서는 효율이 급감함
  • 글은 SDD가 개발자를 대체하려는 시도로서 워터폴 모델의 실패를 반복한다고 지적하고, 대신 자연어 기반의 반복적 개발 방식을 제안함
  • Agile과 Lean Startup 원칙을 결합한 접근이 코딩 에이전트를 활용한 현대 개발에 더 적합하며, 시각적 상호작용 도구의 발전이 다음 과제임

스펙 주도 개발(SDD)의 등장

  • Spec-Driven Development(SDD) 는 AI 코딩 보조 도구를 위한 구조적 개발 방식을 제공하기 위해, 코딩 전 명세 문서를 작성하는 절차를 도입
    • 초기 프롬프트와 지침을 바탕으로 LLM이 제품 명세서, 구현 계획, 작업 목록을 생성
    • 각 문서는 이전 단계에 의존하며, 사용자가 수정해 명세를 정제
  • 완성된 문서는 Claude Code, Cursor, Copilot 등 코딩 에이전트에 전달되어 코드 작성에 활용
  • 대표 도구로 GitHub의 Spec-Kit, AWS의 Kiro, Tessl, BMad Method(BMM) 등이 있음
  • 관련 비교 분석으로 Birgitta Böckeler의 Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl이 언급됨

마크다운 문서화의 문제

  • SDD 명세는 대부분 Markdown 파일 형태로 구성되며, 예시로 GitHub Spec-Kit을 사용한 간단한 기능 구현이 8개 파일, 1,300줄에 달함
  • Kiro를 이용한 Atomic CRM의 “referred by” 필드 추가 사례도 다수의 문서로 분리됨
  • 실제 사용 시 다음과 같은 단점이 드러남
    • 맥락 인식 부족(Context Blindness) : 기존 함수나 코드 맥락을 놓쳐 전문가 검토가 여전히 필요
    • 과도한 문서화(Markdown Madness) : 긴 문서로 인해 단순 오류 탐색에 많은 시간 소모
    • 체계적 관료주의(Systematic Bureaucracy) : 불필요한 반복과 과도한 세부화로 비효율 발생
    • 가짜 애자일(Faux Agile) : “User Story” 개념을 오용해 산만함 초래
    • 이중 코드 리뷰(Double Code Review) : 명세 내 코드와 실제 구현을 각각 검토해야 함
    • 허위 안정감(False Sense of Security) : 에이전트가 명세를 완전히 따르지 않음
    • 효용 감소(Diminishing Returns) : 초기 프로젝트에는 유용하지만, 규모가 커질수록 속도 저하
  • 대부분의 코딩 에이전트가 이미 plan mode와 task list 기능을 제공하므로, SDD의 추가 이점은 제한적이며 오히려 개발 비용을 증가시킬 수 있음

프로젝트 매니저의 복수

  • SDD의 한계는 도구의 미성숙 때문일 수 있으나, 근본적으로 잘못된 문제 설정에서 비롯됨
    • “개발자를 소프트웨어 개발에서 제거하는 방법”이라는 목표를 전제로 함
    • 개발자를 코딩 에이전트로 대체하고, 이를 세밀한 계획으로 통제하려는 구조
  • 이는 워터폴 모델과 유사하며, 방대한 문서화를 통해 개발자가 단순 번역자 역할을 하도록 만드는 방식
  • 그러나 소프트웨어 개발은 비결정적(non-deterministic) 과정으로, 계획만으로 불확실성을 제거할 수 없음 (No Silver Bullet 논문 인용)
  • SDD는 요구사항 단계에서 비즈니스 분석가, 설계 단계에서 개발자의 전문성이 모두 필요해, 실제로는 두 역할을 모두 수행할 수 있는 소수만 사용 가능
  • 결과적으로 No Code 도구와 마찬가지로 “개발자 없는 개발”을 약속하지만, 결국 개발자를 필요로 함

새로운 대안: 자연어 기반 반복 개발

  • Agile 방법론은 예측 가능성 대신 적응성을 택해 비결정적 개발 문제를 해결
  • 복잡한 요구사항을 여러 단순한 문제로 분할하는 것이 코딩 에이전트 활용의 핵심
  • Lean Startup 원칙을 적용한 간단한 반복 절차 제시
    1. 제품의 가장 위험한 가정을 식별
    2. 이를 검증할 최소한의 실험 설계
    3. 실험 개발 및 결과에 따라 반복
  • 예시로, Claude Code를 이용해 약 10시간 만에 3D 조각 도구(sculpt-3D) 를 개발
    • 명세 없이 짧은 지시문으로 기능을 점진적으로 추가
    • 잘못된 구현은 즉시 수정하며 빠른 반복 수행
  • 이 방식은 워터폴식 문서화 없이도 빠른 수렴이 가능하며, Agile과 코딩 에이전트의 결합으로 실시간 제품 구축이 가능
  • 다만 코딩 에이전트가 텍스트 중심이라 시각적 상호작용이 부족하며, 향후 시각적 인터페이스 강화 도구 개발이 필요

결론

  • Agile 방법론은 이미 명세 문서를 불필요하게 만들었으며, SDD는 이를 되살리려는 시도로 평가됨
  • SDD는 개발자를 배제하려는 이론 중심적 접근으로, 코딩 에이전트를 통한 새로운 개발자 세대의 역량 강화 기회를 놓침
  • 코딩 에이전트를 내연기관에 비유하며, SDD가 이를 기관차에만 묶어두는 반면 우리는 자동차·비행기 등 다양한 형태로 확장해야 함
  • 마지막으로, 환경을 고려한다면 코딩 에이전트의 절제된 사용이 필요함
GeekNews Weekly에 포함된 글입니다. 에디터 코멘트 보기

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견

  • 개발자로서 가장 큰 생산성 향상을 얻은 방법은 모든 작업을 미리 계획하는 습관을 들인 것임
    티켓을 받을 때마다 큰 TODO 리스트로 쪼개서 설계, 의존성, 명세를 미리 명확히 함
    이렇게 하면 프로그래밍할 때 몰입 상태(flow) 에 더 자주 들어갈 수 있음
    AI 코딩 에이전트에게도 이 접근법이 효과적인 이유는, 사고 과정을 미리 옮겨놓는 것이기 때문임
    자세한 내용은 내 글에 정리했음

    • 워터폴이 과도하게 나쁜 평판을 받는다고 생각함
      실제로는 문제를 세분화하고 명세를 작성하는 건 좋은 일임
      다만 변경 불가능한 스펙이 문제를 일으킴. 몇 달 뒤에야 구현을 시작하면 스펙이 굳어버림
      반면 Agile은 전략적 계획을 미루는 핑계로 쓰이는 경우가 많음. 그 결과 재작업이 많아짐
    • 예전에 “concrete galoshes”라는 글을 썼는데, 너무 준비만 하다 프로젝트를 망칠 수도 있다는 내용임
      결국 균형의 문제이며, “It depends”가 인생과 개발 모두에 좋은 모토라고 생각함
      LLM이 스펙을 관리하면 유지보수 부담이 줄어드는 장점이 있을 것 같음
      관련 글은 여기에 있음
    • 네가 말한 방식은 사실상 Agile을 설명하는 것 같음
    • 우리 팀은 에픽 단위로 미리 설계를 함
      예측이 어려운 경우 스파이크(spike) 를 먼저 해서 코드와 라이브러리를 탐색함
      이상적인 구조도와 현실적 제약을 반영한 구조도를 함께 만들어, 장기적으로 아키텍처적 함정을 피함

  • 몇 달간 vibe coding을 하다가 최근 6개월은 spec-driven development로 전환했음
    하루 2~3시간 동안 명세를 작성하고, 그날 안에 테스트된 기능을 배포함
    명세를 쓴다고 해서 덜 민첩해진 건 아님. 오히려 8시간 단위의 빠른 반복이 가능함
    명세는 프롬프트가 아니라 정확성 판단 기준임
    잘 정의된 end-to-end 테스트가 AI의 오류를 크게 줄여줌

    • LLM 기반의 spec-driven 개발은 비결정적 컴파일러를 도입하는 셈이라 생각함
      실행마다 결과가 달라지고, 결국 사람이 검토해야 해서 비효율적일 수 있음
    • 네가 말하는 건 사실 기존의 Agile 티켓 단위 스펙과 같음
      하루짜리 작업을 ‘스펙’이라 부르는 건 오해임. 결국 기존 프로세스를 새 이름으로 부르는 셈임
    • LLM은 아직 논리 추론에 약함
      단순한 논리식도 잘못 해석하는 경우가 많아, 자연어 스펙을 이해시키는 건 위험함
    • 나도 비슷하게 침대에 누워서 acceptance criteria를 쭉 써내려감
      그걸 에이전트에게 넘기면 알아서 구현하고, 나는 중간중간 검토만 함
      AI가 일하는 동안 나는 내 레이스카를 만지니까 완전 윈윈임
      결국 중요한 건 코드가 테스트를 통과하는 것뿐임

  • 이 글은 “spec-based development는 내게 맞지 않다”고 이미 결론 낸 사람들을 위한 것 같음
    나는 스펙을 LLM의 컨텍스트 진입점으로 봄
    프로젝트의 구조, 모델, 함수, 요구사항 등을 충분히 제공하면 LLM이 맥락을 이해하고 확장 가능함
    게다가 LLM이 스스로 스펙을 갱신하게 하면 Agile한 반복도 가능해짐

    • 여기에 테스트 주도 개발(TDD) 을 더하면 완벽함
      테스트가 LLM의 현실 고정(grounding) 역할을 하여 환각을 막음
      테스트는 문서이자 품질 기준이 되며, LLM을 주니어 개발자처럼 관리해야 함
      여러 에이전트를 병렬로 돌리되, 테스트 계층으로 상호 검증하게 하면 놀라운 결과가 나옴
    • 하지만 이건 결국 빠른 워터폴에 가깝다고 봄
      LLM 덕분에 싸고 빠르게 전체 스펙을 반복할 수 있을 뿐, 본질은 동일함
    • 나는 초기 입력을 짧게 주고 점진적으로 확장하는 편임
      너무 긴 스펙은 오히려 탐색적 사고를 방해함
    • 문제의 핵심은 방법론이 아니라 인지 과부하(cognitive overload) 임
      LLM은 결정론적 시스템이 아니라 확률적 시스템이므로, 우리는 이제 코드가 아닌 스펙을 디버깅해야 함
      개발자는 이제 인지 시스템 설계자(cognitive systems architect) 로 진화해야 함
    • “스펙”이라는 단어가 너무 과적재(overloaded) 되어 있음
      상위 수준의 스펙과 세부 컴포넌트 스펙이 공존함

  • 나는 GitHub의 Spec-Kit으로 CLI 도구를 만들어봤는데, 너무 많은 수정·분석·재작성 과정이 필요했음
    워터폴처럼 반복 피드백이 부족해 답답했음
    결국 잘못된 코드를 보고 원인을 찾느니, 새로 시작하는 게 나았음
    LLM과 함께 코딩하는 건 좋지만, SDD는 무겁고 비효율적인 워크플로우로 느껴졌음

    • 나도 처음엔 그렇게 했지만, 스펙은 전체 시스템 명세가 아니라 구체적 작업 설명이어야 함
      LLM은 맥락을 좋아하므로, 반복적으로 명확히 지시해야 함
      예시로 NextJS 앱을 만들 때 로그인, RBAC, 테스트 우선 구현 등을 명확히 기술함
    • 핵심은 작지만 확장 가능한 스펙을 만드는 것임
      작은 단위로 시작해 점진적으로 기능을 추가하는 방식이 더 적합함
    • 문제는 네가 아직 코드 장인 정신을 버리지 못했다는 것임. 그냥 흐름에 맡겨야 함

  • 워터폴의 문제는 긴 리드타임과 비싼 반복 비용이었음
    SDD에서는 이 두 가지가 해결되므로 괜찮다고 생각함

    • 사실 대부분은 학교에서만 워터폴을 배웠지, 실제로 경험하진 않았음
      몇 시간짜리 스펙을 워터폴이라 부르는 건 과장임
    • 하지만 워터폴의 핵심 문제는 스펙 자체임
      복잡한 해답 공간으로 너무 빨리 들어가면, 단순한 문제 해결이 어려워짐
      Agile은 작은 공간에서 출발해 점진적으로 확장함
    • 스펙이 문제의 본질임. 지연은 부차적임
      스펙이 충분히 상세하면 반복이 느려지고, 부족하면 LLM이 제대로 작동하지 않음
      결국 관리자가 좋아하는 워터폴의 모순을 그대로 가짐
    • 그래서 Agile은 “작동하는 코드 > 포괄적 문서”를 강조함
      LLM은 작은 단위로 명확히 지시할 때 가장 잘 작동함
    • 하지만 대기업은 여전히 관료적 워터폴을 택할 가능성이 큼
      몇 년짜리 스펙을 쓰고, 6개월마다 LLM을 돌리고, 실패하면 개발자 탓을 할 것임

  • 글쓴이 본인임
    여전히 워터폴 vs 애자일 논쟁이 활발한 게 흥미로움
    SDD가 가치 있다고 느끼는 사람들의 배경을 읽는 것도 재미있음
    하지만 나는 이미 구현 전 Plan 모드를 사용하고 있어서 SDD가 추가 가치를 주진 않음
    코딩 에이전트가 한 번에 완벽히 구현한 적도 거의 없음
    결국 반복이 필요하므로 Big Design Up Front의 의미가 사라짐
    다만 코딩 에이전트는 새로운 개발 패러다임을 열고 있다고 믿음

  • 예전에 본 영상이 떠오름
    엔지니어와 프로그래머가 서로에게 배울 점을 이야기했는데, 사전 계획의 중요성이 인상 깊었음

  • 애자일이 명세 문서를 죽였다고 하지만, 사실은 수천 개의 Jira 티켓으로 쪼개버린 것뿐임

    • 오히려 그게 핵심일지도 모름
      AI가 이런 산발적 결정과 맥락을 모두 기록하고, 과거 선택과 모순될 때 질문할 수 있음
      “Jim이 5년 전에 이 코드를 이렇게 쓴 이유가 여전히 유효한가?” 같은 피드백을 줄 수 있음
    • 맞음, 그리고 그 지식의 80%는 Jim의 머릿속에만 있었음. 그가 떠난 뒤 아무도 모름

  • 이 글은 좀 이상하게 느껴졌음
    불완전한 스펙을 받고 시행착오로 해결하는 건 인간 개발자나 AI나 마찬가지임
    명확히 알고 있다면 세부적으로 지시하는 게 맞음
    아마 글의 요지는 “나쁜 스펙”에 대한 이야기일지도 모르겠음
    전반적으로는 Agile 산업의 자기 방어 논리처럼 보임

    • 가끔 HN 댓글 중 일부가 AI 옹호 내러티브를 자동으로 퍼뜨리는 것 같다는 생각이 듦

  • 나는 여러 Markdown 스펙 파일로 SDD를 해봤는데, 진짜 효율적이었던 건 ** beads**였음
    에이전트가 작업 트리를 따라가며 집중할 수 있게 해줌
    각 작업을 TDD로 나누고, 테스트 통과 전엔 다음 단계로 못 넘어가게 함
    에이전트가 리뷰 명령어까지 알려줘서 코드 리뷰가 쉬워짐
    Spec-Kit은 너무 무거워서 beads가 훨씬 실용적임
    완전히 vibe 기반으로 만든 zmx 프로젝트도, 나중에 에이전트 코드 참고해 전면 재작성했음

    • 왜 굳이 beads로 버전 관리 시스템(VCS) 을 새로 만들었는지 모르겠음. GitHub로도 충분함
    • 흥미로운데, 에이전트에게 어떤 식으로 지시문을 주는지 예시를 보고 싶음
답변달기