제15장 Spec-Driven Development 적용하기

Antigravity가 진짜로 빛나는 순간은 AI가 코드를 몇 줄 대신 써주는 때가 아니다. 요구사항을 구조화하고, 계획을 검토하고, 검증 가능한 결과물로 바꾸는 흐름 전체를 다룰 때다. 공식 소개가 Antigravity를 단순한 채팅형 코딩 도구가 아니라, 잘 설계된 아티팩트와 검증을 바탕으로 생산용 애플리케이션을 만드는 환경으로 설명하는 이유도 여기에 있다.¹

이 장에서는 명세 중심 개발, 즉 Spec-Driven Development를 Antigravity와 결합하는 법을 다룬다. 핵심은 어렵지 않다. 감으로 밀어붙이는 바이브 코딩의 속도는 살리고, 다시 읽고 다시 고치고 다시 물어보는 낭비는 줄이자는 것이다. 한마디로 말해, 떠오른 아이디어를 바로 코드로 던지지 말고 먼저 실행 가능한 명세로 굳힌 뒤 에이전트에게 위임하는 방식이다.

왜 지금 명세 중심 개발인가

바이브 코딩은 놀랍도록 빠르다. 작은 데모를 만들거나, 화면 한 장을 스케치하거나, 아이디어를 시험해 볼 때는 정말 매력적이다. 문제는 기능이 프론트엔드, 백엔드, 데이터 모델, 테스트, 배포까지 엮이기 시작하는 순간이다. 이때부터는 프롬프트 → 코드 생성 → 이상해서 다시 수정 → 또 다른 부작용 발생의 루프가 시작된다. 속도가 빠른 것 같지만, 사실은 방향 전환을 반복하면서 제자리에서 바퀴를 도는 경우가 많다.

Antigravity의 SDD 가이드는 이 문제를 정면으로 다룬다. 요구사항 수집, 아키텍처 설계, 시스템 및 테스트 명세를 먼저 만들고, 그 다음에 코드 생성과 검증을 돌리는 식이다. 중요한 점은 이 과정이 폭포수처럼 한 번 지나가고 끝나는 절차가 아니라는 것이다. 버그가 발견되거나 요구사항이 바뀌면 코드를 먼저 손대는 대신 명세를 고치고 루프를 다시 돌린다.²

이 관점을 받아들이는 순간 개발자의 역할도 바뀐다. 개발자는 타이핑 속도로 승부하는 사람이 아니라, 경계를 정의하고 성공 조건을 문장으로 못 박는 사람이 된다. 설계도가 선명하면 에이전트는 빠르고, 설계도가 흐리면 에이전트는 창의적이 아니라 제멋대로가 된다.

쉽게 비유하면 이렇다. 바이브 코딩은 냉장고를 열고 그때그때 감으로 요리하는 방식에 가깝다. 잘되면 근사하지만, 같은 맛을 다시 내기 어렵다. SDD는 레시피를 먼저 적고 주방을 돌리는 방식이다. 그리고 Antigravity는 그 레시피를 읽고, 재료를 꺼내고, 조리하고, plating까지 해주는 유능한 수셰프에 가깝다.

/speckit.specify로 시작하는 흐름

GitHub Spec Kit 계열 워크플로우는 이 과정을 꽤 잘 정리해 놓았다. constitution, specification, plan, tasks를 중심으로 프로젝트의 단일 진실 원천, 즉 SSOT를 만들고, 필요하면 clarify와 analyze 단계로 모호함과 충돌을 줄인다.³

실무에서는 다음 흐름으로 이해하면 가장 쉽다.

1. 명세 작성 /speckit.specify
   무엇을 만들지 적는다. 사용자 시나리오, 핵심 기능, 제약 조건, 제외 범위를 포함한다.

2. 명료화 /speckit.clarify
   빠진 조건을 드러낸다. 실패 시 처리, 예외 케이스, 최소·최대 제한, 지속성 여부 같은 질문이 이 단계에서 튀어나온다.³

3. 계획 /speckit.plan
   이제 무엇을 어떤 구조로 만들지 정한다. 컴포넌트 구조, API, 데이터 모델, 라이브러리 선택, 테스트 전략이 들어간다.

4. 작업 분해 /speckit.tasks
   큰 계획을 실행 가능한 작업 단위로 나눈다. 파일 경로, 선행 의존성, 완료 조건이 이때 드러난다.

5. 분석 /speckit.analyze
   명세와 계획이 서로 충돌하지 않는지 확인한다. 요구사항은 있는데 구현 계획이 빠졌거나, 테스트 조건이 없거나, 범위가 새어 나가는 지점을 잡는 단계다.³

6. 구현 /speckit.implement 또는 Antigravity에 위임
   그제야 에이전트가 코드를 만든다. 핵심은 구현이 출발점이 아니라, 승인된 문서를 실행하는 마지막 단계라는 점이다.

Antigravity에 맞춘 Spec Kit 변형도 같은 철학을 따른다. 다만 명령 이름이 /define → /architect → /execute → /verify처럼 더 에이전트 오케스트레이션에 맞게 바뀌기도 한다. 즉, 이름은 달라도 본질은 같다. 먼저 정의하고, 그다음 설계하고, 나중에 병렬 실행하고, 마지막에 검증한다.⁴

예를 들어 여러분이 팀 대시보드에 알림 센터 기능을 추가한다고 해보자. SDD 이전의 프롬프트는 보통 이렇다.

사내 대시보드에 알림 기능 추가해 줘. 읽음 처리도 되고, 중요 알림은 상단에 보이고, 모바일도 지원했으면 좋겠어.

이 프롬프트도 나쁘진 않다. 하지만 에이전트는 금방 여러 가지를 제멋대로 가정해 버린다. 저장 방식은 무엇인지, 읽음 상태는 사용자별인지 전역인지, 푸시 알림까지 포함하는지, 관리자만 중요 표시를 할 수 있는지 같은 경계가 없다.

반면 /speckit.specify 단계에서는 이렇게 바뀐다.

사내 대시보드에 알림 센터를 추가한다.
- 대상 사용자: 로그인한 일반 사용자
- 포함 범위: 알림 목록, 읽음/안 읽음 표시, 중요 알림 pin, 모바일 반응형 UI
- 제외 범위: 이메일 발송, 푸시 알림, 관리자용 발송 화면
- 데이터 제약: 읽음 상태는 사용자별로 저장
- 성공 기준: 사용자는 최근 30일 알림을 보고, 단건 또는 전체 읽음 처리를 할 수 있다
- 검증 기준: 데스크톱과 모바일에서 레이아웃이 깨지지 않고, 읽음 상태가 새로고침 후 유지된다

같은 기능인데도 갑자기 작업이 훨씬 덜 위험해진다. 에이전트가 똑똑해져서가 아니다. 우리가 애초에 덜 모호하게 말했기 때문이다.

좋은 명세는 길지 않고, 경계가 선명하다

명세 중심 개발이라고 하면 많은 사람이 문서를 아주 길게 써야 한다고 생각한다. 사실 반대다. 좋은 명세는 장황한 문학 작품이 아니라, 경계가 분명한 계약서에 가깝다. Antigravity의 SDD 설명과 여러 실전 사례가 공통으로 강조하는 것도 바로 작은 모듈, 명확한 범위, 독립 검증 가능성이다.²⁵

명세에 반드시 들어가야 할 것은 대개 다음 네 가지다.

• 포함 범위: 무엇을 이번 작업에서 다루는가

• 제외 범위: 무엇을 의도적으로 하지 않는가

• 성공 판정: 어떤 상태가 되면 완료로 볼 것인가

• 검증 방법: 테스트, 스크린샷, 브라우저 확인 등 무엇으로 맞음을 증명할 것인가

여기에 기술 제약까지 들어가면 더 좋다. 예를 들어 Next.js App Router 사용, 기존 인증 미들웨어 재사용, 새 테이블 추가 금지, 한국어와 영어 둘 다 지원 같은 조건들이다. 이런 제약이 명세에 없으면 에이전트는 종종 매우 열정적으로, 그리고 매우 위험하게 새로운 구조를 도입한다.

여기서 중요한 감각이 하나 있다. 명세는 에이전트를 답답하게 묶는 족쇄가 아니다. 오히려 에이전트가 미친 듯이 헤매지 않도록 해주는 난간이다. 난간이 있을수록 속도를 더 낼 수 있다.

Antigravity에서 구현으로 넘기는 법

Spec Kit과 Antigravity를 함께 쓰는 실전 패턴은 크게 두 가지다. 첫째는 명세 단계는 Spec Kit 계열 명령으로 진행하고, 구현은 Antigravity로 핸드오프하는 방식이다. 둘째는 Antigravity 안에서 그 전체 흐름을 워크플로우로 감싸는 방식이다.⁴⁵

핸드오프 방식은 특히 이해하기 쉽다. 먼저 specs/001-notification-center/ 같은 디렉터리에 spec.md, plan.md, tasks.md를 만든다. 필요하면 data-model.md, api-spec.json, clarifications.md 같은 문서도 넣는다. 그다음 Antigravity에게 이 디렉터리를 먼저 읽게 하고, 자기 방식의 task.md와 implementation_plan.md를 다시 만들게 한다. 그리고 사용자가 그 계획을 검토한 뒤에야 실행에 들어간다.⁵

이게 왜 중요할까. 문서를 읽고 바로 코드를 쓰게 하면, 에이전트가 문서를 대충 이해한 채 출발할 수 있다. 하지만 Antigravity가 먼저 자기 언어로 작업 목록과 구현 계획을 재구성하게 만들면, 인간은 코드가 아니라 이해 수준부터 검토할 수 있다. 즉, 구현 전에 오해를 잡아내는 것이다.

Antigravity를 직접 써본 개발자들이 공통으로 말하는 감각도 비슷하다. 예전처럼 한 줄씩 타이핑하는 사람이 아니라, 프로그램 매니저처럼 요구사항을 놓고 질문하고, 계획을 검토하고, 실행을 승인하는 사람이 된다는 것이다.⁶

이때 Antigravity의 강점이 제대로 살아난다. 예를 들어 다음처럼 나눌 수 있다.

• 에이전트 A는 프론트엔드 컴포넌트 구현

• 에이전트 B는 API와 데이터 모델 수정

• 에이전트 C는 테스트와 브라우저 검증 준비

이 병렬화는 막연한 멀티태스킹이 아니다. 이미 tasks.md에서 경계가 나뉘어 있기 때문에 가능한 오케스트레이션이다. 다시 말해 멀티 에이전트는 명세가 있을 때 강해진다. 명세 없이 동시에 돌리면, 셋이 같이 열심히 꼬이기 쉽다.

specs/ 디렉토리를 Git에 커밋해야 하는 이유

명세를 진지하게 운영하려면 specs/ 디렉토리를 반드시 저장소에 남겨야 한다. Git 저장소는 코드만 보관하는 곳이 아니라, 결정과 경계와 진행 상태를 담는 시스템 오브 레코드가 되어야 한다는 관점이 점점 중요해지고 있다.⁷

많은 팀이 여기서 실수한다. 채팅창에서는 훌륭한 대화를 나눴는데, 저장소에는 최종 코드만 남는 경우다. 그러면 나중에 이런 질문에 답하기 어려워진다.

• 왜 이 구조를 택했지?

• 왜 이 예외 케이스는 처리하지 않았지?

• 이 기능의 원래 제외 범위가 뭐였지?

• 버그가 생겼는데, 코드가 잘못된 건가 아니면 명세가 바뀐 건가?

specs/를 커밋하면 이 문제가 훨씬 줄어든다. 장점은 분명하다.

• 리뷰의 대상이 코드만이 아니게 된다. 설계와 가정도 PR에서 같이 본다.

• 새로운 팀원과 새 에이전트의 온보딩이 빨라진다. 긴 채팅 로그를 뒤질 필요가 없다.

• 변경 이력이 남는다. 기능이 왜 확장되었는지, 언제 범위가 바뀌었는지 diff로 확인할 수 있다.³⁷

실무에서는 대략 이런 구조면 충분하다.

specs/
  001-notification-center/
    spec.md
    clarifications.md
    plan.md
    tasks.md
    data-model.md
    api-spec.json

처음엔 문서가 번거롭게 느껴질 수 있다. 하지만 프로젝트가 커질수록 사람들은 코드보다 결정의 맥락을 더 자주 찾게 된다. 그때 specs/는 단순한 메모가 아니라 팀의 집단 기억이 된다.

명세 → 명료화 → 계획 → 작업 → 분석 → 구현을 실제로 굴리는 법

이제 흐름을 실전 감각으로 다시 정리해 보자. 중요한 건 각 단계를 문서 이름으로 외우는 것이 아니라, 무엇을 확정하는 단계인지를 이해하는 것이다.

명세 단계에서는 기능의 목적과 범위를 못 박는다. 명료화 단계에서는 빠진 질문을 일부러 끌어낸다. 계획 단계에서는 구조와 기술 선택을 정리한다. 작업 단계에서는 병렬 처리 가능한 조각으로 나눈다. 분석 단계에서는 문서끼리 충돌하는 부분을 잡는다. 그리고 구현 단계에서 Antigravity가 비로소 움직인다.³

이 순서는 얼핏 느려 보일 수 있다. 하지만 실제로는 반대다. 구현이 시작된 뒤에 생기는 재작업의 대부분은 코딩 실수보다도 오해에서 나온다. 누락된 요구사항, 애매한 성공 조건, 숨은 제약, 범위 확대가 문제의 본체다. SDD는 바로 그 오해를 구현 전에 잡아내는 방식이다.

그래서 이 프로세스를 잘 쓰는 팀은 처음 30분을 아끼지 않는다. 대신 뒤의 3시간을 बच는다. 진짜 속도는 타자를 빨리 치는 데서 나오지 않는다. 덜 되돌아가는 데서 나온다.

바이브 코딩과 SDD의 균형점 찾기

그렇다고 모든 작업을 엄격한 명세 절차로 시작할 필요는 없다. 버튼 색 하나 바꾸는 일에 spec.md를 여는 순간, 사람도 에이전트도 지친다. 중요한 것은 언제 감으로 밀고, 언제 문서로 고정할지를 구분하는 감각이다.

저는 다음 기준을 추천한다.

• 탐색 단계에서는 바이브 코딩을 허용한다. 아이디어를 스케치하고, 화면 감을 보고, 사용자 반응을 빨리 확인한다.

• 공유 단계에서는 명세로 고정한다. 다른 개발자, 다른 에이전트, 미래의 나와 함께 일해야 하는 순간부터는 문서가 필요하다.

• 위험 단계에서는 SDD를 강제한다. 데이터 모델 변경, 인증, 결제, 운영 도구, 배포 파이프라인처럼 실수 비용이 큰 영역은 특히 그렇다.

즉, 아직 생각 중인 것은 바이브로, 이제 책임져야 하는 것은 스펙으로 다루면 된다.

실전 팁을 하나 더 주자면, 아예 두 단계를 분리하면 좋다. 먼저 10분 정도는 자유롭게 에이전트와 대화하면서 요구사항을 넓게 탐색한다. 그러고 나서 좋아, 이제 방금 이야기한 걸 기준으로 spec.md를 만들어 줘라고 말하며 문서 단계로 넘어간다. 이 전환점이 중요하다. 생각을 열어 둘 때와 실행을 잠글 때를 구분하는 것이다.

Antigravity에 잘 맞는 운영 루틴

Antigravity를 SDD 방식으로 잘 쓰는 팀은 대체로 비슷한 리듬을 가진다.

먼저 요구사항을 한 번에 완벽하게 쓰려 하지 않고, /speckit.specify나 이에 대응하는 정의 워크플로우로 초안을 만든다. 그다음 clarify 단계에서 빠진 질문을 모은다. 이어서 plan과 tasks를 통해 경계와 의존성을 정리한다. 그리고 그 문서를 Antigravity의 Manager View로 넘겨 각 에이전트가 읽게 한다. 마지막으로 브라우저 검증, 테스트, 스크린샷 같은 아티팩트를 보고 승인한다.⁴⁵

이 리듬의 장점은 사람의 집중력이 가장 값비싼 순간에 사람을 쓰게 된다는 점이다. 사람은 요구사항을 고르고, 우선순위를 정하고, 예외를 판정하고, 최종 결과를 승인한다. 반대로 에이전트는 문서화된 범위 안에서 구현과 반복 검증을 맡는다. 역할 분담이 선명해질수록 팀 전체의 처리량이 올라간다.

결국 SDD는 속도를 늦추는 게 아니라, 속도를 낭비하지 않게 만든다

Spec-Driven Development의 핵심은 문서를 숭배하는 데 있지 않다. 인간의 의도를 저장 가능한 형태로 만들고, 그 의도를 여러 에이전트가 재사용할 수 있게 하는 데 있다. Antigravity는 바로 이 지점에서 강하다. 계획과 작업과 검증을 아티팩트로 바꾸고, 그 아티팩트를 검토 대상으로 끌어올리기 때문이다.¹

바이브 코딩은 여전히 유효하다. 다만 그것만으로 제품을 끝까지 밀고 가려 하면, 어느 순간부터는 속도가 아니라 불안정성이 된다. 반대로 SDD는 처음 몇 분의 구조화를 요구하지만, 그 대가로 재현 가능성, 병렬화, 감사 가능성, 유지보수성을 돌려준다.²⁷

이 장의 메시지는 단순하다. 아이디어가 떠올랐을 때 바로 코드를 쓰고 싶다면, 먼저 한 번만 더 참아 보자. 요구사항을 문장으로 고정하고, 경계를 나누고, 성공 조건을 적어 두자. 그러고 나서 Antigravity에게 위임하자. 그 순간부터 개발은 코드를 직접 쓰는 일이 아니라, 제대로 쓰이게 만드는 일이 된다.

참고

¹Google Antigravity 공식 소개

²Antigravity에서 사양 기반 개발 시작하기

³GitHub Spec Kit 개요와 명령 흐름 설명

⁴Spec Kit for Google Antigravity README

⁵GitHub Spec-Kit와 Google Antigravity를 함께 쓰는 핸드오프 워크플로우

⁶Antigravity를 활용한 Spec-Driven Development 체험기

⁷Agent-First Software Engineering 메모