스팩 기반 개발 이해: Kiro, spec-kit 및 Tessl | Birgitta Böckeler

dimohy · 10월 21, 2025, 10:39오후

ai #Spec-Driven-Development sdd도구 #코드생성 ai 어시스턴트

Spec-Driven Development의 정의와 세 가지 구현 수준

핵심 개념: Spec-driven development(SDD)는 AI 코딩 이전에 명확한 스펙(사양)을 작성하는 “문서-우선” 접근법입니다. 스펙은 인간과 AI 모두의 신뢰할 수 있는 정보원이 되며, GitHub는 "유지보수란 사양의 진화를 의미한다"고 정의하고, Tessl은 "스펙이 아닌 코드가 주요 산물인 개발 접근법"으로 표현합니다.

세 가지 구현 수준:

Spec-first: 초기 계획 단계에서만 스펙 사용, 완료 후 삭제
Spec-anchored: 기능 생성 후에도 스펙 유지, 진화 단계에서 지속 편집
Spec-as-source: 스펙이 유일한 마스터 문서, 코드는 // GENERATED FROM SPEC - DO NOT EDIT 주석으로 표시

1단계: 필수 이해 사항 - SDD의 개념과 적용 범위

스펙과 메모리 뱅크의 차이점

스펙은 특정 기능 개발/변경을 위한 구조화된 행동-지향 산물이며, 메모리 뱅크(또는 스티어링)는 전체 코드베이스에 걸친 일반적 맥락 문서입니다. 메모리 뱅크에는 규칙 파일, 고수준 제품 설명, 아키텍처 개요가 포함되며, 스펙은 해당 기능 개발에만 관련됩니다.

SDD 도구 평가의 어려움

실제 사용과 유사한 방식으로 SDD 도구를 평가하려면 다양한 크기의 문제, 녹지 필드 및 갈색 필드 프로젝트에서 반복적으로 테스트해야 합니다. GitHub의 spec-kit 블로그가 강조하듯이 "당신의 역할은 단순히 조종하는 것이 아니라 검증하는 것"입니다. 각 단계에서 중간 산물을 반영하고 개선해야 합니다.

2단계: 세 가지 주요 SDD 도구 상세 분석

Kiro: 경량형 워크플로우

특징: VS Code 기반 배포, 가장 단순한 구조

워크플로우: Requirements → Design → Tasks

Requirements: “As a…” 형식의 사용자 스토리와 “GIVEN… WHEN… THEN…” 형식의 수용 기준으로 구조화
Design: 컴포넌트 아키텍처, 데이터 흐름, 데이터 모델, 오류 처리, 테스트 전략, 구현 접근법, 마이그레이션 전략 포함
Tasks: 요구사항 번호로 추적 가능한 작업 목록, UI 요소로 작업 실행 및 변경사항 검토 제공

메모리 뱅크(스티어링): 유연한 내용 구조, 기본적으로 product.md, structure.md, tech.md 파일 생성

주의사항: 작은 버그 수정도 4개의 사용자 스토리와 16개의 수용 기준으로 확대되어 과도한 복잡성 발생

Spec-kit: 맞춤형 CLI 기반 접근

특징: GitHub 공식 SDD 도구, 다양한 AI 어시스턴트 지원, CLI로 VS Code 구조 생성

워크플로우: Constitution → ↻ Specify → Plan → Tasks ↺

Constitution이 전제조건 역할, “불변의” 고수준 원칙 포함
각 단계에서 bash 스크립트와 템플릿으로 파일/프롬프트 생성
체크리스트를 통해 사용자 확인, 헌법 위반, 연구 작업 추적 (각 단계의 “완료 정의”)

파일 구조: 하나의 스펙이 8개 파일로 구성 (data-model, plan, tasks, spec, research, api, component 등)

현황: GitHub는 “spec-anchored 접근” 추구를 표방하나, 각 스펙마다 브랜치 생성으로 인해 실제로는 spec-first만 구현 중으로 보임

문제점: 검토할 마크다운 파일이 과도하게 많고 반복적이며 장황함

Tessl Framework: 스펙-소스 추구 (비공개 베타)

특징: CLI 기반, 유일하게 명시적으로 spec-anchored 및 spec-as-source 수준 추구

구현 방식:

각 코드 파일마다 해당 스펙 파일 1:1 매핑 (현재, 향후 변경 가능)
코드 상단에 // GENERATED FROM SPEC - DO NOT EDIT 주석 표시
@generate, @test 같은 태그로 생성 방식 지정
tessl build 명령으로 스펙에서 코드 생성

장점: 생성된 JavaScript 코드 파일로 간단한 추상화 수준 유지, LLM의 단계/해석 수 감소

과제: 스펙이 구체할수록 코드 생성 반복 가능성 증가하나, 동일 스펙에서도 비결정론적 생성 목격됨

메모리 뱅크: .tessl/framework 폴더 + KNOWLEDGE.md, AGENTS.md 포함

주요 관찰 사항 및 해결과제

도전과제 1: 모든 규모의 문제에 맞는 단일 워크플로우?

문제: Kiro와 spec-kit 모두 고정 워크플로우를 제공하지만, 실제 개발 문제의 다양한 규모에 대응하기 어려움

사례:

Kiro로 작은 버그 수정 시: 과도한 사용자 스토리/수용 기준 생성
Spec-kit으로 3-5 포인트 규모의 기능 개발 시: 검토할 마크다운 파일 과다, 구현 미완료 상태에서 일반 AI 어시스턴트보다 효율성 낮음

개선 필요: 문제 규모와 유형에 따라 다양한 핵심 워크플로우 제공

도전과제 2: 마크다운 검토 vs 코드 검토

현황: Spec-kit은 많은 마크다운 파일을 생성하며, 파일들이 서로 반복적이고 기존 코드와도 중복 포함

실무 평가: 마크다운 파일보다 코드 검토가 더 직관적

도전과제 3: 실제 통제력이 있는가? (거짓된 통제감)

문제: AI 에이전트가 상세한 파일, 템플릿, 프롬프트, 워크플로우, 체크리스트에도 불구하고 지시사항을 미준수하거나 과도하게 준수

실제 사례:

Spec-kit 연구 단계에서 기존 클래스 설명을 새 사양으로 해석, 중복 생성
일부 헌법 조항을 과도하게 따름

원칙: 과거 경험상 소규모 반복 단계가 최고의 통제 수단, 대규모 사전 설계는 효과 의문

도전과제 4: 기능적 스펙과 기술적 스펙의 효과적 분리

목표: 기능적 스펙만으로 다양한 기술 스택에 적용 가능하도록 함

실제 발생 문제:

Spec-kit 사용 시 기능 수준과 기술 상세 수준 전환 시점 혼동
문서와 튜토리얼의 해석 불일치
역사적으로 요구사항과 구현을 분리하는 데 실패한 사례 다수

도전과제 5: 대상 사용자는 누구인가?

현황: 데모와 튜토리얼에 제품/기능 목표 정의, “사용자 스토리” 용어 포함 → 개발자가 단독으로 분석 수행 가정

질문:

SDD는 어떤 문제 크기를 대상으로 하는가?
미명확한 대규모 기능 개발 시 전문 제품/요구사항 분석 역량과 이해관계자 참여 필요한데, 개발자만 으로 수행 가능한가?

도표: 문제 명확성(X축) vs 문제 규모(Y축) 매트릭스에서 “SDD의 위치는?”

도전과제 6: 역사에서 배우는가? (MDD의 교훈)

SDD와 MDD 유사성:

MDD: 파싱 가능한 스펙(커스텀 UML, 텍스트 DSL)으로 코드 생성
SDD: 자연언어 스펙으로 LLM 기반 코드 생성

MDD가 실패한 이유: 추상화 수준 부적절, 과도한 오버헤드/제약

LLM의 장점: 파싱 가능 스펙 언어 불필요, 복잡한 코드 생성기 구축 불필요

LLM의 대가: 비결정론성 문제 (동일 스펙에서도 다른 코드 생성 가능)

우려사항: MDD의 유연성 부족과 LLM의 비결정론성을 모두 가질 위험 + 검증 도구 지원 상실

결론 및 종합 평가

핵심 통찰

AI 어시스턴트 사용 시 신중한 스펙 작성은 가치 있으나, "Spec-driven development"는 아직 명확히 정의되지 않음. 일부는 "스펙"을 "상세 프롬프트"와 동일시할 정도로 의미가 모호해짐.

실무적 의문

현재 도구들이 기존 워크플로우를 AI 에이전트에 과도하게 문자 그대로 적용하면서:

검토 과부하 증가
환각 현상 증가
파일 생성 과다로 체계가 더 악화되는 “Verschlimmbesserung” (독일어: 악화시키려는 시도로 더 나빠짐) 발생 우려