"user dashboard with analytics 추가해줘." 한 줄 프롬프트를 넣고 AI 에이전트가 생성한 코드를 열어본 적 있다면, 그 결과물이 얼마나 자신감 넘치면서도 얼마나 빗나가 있는지 알 것이다. 데이터 모델은 엉뚱하고, API 엔드포인트는 기존 패턴과 맞지 않고, 에러 핸들링은 없고, '분석' 기능은 하드코딩된 숫자 네 개다. 그 이후 한 시간은 교정과 재프롬프팅의 반복이다. 처음부터 직접 짰으면 더 빨랐을 수도 있다는 생각이 드는 지점.
dev.to에 공개된 Spec-Driven Development 가이드는 이 낭비의 구조적 원인을 명확히 짚는다. AI 코딩 에이전트의 문제는 능력 부족이 아니라 방향 부재다. Claude Code든, Cursor Agent든, 이 도구들은 코드베이스 전체를 읽고 컨벤션을 파악하며 프로덕션 수준의 코드를 만들어낼 수 있다. 단, 당신이 원하는 것을 정확하고 완전하게 알려줬을 때에 한해서. 모호한 프롬프트는 모델이 스스로 빈칸을 채우게 만들고, 그 빈칸은 언제나 일반적이고 맥락 없는 가정으로 채워진다.
해법은 AI를 챗봇이 아니라 시니어 엔지니어처럼 대우하는 것이다. 시니어에게 "로그인 폼 만들어줘"라고 하지 않는다. 어떤 엔드포인트를 호출하는지, 성공 시 토큰을 어디에 저장하는지, 401일 때 어떤 메시지를 어디에 노출하는지, 요청 중에 버튼을 어떻게 처리하는지를 설계 문서로 건넨다. Spec-Driven Development는 이 설계 문서 작성을 AI 워크플로우의 선행 단계로 공식화한 방법론이다.
실용적인 스펙은 다섯 레이어로 구성된다. 무엇을(What): 원하는 동작을 솔루션이 아닌 행동 명세로 기술한다. 어디에(Where): 생성하거나 수정할 파일 경로를 명시한다. 어떻게(How): React Query를 쓸지 useEffect를 쓸지, 어떤 공유 컴포넌트를 재사용할지 등 기술적 제약을 못 박는다. 엣지 케이스(Edge Cases): 로딩 중, 빈 상태, 느린 응답, 포커스 복귀 시 갱신 등 AI가 기본적으로 낙관적으로 처리하고 지나치는 비정상 경로를 명시한다. 테스트(Tests): 검증해야 할 동작을 나열해 에이전트가 테스트까지 함께 작성하도록 유도한다. 이 다섯 레이어가 채워질수록 모델의 선택 범위는 좁아지고, 출력의 예측 가능성은 높아진다.
이 구조가 에이전트를 "더 똑똑하게" 만드는 것은 아니다. 정확히는 더 적게 추측하게 만드는 것이다. 스펙이 있으면 모델은 API 계약을 발명할 필요가 없고, 에러 메시지를 창작할 필요가 없고, 어떤 파일이 중요한지 추론하느라 컨텍스트 윈도우를 소모할 필요가 없다. 가이드에 따르면, 2,000토큰짜리 정밀한 스펙 하나가 20,000토큰 분량의 교정 대화를 대체한다. 10배의 컨텍스트 효율이다.
흥미롭게도, 같은 날 dev.to에 공개된 ToolHub 아키텍처 회고는 다른 각도에서 같은 원칙을 보여준다. 138개 웹 유틸리티를 담은 이 PWA는 Next.js의 output: 'export' 정적 출력, 커스텀 서비스 워커, pSEO 엔진으로 서브초(sub-second) 응답과 완전한 오프라인 지원을 동시에 달성했다. 서버를 없애는 대신 모든 동적 처리를 클라이언트로 밀어넣고, CDN 엣지에서 TTFB를 최소화했다. CLS를 막기 위해 광고 슬롯의 고정 높이를 미리 예약해두는 Zero-CLS 전략까지, 성능 목표를 코드가 아니라 아키텍처 결정 시점에 내장했다.
두 사례가 교차하는 지점이 이 글의 핵심이다. Spec-Driven Development는 AI 에이전트에게 코드를 시키기 전에 설계를 완성하라고 요구하고, ToolHub의 정적 아키텍처는 런타임이 아닌 빌드 타임에 품질을 결정하라고 말한다. 방향은 다르지만 원칙은 같다. 품질은 코드 생성 단계가 아니라 그 이전 단계에서 결정된다. AI가 빠르게 만들어주는 것은 코드다. 그 코드가 의도한 품질을 갖출지는 설계가 결정한다.
실무 적용 관점에서 지금 당장 시작할 수 있는 것은 하나다. 에이전트 창을 열기 전에 15분을 쓴다. 목적, 파일 구조, 기능 요구사항, 기술 제약, 엣지 케이스, 테스트 목록—이 여섯 섹션짜리 템플릿을 채운다. 처음엔 느리게 느껴진다. 하지만 그 15분이 이후 한 시간의 교정 루프를 없앤다. 스펙 작성 자체가 요구사항을 명확히 생각하게 만드는 훈련이기도 하다. "어떻게 구현하지"를 고민하기 전에 "무엇을 원하는지"를 먼저 언어로 완성하는 것, 그게 AI 시대의 프론트엔드 개발자가 회복해야 할 설계 근육이다.
앞으로의 방향은 분명하다. AI 코딩 도구의 능력은 계속 올라간다. 하지만 능력이 올라갈수록 모호한 입력이 만드는 오차도 함께 커진다. 스펙 없이 강력한 에이전트를 쓰는 것은 네비게이션 없이 빠른 차를 모는 것과 같다. 속도는 빨라지지만 목적지에 도착할 확률은 낮아진다. Spec-Driven Development는 그 네비게이션을 워크플로우 안에 고정시키는 방법이다. AI가 빠를수록, 설계는 더 먼저 와야 한다.