Vibe Coding에서 Spec-Driven Development로: AI에게 제대로 개발시키는 방법

AI 코딩 도구를 쓰면 개발 속도는 확실히 빨라집니다. Cursor, Claude Code, GitHub Copilot, Codex 같은 도구에게 요구사항을 말하면 코드 초안이 빠르게 만들어집니다. 간단한 화면이나 프로토타입을 만들 때는 특히 유용합니다.

하지만 실제 프로젝트에 적용해보면 이런 문제가 자주 생깁니다.

- “처음에는 잘 돌아가는 것처럼 보였는데 요구사항과 다르다.”
- “코드는 그럴듯하지만 예외 처리가 빠져 있다.”
- “기존 프로젝트 구조를 무시하고 새 패턴을 만들어버렸다.”
- “수정해달라고 했더니 관련 없는 파일까지 바뀌었다.”

이런 방식의 AI 코딩을 흔히 Vibe Coding이라고 부릅니다. 대략적인 느낌만 전달하고, AI가 만든 코드를 실행해보면서 되는 것 같으면 넘어가는 방식입니다. 작은 개인 프로젝트에서는 괜찮을 수 있지만, 실무 프로젝트에서는 위험합니다.

 

AI는 빠르게 코드를 만들 수 있지만, 우리가 원하는 제품의 의도와 제약 조건을 항상 정확히 이해하지는 못하기 때문입니다.

그래서 최근에는 AI에게 바로 코드를 작성시키기보다, 먼저 명세를 만들고 그 명세를 기준으로 개발하게 하는 방식이 주목받고 있습니다.

이 방식이 바로 Spec-Driven Development, 즉 명세 기반 개발입니다.

Vibe Coding의 문제점

Vibe Coding의 장점은 빠르다는 것입니다. 예를 들어 AI에게 이렇게 요청할 수 있습니다.

“로그인 페이지 만들어줘.”
“게시판 CRUD 만들어줘.”
“관리자 대시보드 만들어줘.”

AI는 금방 코드를 만들어줍니다. 하지만 문제는 그 다음입니다.

• 로그인 페이지를 만들긴 했지만 인증 실패 케이스가 빠져 있을 수 있습니다.
• 게시판 CRUD를 만들긴 했지만 권한 체크가 없을 수 있습니다. 
• 관리자 대시보드를 만들긴 했지만 기존 디자인 시스템을 사용하지 않았을 수 있습니다.

겉으로는 완성된 것처럼 보여도 내부적으로는 많은 문제가 숨어 있을 수 있습니다.

 

Vibe Coding의 핵심 문제는 다음과 같습니다.

- 요구사항이 불명확하다.
- AI가 빈 부분을 임의로 가정한다.
- 완료 기준이 없다.
- 수정 범위가 커질 수 있다.
- 테스트 기준이 부족하다.

즉, Vibe Coding은 속도는 빠르지만 방향과 기준이 약한 방식입니다.

 

Spec-Driven Development란?

Spec-Driven Development는 말 그대로 명세를 중심으로 개발하는 방식입니다. 여기서 명세는 단순한 문서가 아닙니다.
사람과 AI가 함께 바라보는 기준입니다. Vibe Coding은 보통 이렇게 진행됩니다.

 

아이디어 → 바로 코드 생성 → 실행해보기 → 다시 수정

 

반면 Spec-Driven Development는 이렇게 진행됩니다.

 

아이디어 → 명세 작성 → 구현 계획 작성 → 작업 단위 분해 → 코드 생성 → 명세 기준으로 검증

 

가장 큰 차이는 코드를 작성하기 전에 기준을 먼저 만든다는 점입니다. 명세에는 다음 내용이 들어갈 수 있습니다.

- 무엇을 만들 것인가?
- 어떤 사용자가 사용하는가?
- 정상 동작은 무엇인가?
- 예외 상황은 무엇인가?
- 완료 기준은 무엇인가?

AI는 이 명세를 기준으로 코드를 작성합니다. 그래서 개발자는 AI에게 단순히 “만들어줘”라고 시키는 사람이 아니라, AI가 따라야 할 기준을 설계하는 사람이 됩니다.

Vibe Coding VS Spec Driven Development

 

기본 흐름: Specify, Plan, Tasks, Implement

 

Spec-Driven Development는 다음 네 단계로 이해할 수 있습니다.

1. Specify: 무엇을 만들지 정의하기

Specify 단계에서는 구현 방법보다 무엇을 만들지에 집중합니다. 예를 들어 “로그인 기능 만들어줘”라고만 하면 부족합니다.

조금 더 좋은 명세는 다음과 같습니다.

사용자는 이메일과 비밀번호로 로그인할 수 있어야 한다.
이메일 형식이 잘못되면 입력 단계에서 안내 메시지를 보여준다.
로그인 실패 시 ‘이메일 또는 비밀번호를 확인해주세요’라는 메시지를 보여준다.
로그인 성공 시 사용자는 /dashboard로 이동한다.

이렇게 작성하면 AI가 구현해야 할 범위가 훨씬 명확해집니다. 명세는 길 필요가 없습니다. 대신 구체적이어야 합니다.

 

2. Plan: 어떻게 구현할지 계획하기

Plan 단계에서는 명세를 바탕으로 구현 전략을 정리합니다. 예를 들어 로그인 기능이라면 다음을 정할 수 있습니다.

- 로그인 페이지 경로
- 사용할 API
- 폼 검증 방식
- 에러 처리 방식
- 기존 컴포넌트 재사용 여부
- 테스트 방식

 

예시는 다음과 같습니다.

- 로그인 페이지는 /login 경로에 만든다.
- 폼 검증은 zod를 사용한다.
- API 호출은 src/api/auth.ts에 작성한다.
- UI는 기존 Button, Input 컴포넌트를 재사용한다.
- 테스트는 로그인 성공, 실패, 잘못된 이메일 입력 케이스를 포함한다.

이 단계의 목적은 AI가 코드를 만들기 전에 구현 방향을 먼저 맞추는 것입니다.

 

3. Tasks: 작업 단위로 나누기

Tasks 단계에서는 구현 계획을 작은 작업으로 나눕니다. AI에게 큰 작업을 한 번에 맡기면 수정 범위가 커집니다.
그래서 작고 검증 가능한 단위로 나누는 것이 좋습니다. 예를 들어 로그인 기능은 다음처럼 나눌 수 있습니다.

1. 로그인 페이지 UI 작성
2. 이메일/비밀번호 입력 검증 추가
3. 로그인 API 함수 작성
4. 로그인 성공 시 라우팅 처리
5. 로그인 실패 에러 메시지 처리
6. 테스트 코드 작성

 

나쁜 Task는 다음과 같습니다.

“로그인 기능 전체 구현”

 

좋은 Task는 다음과 같습니다.

“기존 Input, Button 컴포넌트를 사용해 로그인 폼 UI만 작성한다. 아직 API 연동은 하지 않는다.”

 

이렇게 나누면 AI가 불필요한 파일을 수정할 가능성이 줄어듭니다.

 

4. Implement: 기준에 따라 구현하기

Implement 단계에서 AI가 실제 코드를 작성합니다.

중요한 점은 AI에게 자유롭게 맡기는 것이 아니라, 앞에서 만든 명세와 작업 목록을 기준으로 구현하게 해야 한다는 것입니다.

 

좋은 요청은 다음과 같습니다.

“위 명세와 작업 목록 중 1번 작업만 구현해줘. API 연동은 하지 말고 UI만 작성해줘.
기존 컴포넌트 구조를 따르고, 작업 후 변경 파일을 요약해줘.”

AI가 라우트, 상태 관리, API, 토큰 저장 방식, UI 컴포넌트, 테스트 방식까지 모두 임의로 결정할 수 있습니다.

Spec-Driven Development에서 AI는 단독 개발자가 아니라, 명세를 따라 구현하는 실행자에 가깝습니다.

 

AGENTS.md와 함께 사용하기

앞선 글에서 다룬 AGENTS.md는 Spec-Driven Development와 함께 쓰기 좋습니다. (AI 코딩 에이전트 제대로 쓰기: AGENTS.md 작성법) AGENTS.md에는 프로젝트 공통 규칙을 적습니다.

- 패키지 매니저는 pnpm을 사용한다.
- 새 파일은 TypeScript로 작성한다.
- 기존 컴포넌트를 우선 재사용한다.
- 테스트를 삭제하지 않는다.
- 작업 후 typecheck, lint, test를 실행한다.

 

반면 Spec 문서에는 특정 기능의 요구사항을 적습니다.

- 로그인 실패 시 에러 메시지를 표시한다.
- 요청 중에는 버튼을 비활성화한다.
- 성공 시 /dashboard로 이동한다.

 

즉, 역할을 나누면 다음과 같습니다. AGENTS.md는 프로젝트 전체 규칙입니다.

Spec 문서는 기능별 요구사항입니다. AI 에이전트는 이 두 가지를 함께 참고할 때 더 좋은 결과를 만들 수 있습니다.

 

AI 코딩 도구는 매우 강력합니다. 하지만 AI에게 “알아서 만들어줘”라고만 요청하면, 빠르지만 불안정한 결과가 나올 수 있습니다.

Vibe Coding은 프로토타입에는 유용하지만, 실무 개발에서는 요구사항 누락, 잘못된 가정, 과도한 수정 범위, 테스트 부족 같은 문제를 만들 수 있습니다. Spec-Driven Development는 이 문제를 줄이기 위한 방법입니다.

정리하면 다음과 같습니다.

- Vibe Coding은 느낌 중심으로 바로 코드를 만드는 방식입니다.
- Spec-Driven Development는 명세를 먼저 만들고, 그 명세를 기준으로 코드를 만드는 방식입니다.
- 핵심 흐름은 Specify, Plan, Tasks, Implement입니다.
- 명세는 사람과 AI가 함께 바라보는 기준입니다.
- 작업을 작게 나누면 AI의 실수를 줄이고 리뷰하기 쉬워집니다.
- AGENTS.md와 함께 사용하면 프로젝트 규칙과 기능 요구사항을 함께 관리할 수 있습니다.

앞으로 AI 코딩 도구를 더 적극적으로 사용할수록 개발자의 역할은 단순히 코드를 직접 치는 것에서, 명확한 요구사항을 정의하고 AI의 결과물을 검증하는 것으로 바뀔 가능성이 큽니다.

AI에게 코드를 잘 쓰게 하고 싶다면, 먼저 AI가 따라야 할 기준을 잘 써야 합니다.

그 기준이 바로 명세입니다.

 

참고 자료

GitHub Blog - Spec-driven development with AI
https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

GitHub Spec Kit
https://github.com/github/spec-kit

Martin Fowler - Understanding Spec-Driven Development
https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html