# 스펙 주도 개발(SDD): 워터폴의 귀환 > Clean Markdown view of GeekNews topic #24400. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=24400](https://news.hada.io/topic?id=24400) - GeekNews Markdown: [https://news.hada.io/topic/24400.md](https://news.hada.io/topic/24400.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2025-11-17T04:40:23+09:00 - Updated: 2025-11-17T04:40:23+09:00 - Original source: [marmelab.com](https://marmelab.com/blog/2025/11/12/spec-driven-development-waterfall-strikes-back.html) - Points: 20 - Comments: 1 ## Summary 최근 떠오른 **Spec-Driven Development(SDD)** 는 AI 코딩 에이전트를 위해 모든 개발 과정을 문서화하는 **워터폴식 접근**을 되살리지만, 실제로는 **민첩성과 창의성**을 크게 제한할 수 있다는 비판을 받습니다. GitHub의 **Spec-Kit**이나 AWS의 **Kiro** 같은 도구들이 자동 명세 생성을 시도하지만, **맥락 인식 부족**과 **이중 검토 부담** 등으로 대규모 프로젝트에서는 효율이 급감합니다. 이 글에선 결국 **Agile과 Lean Startup 원칙**을 결합한 **자연어 기반 반복 개발**이 코딩 에이전트 시대에 더 현실적인 해법임을 강조하며, 다음 과제로 **시각적 인터페이스 강화**를 제시합니다. “AI가 개발자를 대체할까?”보다 “AI와 함께 더 빠르게 실험할 수 있을까?”를 묻는 시점이 된 듯합니다. ## Topic Body - **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가 이를 기관차에만 묶어두는 반면 우리는 **자동차·비행기 등 다양한 형태**로 확장해야 함 - 마지막으로, 환경을 고려한다면 **코딩 에이전트의 절제된 사용**이 필요함 ## Comments ### Comment 46381 - Author: neo - Created: 2025-11-17T04:40:23+09:00 - Points: 1 ###### [Hacker News 의견](https://news.ycombinator.com/item?id=45935763) - 개발자로서 가장 큰 **생산성 향상**을 얻은 방법은 모든 작업을 미리 계획하는 습관을 들인 것임 티켓을 받을 때마다 큰 TODO 리스트로 쪼개서 설계, 의존성, 명세를 미리 명확히 함 이렇게 하면 프로그래밍할 때 **몰입 상태(flow)** 에 더 자주 들어갈 수 있음 AI 코딩 에이전트에게도 이 접근법이 효과적인 이유는, 사고 과정을 미리 옮겨놓는 것이기 때문임 자세한 내용은 [내 글](https://liampulles.com/jira-tickets.html)에 정리했음 - 워터폴이 과도하게 나쁜 평판을 받는다고 생각함 실제로는 문제를 세분화하고 명세를 작성하는 건 좋은 일임 다만 **변경 불가능한 스펙**이 문제를 일으킴. 몇 달 뒤에야 구현을 시작하면 스펙이 굳어버림 반면 **Agile**은 전략적 계획을 미루는 핑계로 쓰이는 경우가 많음. 그 결과 재작업이 많아짐 - 예전에 “**concrete galoshes**”라는 글을 썼는데, 너무 준비만 하다 프로젝트를 망칠 수도 있다는 내용임 결국 균형의 문제이며, “It depends”가 인생과 개발 모두에 좋은 모토라고 생각함 LLM이 스펙을 관리하면 유지보수 부담이 줄어드는 장점이 있을 것 같음 관련 글은 [여기](https://littlegreenviper.com/various/concrete-galoshes/)에 있음 - 네가 말한 방식은 사실상 **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**의 의미가 사라짐 다만 코딩 에이전트는 **새로운 개발 패러다임**을 열고 있다고 믿음 - 예전에 본 [영상](https://youtu.be/CmIGPGPdxTI)이 떠오름 엔지니어와 프로그래머가 서로에게 배울 점을 이야기했는데, **사전 계획의 중요성**이 인상 깊었음 - 애자일이 명세 문서를 죽였다고 하지만, 사실은 **수천 개의 Jira 티켓**으로 쪼개버린 것뿐임 - 오히려 그게 핵심일지도 모름 AI가 이런 **산발적 결정과 맥락**을 모두 기록하고, 과거 선택과 모순될 때 질문할 수 있음 “Jim이 5년 전에 이 코드를 이렇게 쓴 이유가 여전히 유효한가?” 같은 피드백을 줄 수 있음 - 맞음, 그리고 그 지식의 80%는 **Jim의 머릿속**에만 있었음. 그가 떠난 뒤 아무도 모름 - 이 글은 좀 이상하게 느껴졌음 불완전한 스펙을 받고 시행착오로 해결하는 건 인간 개발자나 AI나 마찬가지임 명확히 알고 있다면 **세부적으로 지시**하는 게 맞음 아마 글의 요지는 “나쁜 스펙”에 대한 이야기일지도 모르겠음 전반적으로는 **Agile 산업의 자기 방어 논리**처럼 보임 - 가끔 HN 댓글 중 일부가 **AI 옹호 내러티브**를 자동으로 퍼뜨리는 것 같다는 생각이 듦 - 나는 여러 **Markdown 스펙 파일**로 SDD를 해봤는데, 진짜 효율적이었던 건 [** beads**](https://github.com/steveyegge/beads)였음 에이전트가 작업 트리를 따라가며 집중할 수 있게 해줌 각 작업을 **TDD**로 나누고, 테스트 통과 전엔 다음 단계로 못 넘어가게 함 에이전트가 리뷰 명령어까지 알려줘서 코드 리뷰가 쉬워짐 **Spec-Kit**은 너무 무거워서 beads가 훨씬 실용적임 완전히 vibe 기반으로 만든 [zmx](https://github.com/neurosnap/zmx) 프로젝트도, 나중에 에이전트 코드 참고해 전면 재작성했음 - 왜 굳이 beads로 **버전 관리 시스템(VCS)** 을 새로 만들었는지 모르겠음. GitHub로도 충분함 - 흥미로운데, 에이전트에게 **어떤 식으로 지시문을 주는지** 예시를 보고 싶음