Claude Code를 팀에 도입하기로 결정했다면, 다음 질문은 어떻게 쓸 것인가가 아니다. 어디서 먼저 무너지는가를 먼저 따져야 한다. Anthropic이 공개한 대규모 코드베이스 모범 사례, MCP 기반 테스트 자동화 실전 사례, 그리고 LLM 모델 퇴역 타임라인을 나란히 놓고 보면, 팀 도입 과정에서 반복되는 함정 세 가지가 선명하게 드러난다.
함정 1. 하네스 없이 모델에 기대는 롤아웃
Anthropicが 정리한 모범 사례 문서가 가장 먼저 짚는 것은 놀랍도록 단순하다. Claude Code의 성능은 모델보다 하네스가 결정한다. CLAUDE.md, Hooks, Skills, Plugins, MCP 서버—이 다섯 레이어가 제대로 쌓이지 않으면, 아무리 최신 모델을 붙여도 대규모 코드베이스에서 Claude는 방향 없이 grep만 돌리는 에이전트가 된다.
현장에서 가장 흔히 보이는 실수는 루트 CLAUDE.md 하나에 모든 것을 몰아넣는 패턴이다. 세션마다 전체 문맥이 로드되니 컨텍스트 창이 잡음으로 가득 차고, Claude는 정작 필요한 심볼을 찾기 전에 한계에 부딪힌다. Anthropic이 권장하는 구조는 반대다. 루트는 치명적 주의사항과 포인터만, 하위 디렉터리 CLAUDE.md는 해당 서비스의 로컬 규칙만 담는다. 테스트와 린트 명령도 전체 스위트가 아니라 하위 디렉터리 범위로 한정해야 타임아웃 없이 돌아간다.
더 중요한 설계 포인트는 LSP 통합이다. 문자열 패턴으로 grep하면 흔한 함수 이름 하나에 수천 개 매치가 쏟아지고, Claude는 무엇이 진짜 참조인지 판단하려고 파일을 열며 컨텍스트를 소모한다. LSP를 연결하면 같은 심볼을 가리키는 참조만 반환되므로, 파일을 읽기 전에 필터링이 완료된다. 다중 언어 코드베이스라면 이것 하나만으로도 Claude의 탐색 정밀도가 달라진다.
그리고 이 모든 설정을 DRI 또는 agent manager 한 명이 소유해야 한다. 상향식 도입은 열의를 만들지만, 중앙화할 사람이 없으면 팀마다 다른 CLAUDE.md가 생기고 지식은 파편화된다. 설정 검토 주기는 3~6개월. 특히 모델 릴리스 직후 성능이 정체된 것처럼 느껴질 때가 바로 CLAUDE.md를 다시 들여다볼 타이밍이다.
함정 2. MCP 없이 사람이 클립보드 역할을 하는 테스트 루틴
Zod 스키마를 복사해 ChatGPT에 붙여넣고, 유효한 목 데이터를 받아서 다시 테스트 파일에 붙여넣는다. 부정 케이스가 필요하면 또 붙여넣는다. Playwright 보일러플레이트가 필요하면 또 한 번. 이 루틴을 AI를 쓰는 것이라고 착각하기 쉽지만, 실제로는 개발자가 IDE와 AI 사이의 인간 클립보드로 전락한 것이다.
dev.to에 공개된 zod-contract-mock-forge-mcp 사례는 이 루틴을 MCP 서버 하나로 끊어낸다. Claude Desktop이나 Cursor에 MCP 서버를 연결하면, AI가 직접 스키마 파일을 읽고(read_schema_from_file), 유효한 목 데이터를 생성하고(generate_valid_mock), 경계 위반 부정 케이스를 재귀적으로 만들어(generate_boundary_violations), Playwright·Jest·MSW 보일러플레이트까지 scaffolding한다(scaffold_api_contract_test). 개발자가 할 일은 "이 스키마 읽고 부정 테스트 스위트 써줘" 한 문장이다.
이 사례가 보여주는 시사점은 도구 하나의 편의성이 아니다. MCP 서버는 AI 에이전트의 행동 반경을 IDE 바깥까지 확장하는 인프라라는 점이다. Claude Code 하네스에 MCP 서버를 연결하는 순간, 에이전트는 내부 분석 플랫폼, 티켓 시스템, 테스트 프레임워크까지 직접 호출할 수 있다. 반대로 MCP 없이 Claude Code만 도입하면, 테스트·배포 자동화의 절반은 여전히 사람 손에 남는다. 기초 하네스가 안정화되기 전에 MCP 연결부터 만들려는 충동은 경계해야 하지만, 안정화 이후의 다음 스텝은 반드시 MCP 확장이어야 한다.
함정 3. 모델 퇴역을 운영 리스크로 설계하지 않은 파이프라인
2026년 5월 15일, xAI는 Grok API 모델 8개를 퇴역시켰다. 공지 기간은 9일이었다. 더 심각한 것은 퇴역된 slug가 하드 에러를 내지 않는다는 점이다. 조용히 grok-4.3으로 리다이렉트되고, 과금은 새 모델 요금으로 바뀌며, 로그에는 아무 에러도 찍히지 않는다. 출력 품질과 비용이 바뀌었지만 알림은 없다.
xAI만의 문제가 아니다. Anthropic은 Claude Opus 4와 Sonnet 4를 2026년 6월 15일에 종료한다(Opus 3는 이미 1월 5일에 퇴역). OpenAI는 Assistants API를 8월 26일에 선셋한다. Google은 Gemini 2.0 Flash를 6월 1일부로 종료할 수 있다. 모델 ID를 프로덕션에 고정하는 것은 정답이면서 동시에 새로운 부채가 됐다. 고정하지 않으면 동작이 조용히 바뀌고, 고정하면 퇴역 시점에 파이프라인이 끊기거나 더 나쁘게는 조용히 리라우팅된다.
Claude Code를 팀에 통합한다는 것은 Anthropic API를 프로덕션 의존성으로 가져간다는 뜻이다. 그렇다면 모델 퇴역은 라이브러리 breaking change와 동급의 운영 리스크로 다뤄야 한다. 최소한의 대응은 세 가지다. 첫째, 공급자별 deprecation 타임라인을 RSS 또는 자동화 채널로 구독할 것. 둘째, 모델 버전을 환경 변수로 외부화하고 배포 파이프라인에서 변경 가능하도록 설계할 것. 셋째, 새 모델로의 전환 테스트를 정기 배포 사이클에 포함시킬 것. CLAUDE.md를 3~6개월마다 검토하라는 Anthropic의 권고가 모델 퇴역 주기와 맞물리는 이유가 여기에 있다.
세 함정이 가리키는 하나의 구조적 진실
세 함정을 나란히 놓으면 공통 패턴이 보인다. Claude Code 도입의 실패는 대부분 도구의 한계가 아니라 운영 설계의 부재에서 온다. 하네스 없는 롤아웃, 클립보드 루틴, 모델 퇴역 무방비—세 가지 모두 도구를 쓰기 전에 팀이 설계해야 할 인프라와 프로세스의 문제다.
내일 당장 확인해볼 체크리스트는 간단하다. CLAUDE.md가 계층적으로 설계됐는가, MCP 서버가 테스트 자동화 루틴에 연결됐는가, 그리고 현재 프로덕션에 고정된 모델 ID의 퇴역 일정을 팀 누군가가 구독하고 있는가. 세 질문에 모두 '예스'가 나오는 팀이 AI-First 워크플로우를 실제로 운영하는 팀이다.