SDD란?

최근 AI Agent를 활용한 개발이 확산되면서, 구현에 앞서 요구사항과 설계를 명확하게 정의하는 Spec-Driven Development가 주목받고 있다.

AWS의 Kiro는 요구사항·설계·작업 문서를 단계적으로 작성한 뒤, 이를 바탕으로 AI가 기능을 순차적으로 구현하는 개발 흐름을 지원하는 전용 IDE까지 출시하기도 했다.

Introducing Kiro

SDD(Spec-Driven Development)는 구현에 앞서 요구사항과 제약 조건을 명세하고, 이를 기준으로 설계·구현·검증을 진행하는 개발 방식이다.

명세를 먼저 작성하는 방식 자체는 새로운 개념이 아니다. 소프트웨어 개발에서는 오래전부터 요구사항 명세서와 설계 문서를 사용해 왔다.

다만 기존 개발 과정에서 Spec은 구현을 위한 참고 문서로 사용된 뒤, 코드가 완성되면 더 이상 적극적으로 활용되지 않는 경우가 많았다.

SDD에서는 Spec의 역할이 달라진다. Spec은 단순히 구현 방향을 안내하는 문서가 아니라,

무엇을 만들어야 하는지 정의하고
구현 작업을 분리하며
완성된 결과가 요구사항을 만족하는지

검증하는 기준으로 사용된다.

특히 AI Agent 기반 개발에서는 이러한 역할이 더욱 중요해진다. 사람이 한 번 참고하고 보관하는 문서를 넘어, AI Agent가 구현 범위를 판단하고 작업 순서를 결정하며 결과를 검증하는 기준으로 Spec을 활용하기 때문이다.

소프트웨어 개발 방법론

기존에 하나의 프로그램을 구현하려면 일반적으로 다음과 같은 과정이 필요했다.

요구사항과 목적을 정의한다.
해결해야 할 문제를 분석한다.
프로그램의 구조와 동작 방식을 설계한다.
설계를 바탕으로 기능을 구현한다.
구현 결과가 요구사항을 만족하는지 검증한다.

Waterfall이나 Agile 등과 같은 전통적인 소프트웨어 개발 방법론 역시 이러한 과정의 순서와 반복 방법, 구성원 간의 협업 방식을 정의한다.

SDD는 이러한 기존 개발 방법론을 대체하는 별도의 방법론이라기보다, 개발 과정의 중심에 Spec을 두고 각 단계를 연결하는 접근법에 가깝다. 즉, Waterfall이나 Agile을 새롭게 대체하는 것이 아니라 어떤 개발 방법론을 사용하더라도 요구사항과 설계, 구현, 검증의 기준을 Spec으로 명확하게 관리하는 방식이다.

따라서 SDD는 AI 때문에 새롭게 만들어진 개념이라기보다, 기존의 명세 중심 개발을 AI Agent 환경에 맞게 재구성하고 강조한 용어에 가깝다.

과거에는 Spec이 개발자가 참고하는 문서에 머무르는 경우가 많았다면, SDD에서는 AI Agent가 구현 계획을 세우고 작업을 수행하며 결과를 검증하는 기준으로 Spec을 적극적으로 활용한다.

Spec

SDD에서 가장 핵심적인 요소는 구현의 기준이 되는 Spec 문서이다. 일반적으로 AI에서 사용하기 편한 .md형식의 문서를 많이 이용한다.

GitHub Spec Kit

2025년 9월 GitHub는 Spec-Driven Development를 지원하기 위한 오픈 소스 도구인 Spec Kit을 공개하며, Spec을 중심으로 한 개발 흐름을 제시했다.

GitHub Spec Kit은 개발 과정을 다음과 같은 단계로 구성한다.

`Constitution → Specify → Plan → Tasks → Implement → Converge`

Constitution : 프로젝트 전체에서 지켜야 할 원칙과 개발 기준을 정의한다.
Specify : 무엇을 만들 것인지 정의한다.
Plan : 어떤 기술과 구조로 구현할지 계획한다.
Tasks : 구현 계획을 실행 가능한 작업 단위로 분해한다.
Implement : 분리된 작업을 실제 코드로 구현한다.
Converge : 구현 결과를 Spec과 비교하고, 충족되지 않은 요구사항을 추가 작업으로 정리한다.

이 과정은 한 번의 Prompt로 곧바로 코드를 생성하는 방식과 다르다. 먼저 구현 의도와 요구사항을 명확하게 정의하고, 이를 기술 계획과 작업 목록으로 구체화한 뒤, 구현 결과를 다시 Spec과 비교한다.

결국 GitHub Spec Kit이 제시하는 핵심은 Spec을 작성하고 버리는 것이 아니다. Spec을 개발 과정 전체에서 지속적으로 참조하는 기준으로 활용하는 것이다.

Spec 문서 예시

아래 예시는 본인이 실제로 개발에서 사용했던 Spec 문서의 일부다.

개발 방식에 절대적인 틀은 없다. 본인이 작업하기 편한 방식으로 Spec 문서의 양식을 바꿔도 좋다.

# 파티원·적 아이템 습득 공통 처리

## 문서 목적

플레이어 입력에만 연결되어 있는 아이템 습득 로직을 모든 캐릭터가 사용할 수 있는 공통 후처리로 이동한다.

## 현재 문제

현재 아이템 습득이 플레이어 입력 처리 과정에 포함되어 있다. 이 때문에 파티원이나 적이 아이템이 있는 칸으로 이동하더라도 아이템을 습득하지 못한다.

## 구현 요구사항

캐릭터의 이동이 확정된 뒤 다음 순서로 아이템 습득을 처리한다.

1. 이동 결과를 확정한다.
2. 이동한 위치의 바닥 아이템을 조회한다.
3. 캐릭터의 진영에 따라 습득 가능 여부와 처리 방식을 결정한다.
4. 습득한 아이템의 런타임 레코드와 Actor를 제거한다.
5. 아이템 습득 이벤트를 발생시키고 UI를 갱신한다.
6. 다음 SpawnIndex를 가진 캐릭터의 행동을 진행한다.

## 완료 조건

- 플레이어, 파티원, 적이 각자의 조건에 따라 아이템을 습득한다.
- 바닥 아이템의 Actor와 런타임 데이터가 함께 제거된다.
- 인벤토리와 UI가 아이템 습득 결과를 반영한다.
- 아이템 습득 이후 다음 캐릭터의 턴이 정상적으로 진행된다.
- 플레이어 입력 전용 로직에 아이템 습득 처리가 남아 있지 않다.

## 제외 범위

- 아이템 종류별 효과 처리 방식은 변경하지 않는다.
- 인벤토리 용량 규칙은 변경하지 않는다.
- 아이템을 습득할 수 없는 조건은 별도 Spec에서 다룬다.

이 문서에서 중요한 부분은 단순히 “파티원과 적도 아이템을 줍게 한다”라고 작성하지 않았다는 점이다.

현재 문제가 발생하는 이유와 기능을 이동해야 하는 위치, 처리 순서, 런타임 데이터와 UI의 갱신 조건, 이번 작업에서 변경하지 않을 범위를 함께 정의한다.

다만 AI Agent가 작업가능한 수준의 Context 용량을 고려하는 것도 중요하다!

AI Agent는 기존 코드를 임의로 수정하는 대신, 문서에 정의된 조건을 기준으로 현재 구조를 분석하고 작업을 진행해준다.

Spec 문서 관리

Spec은 한 번 작성한 뒤 보관하는 문서가 아니라, 코드와 함께 지속적으로 관리해야 하는 개발 자산이다. 그런 만큼 관리하는 방법 역시 고민하는 것도 중요하다.

프로젝트 저장소와 함께 관리하기

가장 기본적인 방법은 프로젝트 저장소 내부에서 Markdown 파일로 관리하는 것이다.

코드와 Spec을 Git으로 함께 버전 관리하면 특정 커밋 시점의 구현과 당시의 요구사항을 함께 확인할 수 있다. 기능이 변경되거나 버그가 수정되었을 때에도 어떤 요구사항을 기준으로 코드가 바뀌었는지 추적하기 쉽다.

또한 Spec 파일을 저장소에 함께 두면 AI Agent가 프로젝트를 분석할 때 동일한 문서를 참고할 수 있다. 다만 문서와 실제 코드의 내용이 달라지지 않도록 구현 결과에 맞춰 Spec도 함께 갱신해야 한다는 단점도 있다.

GitHub Projects로 관리하기

GitHub Projects는 Spec을 실제 작업 단위와 연결하고 진행 상태를 관리하는 도구로 활용할 수 있다.

각 Spec 문서를 GitHub Issue나 Project 카드에 연결하면 현재 작업의 우선순위와 진행 상황, 담당 범위를 한눈에 확인할 수 있다. 또한 작업이 예정, 진행 중, 검토, 완료 중 어느 단계에 있는지 쉽게 관리할 수 있다.

상세한 요구사항과 구현 기준은 Markdown Spec에 기록하고, GitHub Projects에서는 해당 Spec의 작업 상태만 관리하면 문서를 중복해서 작성하는 문제를 줄일 수 있다.

Obsidian으로 관리하기

Obsidian과 같은 Second Brain 도구를 이용해 Spec 정리하는 방법도 있다.

Obsidian에서는 Spec 문서뿐만 아니라 기술 조사 내용, 설계 결정의 배경, 관련 기능과의 연결 관계를 링크로 구성할 수 있다. 이를 바탕으로 프로젝트의 구조와 개발 지식을 하나의 LLM Wiki처럼 정리할 수도 있다.

또한 MCP를 통해 Obsidian의 문서와 프로젝트 저장소를 AI Agent에 연결하면, AI Agent가 단일 작업지시서뿐만 아니라 과거의 설계 결정과 관련 문서까지 참고하도록 구성할 수 있다.

구현

Spec 문서가 작성되었다면, Spec에 정의된 작업 범위와 처리 순서에 따라 구현을 진행한다.

혹은 Claude나 Codex같은 AI Assistant를 이용해서 구현하는 것도 좋은 방법이다.

이때 문서에 명시되지 않은 부분은 임의로 확장하지 않고, 기존 기능을 훼손하지 않는 범위에서 수정한다. 구현이 완료되면 완료 조건과 검증 기준을 다시 확인한다. 요구사항이 모두 반영되었는지, 기존 기능에 문제가 발생하지 않았는지 검토한 뒤 변경된 설계나 추가된 제약 조건을 Spec 문서에도 반영한다.

SDD의 장점과 단점

SDD를 적용하면서 개발하면서 느낀 장점과 단점은 다음과 같다.

장점

AI Agent의 Context 한계에 맞춰 작업을 분리할 수 있다.
새로운 대화나 다른 Agent에서도 작업을 쉽게 이어 갈 수 있다.
구현 과정에서 발생한 설계 판단을 문서로 남길 수 있다.
사람이 AI의 개발 프로세스에서 의사결정판단에 참여하기 하기 쉽다.

단점

Spec을 위한 토큰과 오버헤드가 추가적으로 필요하다.
Spec을 작성하고 검토하는 데 시간이 필요하다.
요구사항이 자주 변경되면 문서 관리 비용이 커진다.
AI Agent가 Spec의 일부 조건을 누락하거나 잘못된 동작을 유발할 수 있다.

일반적으로 Spec 문서 작성의 경우, 추론 능력이 높은 모델을 활용하여 재수정을 최소화하고 구체화된 Spec 문서를 통해 구현과 테스트는 추론이 낮은 모델을 활용하는 것도 토큰을 아끼는 방법 중 하나이다.

마무리

SDD는 단순히 AI Agent에게 코드를 대신 작성하게 하는 방법이 아니다. 개발자가 구현 의도와 설계 방향을 먼저 정의하고, 이를 바탕으로 AI Agent의 작업 범위와 순서를 조절하는 개발 프로세스이다.

Spec을 통해 요구사항과 판단 기준을 명확하게 전달하면, AI Agent를 활용하면서도 개발자가 설계의 주도권을 유지할 수 있다. 또한 구현 과정에서 발생하는 판단을 일관된 기준으로 통제하고, 반복적인 작업은 자동화하여 보다 예측 가능한 결과를 얻을 수 있다.

결국 SDD의 핵심은 AI에게 개발을 맡기는 것이 아니라, AI가 올바른 방향으로 개발하도록 과정을 구조화하는 데 있다.