Claude Code를 팀에 붙이는 건 생각보다 쉽다. 문제는 그 다음이다. 처음 며칠은 놀라울 정도로 빠르게 코드가 나온다. 그런데 일주일쯤 지나면 조용한 균열이 보이기 시작한다. 이미 Zustand로 마이그레이션했는데 Redux 패턴이 새 파일에 들어와 있거나, 절대 건드리면 안 되는 자동생성 폴더에 손을 댔거나, 도메인 용어를 엉뚱하게 쓴 로직이 리뷰를 통과해 버린다. Claude Code가 나쁜 게 아니다. 컨텍스트 없이 50,000줄짜리 코드베이스에 던져놓으면 어떤 모델도 같은 실수를 한다.
실전에서 가치를 뽑아내는 팀과 그렇지 못한 팀의 차이는 단 하나다. AI 온보딩을 사람 온보딩처럼 설계했느냐. dev.to에 공개된 실전 가이드(stacknotice)는 이 지점을 정확히 짚는다. /init 커맨드로 CLAUDE.md 초안을 뽑은 뒤, 거기서 끝내면 안 된다. 아키텍처 결정과 그 이유, 지금 마이그레이션 상태, 절대 건드리면 안 되는 경로, 팀 고유의 도메인 어휘—이 네 가지를 명시적으로 채워야 한다. 특히 "do not modify" 섹션이 실제로 가장 많은 사고를 막는다. Claude는 도움이 되려고 하기 때문에, 명시적으로 막지 않으면 건드린다.
첫 주는 편집 권한을 주지 말고 읽기 전용 태스크부터 시작하는 게 맞다. "수정하지 말고 /lib/actions/ 폴더를 읽고 각 액션이 무엇을 하는지 설명해라"—이런 태스크 두세 개를 돌리면 Claude가 우리 코드베이스의 패턴을 제대로 이해했는지 검증할 수 있다. 이해가 확인된 뒤에 작고 리스크가 낮은 태스크부터 편집을 허용한다. 자율 커밋은 최소 일주일 뒤. 이 순서를 지키지 않으면 디버깅에 쓰는 시간이 생산성 향상분을 잡아먹는다.
컨텍스트 설계가 끝났다면 다음 문제는 AI가 생성한 코드의 품질을 어떻게 일관되게 검증하느냐다. 여기서 테스트 자동화 전략이 결합된다. dev.to에 공개된 크로스스택 단위 테스트 가이드는 한 가지 원칙을 강하게 밀어붙인다. 스택당 라이브러리를 하나만 쓰고, 절대 섞지 않는다. Node.js/NestJS는 Jest, React는 Vitest + Testing Library, Python은 pytest, Angular는 Jest(Karma 교체), Laravel은 Pest. 선택이 끝나면 .cursor/rules/ 디렉터리 아래에 스택별 규칙 파일을 세팅한다. 이 파일들이 AI 프롬프트에 자동으로 주입되면서 할루시네이션을 구조적으로 차단한다.
테스트 규칙의 핵심은 세 가지다. 첫째, 모든 외부 의존성은 mock으로 대체—실제 DB, 실제 HTTP 호출이 단위 테스트에 들어오는 순간 테스트가 환경에 종속된다. 둘째, AAA(Arrange-Act-Assert) 구조를 주석으로 명시—AI가 생성한 테스트도, 사람이 작성한 테스트도 같은 구조를 강제하면 리뷰 비용이 줄어든다. 셋째, 메서드당 최소 4개 케이스—정상 경로, null 입력, 에러 경로, 경계값. 이 규칙을 Cursor의 .cursor/rules/ 파일로 프로젝트에 박아두면 AI가 테스트를 생성할 때마다 자동으로 적용된다. 규칙이 IDE 레벨에서 주입되는 구조이기 때문에 팀원이 매번 프롬프트에 조건을 적을 필요가 없다.
마지막 레이어는 커밋 전 리뷰다. 컨텍스트를 아무리 잘 설계하고 테스트를 자동화해도, AI가 생성한 diff가 git에 쌓이는 속도는 사람의 리뷰 속도를 초과한다. git-lrc는 git commit 훅에 AI 리뷰어를 붙여서 diff가 레포에 들어오기 전에 10개 리스크 카테고리, 100개 이상의 실패 패턴을 체크한다. 설정이 60초면 끝나고 무료로 사용할 수 있다는 점에서 도입 장벽이 낮다. 완벽한 솔루션이라기보다 '속도가 붙은 AI 코딩에 브레이크를 하나 달아두는 것'으로 이해하면 적절하다.
세 레이어를 합치면 실행 루프가 완성된다. CLAUDE.md로 컨텍스트를 설계하고 → Cursor rules로 테스트 생성 규칙을 주입하고 → git hook으로 커밋 전 리뷰를 자동화한다. 각 레이어는 단독으로도 효과가 있지만, 셋이 연결될 때 AI 코딩 에이전트를 팀 워크플로우에 안전하게 녹이는 구조가 생긴다. 도입 첫 주에 전부 세팅하려 하지 말 것. CLAUDE.md 초안 작성과 읽기 전용 태스크 검증이 먼저다. 테스트 규칙과 커밋 훅은 팀이 AI 생성 코드의 패턴에 익숙해진 뒤 순서대로 붙이는 게 현실적이다.
AI 코딩 도구의 ROI는 도구 자체의 성능보다 팀이 설계한 검증 루프의 품질에 달려 있다. Claude Code가 코드를 빠르게 생성하는 만큼, 그 출력물이 우리 코드베이스의 패턴을 따르는지, 테스트가 제대로 붙는지, 위험한 변경이 커밋 전에 걸러지는지—이 세 가지를 팀이 먼저 설계하지 않으면 속도 향상은 기술 부채 누적 속도와 같아진다. 도구를 켜는 것과 워크플로우를 설계하는 것은 여전히 다른 일이다.