블로그로 돌아가기튜토리얼

Claude Code 팀 브랜치 전략: Worktree부터 Agent Teams까지 완전 가이드

9분 읽기0

Claude Code 팀 브랜치 전략: Worktree부터 Agent Teams까지 완전 가이드

2026년 1월, Anthropic은 Team 및 Enterprise 플랜에 Claude Code를 기본 포함시켰습니다. 최소 5명 이상의 Team 플랜 사용자 모두가 Claude Code에 접근할 수 있게 된 것입니다. 이제 한 팀에서 여러 Claude Code 세션이 동시에 코드를 작성하는 시대가 되었습니다. 하지만 적절한 Claude Code 팀 브랜치 전략 없이는 병합 충돌과 코드 불일치가 일상이 됩니다.

Claude Code 팀 브랜치 전략이란? 여러 개발자와 AI 에이전트가 동시에 코드를 작성할 때, 충돌 없이 효율적으로 협업하기 위한 Git 브랜치 관리 체계입니다. Git Worktrees, Agent Teams, CLAUDE.md를 조합하여 팀 크기에 맞게 구성합니다.

이 글에서는 Claude Code 팀 브랜치 전략을 팀 크기별로 구체적으로 안내합니다. DORA 리서치에서 고성능 팀의 핵심 역량으로 식별한 Trunk-Based Development를 기반으로, Claude Code의 Agent Teams와 Git Worktrees를 어떻게 결합하는지 살펴보겠습니다.

Git Worktrees: 병렬 개발의 기술적 기반

Git Worktrees는 Claude Code 팀 브랜치 전략의 핵심 인프라입니다. 동일한 리포지토리에서 여러 브랜치를 별도 디렉토리로 체크아웃하여, 각 디렉토리가 독립적인 파일 상태를 유지하면서도 동일한 Git 히스토리를 공유합니다.

왜 Worktrees인가

기존 방식에서는 브랜치를 전환할 때마다 작업 디렉토리 전체가 변경되었습니다. Claude Code 세션이 진행 중인 상태에서 브랜치를 전환하면, 에이전트의 컨텍스트와 실제 파일 상태가 불일치합니다. Worktrees는 이 문제를 근본적으로 해결합니다.

  • 독립적 파일 상태: 각 Worktree가 별도 디렉토리이므로 서로 간섭하지 않습니다
  • 동시 세션 지원: 여러 Claude Code 인스턴스를 각 Worktree에서 독립 실행합니다
  • 컨텍스트 보존: 장기 실행 작업을 별도 Worktree에서 처리하며 메인 개발을 지속합니다

Worktrees 설정 예시

# 새 브랜치로 Worktree 생성
git worktree add ../worktrees/feature-auth feature/auth

# 유저네임 프리픽스로 자동화
git worktree add ~/projects/worktrees/$(whoami)-feature-name feature-name

# 모든 Worktree 나열
git worktree list

# 작업 완료 후 Worktree 제거
git worktree remove ../worktrees/feature-auth

incident.io 팀의 사례에 따르면, 팀당 3~4개의 활성 Worktree를 유지하는 것이 관리 측면에서 최적입니다. 너무 많으면 오히려 동기화 부담이 커집니다.

Agent Teams(Swarm Mode): AI 멀티 에이전트 협업

Claude Code의 Agent Teams는 2026년 초 출시된 기능으로, 단일 AI 어시스턴트를 멀티 에이전트 팀 오케스트레이터로 변환합니다. Leader-Worker 모델을 사용하여 리더 에이전트가 작업을 분해하고, 팀원 에이전트에게 할당합니다.

Agent Teams 아키텍처

Agent Teams는 세션당 최대 4명(리더 1명 + 팀원 최대 3명)으로 구성됩니다. 각 팀원은 독립적인 Git Worktree에서 작업하며, 팀원 간 직접 메시지 전송이 가능합니다. 이는 Subagents와의 핵심 차이점입니다.

특성SubagentsAgent Teams
통신메인 에이전트에게만 보고팀원끼리 직접 메시지
조율메인 에이전트가 관리공유 작업 목록으로 자체 조율
최적 용도결과만 중요한 집중 작업논의/협업이 필요한 복잡한 작업
토큰 비용낮음높음

Agent Teams 최적 활용 시나리오

Agent Teams는 모든 작업에 적합하지 않습니다. 다음 경우에 효과적입니다:

  • 교차 계층 변경: 프론트엔드, 백엔드, 테스트를 각 팀원이 담당
  • 새 모듈 개발: 팀원별 별도 파일을 소유하여 병렬 구현
  • 리서치 및 검토: 여러 관점에서 동시에 조사

반면 순차적 작업이나 동일 파일 편집이 필요한 경우에는 Subagents가 더 적합합니다.

팀 크기별 브랜치 전략

소규모 팀 (2~5명): Modified Trunk-Based Development

DORA 리서치에서 고성능 팀의 핵심 역량으로 식별한 Trunk-Based Development를 기반으로 합니다. 단기 feature 브랜치(최대 수시간~1일)를 빈번하게 메인에 통합하는 방식입니다.

일일 워크플로우:

  1. 오전에 main에서 최신 코드를 pull합니다
  2. 새 작업 시작 시 단기 브랜치를 생성하거나 Worktree를 추가합니다
  3. Claude Code로 개발하며 빈번하게 커밋합니다
  4. 오후에 PR을 생성하고 AI 기반 코드 리뷰를 진행합니다
  5. 병합 후 브랜치와 Worktree를 삭제합니다

중규모 팀 (6~20명): Worktree 기반 병렬 개발

각 개발자가 메인 외에 2~3개의 feature Worktree를 유지합니다. 복잡한 작업에는 Agent Teams를 선택적으로 활용합니다.

~/projects/my-app/                (main worktree)
~/projects/worktrees/
  user1-feature-auth/             (feature/auth)
  user1-feature-payment/          (feature/payment)
  user2-bugfix-login/             (bugfix/login)

핵심 관행:

  • 브랜치 명명 규칙: feature/TICKET-123-description
  • 일일 리베이스로 main과 동기화
  • PR 리뷰 로테이션 (AI 리뷰 + 팀원 리뷰)

대규모 팀 (21명 이상): Agent Teams + Epic 브랜치

Epic 단위로 작업을 분해하고, 각 Epic에 Agent Team을 할당합니다. 팀원별 독립적 feature 브랜치에서 작업 후 Epic 브랜치에 먼저 병합하고, Epic 완료 시 main에 통합합니다.

main
  epic/user-management       (리더 브랜치)
    feature/um-auth          (팀원 1)
    feature/um-profile       (팀원 2)
    feature/um-permissions   (팀원 3)

CLAUDE.md로 팀 표준 통일하기

CLAUDE.md는 프로젝트 루트에 위치하며 모든 Claude Code 세션 시작 시 자동으로 읽힙니다. Anthropic 내부 팀도 이 파일에 실수를 문서화하여 Claude가 시간이 지남에 따라 더 나은 코드를 작성하도록 만들고 있습니다.

CLAUDE.md에 반드시 포함할 항목

  • 기술 스택: 비표준 선택 사항을 명시합니다 (예: tRPC vs REST)
  • 브랜치 명명 규칙: feature/TICKET-123-description 형태의 예시를 포함합니다
  • 커밋 메시지 포맷: Conventional Commits 등 팀 규칙을 기록합니다
  • "Do NOT" 섹션: 축적된 실수와 금지 사항을 기록합니다
  • 사용 가능한 커맨드: .claude/commands/의 커스텀 커맨드를 문서화합니다

Agent Teams 사용 시 팀원이 자동으로 CLAUDE.md를 수신하므로, 이 파일이 팀 컨벤션의 단일 진실 공급원(Single Source of Truth) 역할을 합니다.

충돌 방지 및 CI/CD 통합

충돌 방지 4원칙

  1. 파일 소유권 분리: 같은 파일을 두 에이전트가 동시에 수정하지 않도록 작업을 나눕니다
  2. Worktree 기반 격리: 각 기능 개발을 별도 Worktree에서 진행합니다
  3. Fast-Forward Only 병합: 병합 전 베이스 브랜치에 리베이스합니다
  4. AI 기반 충돌 해결: 동일 세션 내에서 Claude에게 충돌 해결을 요청합니다

CI/CD에 Claude Code 통합하기

Headless Mode(-p 플래그)를 사용하면 CI 파이프라인에서 Claude Code를 비대화형으로 실행할 수 있습니다. GitHub Actions에서 모든 PR에 대해 자동 코드 리뷰를 수행하거나, Pre-commit 훅으로 보안 취약점을 검사하는 것이 대표적인 활용 사례입니다.

# GitHub Actions 예시
- name: AI Code Review
  run: |
    claude -p "Review this PR for security issues and style violations" \
      --output-format json > review.json

자주 묻는 질문 (FAQ)

Q: Agent Teams와 Git Worktrees를 동시에 사용해야 하나요?

Agent Teams는 내부적으로 Git Worktrees를 사용합니다. Agent Teams를 활성화하면 각 팀원이 자동으로 독립된 Worktree에서 작업합니다. 소규모 팀에서는 Agent Teams 없이 수동 Worktree 관리만으로도 충분합니다.

Q: Trunk-Based Development에서 Feature Branches를 아예 사용하지 않나요?

단기 feature 브랜치(수시간~1일)는 사용합니다. 핵심은 브랜치 수명을 짧게 유지하여 병합 충돌을 최소화하는 것입니다. 미완성 기능은 Feature Flag로 숨기는 것이 권장됩니다.

Q: CLAUDE.md는 팀원마다 다르게 설정할 수 있나요?

프로젝트 루트의 CLAUDE.md는 팀 공통 설정이고, 개인 설정은 ~/.claude/ 디렉토리에서 관리합니다. 프로젝트 설정(.claude/settings.json)은 팀 기본값으로 버전 컨트롤에 체크인하고, 로컬 설정(.claude/settings.local.json)은 개인 오버라이드용으로 gitignore에 추가합니다.

Q: Agent Teams의 세션당 최대 인원은 몇 명인가요?

리더 1명 + 팀원 최대 3명으로, 세션당 최대 4명입니다. 4명을 초과하는 작업은 순차 배치로 분할해야 합니다. 현재 Agent Teams는 실험적 기능으로, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 설정해야 활성화됩니다.

마무리: 팀에 맞는 Claude Code 팀 브랜치 전략 선택하기

Claude Code 팀 브랜치 전략의 핵심은 팀 크기와 작업 복잡도에 맞는 도구 조합을 선택하는 것입니다. 소규모 팀은 Trunk-Based Development + Worktrees로 시작하고, 팀이 성장하면 Agent Teams와 Epic 브랜치를 도입하세요. CLAUDE.md로 팀 표준을 문서화하고, CI/CD에 Headless Mode를 통합하면 AI 시대의 팀 개발 워크플로우를 완성할 수 있습니다.

지금 바로 프로젝트 루트에 CLAUDE.md를 만들고, Git Worktrees를 설정해 보세요.

참고 자료