SDD(Spec-Driven Development) + AWS Kiro IDE 적용기

안녕하세요. 갓대희 입니다.

오늘은 실습이 아닌  간단한 이론 이야기를 하고자 한다.

 

Spec-Driven Development와 AWS Kiro IDE 에 대하여

이전 포스팅에서는 kiro를 통해 어느정도 수준의 Spec-Driven Development 진행을 하게 되었다.

1. 아마존 키로(Kiro) 설치방법 및 사용방법

2. Kiro 사용방법(1) - Kiro 스펙 기반 개발 방법(Spec Driven Development(SDD)) 사용 해보기(with RAG 개발 환경 구축)

3. Kiro 사용방법(2) - Kiro Agent Hooks, Steering 설정 예시(Agent Hooks, Steering 설정 방법 with RAG 개발 환경 구축)

 

그런데 SDD(Spec-Driven Development)라는것을 정리 하지 않고 넘어가긴 좀... 그런것 같아 간단하게나마 정리해두려고 한다.

 

기존 AI 도구들의 한계 

요즘 개발자라면 ChatGPT, GitHub Copilot, Claude 같은 AI 도구 없이는 개발이 상상도 안 되는 시절이 온 것 같다.

하지만 이런 도구들을 쓰다 보면 언젠가 공통적으로 느끼는 문제점들이 있다.

문제 상황 예시
맨 처음 "특정 함수, 기능 만들어줘"라고 요청하면,우리가 생각 한 것 이상으로 소스를 잘 뽑아 낸다.
하지만 "이 부분 수정해줘"라고 하면 AI 본인?? 이 짠 소스임에도 기억을 못하고 ( 전체 맥락을 잃어버리고 ) 방황하게 된다.
몇번 대화하다보면 기억을 잃어버려, AI에게 전체 코드를 다시 설명해야 하고, 일관성도 떨어진다.
더 큰 문제는 생성된 코드가 왜 이렇게 만들어졌는지, 어떤 요구사항을 반영한 건지 추적하기 어렵다는 점이다.

이런 방식을 개발 커뮤니티에서는 "Vibe Coding"이라고 부른다. 그때그때 감으로, 필요에 따라 코딩하는 방식이라고 정의해 보겠다. 개인 프로젝트나 프로토타입에서는 빠르고 좋지만, 실제 운영 환경이나 팀 프로젝트에서는 한계가 보이는 것 같다.

 

SDD란?

Spec-Driven Development는 이름 그대로 명세(Specification)를 중심으로 개발을 진행하는 방법론이다.

API 개발에서 주로 사용되던 개념이었는데, AI 시대와 마이크로서비스의 확산으로 더 넓은 영역에서 주목받고 있는것 같다.

SDD의 3단계 워크플로우

1. Spec 작성: 상세한 사용자 스토리와 수용 기준 정의
2. Technical Design: 아키텍처와 구현 방법 설계
3. Task Breakdown: 추적 가능한 구현 작업으로 분해

핵심은 추적성(Traceability)이다. 작성된 모든 코드가 어떤 명세에서 나왔는지, 왜 이렇게 구현되었는지를 명확하게 추적할 수 있다.

이는 특히 엔터프라이즈 환경에서 컴플라이언스와 코드 감사가 중요한 상황에서 큰 장점이 된다.

개발 방식	개발 속도	코드 품질	추적성	유지보수성
Vibe Coding	빠름	보통	낮음	어려움
Spec-Driven	초기 느림	높음	높음	용이함

 

SDD의 핵심 원칙과 명세 전략 

SDD의 기술적 구현을 위해서는 명확한 원칙과 전략이 필요하다. 단순히 문서를 많이 작성하는 것이 아니라, AI와 인간이 모두 이해할 수 있는 구조화된 명세를 만드는 것이 핵심이다.

Contract-First Development 원칙

Contract-First Development는 SDD의 핵심 철학이다. API 계약을 먼저 정의하고 비즈니스 로직을 나중에 프로그래밍하는 패러다임으로, 코드를 먼저 작성한 후 그 행동을 설명하는 계약을 나중에 작성하는 것과 대조적이다.

• API as First-Class Citizens: API를 1급 시민으로 취급, 모든 것이 클라이언트 애플리케이션에서 사용되는 최종 제품을 중심으로 돌아감
• Consistent and Reusable APIs: API 설명 언어를 사용하여 일관되고 재사용 가능한 API 개발
• Language-Agnostic Interface: 클라이언트-서버 통신을 위한 공통 언어 정의, 다양한 프로그래밍 언어와 호환

이런 원칙들은 실제로는 다양한 형태로 구현된다. 일반적인 SDD에서는 OpenAPI와 RAML 같은 명세 언어를 사용하지만, Kiro는 독특하게도 마크다운 형식을 채택했다.

Kiro의 3개 핵심 명세 파일

• requirements.md: EARS 포맷(Easy Approach to Requirements Syntax)을 사용한 사용자 스토리와 수용 기준
• design.md: 기술적 아키텍처, 컴포넌트 상호작용, 데이터 모델 설계
• tasks.md: 구체적이고 추적 가능한 구현 작업 체크리스트

Kiro의 접근법은 일반적인 OpenAPI/YAML 명세와는 다르다. EARS 포맷을 사용하여 "WHEN [조건/이벤트] THE SYSTEM SHALL [예상 동작]" 형태로 요구사항을 구조화한다. 이는 Rolls Royce에서 개발된 텍스트 요구사항 제약 메커니즘이다.

// Kiro EARS 포맷 명세 예시 (실제 사용 패턴)

# requirements.md

## 사용자 스토리
사용자로서 할일을 관리할 수 있어야 한다.

## 수용 기준 (EARS 포맷)
WHEN 사용자가 새로운 할일을 추가할 때
THE SYSTEM SHALL 할일을 데이터베이스에 저장하고 목록에 표시한다

WHEN 사용자가 잘못된 데이터로 폼을 제출할 때
THE SYSTEM SHALL 해당 필드 옆에 검증 오류를 표시한다

WHEN 사용자가 할일을 완료로 표시할 때
THE SYSTEM SHALL 할일의 상태를 업데이트하고 시각적 표시를 변경한다

---

# design.md

## 기술 아키텍처
- Frontend: React + TypeScript + Material-UI
- Backend: Node.js + Express + Prisma ORM
- Database: PostgreSQL
- Testing: Jest

## 컴포넌트 구조
TodoList → TodoItem → TodoForm

Kiro의 마크다운 기반 명세는 AI가 이해하기 쉽도록 구조화되어 있으면서도, 개발자가 읽고 수정하기에도 직관적이다. 각 명세 파일이 명확한 역할을 가지고 있어 체계적인 개발이 가능하다.

 

AWS Kiro IDE 를 통해 SDD를 진행 해본 후기

AWS에서 2025년 7월에 퍼블릭 프리뷰로 출시한 Kiro는 SDD를 구현하고자한 IDE다.

혹시나 오해를 하실 수 있는데, 정확히 말하면 AWS 팀에서 만든 것은 맞다. 

하지만 이와는 별개로 AWS 서비스는 아니고 독립적인 Agentic IDE다. 즉 AWS의 서비스와 전혀 무관하게 AWS의 서비스를 사용하지않아도 평소 개발시에도 사용할 수 있따.

Kiro의 핵심 특징 (공식 발표 기준)

• Code OSS 기반: VS Code 설정과 플러그인 호환
• Claude Sonnet 4.0/3.7 지원(나의 경우 4.0만 보인다.): 퍼블릭 프리뷰 기간 무료 제공

• Agent Hooks: 파일 변경시 자동 실행되는 커스텀 액션
• MCP 서버 연동: 다양한 외부 도구와 통합
• 완전한 추적성: 모든 코드를 원래 명세로 역추적 가능

 

가장 Kiro에서 강조하는 부분이자 다른 IDE와의 차별점은 프로젝트를 시작할 때 Kiro가 던지는 질문을 보면 알 수 있따.

"Spec(명세)부터 시작할 건가요, 아니면 Vibe모드로 시작할 건가요?"

// 예시: 간단한 TODO API 명세

## User Story
사용자는 할일을 생성, 조회, 수정, 삭제할 수 있다.

## Acceptance Criteria
- [ ] POST /api/todos로 새로운 할일 생성
- [ ] GET /api/todos로 전체 할일 목록 조회
- [ ] PUT /api/todos/:id로 특정 할일 수정
- [ ] DELETE /api/todos/:id로 특정 할일 삭제
- [ ] 모든 응답은 JSON 형식
- [ ] 에러 처리와 상태코드 정의

## Technical Constraints
- Node.js + Express 사용
- SQLite 데이터베이스
- RESTful API 설계 원칙 준수

이런 명세를 작성하면 Kiro는 이를 바탕으로 코드, 설계 문서, 데이터베이스 스키마, API 엔드포인트를 자동으로 생성한다.

더 중요한 건 나중에 요구사항이 변경되어도 명세를 수정하면 관련된 모든 코드가 일관되게 업데이트된다는 점이다.

 

ex) 자세한 내용은 하기 링크에 작성하였따.

Kiro 스펙 기반 개발 방법(Spec Driven Development(SDD)) 사용 해보기(with RAG 개발 환경 구축)

 

ex) 개발하고자 하는 내용을 쭉 해당 Prompt에 입력하고 요청.

 

ex) requirements 생성 및 검토

 
ex) 설계 문서 생성 및 검토

 

ex) Task List 생성후 각각의 태스크 실행

 

커뮤니티 반응과 현실적 평가 

개발 커뮤니티에서 Kiro와 SDD에 대한 반응을 살펴보면, 장단점이 명확하게 나뉜다.

Hacker News 등에서 실제 피드백들을 요약해봤다.

긍정적 평가

• 일관성 유지: 여러 세션에 걸쳐 작업해도 맥락을 잃지 않음
• 엔터프라이즈 적합성: 컴플라이언스와 코드 감사 환경에 유리
• 추적성: 버그 발생시 원인을 명세까지 역추적 가능
• 단일 개발자의 생산성: 복잡한 시스템도 체계적으로 구축 가능

부정적 피드백

• 개발 속도 저하: 특히 빠른 프로토타이핑에는 부적합
• 도입 장벽: 기존 개발 환경을 완전히 재구성해야 하는 부담
• 학습 곡선: 팀원들이 새로운 방식에 적응하는 데 시간 필요

결론적으로, 프로젝트 규모와 성격에 따라 효과가 크게 달라진다는 것 같다.

큰 규모의 프로젝트나 장기간 유지보수가 필요한 시스템에서는 효과적이지만, 빠른 프로토타이핑이나 간단한 작업에는 불필요하게 느껴질수도 있을 것 같다.

 

다른 개발 방법론과의 비교

SDD가 기존 방법론들과 어떻게 다른지, 어떤 상황에서 더 유용한지 정리해보자.

개발 방법론 비교

• TDD (Test-Driven Development)
  테스트 → 구현 → 리팩토링. 코드 품질 보장하지만 전체 설계 고려 부족
• BDD (Behavior-Driven Development)
  사용자 행동 중심. 요구사항 명확하지만 기술적 제약 고려 부족
• SDD (Spec-Driven Development)
  명세 중심으로 요구사항과 기술 제약을 모두 고려한 체계적 접근

SDD의 핵심 차별점은 AI 시대에 최적화되어 있다는 점이다.

기존 방법론들은 인간 개발자를 전제로 설계되었지만, SDD는 AI와 인간의 협업을 염두에 두고 만들어졌다.

 

개발 방법론의 변천사를 간단히 살펴보자면, 흔히 개발자들이 알고있는 Waterfall은 체계성을, Agile은 유연성을, TDD는 품질을, BDD는 소통을 강조했다. SDD는 AI 협업 시대에 이 모든 요소를 통합하려는 시도이다.

TDD나 BDD와 달리 SDD는 AI와 인간의 협업을 전제로 설계되었다. 기존 방법론들이 인간 개발자 간의 협업에 초점을 맞췄다면, SDD는 AI가 명세를 이해하고 코드를 생성할 수 있도록 구조화된 정보를 제공하는 것이 핵심이다.
BDD가 "행동 중심"이라면 SDD는 "명세 중심"이다. BDD의 Given-When-Then이 사용자 시나리오에 집중했다면, SDD는 기술적 제약과 비즈니스 요구사항을 모두 포괄하는 포괄적 명세를 지향한다.

 

현재 한계와 개선 방향

Kiro와 SDD가 완벽한 것은 아니다. 현재 몇 가지 명확한 한계가 있다:

Current Limitations:

1. 명세 작성 비용: 간단한 작업에도 과도한 문서화 요구
2. 기존 코드베이스 적용 어려움: 레거시 시스템 점진적 전환 필요
3. 팀 차원의 문화 변화: 개발자들의 사고방식 전환 필요
4. AI 모델 의존성: 모델 성능에 따른 결과물 품질 편차
5. 도구의 성숙도: 아직 초기 단계로 기능적 한계 존재

하지만 이런 한계들은 대부분 시간이 해결해줄 문제들이다. AI 모델의 성능은 계속 향상되고 있고, 도구의 성숙도도 빠르게 개선되고 있다. 더 중요한 건 개발 커뮤니티가 이런 방향으로 진화하고 있다는 점이다.

 

분석을 통해 얻은 인사이트

• 패러다임의 변화: AI 시대에는 "어떻게 코딩할 것인가"보다 "무엇을 만들 것인가"가 더 중요해졌다.
• 명세의 중요성: 잘 작성된 명세는 개발 효율성과 코드 품질을 동시에 향상시킬 수 있다.
• 도구 선택의 중요성: 프로젝트 성격에 따라 적합한 도구와 방법론을 선택하는 것이 핵심이다.
• 점진적 도입 전략: 기존 프로젝트에는 단계적으로 적용하는 전략이 필요하다.
• 팀 차원의 접근: 개인이 아닌 팀 차원에서 도입해야 진정한 효과를 볼 수 있다.

 

자주 묻는 질문

Q: SDD는 기존 Agile 방법론과 충돌하나요?

A: 전혀 그렇지 않습니다. SDD는 Agile의 빠른 반복 개발 위에서 더 체계적인 명세 관리를 추가하는 개념입니다. 오히려 스프린트별 요구사항을 더 명확하게 정의할 수 있어 Agile의 효과를 높여줄 수 있습니다.

Q: Kiro 없이도 SDD를 적용할 수 있나요?

A: 물론입니다. SDD는 방법론이고 Kiro는 도구일 뿐입니다. Notion, GitLab, Confluence 등을 활용해서도 충분히 SDD를 실천할 수 있습니다. 다만 Kiro같은 전용 도구가 있으면 더 효율적입니다.

Q: 소규모 팀에서도 SDD가 유용한가요?

A: 2-3명의 소규모 팀이라면 굳이 SDD를 완전히 도입할 필요는 없습니다. 하지만 프로젝트가 6개월 이상 지속되거나 코드 복잡도가 높다면 고려해볼 만합니다.

 

미래 전망과 결론

SDD와 Kiro가 완전히 새로운 개념은 아니지만, AI 시대에 맞게 재해석된 의미는 크다.

특히 다음 몇 가지 트렌드와 맞물려 더욱 중요해질 것으로 보인다고 한다.

예상되는 발전 방향

• 도구 생태계 확장: 다양한 IDE와 플랫폼에서 SDD 지원
• 표준화 진행: 명세 작성 방법과 포맷의 표준화
• 기업 도입 확산: 대기업을 중심으로 점진적 도입

개인적으로는 SDD가 모든 개발 상황의 만능 해결책은 아니라고 본다.

하지만 복잡한 시스템을 체계적으로 개발하고 관리해야 하는 상황에서는 분명히 유용한 접근법이 될 수 있다.

특히 한국의 IT 업계에서는 문서화와 추적성이 부족한 경우가 많은데, SDD 방식이 이런 문제들을 자연스럽게 해결해줄 수 있을 것으로 기대된다. 다만 중요한 건 도구에만 의존하지 말고 방법론 자체를 이해하고 적절히 적용하는 것이다.

 

참고 자료

• Kiro 공식 사이트 - Kiro IDE 소개와 기능 설명
• GeekNews 주간 소식 - SDD와 Kiro에 대한 최신 정보
• Kiro GitHub 리포지토리 - 오픈소스 코드와 문서
• The New Stack 기사 - Kiro의 Spec-Driven 접근법 분석
• InfoQ 기사 - Beyond Vibe Coding, Amazon의 Kiro 소개

결국 중요한 건 적재적소에 맞는 도구와 방법론을 선택하는 것이다.

SDD와 Kiro도 마찬가지다. 맹목적으로 따라하기보다는, 자신의 프로젝트 특성과 팀 상황을 고려해서 점진적으로 도입해보는 것을 추천한다.