기본값으로 쓰는 팀이 놓치는 것
Claude Code를 도입한 팀 대부분은 출력을 기본값으로 받는다. 프롬프트를 날리고, 코드를 받고, 리뷰한다. 그러다 어느 순간 '이거 생각보다 별로네'라는 결론에 도달한다. 문제는 모델이 아니다. 세팅을 안 한 것이다. AWS 빌더 커뮤니티에 올라온 실전 마이그레이션 사례는 이걸 정면으로 짚는다—"디폴트 경험은 그럭저럭하다. 설정된 경험은 변혁적이다." MySQL→PostgreSQL 마이그레이션, Spring Boot 2→3, Java 17→21, React 17→18, 레거시 4개 레포를 2개로 통합. 보통 팀이라면 여러 스프린트가 걸릴 작업을 혼자 끝냈다. 가능하게 만든 건 Claude Code가 아니라 그 전에 깔아둔 구조였다.
병렬 개발의 함정: 워크트리가 실패하는 이유
여러 Claude Code 에이전트를 동시에 돌리는 건 이제 표준 조언에 가깝다. 그리고 그 표준 조언은 'git worktree를 써라'다. 에이전트마다 코드베이스 사본을 주고, 독립 브랜치에서 충돌 없이 작업하라는 논리다. TypeScript 모노레포를 운영하는 Trigger.dev는 이걸 실제로 시도했고, 빠르게 포기했다.
이유는 단순하다. 포트 충돌, 데이터베이스 격리, 공유 서비스 증식, 디스크 폭증. 한 유저는 ~2GB 코드베이스에서 워크트리 두 개만 만들었더니 9.82GB가 사라졌다고 보고했다. 각 워크트리마다 node_modules, 빌드 아티팩트, 독립 DB가 필요하다. 결국 기능 배포가 아니라 워크트리 관리 스크립트 개발에 시간을 쓰게 된다.
GitButler: 하나의 워킹 디렉토리, 여러 브랜치
Trigger.dev가 선택한 대안은 GitButler다. 핵심 발상은 단순하다. 브랜치를 디렉토리로 격리하지 않고, 변경사항을 브랜치에 할당한다. 파일을 수정한 뒤 '이 변경은 feat 브랜치, 저 변경은 docs 브랜치'로 지정하면, 커밋 시 각 브랜치에 해당 변경만 들어간다. 서버는 계속 돌아가고, DB는 하나고, 환경변수도 하나다.
그리고 Claude Code에 but CLI를 스킬로 가르쳤다. 150줄짜리 마크다운 스킬 파일이 핵심이다. git commit, git add, git push를 절대 쓰지 말고 but만 쓰도록 강제한다. Claude는 but status --json으로 현재 상태를 읽고, --changes 플래그로 파일별로 다른 브랜치에 커밋한다. 하나의 세션에서 API 코드는 feat/usage-api에, 문서는 docs/usage-api에 각각 깔끔하게 들어간다. 훅이나 매직 없이, Claude가 도구 사용법을 알고 있기 때문이다.
컨텍스트 계층화: CLAUDE.md가 팀 온보딩 문서가 되는 순간
병렬 브랜치 전략이 실행 레이어라면, CLAUDE.md는 전략 레이어다. 앞서 언급한 마이그레이션 사례에서 CLAUDE.md는 세 계층으로 설계됐다. 워크스페이스 레벨(25개 이상 레포 개요, 아키텍처 전체), 도메인 레벨(18개 서비스 카탈로그, JWT 인증 구조), 레포 레벨(서비스별 컨벤션, 테스트 기준). Claude Code가 어느 레포에서 세션을 열어도 자동으로 전체 컨텍스트 스택을 갖고 시작한다.
메모리 시스템은 한 단계 더 나아간다. 17개 메모리 파일이 세션을 넘어 지속된다. 특히 피드백 메모리가 강력하다. "커밋을 amend하지 마라, CI가 깨진다" "테스트 실패는 커밋 전에 모두 잡아라" 같은 교정이 영구 규칙으로 쌓인다. 신규 팀원이 몇 달에 걸쳐 체득할 워크플로우 규칙을 Claude가 몇 주 만에 내면화한다. 이게 팀 인프라로서의 Claude Code가 개인 도구와 근본적으로 다른 지점이다.
품질 천장의 정체: 스펙을 늘려도 올라가지 않는 것
세팅이 아무리 탄탄해도 넘어서지 못하는 벽이 있다. AI 출력 품질 연구에서 이를 '취향 격차(taste gap)'라고 부른다. AI는 실행 격차는 메운다. 2000줄짜리 스펙을 주면 모든 요구사항을 충족하는 코드를 만든다. 그런데 동작은 하지만 공허하다. 숙제 증명처럼 개념은 맞는데 '이게 실제 제품인가'라는 느낌이 없다.
이유는 스펙에 적히지 않는 것들 때문이다. 200ms에서도 로딩 상태가 깨진 것처럼 느껴지는 순간, 빈 상태가 방치감을 주는 타이밍, 기술적으로 정확한 드롭다운이 이 사용자에겐 틀린 선택인 이유—이런 판단은 요구사항으로 쓸 수 없다. Andrej Karpathy가 '바이브 코딩' 표현을 정정한 것도 이 맥락이다. "여전히 취향과 아키텍처 사고가 필요하다." 개발자의 역할이 코더에서 오케스트레이터로 바뀌었지만, 잘 지휘하려면 좋은 게 어떻게 생겼는지 알아야 한다.
천장을 올리는 유일한 연습
AI 출력을 수용하기 전에 하나만 하면 된다. 버그가 아니라, 누락된 요구사항도 아니라, "이 상황에서 기술적으로는 맞지만 틀린 것이 무엇인가"를 명확히 말로 표현하는 것. 이 연습은 두 가지를 한다. 취향 판단을 언어화하면서 판단력이 더 정밀해지고, 언어화되면 재스펙화가 가능해진다. 다음 AI 이터레이션은 암묵적 기대가 아니라 실제 타깃을 갖는다.
프로세스와 가드레일은 출력의 바닥을 올린다. 취향의 천장은 반복적인 인식-명명-재스펙 사이클로만 올라간다. 세팅이 전략인 것처럼, 판단력도 설계 가능한 역량이다.
세팅을 전략으로 쌓는 순서
세 기사가 수렴하는 지점은 하나다. Claude Code를 팀 워크플로우에 통합할 때 속도만큼 중요한 것은 레이어의 순서다.
첫째, 실행 인프라를 먼저 잡는다. GitButler처럼 병렬 작업이 서로를 망가뜨리지 않는 구조. 워크트리의 직관적 격리 대신, 하나의 환경에서 변경사항을 분리하는 발상의 전환이 핵심이다.
둘째, 컨텍스트를 문서화하고 계층화한다. CLAUDE.md와 메모리 시스템은 AI를 위한 온보딩 패키지다. 팀이 아는 것을 Claude도 알게 만드는 것이 레버리지의 원천이다.
셋째, 취향 판단을 명시적 루틴으로 만든다. AI가 만든 출력을 검토할 때 '뭔가 이상하다'를 '정확히 이게 틀렸다'로 바꾸는 연습을 팀 규범으로 세운다.
이 세 레이어 없이 Claude Code를 쓰는 건 IDE를 익스텐션 없이 쓰는 것과 같다. 동작은 한다. 하지만 팀의 전략 자산이 되진 않는다.