SYDE
SYDESYDESYDEAI가 뚝딱 짜준 코드, 진짜 믿어도 될까요?
AI 코딩 에이전트는 데모에서는 완벽하지만, 실제 프로덕션 코드베이스에선 쉽게 무너져요. 그 이유는 툴이 아니라 방법론의 문제예요.
SDD(Specification-Driven Development)는 요구사항 → 설계 → 태스크 → 구현의 4단계 루프로 AI가 "당신의 프로젝트 방식"을 따르도록 만들어요.
TDD(테스트 주도 개발)와 결합하면 AI가 스스로 테스트를 통과할 때까지 반복해줘요.
SDD를 도입한 팀은 AI 생성 코드의 회귀 버그가 60~80% 줄고, 피처 배포 속도가 30~40% 빨라진다고 해요.
AI 코딩 에이전트 데모를 보면 다들 입이 떡 벌어지죠. "SaaS 대시보드 만들어줘" 한 마디에 3분 만에 인증, DB, 결제까지 갖춘 앱이 뚝딱 나오는 걸 보면서요.
그런데 내 프로젝트에 써보면 다르죠. 파일 200개짜리, 커스텀 인증 레이어에 외부 API 3개 연동된 모노레포에다 프롬프트를 넣는 순간 — AI가 신나서 DB 스키마를 갈아치우고, 핵심 미들웨어를 지우고, 보안 취약점 4개를 뚝딱 만들어놓아요.
이게 바로 "바이브 코딩 갭(Vibe Coding Gap)"이에요. 데모에서 되는 것과 프로덕션에서 되는 것 사이의 거리는 도구의 문제가 아니라 방법론의 문제예요.
바이브 코딩이 실무에서 망하는 이유는 딱 4가지로 정리돼요.
첫 번째는 컨텍스트 붕괴예요.
AI 에이전트는 기억이 없어요. 새 세션이 시작될 때마다 제로에서 출발하죠. 여러분 코드베이스에 있는 암묵적 규칙들 — 네이밍 컨벤션, 에러 핸들링 패턴, 인증 레이어에서 userId는 UUID고 레거시 API에선 user_id가 순차 정수라는 사실 — 이 모든 게 AI한텐 존재하지 않아요. 결과적으로 혼자서는 돌아가지만 기존 코드와 충돌하는 코드가 나오는 거예요.
두 번째는 해피 패스 편향이에요.
AI는 주로 튜토리얼 코드, 문서 예제, 스택오버플로 답변으로 학습됐어요. 그런 데이터들은 압도적으로 "다 잘 됐을 때" 시나리오만 보여줘요. 그래서 AI가 짠 코드는 주요 플로우엔 강하지만 네트워크 타임아웃, 동시 요청 충돌, DB 커넥션 고갈, 잘못된 사용자 입력엔 속수무책이에요. 2025년 Endor Labs 연구에 따르면 AI 생성 코드의 62%에 보안 취약점이나 설계 결함이 있다고 해요.
세 번째는 오너십 공백이에요.
바이브 코딩으로 배포한 코드는 만든 사람도 설명 못 하는 코드가 돼요. 새벽 2시에 프로덕션에서 버그가 터지면? 내가 짠 것도 아닌 코드를 뜯어봐야 하는데, 왜 이렇게 설계됐는지 맥락이 없으니 고치는 데 몇 시간이 걸리죠.
네 번째는 기술 부채의 복리 효과예요.
세션이 쌓일수록 각각 조금씩 다른 스타일, 다른 에러 처리 방식, 다른 아키텍처 가정이 뒤섞여요. 10번 세션 후에 여러분 코드베이스는 사실 10개의 서로 다른 미니 코드베이스가 된 거예요. 그리고 새 AI 세션은 그 혼돈을 고스란히 이어받죠.
SDD(Specification-Driven Development)는 "프롬프트 → 코드" 한 방을 4단계 루프로 바꿔요. 각 단계마다 AI가 참조할 수 있는 문서 아티팩트가 나와요.
📋 1단계 — 요구사항 (requirements.md):
코드 생성 전에 AI에게 요구사항 분석을 먼저 시켜요. "팀 초대 시스템을 추가하고 싶어. 코드 짜기 전에, 유저 스토리, 엣지 케이스, 보안 요구사항, 기존 인증 시스템과의 연동 포인트, 그리고 이번 단계에서 만들지 않을 것들을 requirements.md에 정리해줘." 여기서 "만들지 않을 것"을 명시하는 게 핵심이에요. 이게 없으면 AI는 요청하지 않은 기능까지 과잉 구현하거든요.
🏗️ 2단계 — 설계 (design.md):
요구사항이 확정되면 기술적 결정을 문서화해요. DB 스키마 변경, API 엔드포인트, 서비스 레이어 아키텍처, 에러 핸들링 전략 등을 다루죠. 이 단계에서 코드를 짜지 않는 게 포인트예요. 아키텍처 실수는 코드가 생기기 전에 잡는 게 훨씬 저렴하니까요.
📝 3단계 — 태스크 (tasks.md):
설계를 의존성 순서대로 잘게 쪼개요. DB 레이어 → 서비스 레이어 → API → 통합 테스트 순으로 묶고, 각 태스크마다 예상 테스트 커버리지와 복잡도(S/M/L)를 표기해요. AI 에이전트가 한 세션에 하나씩 집중해서 처리할 수 있는 크기여야 해요.
⚙️ 4단계 — 구현:
이제야 코드를 짜요. 그것도 한 번에 전부가 아니라 태스크 하나씩이에요. "tasks.md의 태스크 2를 구현해줘. src/services/TeamService.ts의 기존 패턴을 따르고, 입력 검증엔 Zod를 써줘. 테스트 먼저 작성하고, 구현 후 실행해서 통과 확인해줘. 다른 파일은 import 추가 외엔 절대 수정하지 말고, 태스크 3~5는 아직 하지 마." 이 프롬프트의 제약 조건들이 바로 핵심이에요.
SDD 루프는 세션 간 영구적으로 유지되는 파일에 의존해요. CLAUDE.md, Cursor Rules, AGENTS.md 같은 파일이에요. 이건 도구는 달라도 목적은 같아요 — 모든 AI 세션이 시작할 때 읽는 "프로젝트 브리핑 문서"예요.
여기엔 기술 스택, 아키텍처 규칙, 코딩 컨벤션, 자주 쓰는 커맨드, 그리고 절대 하면 안 되는 것들이 들어가요. 중요한 건 루트 스펙 파일은 200~300줄 이내로 유지하는 거예요. 모든 규칙을 다 넣는 게 아니라 "어디서 더 찾을 수 있는지"를 알려주는 라우터 역할이에요. AI가 관련 영역을 작업할 때 세부 문서를 필요에 따라 읽는 방식이죠. 좋은 소프트웨어의 점진적 공개(Progressive Disclosure) 원칙을 AI 컨텍스트 관리에 그대로 적용한 거예요.
디렉토리별 규칙도 활용하면 좋아요. src/services/.rules 같은 파일에 서비스 레이어 전용 제약 조건을 넣어두면, 해당 영역 작업 시 더 정밀한 가이드가 생기죠.
TDD는 AI 에이전트와 함께할 때 오히려 더 강력해요. 테스트가 AI에게 가장 필요한 것 — "정확함"의 객관적이고 검증 가능한 정의 — 을 줘요.
기존 방식에선 AI가 코드를 생성하면 사람이 직접 검토해요. 내가 짜지 않은 코드에서 버그를 찾아야 하는 인지적으로 고통스러운 작업이에요. TDD에선 정확함을 먼저 정의하고, AI가 테스트를 통과하는 코드를 생성하게 해요. 구현 디테일이 아니라 결과를 검토하는 거죠.
실전 흐름은 이래요. 먼저 사람이 테스트 스펙을 써요. 정상 케이스, 중복 거부, 팀 인원 제한, 만료 시간 등 예상되는 모든 시나리오를 테스트로 표현하죠. 그 다음 AI에게 "이 테스트 파일이 기대 동작을 정의하고 있어. 테스트를 통과하도록 구현해줘. 실패하면 스스로 반복해서 수정해"라고 하는 거예요. AI가 스스로 레드-그린 루프를 돌아요. 사람은 테스트 통과 후 패턴 준수 여부, 성능 문제, 보안 이슈만 목적의식을 갖고 검토하면 돼요.
팀들은 보통 3단계를 거쳐 SDD에 익숙해져요.
1단계 — 반응형(대부분의 팀): 즉흥적인 프롬프트로 AI 활용, 자주 디버깅, 영구 컨텍스트 파일 없음, 매 세션 제로에서 시작.
2단계 — 구조화(SDD 도입): CLAUDE.md/AGENTS.md 세팅 완료, 복잡한 피처에 4단계 루프 적용, TDD 통합, 디자인 리뷰가 구현 전에 이루어짐.
3단계 — 체계화(SDD 완숙): 스펙 레포지토리를 코드와 함께 버전 관리, AI 에이전트가 작업하면서 스펙 문서도 업데이트, Cursor/Claude Code/Copilot 등 툴에 관계없이 일관성 유지.
대부분의 팀이 한 스프린트 만에 2단계에 도달할 수 있어요. 3단계는 2~3개월에 걸쳐 자연스럽게 형성돼요.
사이드프로젝터에게 AI 코딩 에이전트는 정말 강력한 무기예요. 그런데 그 무기를 "바이브로" 쓰면 내가 이해하지 못하는 코드가 쌓이고, 새벽에 버그를 마주할 때 가장 외로운 순간이 찾아오죠. SDD의 핵심은 거창한 프로세스가 아니에요 — "AI한테도 온보딩이 필요하다"는 인식의 전환이에요. CLAUDE.md 하나 제대로 만드는 것부터 시작해보세요. 생각보다 금방 달라지는 걸 느끼실 거예요.
👇 원문 보기
https://pockit.tools/blog/specification-driven-development-ai-coding-agents-complete-guide/첫 번째 댓글을 남겨보세요!