본문은 버기타 뵈켈러(Birgitta Böckeler)의 글 <Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl>을 번역한 글입니다. 버기타 뵈켈러는 Thoughtworks의 수석 엔지니어이자 AI 지원 개발 전문가로, 소프트웨어 개발자, 아키텍트, 기술 리더로서 20년 이상의 경력을 가지고 있습니다. 필자에게 허락받고 번역과 게재를 진행했습니다.

소프트웨어 개발은 인공지능(AI) 코딩 도구의 등장으로 급변하고 있으며, 그중 스펙 주도 개발(Spec-driven development, SDD)은 최근 주목받는 용어입니다. 이번 글에서는 SDD 도구를 표명하는 세 가지 도구(Kiro, spec-kit, Tessl)를 분석하고 그 의미를 살펴봅니다.

정의: SDD란 무엇이며, 왜 등장했는가?

SDD는 빠르게 발전하는 분야에서 새로 등장한 용어인 만큼 정의가 유동적이지만, 현재까지 파악된 핵심은 코드를 작성하기 전에 "스펙(spec)"을 작성하는 것을 의미합니다. "문서 우선(documentation first)" 방식이라고도 할 수 있습니다. 따라서, 이때 스펙이라 함은 인간 개발자와 AI 모두에게 신뢰할 수 있는 단일 소스(source of truth) 역할을 합니다.

GitHub는 "소프트웨어를 유지보수 한다는 것은 스펙을 발전시키는 것을 의미한다"고 설명하며, 보다 추상화된 개발의 공용어가 스펙에 쓰이며, 코드는 최종 단계에 접하는 것으로 변화한다고 봅니다. Tessl은 "코드 대신 스펙을 주요 결과물로 두는 개발 방식"을 제시합니다. 스펙은 구조화되고 테스트 가능한 언어로 의도를 설명하고, 에이전트가 이에 맞춰 코드를 생성한다고 정의합니다.

이처럼 용어를 사용하는 방식과 SDD 구현을 표방하는 몇몇 도구들을 살펴보면, 실제로는 몇 가지 구현 단계가 있어 보입니다.

스펙 우선(Spec-first): 잘 정리된 스펙을 먼저 작성하고, 이를 AI와 함께 개발하는 과정에서 활용하는 방식입니다.
스펙 고정형(Spec-anchored): 작업 완료 후에도 스펙을 유지하여, 해당 기능의 변경과 유지보수에 계속 활용합니다.
스펙을 소스로(Spec-as-source): 스펙이 시간이 지남에 따라 주요 소스 파일이 되며, 개발자는 스펙만 수정하고 코드는 직접 건드리지 않습니다.

물론 현재까지 발견된 모든 SDD 접근 방식과 정의는 스펙 우선 방식으로, 스펙 고정형이나 스펙을 소스로 삼는 단계까지는 고려하지 않고 있습니다. 그로 인해 스펙 유지 관리 전략은 모호한 상태로 기준 없이 방치되어 있습니다.

스펙이란 무엇인가?

이렇게 SDD를 정의할 때, 가장 중요한 질문은 당연하게도 "스펙이란 무엇인가?"입니다. 아직 보편적으로 받아들여지는 정의는 없지만, "제품 요구 사항 문서(PRD, Product Requirements Document)"와 가장 유사하다고 볼 수 있습니다.

지금은 용어가 많이 혼란스럽지만, 제가 내린 정의를 소개합니다.

스펙은 자연어로 작성된 구조화되고 행동 지향적인 결과물 혹은 관련 결과물의 집합이며, 소프트웨어 기능을 자연어로 표현해서 AI 코딩 에이전트에게 지침을 제공하는 역할을 합니다.

실제 각각의 SDD 사례를 보면 스펙의 구조, 세부 수준, 그리고 프로젝트 내에서 스펙이 조직되는 방식을 정의합니다.

특히, 스펙과 코드 전체의 맥락을 설명하는 일반적인 문서를 비교하는 일이 유용할 수 있습니다. SDD에서 일반적인 맥락은 규칙을 작성한 파일이나 제품 또는 코드에 대한 추상적인 설명들에 해당합니다. 일부 도구는 이들을 기억 은행(memory bank)이라고 부르는데, 이 글에서도 그 표현을 사용하려고 합니다. 이 파일들은 코드 베이스 내의 모든 AI 코딩 세션 전반에 걸쳐 관련이 있지만, 스펙은 특정 기능을 생성하거나 변경하는 작업에만 관련됩니다.

SDD 도구 평가의 어려움

SDD 도구와 접근 방식을 실제 개발 환경과 밀접하게 평가하는 것은 매우 시간이 많이 걸리는 일입니다. 다양한 규모의 문제 해결에 시도해 봐야 하고, 신규 프로젝트(greenfield)인지 아니면 기존 프로젝트(brownfield)인지에 따라, 생성된 중간 결과물을 대충 훑어보는 것을 넘어 시간을 들여 검토하고 수정하는 일도 필요합니다. GitHub의 spec-kit 블로그 게시물에서도 "무엇보다 중요한 건, 당신의 역할이 단순히 방향을 잡는 것에 그치지 않는다는 점입니다. 검증하는 역할을 맡아야 합니다. 단계마다 스스로 되돌아보고 지속적으로 개선해야 합니다"라고 말합니다.

제가 시도한 세 가지 도구 중 두 가지는 기존 코드 베이스에 도입할 경우 훨씬 더 많은 작업이 필요해 보였기 때문에, 기존 코드 베이스(brownfield)에서의 유용성을 평가하기는 더욱 어렵습니다. 실제로 사람들이 자신의 코드 베이스에서 상당 기간 이 도구를 사용한 경험이 나오기 전까지는 이 방식이 실제 생활에서 작동할 수 있을지는 많은 의문을 가지고 있습니다.

세 가지 SDD 도구 분석: Kiro, Spec-kit, Tessl

세 가지 도구는 매우 빠르게 발전하고 있기 때문에, 제가 사용했을 때와는 이미 달라졌을 수 있다는 점을 유의해야 합니다.

Kiro: 가장 가벼운 스펙 우선 접근 방식

Kiro는 세 가지 도구 중 가장 단순하고 가벼운 도구입니다. 스펙 우선 방식으로 볼 수 있고, 조사에 따르면 모든 예시가 하나의 작업이나 사용자 스토리에 쓰였습니다. 여러 작업을 거치며 스펙 기반 유지 방식으로 요구 사항 문서를 사용하는 방법에 대한 언급은 없었습니다.

작업 흐름: 요구 사항(Requirements) → 설계(Design) → 작업(Tasks)

각 작업 단계는 하나의 마크다운 문서로 표현되며, Kiro는 VS Code 기반 배포판 내에서 이 세 단계를 안내합니다.

요구 사항: 목록 형태로 구성되며, 각 요구 사항은 "As a" 형식의 사용자 스토리(User Story)와 "GIVEN... WHEN... THEN..." 형식의 수용 기준(acceptance criteria)을 표현합니다.

설계: 제 경우 설계 문서는 특정 단락으로 구성했지만, 일관된 구조인지 작업에 따라 변하는지는 확실치 않습니다.

작업: 요구 사항 번호로 추적되는 작업 목록이며, 각 작업을 하나씩 실행하고 변경 사항을 검토할 수 있는 추가 UI 요소가 제공됩니다.

Kiro는 메모리 뱅크 개념을 가지고 있으며, 이를 "스티어링(steering)"이라고 부릅니다. 유연성이 특징으로, 작업 흐름이 특정 파일에 의존하는 것 같지는 않습니다. Kiro가 스티어링 문서를 생성하도록 요청했을 때, 기본적으로 생성되는 형태는 product.md, structure.md, tech.md입니다.

Spec-kit: GitHub의 구조화된 접근 방식

Spec-kit은 GitHub의 SDD 버전으로, CLI(명령줄 인터페이스)로 배포됩니다. 그래서, AI 코딩 어시스턴트를 쓸 때 다양한 범위로 작업 공간에서 설정을 생성할 수 있습니다. 첫 설정을 마치고 나면, 개발자는 코딩 어시스턴트에서 슬래시 명령을 통해 spec-kit을 호출합니다.

이 도구에서는 모든 결과물이 작업 공간에 즉시 배치되며, 세 가지 도구 중 사용자 입맛에 맞추는 데는 가장 우수합니다.

작업 흐름: 헌장(Constitution) → 스펙화(Specify) → 계획(Plan) → 작업(Tasks)

Spec-kit의 메모리 뱅크 개념은 SDD 접근 방식의 전제 조건입니다. 이들은 이를 헌장(Constitution)이라고 부릅니다. 이러한 헌장은 "불변적"이며 모든 변경에 항상 적용되어야 하는 높은 수준의 원칙을 포함해야 합니다. 작업 흐름 내내 강력하게 적용할 규칙 파일과 같습니다.

각 작업 단계(스펙화, 계획, 작업)에서 spec-kit은 Bash 스크립트와 템플릿을 사용하여 파일과 프롬프트를 생성합니다. 작업 흐름은 파일 내의 체크리스트를 광범위하게 사용하여 필요한 사용자 설명, 헌장 위반, 연구 활동 따위를 추적합니다. 이 체크리스트는 각 작업 단계에 대한 "완료 정의(definition of done)"와 같지만, AI에 의해 해석되므로 100% 준수를 보장할 수는 없습니다.

아래는 spec-kit에서 제가 본 파일 구조를 정리한 개요입니다. 하나의 스펙이 여러 파일로 구성된다는 점에 주목하세요.

Spec-kit은 언뜻 보기에 스펙 고정형(spec-anchored)을 지향하는 것처럼 보입니다. GitHub는 "우리는 스펙을 정적인 문서가 아니라, 프로젝트와 함께 진화하는 살아있는, 실행 가능한 결과물로 발전시키고 있습니다. 스펙은 공유할 수 있는 진실의 근원이 됩니다"라고 말합니다.

그러나 이러한 언급과 달리, spec-kit은 생성되는 모든 스펙에 대해 브랜치를 생성하는데, 그 과정에서 스펙은 기능의 수명이 아닌 변경 요청의 수명 동안만 유효한 결과물로 간주됩니다. 이에 대한 커뮤니티 논란도 있을 정도입니다. 이로 인해 spec-kit은 스펙 고정형이 아닌, 여전히 스펙 우선 방식으로 간주됩니다.

Tessl Framework: 스펙을 소스로 추구하는 접근 방식

Spec-kit과 마찬가지로, Tessl Framework는 다양한 코딩 어시스턴트의 작업 공간과 다양한 구조의 구성을 생성할 수 있는 CLI로 배포됩니다.

Tessl은 이 세 도구 중 유일하게 스펙 고정형 접근 방식을 명시적으로 지향하며, 심지어 스펙을 소스로(spec-as-source) 삼는 수준까지 탐색하고 있습니다. Tessl에서 스펙은 유지보수하고 편집하는 주요 결과물 역할을 할 수 있습니다.

이러한 스펙으로 만들어지는 코드는 상단에 // GENERATED FROM SPEC - DO NOT EDIT와 같은 주석으로 표시될 수 있습니다. 현재는 스펙과 코드 파일 간에 1:1 매핑이 있지만, Tessl 팀은 다양한 버전을 실험하고 있으므로 하나의 스펙이 여러 파일로 구성된 코드 컴포넌트에 매핑되는 방식으로 발전할 가능성도 있습니다. (테슬 팀은 그들의 프레임워크를 현재 공개된 제품인 테슬 레지스트리보다 더 미래지향적인 것으로 보고 있습니다)

다음은 기존 코드 베이스의 JavaScript 파일에서 Tessl CLI의 역공학 명령어(tessl document --code ...js)를 사용해 만든 스펙 예시입니다.

@generate 또는 @test와 같은 태그는 Tessl에게 무엇을 생성할지 알려주는 것으로 보입니다. API 섹션은 코드 베이스의 다른 부분에 노출되는 인터페이스를 최소한으로 스펙에서 정의하여, 생성된 컴포넌트의 중요한 부분이 유지보수자의 통제 하에 있도록 보장하고자 하는 의도를 보여줍니다. 이 스펙에 대해 tessl build 명령을 실행하면 해당하는 JavaScript 코드 파일이 생성됩니다.

스펙을 코드 파일마다 상당히 낮은 추상화 수준에 두는 것은 LLM이 수행해야 하는 단계와 해석의 양을 줄여 오류 가능성을 낮춥니다. 그러나 이 낮은 추상화 수준에서도 동일한 스펙에서 코드를 여러 번 생성했을 때 비결정론(non-determinism)적 결과를 목격했습니다. 이처럼 스펙을 반복하고 더 구체적으로 만들어 같은 결과가 나올 가능성을 높이는 과정은, 명확하고 완전한 스펙 작성의 어려움을 다시 확인시켜 줍니다.

관찰 결과와 의문점: SDD의 실제 적용 가능성

세 도구는 모두 스펙 주도 개발을 구현했다고 주장하지만, 서로 상당히 다릅니다. 따라서 SDD 도구에 대해 이야기할 때는 이들이 바라는 SDD가 동일한 하나의 개념이 아니라는 점을 염두에 두어야 합니다.

모든 규모에 맞는 하나의 작업 흐름이 있을까?

Kiro와 spec-kit은 각기 독자적인 작업 흐름을 제공하지만, 이들 중 어느 것도 실제 코딩으로 해결할 문제에 충분히 부합하지 않다고 확신합니다. 특히, 보편적인 적용을 위해서는 충분히 다양한 문제 규모를 수용할 수 있어야 하는데, 그 부분이 명확하지 않습니다.

예를 들어, Kiro에게 작은 버그 수정을 요청했을 때 (이전에 Codex로 해결하려고 시도했던 것과 동일한 버그), 이 도구가 보여준 작업 흐름은 "못 하나 박으려고 거대한 해머를 사용하는 것"과 같다는 것이 금세 명확해졌습니다. 이렇게 작은 버그를 해결하기 위해 요구 사항 문서는 4개의 "사용자 스토리"와 총 16개의 수용 기준을 포함하게 되었습니다. 여기에는 “사용자 스토리: 개발자로서, 새로운 카테고리 형식이 도입될 때 시스템이 견고하게 유지되도록 변환 함수가 예외적인 경우(edge cases)를 우아하게 처리하기를 원한다” 같은 내용이 포함됩니다.

Spec-kit을 사용할 때도 비슷한 어려움이 있었습니다. 이 도구는 어떤 규모의 문제에 적합한지 확신이 서지 않습니다. 공개된 튜토리얼은 보통 처음부터 애플리케이션을 만드는 것을 기반으로 하는데, 이는 튜토리얼을 만들기 가장 쉬운 방식일 뿐입니다. 제가 시도한 것들 중 하나는 기존 대시보드의 데이터를 요약하는 개요를 모달 형태로 구축하는 기능이었습니다 (과거 팀에서는 3~5점짜리 스토리 규모). 이를 해결하고자 spec-kit이 수행하는 단계의 수와 제가 검토해야 할 마크다운 파일의 양은 문제의 규모에 비해 지나치게 복잡하다고 느껴졌습니다. Kiro를 사용했을 때보다는 더 큰 문제였지만, 작업 흐름도 훨씬 복잡했습니다. 저는 결국 전체 구현을 끝내지 못했습니다. 다만, spec-kit의 결과를 실행하고 검토하는 데 걸린 시간 동안 ‘일반적인’ AI 지원 코딩으로 기능을 구현하는 것이 훨씬 더 편안하게 상황을 통제할 수 있겠다고 느꼈습니다.

따라서 앞으로 나올 효과적인 SDD 도구는 최소한 다양한 크기와 유형의 변경 사항을 처리할 수 있도록 몇 가지 핵심 작업 흐름에 대한 유연성을 제공해야 합니다.

코드 검토가 마크다운 검토로 대체된 것 아닌가?

앞서 언급했듯이, spec-kit은 저자가 검토해야 할 엄청나게 많은 마크다운 파일을 생성했습니다. 이 파일들은 꾸준히 나왔었고, 이미 존재하는 코드와도 서로 반복되었으며, 일부는 중복을 포함하고 있었습니다. 무엇보다 전반적으로 매우 장황하고 검토하기가 지루했습니다. 반면 Kiro에서는 조금 더 쉬웠는데, 파일이 3개만 생성되기 때문에 "요구사항 > 설계 > 작업"이라는 모델을 이해하기도 더 직관적이었습니다. 하지만 앞서 언급했듯이, 제가 고치려 했던 작은 버그에 비해 Kiro 역시 지나치게 상세한 설명이 많았습니다.

솔직히 말해, 저는 이 모든 마크다운 파일보다는 코드를 검토하는 게 더 낫습니다. 효과적인 SDD 도구는 매우 우수한 스펙 검토 경험을 제공해야 합니다.

통제하고 있다는 착각?

이 모든 파일, 템플릿, 프롬프트, 작업 흐름과 체크리스트에도 불구하고, 에이전트가 궁극적으로 지침을 따르지 않는 경우를 자주 보았습니다. 스펙 주도 개발의 동력 중 하나로 종종 언급되는 컨텍스트 창이 이제 더 커졌다는 것은 사실이지만, 창이 크다고 해서 AI가 그 안에 있는 모든 것을 적절하게 파악한다는 의미는 아닙니다.

예를 들어, spec-kit은 계획을 수립할 때, 이를 연구하는 단계를 가지고 있습니다. 기존 코드와 이미 존재하는 것에 대해 많은 연구를 수행하는 방식이야 좋았지만, 궁극적으로 에이전트는 이것이 기존 클래스에 대한 설명이라는 메모를 무시하고, 이를 새로운 사양으로 간주하여 모든 것을 다시 생성해서 중복을 만들었습니다. 지침을 무시하는 예뿐만 아니라, 에이전트가 지침을 너무 열성적으로 따랐기 때문에 지나치게 행동하는 경우도 보았습니다.

과거 경험은 우리가 구축하는 것을 통제하는 가장 좋은 방법은 작고 반복적인 단계를 밟는 것임을 보여주었습니다. 따라서 지나치게 장황한 경우, 사전 스펙 설계를 많이 하는 방법이 좋은 아이디어인지에 대해 저는 매우 회의적입니다. 효과적인 SDD 도구는 반복적인 접근 방식을 수용해야 하지만, 작은 작업 패키지는 SDD의 아이디어와 거의 상반되는 것처럼 보입니다.

기능적 스펙와 기술적 스펙을 효과적으로 분리하는 방법

SDD에서 기능적 스펙와 기술적 스펙을 의도적으로 분리하는 것은 일반적인 아이디어입니다. 이 작업의 궁극적인 목표는 AI가 모든 솔루션과 세부 사항을 채우고, 동일한 스펙을 활용해 다른 기술적 선택으로 전환할 수 있도록 하는 방향일 것입니다.

그러나 현실적으로, spec-kit을 시도했을 때, AI는 기능적 수준에 머물러야 할 때와 기술적 세부 사항을 추가해야 할 때를 자주 혼동했습니다. 튜토리얼과 문서도 일관성이 없었으며, "순수하게 기능적(purely functional)"이라는 것이 실제로 무엇을 의미하는지에 대한 해석이 다른 것 같았습니다. 과거 경험을 되짚어 보면 요구 사항과 구현을 제대로 분리하지 못한 수많은 사용자 스토리를 만들었을 때, 개발 전문가인 제가 이 작업을 잘 수행한 좋은 기억은 없었다고 생각합니다.

대상 사용자는 누구인가?

SDD 도구의 데모와 튜토리얼 중 다수는 제품과 기능 목표를 정의하는 것과 같은 내용을 포함하며, "사용자 스토리"와 같은 용어까지 통합합니다. 이러한 아이디어는 AI를 교차 기술을 위한 조력자로 사용하여 개발자가 요구 사항 분석에 더 적극적으로 참여하도록 하거나, 제품 담당자와 짝을 이루어 작업하도록 하려는 것일 수 있습니다. 하지만 이러한 점이 명시적으로 설명되지 않았기에, 개발자가 이 모든 분석을 수행하는 것이 당연한 것처럼 제시됩니다.

이러한 경우, 저자는 SDD가 어떤 문제 규모와 유형을 위한 것인지 다시 되묻게 됩니다. 아직 이 방식이 매우 불명확한 대규모 기능을 위한 상태는 아닐 것입니다. 그러한 기능은 분명히 더 전문적인 제품과 요구 사항 기술과 연구, 그리고 이해관계자 참여와 같은 다른 많은 단계를 필요로 할 것이기 때문입니다.

스펙 기반 유지와 스펙을 소스로: 과거로부터 배우고 있는가?

많은 사람이 SDD를 TDD(테스트 주도 개발) 또는 BDD(행동 주도 개발) 사이의 무언가로 유추하지만, 특히 스펙을 소스로 삼는 접근 방식에서 살펴봐야 할 또 다른 중요한 모델은 MDD(모델 주도 개발)입니다.

저는 경력 초기에 MDD를 광범위하게 사용했던 프로젝트에 참여한 적이 있는데, Tessl Framework를 사용하면서 계속해서 그때 적용했던 MDD를 떠올렸습니다. MDD의 모델은 기본적으로 스펙이지만, 자연어가 아닌 맞춤형 UML 또는 텍스트 DSL 등으로 표현되었으며, 개발자들은 맞춤형 코드 생성기를 구축하여 이 스펙을 코드로 변환하고는 했습니다.

궁극적으로 MDD는 비즈니스 애플리케이션에서는 성공하지 못했습니다. 어색한 추상화 수준에 머물렀고 너무 많은 부가 작업과 제약 조건을 만들었기 때문입니다.

하지만 LLM은 MDD의 일부 부가 작업과 제약 조건을 제거하여, 이제 개발자가 스펙 작성에 집중하고 코드만 생성할 수 있다는 새로운 희망을 제시합니다. LLM을 사용하면 미리 정의된 상태로 구문 분석이 가능한 스펙 언어에 더 이상 구애받지 않으며, 정교한 코드 생성기를 구축할 필요도 없습니다. (물론 그를 얻기 위해 내줘야 할 대가는 LLM의 비결정론입니다.) 또한 구문 분석 가능한 구조라는 특징은 우리가 지금 얻지 못한 장점도 가지고 있었습니다: 스펙 작성자에게 유효하고 완전하며 일관된 스펙을 작성할 수 있도록 많은 도구를 지원할 수 있다는 점입니다.

다만, 저는 스펙을 소스로 삼는 방식, 그리고 나아가 스펙 기반 유지 방식이 MDD와 LLM의 단점, 즉 비유연성과 비결정론을 모두 가지지는 않을지 의문이 듭니다.

이러한 우려는 과거 MDD 경험에 향수를 느끼며 "그것을 다시 가져오자"고 말하는 것이 아니라, 오늘날 스펙 주도 개발을 탐구할 때 과거의 '스펙으로부터 코드를 생성하려는 시도'를 참고하여 배워야 한다고 강조하려는 시도입니다.

마치며

개인적으로 AI 지원 코딩을 사용할 때, 저 역시 코딩 에이전트에게 제공할 어떤 형태의 스펙을 신중하게 작성하는 데 시간을 할애합니다. 따라서 스펙 우선이라는 일반적인 원칙은 많은 상황에서 분명히 가치가 있으며, 그 스펙을 구조화하는 방법에 대한 다양한 접근 방식은 매우 중요하게 모색되고 있습니다. 실제로도 실무자들 사이에서 가장 많이 나오는 질문 중에는 "메모리 뱅크를 어떻게 구조화해야 할까요?" 또는 "AI를 위한 좋은 사양 및 설계 문서를 어떻게 작성해야 할까요?"와 같은 것들이 포함됩니다.

그러나 "스펙 주도 개발"이라는 용어는 아직 잘 정의되지 않은 상태에서, 이미 지나치게 의미론적으로 확산되었습니다. 그러다 보니 최근 사람들이 "스펙"을 사실상 "상세한 프롬프트"의 동의어로 사용하는 것까지 들었습니다.

제가 시도한 도구들의 실제 유용성에 대해서는 많은 의문이 남아 있습니다. 저는 일부 도구가 우리의 기존 워크플로우를 너무 문자 그대로 AI 에이전트에게 주입하려고 시도하며, 결과적으로 검토 과부하 및 환각과 같은 기존의 어려움을 증폭시키는 것이 아닌지 궁금해합니다. 특히 많은 파일을 생성하는 더 정교한 접근 방식에서는, 독일어의 복합어인 "Verschlimmbesserung"(개선을 시도했지만 오히려 상황을 악화시키는 행위)을 떠올리지 않을 수 없었습니다.