만능 에이전트를 찾는 것 자체가 함정이다
팀에 AI 코딩 도구를 처음 도입할 때 가장 흔히 저지르는 실수가 있다. '가장 좋은 도구 하나'를 찾는 것이다. Cursor냐 Windsurf냐, Claude Code냐 Copilot이냐를 두고 벤치마크를 돌리고 비교표를 만들다 보면 어느새 도구 선택이 목표가 되어버린다. 그런데 현장에서 실제로 AI 도구를 써보면 금방 깨닫는 사실이 있다. 작업 단계마다 필요한 AI의 결이 완전히 다르다는 것.
브런치에 공개된 한 개발자의 경험이 이 지점을 정확하게 짚는다. 그는 안티그래비티(Antigravity), Windsurf, 코덱스(Codex)를 단계별로 분리해서 사용하는 'AI 오케스트라' 방식으로 프로덕트를 만들었다. 기획 단계에서는 멀티모달 추론으로 구조를 잡아주는 안티그래비티, 뼈대가 잡힌 코드베이스 위에 새 기능을 얹을 때는 프로젝트 전체를 하나의 문서처럼 읽어내는 Windsurf, 그리고 이유를 알 수 없는 버그 앞에서는 실행 흐름을 따라가며 예외 처리가 어디서 삼켜지는지를 추적하는 코덱스. 이 세 도구는 서로 경쟁하지 않는다. 각자의 타이밍에 각자의 방식으로 쓸모가 있다.
도구를 길들이는 것도 설계다: Claude Code CLAUDE.md 워크어라운드
에이전트를 선택했다고 끝이 아니다. 도구를 실무에서 안정적으로 운영하려면 도구의 약점을 미리 설계로 막아야 한다. Claude Code를 멀티파일 프로젝트에 쓰는 팀이라면 한 번쯤 마주쳤을 에러가 있다. API Error: Stream idle timeout — partial response received. 작업 중간에 스트림이 끊기고, 재시도하면 같은 방식으로 다시 끊긴다.
dev.to에 공개된 실전 워크어라운드에 따르면, 이 타임아웃의 원인은 프롬프트 길이가 아니라 출력 길이다. Claude Code가 300줄짜리 파일을 한 번의 tool call로 쓰거나, 수백 줄을 뱉는 grep을 제한 없이 실행하거나, 무거운 tool call을 멈추지 않고 체이닝하면 스트림이 유휴 상태가 되고 연결이 끊긴다. 세션이 길어질수록—tool call이 20회를 넘어서면—이 확률은 급격히 올라간다.
해결책은 설정 변경이 아니다. CLAUDE.md에 다섯 줄의 제약 규칙을 추가하는 것이다. 핵심만 추리면 이렇다: 작업은 한 번에 하나씩, 파일은 150줄 이상이면 여러 번에 나눠 쓰기, 20회 tool call 이전에 세션 새로 시작, grep 출력은 플래그로 제한, 타임아웃이 터지면 같은 프롬프트를 그대로 재시도하지 말고 더 짧은 형태로 분할해서 재시도. Claude Code는 세션 시작마다 CLAUDE.md를 읽고 이 규칙을 제약으로 따른다. 이전에 이미 다룬 것처럼, CLAUDE.md는 프롬프트가 아니라 아키텍처다. 도구의 행동 방식을 구조적으로 통제하는 설계 레이어다.
AI가 짠 코드를 그냥 배포하면 조용히 터진다
에이전트를 잘 선택하고, 도구를 안정적으로 길들였다고 해도 마지막 관문이 남아 있다. AI가 생성한 코드의 품질 검증이다. dev.to에서 공개된 체크리스트는 이 검증을 세 단계로 나눈다.
즉시 고쳐야 할 Critical 항목부터다. <img> 태그에 width와 height가 없으면 레이아웃 시프트가 발생한다. 라이브러리 전체를 import하는 코드는 번들 사이즈를 조용히 부풀린다. AI는 특정 함수 하나만 필요한 상황에서도 습관적으로 전체 패키지를 불러오는 패턴을 자주 만든다.
배포 전에 최적화해야 할 항목도 있다. moment, axios, lodash, 아이콘 풀 라이브러리처럼 무거운 의존성이 들어왔는지 확인하고, 차트 라이브러리나 PDF 파서처럼 무거운 모듈은 dynamic import()로 래핑해야 한다. 애니메이션은 transform과 opacity만 써야 하고, transition: all은 레이아웃을 건드리는 속성까지 함께 트리거한다. 데이터 페칭은 순차 await 대신 Promise.all로 병렬 처리해야 하고, 상호작용이 필요 없는 React 컴포넌트는 Server Component로 써야 한다.
장기적으로 갖춰야 할 구조도 있다. .cursorrules나 Copilot instructions 같은 AI 컨텍스트 파일에 성능 기준을 인코딩해서 AI가 처음부터 제약 안에서 코드를 만들게 한다. ESLint 룰로 이미지 디멘션 요구사항을 강제하고 문제 있는 import 패턴을 금지한다. CI 파이프라인에 size-limit이나 bundlesize를 붙여서 AI가 생성한 import로 인한 번들 사이즈 회귀를 자동으로 잡는다.
AI 오케스트라를 운영한다는 것의 진짜 의미
세 가지를 엮어서 보면 하나의 실무 원칙이 나온다. 에이전트를 선택하는 것, 도구의 행동을 설계로 통제하는 것, AI가 만든 결과물을 구조적으로 검증하는 것. 이 세 단계가 모두 갖춰져야 AI-First 워크플로우가 실제로 작동한다.
만능 에이전트를 찾는 것이 잘못된 질문이라면, 올바른 질문은 이것이다. '우리 팀의 작업 단계를 어떻게 구분하고, 각 단계에 어떤 도구를 배치하고, 그 도구들이 만들어낸 결과물을 어떻게 검증할 것인가.' 이 질문에 답하는 순간, AI 도구 도입은 도구 선택의 문제가 아니라 워크플로우 설계의 문제가 된다.
앞으로 에이전트 성능은 계속 올라갈 것이다. Claude Code의 스트림 타임아웃 이슈도 결국 플랫폼 레벨에서 해결될 것이다. 하지만 도구가 좋아질수록 검증의 책임은 더 선명하게 팀에 남는다. AI가 빠르게 만들수록, 팀이 설계자이자 검증자로서 역할을 얼마나 잘 수행하느냐가 결과물의 품질을 가른다. 오케스트라에서 지휘자의 역할이 사라지지 않는 것처럼.