스펙 주도 개발(Spec-Driven Development)이란?

이 글은 최근 AI 개발 도구들에서 주목받고 있는 **스펙 주도 개발(Spec-Driven Development)**에 대해 처음 접하는 분들을 위해 작성되었습니다. 어려운 개념처럼 보이지만, 실제로는 우리가 일상에서도 자주 사용하는 방식을 개발에 적용한 것입니다.

스펙 주도 개발이란?

스펙 주도 개발은 "무엇을 만들어야 하는지"를 먼저 명확하게 정의하고, 그 정의(specification)를 기반으로 코드를 구현하는 방식입니다.

최근 ChatGPT나 Cursor 같은 AI 코딩 도구들이 인기를 끌면서 바이브 코딩이라는 새로운 개발 방식이 등장했습니다. 개발자들이 즉흥적으로 AI에게 프롬프트를 입력해서 코드를 생성하는 방식이죠. 하지만 이 방식은 작은 기능은 잘 만들어내지만, 복잡하고 큰 프로젝트에서는 한계가 드러났습니다.

현재 AI 코딩의 예측 가능한 문제 패턴

대부분의 AI 코딩 도구들은 다음과 같은 비효율적인 패턴을 보입니다.

성급한 코드 생성: 개발자가 높은 수준의 프롬프트를 제공하면, AI가 요구사항을 완전히 이해하기 전에 즉시 코드 생성을 시작합니다.
반복적인 수정 사이클: 이로 인해 개발자는 "actually, I meant..." 같은 수정 요청을 반복하게 되고, 초기 요구사항이 충분히 명확하지 않았음을 깨닫게 됩니다.
컨텍스트 윈도우 낭비: 탐색적 대화가 계속되면서 컨텍스트 윈도우가 왔다갔다하는 논의로 채워져, 실제 코드 생성을 위한 공간이 부족해집니다.
품질 저하: 제한된 컨텍스트 공간으로 인해 최종 결과물의 품질과 완성도가 떨어집니다.

이런 접근 방식은 LLM을 단순한 코드 생성기로 취급하는 것인데, 실제로는 전체 개발 생명주기에 걸쳐 사고하는 파트너로 활용해야 합니다.

스펙 주도 개발의 해결책

스펙 주도 개발의 접근법:

프로젝트의 모든 요구사항과 설계를 문서로 명확히 정리
AI가 이 문서를 지속적으로 참고하여 일관성 있는 개발 진행
변경사항은 문서에 반영하고, AI가 문서를 기반으로 코드 업데이트

왜 이 방식이 주목받고 있을까?

1. AI 시대와 잘 맞아떨어진다

ChatGPT나 KIRO 같은 AI 도구들을 사용해보신 분들은 아실 겁니다. AI는 명확한 지시를 받으면 정말 잘 작동합니다. 하지만 막연한 요청을 하면 엉뚱한 결과를 내놓기도 하죠.

스펙 문서는 마치 AI에게 주는 "매우 상세한 작업 지시서" 역할을 합니다. 그리고 이 지시서는 한 번 쓰고 버리는 게 아니라, 프로젝트 내내 계속 참고하고 업데이트할 수 있습니다.

2. "바이브 코딩"의 한계를 보완한다

요즘 많은 개발자들이 AI와 함께 "분위기 따라" 코딩을 합니다. 이른바 바이브 코딩이죠. 빠르고 재미있지만 몇 가지 문제가 있습니다.

기능을 수정할 때마다 처음부터 다시 설명해야 한다
전체적인 구조를 파악하기 어렵다
이전에 내린 결정들을 까먹는다

스펙 주도 개발은 이런 문제들을 해결해줍니다. 모든 결정과 요구사항이 문서에 기록되어 있으니까요.

3. 팀 협업이 쉬워진다

스펙 문서는 개발자가 아닌 사람도 읽을 수 있습니다. 기획자, 디자이너, 클라이언트 모두가 같은 문서를 보고 이야기할 수 있어서 의사소통이 훨씬 원활해집니다.

4. 개발 전 문제점 발견

스펙을 작성하면서 개발을 시작하기 전에 잠재적인 기술적 문제나 의존성 이슈를 미리 발견할 수 있습니다. 이를 통해 나중에 큰 수정 작업을 피할 수 있습니다.

5. 일관적인 코딩 가능

스펙 문서에 코딩 스타일, 아키텍처 원칙, 네이밍 컨벤션 등을 명시해두면 프로젝트 전체에서 일관성 있는 코드를 유지할 수 있습니다. AI도 이 가이드라인을 따라 코드를 생성하므로 통일된 품질의 코드를 얻을 수 있습니다.

KIRO에서의 실제 워크플로우

KIRO에서는 체계적인 스펙 주도 개발 워크플로우를 제공합니다. 실제 사례를 통해 살펴보겠습니다.

1단계: 프로젝트 기반 설정 (Steering)

새로운 기능을 개발하기 전에 먼저 프로젝트의 맥락을 파악합니다.

사용자: "프로젝트 진행을 위한 Steering 문서를 작성해 주세요"

KIRO가 기존 코드베이스를 분석하여 3개의 기초 문서를 생성합니다:

structure.md: 현재 아키텍처, 주요 컴포넌트, 코드 구조
tech.md: 기술 스택, 패턴, 기술적 제약사항
product.md: 비즈니스 맥락, 기존 기능, 사용자 워크플로우

2단계: 프로젝트 스펙 생성

이제 구체적인 프로젝트 요구사항을 입력합니다.

사용자: "이벤트 관리 API를 만들고 싶습니다. 
이벤트 생성, 초대 발송, 참석자 응답 관리 기능이 필요합니다.
백엔드는 Python으로 작성해주세요."

KIRO는 즉시 코드를 생성하지 않고, 먼저 요구사항을 완전히 이해하고 종합적인 계획을 수립합니다. 기존 steering 문서를 참고하여 이 새로운 기능이 현재 아키텍처와 어떻게 맞아떨어지는지 분석합니다.

그 후 순차적으로 다음 문서들을 생성합니다:

requirements.md: 사용자 스토리와 수락 기준을 포함한 상세한 기능 분석
design.md: 프레임워크, 아키텍처 다이어그램, 구조를 포함한 아키텍처 및 기술 결정
tasks.md: 순차적으로 실행할 개발 단계와 작업

3단계: 검토 및 수정

생성된 스펙을 검토하고 필요에 따라 수정합니다. 예를들면 새로 발견된 요구사항을 requirements.md에 추가하는 식으로 진행합니다.

requirements.md에 추가:
- 이벤트 생성 시 자동으로 캘린더에 동기화되어야 함
- 참석자들에게 이메일 리마인더 발송 기능 필요

3단계: 정보에 기반한 개발

이제 KIRO가 코딩을 시작할 때는 대화 기록에서 요구사항을 추론하는 것이 아니라, 포괄적인 스펙 문서를 참조합니다. 모든 구현 결정은 문서화된 요구사항과 설계 선택에 근거합니다.

스펙 주도 개발의 핵심 이점

비용이 많이 드는 문제를 미리 포착

개발 중에 요구사항 문제를 발견하는 대신, KIRO는 미리 모호함을 식별하고 해결합니다. 이는 비용이 많이 드는 재작업을 방지하고 코딩을 시작하기 전에 팀 간 정렬을 제공합니다.

프로젝트 방향성 통제

스펙 단계에서는 인간이 검토하고 수정하며 구현에 자원을 투자하기 전에 방향을 승인할 수 있는 자연스러운 중단점을 만듭니다.

진행상황을 잃지 않고 반복

요구사항 정의에서 실수를 하더라도 문제없습니다. 스펙 파일을 수정하고 전체 대화 기록을 잃지 않고 구현 계획을 재생성할 수 있습니다.

시작하기 전 알아두면 좋은 팁

Tip 1: 완벽하지 않아도 된다

처음부터 완벽한 스펙을 작성하려고 하지 마세요. 기본적인 틀을 잡고 시작해서, 개발하면서 점점 구체화해나가면 됩니다.

Tip 2: 사용자 관점에서 생각하기

기술적인 내용보다는 "사용자가 무엇을 할 수 있어야 하는지"에 초점을 맞춰보세요. 이렇게 하면 본질적인 기능에 집중할 수 있습니다.

Tip 3: 작은 프로젝트부터 연습

복잡한 프로젝트보다는 간단한 할 일 목록이나 계산기 같은 작은 프로젝트로 먼저 연습해보세요.

주의사항

문서 작성에 너무 많은 시간을 쓰지 말자

스펙 문서는 코딩을 도와주는 도구입니다. 문서 작성 자체가 목적이 되어서는 안 됩니다. 적당한 수준에서 시작해서 필요에 따라 보완해나가면 됩니다.

AI 도구의 한계 인정하기

AI가 스펙을 완벽하게 이해하고 구현하는 것은 아닙니다. 생성된 코드는 반드시 검토하고 테스트해야 합니다.

마무리

스펙 주도 개발은 "코드보다 의도를 먼저 생각하게 만드는" 개발 방식입니다. 처음에는 번거로울 수 있지만, 익숙해지면 더 안정적이고 예측 가능한 개발을 할 수 있습니다.

특히 AI와 함께 개발하는 시대에는 이런 체계적인 접근이 더욱 중요해질 것 같습니다. 한번 시도해보시는 것을 추천합니다.