스펙 주도 개발(SDD)은 폭포수와 무엇이 다를까?

코딩 에이전트에게 「로그인 화면에 비밀번호 재설정을 넣어 줘」라고 한 줄을 건넵니다. 몇 분 뒤 코드가 돌아옵니다. 그 안에는 아무도 묻지 않은 결정이 여럿 들어 있습니다. 재설정 링크를 메일로 보낼지 문자로 보낼지, 링크가 몇 분 뒤에 만료되는지, 없는 이메일을 넣었을 때 「없는 계정」이라고 알려 줄지 같은 것들입니다. 에이전트는 이것들을 정하지 않고 넘어갈 수 없으니 그럴듯한 쪽으로 골랐고, 코드를 읽기 전에는 무엇을 골랐는지 알 수 없습니다.

스펙 주도 개발(spec-driven development, SDD)은 이 결정들을 코드보다 먼저 문서로 적게 하는 방식입니다. 이렇게 설명하면 먼저 떠오르는 반응은 「그거 폭포수잖아요」입니다. 요구사항 문서를 먼저 쓰고 설계를 거쳐 구현으로 내려가는 순서만 보면 맞는 말입니다. 그런데 이 비교는 SDD 가 실제로 풀려는 문제와 실제로 부딪히는 한계를 둘 다 가립니다.

코드 대신 의도를 정본으로 삼는 발상

GitHub 는 2025년 9월 오픈소스 도구 Spec Kit을 내면서 이 방식을 이렇게 요약했습니다.

We're moving from "code is the source of truth" to "intent is the source of truth."

지금까지는 코드가 정본이었습니다. 문서와 코드가 어긋나면 코드가 맞고 문서가 틀린 것으로 봤습니다. 사람이 코드를 직접 쓰던 때는 이것이 자연스러웠습니다. 코드를 쓴 사람의 머릿속에 의도가 있었고, 그 사람에게 물으면 됐기 때문입니다.

에이전트가 코드를 쓰면 이 전제가 깨집니다. 코드는 빨리 나오지만 그 코드를 만든 의도는 어디에도 남지 않습니다. 다음 대화의 에이전트는 이전 대화를 기억하지 못합니다. 그래서 의도를 사람의 머리가 아니라 파일에 두고, 에이전트가 그 파일을 읽고 코드를 만들게 하자는 것이 SDD 의 출발점입니다. Thoughtworks 의 Birgitta Böckeler 는 martinfowler.com 에 쓴 분석 글에서 이를 「AI 로 코드를 쓰기 전에 스펙을 먼저 쓰는 것, 그리고 그 스펙이 사람과 AI 모두의 정본이 되는 것」이라고 정의했습니다. 그러면서 이 정의가 아직 굳지 않았다는 단서도 달았습니다.

명세, 계획, 작업으로 쪼개는 순서

도구마다 이름은 다르지만 뼈대는 비슷합니다. Spec Kit 은 네 단계로 나눕니다.

단계	사람이 건네는 것	나오는 문서
Specify	무엇을, 왜 만드는지	사용자 시나리오와 요구사항
Plan	기술 스택, 구조, 제약	설계와 데이터 모델
Tasks	(계획을 바탕으로 자동 생성)	따로 구현하고 시험할 수 있는 작은 작업 목록
Implement	작업 하나씩 검토	코드

여기서 눈여겨볼 것은 첫 단계에서 기술 이야기를 일부러 뺀다는 점입니다. Microsoft 개발자 블로그의 해설은 /specify 단계가 기술적 결정을 「명시적으로 제외한다」고 씁니다. 무엇을 만들지와 어떻게 만들지를 한 문서에 섞으면, 에이전트가 「어떻게」에 끌려 「무엇을」을 고쳐 버리기 쉽기 때문입니다.

Spec Kit 에는 단계 밖에 하나가 더 있습니다. 헌법(constitution)이라고 부르는 .specify/memory/constitution.md 파일입니다. 같은 해설은 이것을 프로젝트의 「협상할 수 없는 원칙」을 적는 곳이라고 설명합니다. 테스트를 어떤 방식으로 쓰는지, 모든 앱을 CLI 부터 만드는지 같은 규칙입니다. 계획 단계는 이 헌법에 비추어 설계를 점검합니다. 저는 이 파일이 Claude Code 의 CLAUDE.md 나 다른 도구의 규칙 파일과 같은 자리에 있다고 봅니다. 기능마다 바뀌지 않는 판단을 매번 다시 말하지 않게 하는 문서입니다.

AWS 의 Kiro 는 같은 생각을 requirements.md, design.md, tasks.md 세 파일로 풀었습니다. 어느 도구든 단계 사이에서 사람이 문서를 읽고 넘어가는 것을 전제로 합니다. GitHub 의 글은 이 확인을 이렇게 강조합니다. 「사람의 역할은 방향을 잡는 데서 끝나지 않습니다. 검증하는 것입니다.」

요구사항 문장을 고정하는 EARS 표기

Kiro 는 요구사항을 EARS(Easy Approach to Requirements Syntax)라는 형식으로 씁니다. 새로 만든 형식이 아닙니다. Rolls-Royce 의 Alistair Mavin 과 동료들이 제트 엔진 제어 시스템의 감항 규정을 분석하다 만들어 2009년 IEEE 요구공학 학회(RE'09)에 발표한 것입니다. 자연어는 그대로 쓰되 문장의 순서와 쓸 수 있는 키워드를 몇 개로 묶어 모호함을 줄이는 방식입니다.

기본 꼴은 다섯 가지입니다. 아래 예시는 앞의 비밀번호 재설정을 설명하려고 제가 만든 것입니다.

꼴	키워드	예시
상시	(없음)	시스템은 비밀번호를 해시로만 저장해야 한다
사건	When	사용자가 재설정을 요청하면, 시스템은 30분 동안 유효한 링크를 메일로 보내야 한다
상태	While	계정이 잠겨 있는 동안, 시스템은 재설정 요청을 받지 않아야 한다
선택 기능	Where	2단계 인증을 쓰는 계정이면, 시스템은 재설정 전에 인증 코드를 확인해야 한다
원치 않는 동작	If, then	만료된 링크로 접속하면, 시스템은 새 링크를 요청하는 화면을 보여야 한다

에이전트 입장에서 이 형식이 좋은 이유는 문장 하나가 거의 그대로 시험 하나가 되기 때문입니다. 「When 조건, 시스템은 무엇을 해야 한다」는 「조건을 만들고, 결과를 확인한다」로 바로 옮겨집니다. 처음에 말한 숨은 결정 중 링크 만료 시간과 만료 뒤의 동작이 이 표에서는 문장으로 드러나 있습니다. 「없는 이메일을 넣으면?」은 아직 비어 있는데, 표를 읽는 사람이 그 빈칸을 볼 수 있다는 것이 핵심입니다.

스펙을 얼마나 오래 살려 두는가에 따른 세 수준

Böckeler 의 글에서 가장 쓸모 있는 부분은 SDD 를 세 수준으로 나눈 것입니다.

수준	스펙의 수명	사람이 고치는 것
spec-first	그 작업이 끝날 때까지	스펙과 코드
spec-anchored	기능이 사는 동안 계속	스펙과 코드, 바뀔 때마다 스펙부터
spec-as-source	영구, 스펙이 곧 소스	스펙만. 코드는 손대지 않음

그녀가 본 바로는 모든 SDD 도구가 spec-first 였고, 그 너머까지 가려는 도구는 일부였습니다. Kiro 는 대체로 spec-first 였습니다. Spec Kit 은 스펙마다 브랜치를 만들기 때문에, 그녀는 스펙이 「기능의 수명이 아니라 변경 요청 하나의 수명」만큼 산다고 봤습니다. 세 번째 도구 Tessl 만 spec-anchored 를 내세웠고 spec-as-source 까지 시험하고 있었습니다. Tessl 이 만든 코드 파일 맨 위에는 // GENERATED FROM SPEC - DO NOT EDIT 라는 주석이 붙습니다.

이 구분을 알고 나면 「SDD 를 도입한다」는 말이 얼마나 다른 뜻을 품는지 보입니다. spec-first 는 큰 작업 하나를 시작하기 전에 계획서를 쓰는 것과 크게 다르지 않습니다. spec-as-source 는 프로그래밍 언어를 하나 더 만드는 일에 가깝습니다. 저는 지금 대부분의 팀에게 맞는 것은 spec-first 이고, 오래 유지할 핵심 기능 몇 개에만 spec-anchored 를 걸어 보는 정도라고 봅니다.

스펙을 자세히 쓸수록 그대로 따른다는 기대의 한계

SDD 를 처음 접하면 이런 기대를 하게 됩니다. 스펙을 꼼꼼히 쓸수록 에이전트가 그만큼 정확하게 따를 것이라는 기대입니다. Böckeler 가 2025년 9월에 Kiro 와 Spec Kit 을 직접 써 보고 남긴 기록은 이 기대가 어디서 틀리는지 보여 줍니다.

첫째, 에이전트는 스펙을 다 따르지 않았습니다. 그녀는 「에이전트가 결국 모든 지시를 따르지는 않는 것을 자주 봤다」고 썼습니다. Spec Kit 에서는 에이전트가 앞 단계에서 만든 조사 노트를 무시하고 처음부터 다시 만들어 중복을 남겼습니다. 반대 방향의 실패도 있었습니다. 헌법의 한 조항을 지나치게 따르느라 일을 부풀린 것입니다. 문서가 많아질수록 사람은 통제하고 있다고 느끼는데, 그 느낌이 실제 통제보다 크다는 것이 그녀의 지적입니다. 이것은 컨텍스트 엔지니어링에서 다루는 문제와 같은 뿌리입니다. 맥락에 들어간 글이 많을수록 모델이 그 글을 고르게 쓰지 못합니다.

둘째, 일의 크기와 상관없이 같은 절차를 밟습니다. 작은 버그 하나를 Kiro 에 맡겼더니 사용자 스토리 4개와 인수 조건 16개가 나왔습니다. Spec Kit 은 작은 기능 하나에 마크다운 파일 8개를 만들었습니다. 그녀는 「이 마크다운 파일들보다 차라리 코드를 리뷰하겠다」고 썼습니다. GitHub 도 발표 글에서 마크다운 파일이 많아지면 감당하기 어렵다는 점을 아직 풀지 못한 질문으로 남겼습니다.

Thoughtworks 는 2025년 11월 기술 레이더에서 SDD 를 Assess 칸에 넣었습니다. 써 보며 이해해 둘 가치는 있지만 채택을 권하는 단계는 아니라는 뜻입니다. 이유로는 절차가 정교하고 도구마다 고집이 세다는 점, 리뷰하기 힘든 긴 스펙 파일을 만든다는 점을 들었습니다.

폭포수, 모델 주도 개발과 갈리는 조건

이제 처음의 질문으로 돌아갈 수 있습니다. 폭포수의 문제는 문서를 먼저 쓴 것이 아니었습니다. 몇 달 치 요구사항을 한 번에 확정하고, 구현하면서 알게 된 것을 되돌려 반영할 길이 없었던 것이 문제였습니다.

SDD 의 단위는 프로젝트가 아니라 기능 하나, 변경 하나입니다. Spec Kit 이 스펙마다 브랜치를 만드는 것도 그래서입니다. 스펙을 쓰고, 에이전트가 구현하고, 사람이 확인하는 한 바퀴가 몇 시간 안에 돕니다. 구현하다 스펙이 틀렸다는 것을 알면 스펙을 고치고 다시 돌리면 됩니다. 에이전트에게 코드를 다시 쓰게 하는 비용이 낮아졌기 때문에 가능한 순서입니다. 이 점에서 SDD 는 폭포수보다 테스트를 먼저 쓰는 TDD 에 가깝다고 저는 봅니다. 기대하는 동작을 먼저 고정하고 구현을 거기에 맞추는 구조가 같고, 고정하는 것이 테스트 코드가 아니라 문장이라는 점만 다릅니다.

그렇다고 경계할 역사가 없는 것은 아닙니다. Böckeler 는 spec-as-source 가 모델 주도 개발(MDD)을 떠올리게 한다고 썼습니다. 그림이나 모델에서 코드를 생성하겠다던 MDD 는 업무 시스템에서는 끝내 자리 잡지 못했습니다. 추상화 수준이 어정쩡하고 부담과 제약이 너무 컸기 때문입니다. 그녀의 걱정은 SDD 가 MDD 의 경직성과 LLM 의 비결정성을 둘 다 물려받을 수 있다는 것입니다. 실제로 Tessl 에서 같은 스펙으로 코드를 여러 번 만들었을 때 결과가 달라지는 비결정성을 봤다고 적었습니다. MDD 의 생성기는 적어도 같은 입력에 같은 코드를 냈습니다.

루프와 하네스 안에서 스펙이 맡는 일

SDD 를 독립된 방법론으로 보면 무겁게 느껴집니다. 에이전트를 돌리는 구조의 일부로 보면 역할이 분명해집니다.

에이전트를 반복해서 돌리는 루프에는 「언제 멈추는가」가 있어야 합니다. 스펙의 인수 조건은 그 멈춤 조건을 사람이 읽을 수 있는 문장으로 미리 적어 둔 것입니다. EARS 문장 하나가 시험 하나로 옮겨지면, 루프는 그 시험이 모두 통과할 때 멈추면 됩니다. Anthropic 이 긴 작업용 하네스에서 기능 목록마다 통과 여부를 적어 두게 한 것도 같은 생각입니다.

여러 세션이나 여러 에이전트가 일을 나눌 때도 스펙은 쓸모가 있습니다. 대화 기록은 넘겨줄 수 없어도 스펙 파일은 넘겨줄 수 있습니다. 새 세션이 「무엇을 왜 만들고 있었나」를 대화가 아니라 파일에서 다시 읽게 되는 것입니다. 이때 중요한 것은 스펙 전체를 매번 맥락에 넣지 않는 것입니다. 지금 작업에 해당하는 요구사항 몇 줄만 꺼내 읽게 하는 편이 앞에서 본 「지시를 다 따르지 않는」 문제를 덜 일으킵니다.

작은 일에는 꺼내지 않는 기준

Böckeler 는 SDD 가 어디에 맞는지를 문제의 크기와 문제가 얼마나 분명한지 두 축으로 물었습니다. 저는 이 두 축에 하나를 더해 판단합니다. 결정이 몇 개나 숨어 있는가입니다.

오타 수정이나 버튼 색 변경처럼 숨은 결정이 없는 일에는 스펙이 필요 없습니다. 바로 시키고 결과를 보면 됩니다. 비밀번호 재설정처럼 크기는 작아도 보안과 사용자 경험에 걸친 결정이 여럿 숨은 일은, 스펙 파일 여러 개까지는 아니어도 EARS 문장 몇 줄은 먼저 적을 가치가 있습니다. 여러 날에 걸쳐 여러 세션이 나눠 할 기능이라면 그때 Spec Kit 이나 Kiro 같은 절차를 다 밟는 것을 고려합니다. 처음부터 절차를 다 들이면 작은 일까지 무거워지고, 그러면 사람들은 절차를 건너뛰기 시작합니다.

아직 풀리지 않은 숙제

여기 인용한 자료는 대부분 2025년 9월부터 11월 사이의 것입니다. Böckeler 도 도구가 빠르게 바뀌어서 자신이 쓴 뒤에 이미 달라졌을 수 있다고 적었고, Thoughtworks 레이더의 이 항목도 지금 판에서는 빠져 있습니다. 도구의 세부는 바뀌었을 가능성이 큽니다.

변하지 않을 것 같은 질문도 있습니다. 스펙과 코드가 어긋날 때 어느 쪽을 고치는가, 그리고 그 어긋남을 누가 발견하는가입니다. spec-first 에서는 작업이 끝나면 스펙을 버리니 이 질문이 생기지 않습니다. spec-anchored 이상으로 가려면 이 질문에 답이 있어야 하는데, 저는 아직 설득력 있는 답을 보지 못했습니다. 그래서 지금 SDD 를 들인다면 스펙을 정본으로 모시기보다는, 에이전트에게 숨은 결정을 미리 건네는 작업 메모로 쓰는 쪽에서 시작하겠습니다.

참고: Spec-driven development with AI (GitHub) · Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl · Diving Into Spec-Driven Development With GitHub Spec Kit · Thoughtworks Technology Radar: Spec-driven development