Claude Code로 iOS 앱을 혼자 만들어 App Store까지 출시한 사례, 멀티 에이전트 환경에서 컨텍스트 파일이 분산되는 문제를 CLI 하나로 통합한 사례, 그리고 AI가 생성한 코드 40%를 통째로 지워버린 사례. 세 이야기는 얼핏 따로 놓인 것처럼 보이지만, 실제로는 하나의 구조적 질문을 향해 수렴한다. AI 코딩 에이전트를 팀에 실전 도입할 때, 속도 이면에 숨어 있는 함정은 무엇인가.
함정 1. AI는 레이아웃을 '느낌'으로 못 잡는다
dev.to에 공개된 iOS 주식 예측 앱 'Stock HiLo' 개발기는 Claude Code의 가능성과 한계를 동시에 드러낸다. 개발자는 SwiftUI 카드 UI 구현에 가장 많은 토큰을 소비했다고 밝혔는데, 결국 마진을 pt 단위로 직접 지정하고, VStack 대신 ZStack을 제안하고, 네거티브 오프셋을 명시해야 원하는 레이아웃이 나왔다. 퍼포먼스 최적화 요청에서는 "생각할 수 있는 모든 개선 방법을 나열하고 하나씩 구현해줘"라는 프롬프트 하나로 20분 만에 캐시 우선 로딩, 차트 프리로드, 옵티미스틱 업데이트 등을 완성했다. 이 두 경험은 명확한 패턴을 보여준다. AI는 논리 구조에는 강하고, 시각적 정밀도에는 약하다. 팀 도입 시 이 경계를 설계 단계에서 명확히 그어두지 않으면, 프론트엔드 작업에서 반복적인 수정 루프가 발생하고 기대했던 속도 이득이 상당 부분 상쇄된다.
함정 2. 도구가 늘어날수록 컨텍스트가 분열된다
Claude Code가 읽는 파일은 CLAUDE.md다. Cursor는 .cursorrules, GitHub Copilot은 .github/copilot-instructions.md, Kiro는 .kiro/steering/*.md, Windsurf는 .windsurf/rules/*.md, Gemini CLI는 GEMINI.md를 각각 요구한다. 팀이 에이전트를 하나만 쓰는 경우는 드물다. 그런데 이 파일들이 동기화 없이 제각각 업데이트되는 순간, 같은 프로젝트에서 도구마다 다른 코딩 컨벤션을 제안하는 혼돈이 시작된다. dev.to에서 소개된 오픈소스 CLI contextai는 이 문제를 TypeScript 단일 설정 파일에서 9개의 에이전트 컨텍스트 파일을 자동 생성하는 방식으로 접근한다. npx contextai generate 한 번으로 전체 동기화가 완료되고, scope: 'agent-only' 옵션으로 AI 전용 지침과 인간용 문서를 분리할 수도 있다. 팀 규모와 무관하게 에이전트 컨텍스트 관리는 단일 소스 오브 트루스(Single Source of Truth) 체계를 처음부터 설계해야 한다. 나중에 고치려 하면 이미 각 도구가 서로 다른 판단을 내리고 있는 상태다.
함정 3. AI가 빠르게 쌓은 코드는 빠르게 부채가 된다
베트남에서 치과 관광 마켓플레이스를 운영하는 개발자는 Claude를 활용해 18만 줄짜리 Laravel 코드베이스를 감사했다. 결과는 냉혹했다. 컨트롤러 14개, Vue 컴포넌트 23개, 미들웨어 클래스 9개, Blade 템플릿 디렉터리 2개가 최근 90일간 실질적으로 사용되지 않은 상태였다. 이것들을 단 하루 만에 삭제했다. 테스트는 모두 통과했고, 배포 속도는 빨라졌으며, 신규 온보딩 개발자가 탐색해야 할 파일이 40% 줄었다. 그리고 한 가지 예상치 못한 효과가 더 있었다. 다음 날 Claude에게 새 기능 구현을 요청했을 때, 컨텍스트 윈도우에 노이즈가 줄어 제안 품질이 눈에 띄게 개선됐다는 것이다. 코드를 지우는 것이 AI를 더 잘 쓰는 방법이 된다. 이 역설은 AI 시대의 핵심 원리다. AI가 쓴 코드든 사람이 쓴 코드든, 유지되는 코드는 곧 유지 비용이다.
시사점: 테크 리드가 설계해야 할 것들
세 사례를 팀 도입 관점으로 종합하면 실행 포인트가 세 가지로 정리된다.
첫째, AI 작업 경계 매트릭스를 사전에 정의하라. 비즈니스 로직과 알고리즘은 AI에게, 픽셀 단위 시각 정밀도는 사람이 리뷰 루프를 통해 통제하는 구조를 명시적으로 설계해야 한다. 암묵적으로 기대하면 반드시 병목이 된다.
둘째, 컨텍스트 파일 거버넌스를 CI에 포함시켜라. contextai의 validate 명령이나 pre-commit 훅처럼, 에이전트 컨텍스트 동기화를 개인의 기억에 맡기지 말고 자동화 파이프라인의 일부로 만들어야 한다. 팀원이 한 명이라도 늘어나면 수동 관리는 즉시 무너진다.
셋째, AI 생성 코드에 대한 정기 감사 사이클을 스프린트에 넣어라. 분기 단위로 "이 모듈이 사라져도 누가 알아챌까?"라는 질문을 코드베이스 전체에 던지는 루틴이 필요하다. 작성보다 삭제가 더 어렵고, AI는 삭제 타이밍을 스스로 판단하지 못한다.
전망: '빠른 생성'에서 '좋은 판단'으로
AI 코딩 에이전트가 팀에 완전히 정착하는 시점이 가까워질수록, 경쟁 우위는 도구를 얼마나 빠르게 쓰는가에서 도구를 언제 멈추는가를 아는 쪽으로 이동할 것이다. 코드를 생성하는 능력은 이제 범용재다. 어떤 모듈을 만들지 않을 것인지, 어떤 컨텍스트를 AI에게 주지 않을 것인지, 어떤 코드를 지울 것인지를 판단하는 능력이 테크 리드와 시니어 개발자의 실질적 역할로 올라오고 있다. Claude Code는 강력한 도구다. 하지만 팀에 심을 때 속도만 보고 구조를 건너뛰면, 그 속도가 부채의 속도가 된다.