스펙 기반 개발
코드를 바로 짜게 하지 않고 입출력·인터페이스·제약 사항 같은 외부 동작 명세를 먼저 정한 뒤, AI 에이전트가 그 명세대로 구현만 하게 하는 개발 방식이다. 요구사항이 복잡하거나 에이전트 결과물이 자꾸 엇나갈 때 쓰며, 결정을 에이전트에 맡기는 바이브 코딩과 달리 사람이 명세로 결정한다.
| 구분 | 바이브 코딩 | 스펙 기반 개발 |
|---|---|---|
| 지시 방식 | "느낌대로 짜 봐" | "이 계약서대로 짜" |
| 결정하는 쪽 | 에이전트 | 사람이 명세로 |
| 잘 맞는 일 | 시제품, 일회성 스크립트 | 기능 추가, 오래 유지할 코드 |
"로그인 기능 만들어줘"라고만 하면 인증 방식과 에러 처리를 에이전트가 알아서 정해서, 처음부터 다시 해야 할 때가 많다. 이런 결정을 명세에 미리 적어 두는 것이 출발점이다.
Spec Kit은 네 단계로 나눈다
GitHub이 공개한 오픈소스 도구 Spec Kit은 이 흐름을 네 단계로 나눈다. 단계마다 결과물을 문서로 남기고, 사람이 확인한 뒤에 다음 단계로 넘어간다.
| 단계 | 하는 일 | 결과물 |
|---|---|---|
| Specify | 무엇을, 왜 만드는지 설명 | 상세 명세 |
| Plan | 기술 스택과 구조 결정 | 기술 계획서 |
| Tasks | 작은 작업 단위로 쪼개기 | 작업 목록 |
| Implement | 작업 목록대로 구현 | 코드 |
Claude Code에서는 명령어로 한 단계씩
Claude Code에 Spec Kit을 스킬로 설치하면 /speckit-specify, /speckit-plan 같은 명령으로 단계를 하나씩 부를 수 있다. Specify에서는 기술 얘기는 빼고 사용자가 겪을 동작만 적는다. Plan에서 "이 프레임워크와 이 DB를 쓴다"처럼 기술 선택을 정한다.
단계가 끝날 때마다 생성된 문서를 직접 읽고, 틀린 부분은 고친 뒤 다음 명령을 부른다. 명세에서 바로잡은 실수 하나가 구현 단계의 재작업 여러 번을 줄여 준다.
언제 쓰고 언제 건너뛰나
| 상황 | 추천 |
|---|---|
| 여러 파일에 걸친 새 기능 | 스펙 먼저 |
| 기존 서비스에 기능 추가 | 스펙 먼저 (기존 규칙을 명세에 적기) |
| 오타 수정, 작은 버그 | 바로 지시 |
| 버릴 시제품 | 바이브 코딩으로 충분 |
명세는 '무엇'만, '어떻게'는 맡긴다
명세를 너무 세밀하게 쓰면 직접 코드를 짜는 것과 시간 차이가 없어진다. 외부에서 보이는 동작만 정하고, 내부 구현은 에이전트에게 맡기는 게 핵심이다.
명세 문서도 코드처럼 관리해야 한다. 요구사항이 바뀌었는데 코드만 고치고 명세를 그대로 두면, 다음 작업에서 에이전트가 낡은 명세를 기준으로 움직인다.
코딩 에이전트에 기능을 맡길 때 주로 쓴다
가장 흔한 건 코딩 에이전트에 기능 하나를 통째로 맡기기 전에 명세부터 함께 만드는 방식이다. 명세 문서를 저장소에 남겨 두면 다음 작업에서도 에이전트와 팀원이 같은 기준을 본다.
| 어디서 | 어떻게 쓰나 |
|---|---|
| 코딩 에이전트 | Spec Kit 명령으로 명세·계획·작업 목록을 차례로 만들고, 사람이 검토한 뒤 구현을 맡긴다 |
| 기존 서비스 개발 | 지켜야 할 기존 규칙과 인터페이스를 명세에 적어, 에이전트가 이를 깨지 않게 한다 |
| 팀 협업·코드 리뷰 | 명세 문서를 코드와 함께 관리하고, 리뷰할 때 구현이 명세와 맞는지 확인한다 |
