Git worktree는 에이전트 충돌을 막습니다. 작업 중복이 아닙니다.

하나의 저장소에 코딩 에이전트 열댓 개를 동시에 돌리면 지루한 이유로 실패합니다. 모두 같은 작업 디렉터리를 원하기 때문입니다. Git의 worktree 명령은 이 제약을 없애고, Anthropic과 Cursor도 이제 그 위에 에이전트 격리를 구축했습니다. 하지만 격리가 보장하는 범위는 대부분의 운영자가 생각하는 것보다 좁습니다.

Git Worktree 격리가 병렬 에이전트에 실제로 제공하는 것

연결된 worktree는 같은 저장소에 붙어 있는 두 번째 작업 디렉터리입니다. git worktree add로 만들며, 한 번에 둘 이상의 브랜치를 체크아웃할 수 있게 해줍니다 . 에이전트 관점에서 중요한 구분은 무엇이 공유되고 무엇이 개별로 분리되는가입니다. 객체 저장소와 refs/는 공유되지만, HEAD와 index는 worktree마다 따로 있으며, refs/bisect, refs/worktree, refs/rewritten도 마찬가지입니다 . Git의 repository-layout 참고 문서도 저장 구조 측면에서 같은 내용을 설명합니다. 여러 작업 트리를 사용할 때 $GIT_DIR 안의 대부분 파일은 worktree별로 분리되고, 공유 상태는 $GIT_COMMON_DIR를 통해 접근합니다 .

짧은 답: git worktree add는 하나의 객체 저장소와 refs를 공유하면서 각 에이전트에 자기 작업 디렉터리와 인덱스를 줍니다. 에이전트가 N개면 히스토리를 N번 복사하지 않고도 스테이징 영역이 N개 생기므로 .git/index.lock을 두고 경합하지 않습니다. 하지만 worktree가 두 에이전트가 같은 작업을 두 번 푸는 것까지 막아주지는 않습니다.

작동 방식으로 보면, 연결된 각 worktree에는 디렉터리가 아니라 .git 파일이 있고, 이 파일은 $GIT_DIR를 /path/main/.git/worktrees/test-next 같은 비공개 경로로 가리킵니다 . Git은 규율도 강제합니다. 기본적으로 같은 브랜치를 두 worktree에서 체크아웃하지 못하게 하므로 에이전트마다 브랜치를 나누게 되며, git worktree lock은 사용 중인 worktree가 정리 과정에서 삭제되지 않게 지켜줍니다 .

따라서 충돌 회피 이야기는 파일시스템 계층에서는 완성되지만, 거기서 끝납니다. 에이전트 13개가 하나의 체크아웃된 브랜치나 하나의 스테이징 영역을 두고 다투는 일은 없고, 모든 커밋은 여전히 하나의 저장소 계보 안에 남습니다. 하지만 어떤 worktree도 두 에이전트가 각자 다른 브랜치에서 같은 수정사항을 독립적으로 작성하거나, 에이전트 10개가 같은 개발 서버 포트에 바인딩하는 것을 막지는 못합니다. 격리는 파일에 대한 상호 배제이지, 의도에 대한 상호 배제가 아닙니다.

Git, Claude Code, Cursor: 병렬 에이전트에 필요한 것

worktree에서 병렬 에이전트를 실행하려면 세 가지가 필요합니다. 이미 로컬에 클론된 저장소, git worktree를 지원하는 Git 버전, 그리고 연결된 worktree를 만들고 그 안에 머물 줄 아는 에이전트 실행기입니다. Git은 기본 도구를 제공합니다. git worktree add는 같은 저장소에 연결된 작업 트리를 만들고, 객체와 refs/는 공유한 채 HEAD와 index는 worktree마다 분리합니다 . 그 위의 모든 것은 도구가 맡습니다.

• Claude Code: claude --worktree <name> 또는 -w는 worktree-<name>이라는 브랜치에 .claude/worktrees/<name>/ 아래 worktree를 만듭니다. 이름을 생략하면 Claude가 bright-running-fox 같은 이름을 생성합니다 .
• 에이전트 팀: 공유 작업 목록과 메일박스 계층은 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 뒤에 잠겨 있습니다. 이는 기본으로 켜져 있는 기능이 아니라 실험적 플래그이며, 팀원들을 worktree 안에 배치하지도 않습니다 .
• Cursor Background Agents: API 접근이 필요합니다. 이 에이전트들은 저장소를 별도 브랜치에 클론하는 격리된 Ubuntu 머신에서 실행되기 때문입니다. Cursor의 API 문서는 API 키 하나당 활성 에이전트를 최대 256개까지 지원한다고 명시합니다 .

놓치기 쉬운 전제 조건이 하나 있습니다. 새 worktree는 깨끗한 체크아웃이므로 gitignore된 파일은 따라오지 않습니다. Claude Code는 gitignore 문법의 .worktreeinclude 파일을 읽어 .env 같은 파일을 새 worktree마다 복사하며, 매칭되면서 동시에 gitignore된 파일만 복사합니다 .

Worktree에서 Claude Code와 Cursor 에이전트 병렬 실행하기

worktree로 격리된 에이전트는 명령 하나로 실행할 수 있습니다. claude --worktree fix-auth를 실행하면 .claude/worktrees/fix-auth/에 worktree가 만들어지고, worktree-fix-auth라는 이름의 브랜치가 생성됩니다. 다른 이름으로 다시 실행하면 두 번째로 완전히 분리된 세션을 얻을 수 있습니다 . 이름을 생략하면 자동으로 생성됩니다(예: bright-running-fox). 기본적으로 새 브랜치는 원격 저장소의 기본 브랜치에서 시작하며(worktree.baseRef: "fresh"), origin/HEAD를 24시간 동안 가져오지 않았다면 최대 5초 안에서 갱신합니다 .

1. 로컬 비밀값을 함께 가져갑니다. gitignore 문법으로 .worktreeinclude 파일을 추가하면 .env 같은 파일이 새 worktree마다 들어갑니다. 패턴에 일치하면서 gitignore 처리된 파일만 복사되므로, 추적 중인 파일은 절대 중복되지 않습니다 .
2. 관련 작업이라면 작업 목록을 공유합니다. 에이전트 팀을 활성화한 상태(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)로 리드 세션을 시작합니다. 팀원은 아직 배정되지 않았고 막히지 않은 다음 작업을 스스로 가져가며, 작업 가져가기는 파일 잠금을 사용하므로 두 팀원이 같은 작업을 가져갈 수 없습니다 .
3. 큰 변경을 여러 갈래로 나눕니다. /batch는 하나의 변경을 5~30개의 worktree 격리 서브에이전트로 나누고, 각 서브에이전트는 pull request를 엽니다 . 서브에이전트 정의에서는 frontmatter 한 줄이면 격리가 설정됩니다: isolation: worktree.
4. 또는 내 머신 밖으로 넘깁니다. Cursor Background Agent는 저장소를 격리된 Ubuntu 머신에 clone하고 자체 브랜치에서 작업합니다 .

다른 터미널에서 두 번째 에이전트를 추가합니다. 이름이 다르면 체크아웃, 브랜치, 인덱스도 각각 달라집니다.

claude --worktree fix-billing

첫 번째 격리 세션을 엽니다.

claude --worktree fix-auth

4단계에는 규모를 키우기 전에 꼭 이해해야 할 주의점이 있습니다. 에이전트 팀은 논리적 조율을 제공할 뿐, 파일시스템 격리를 제공하지 않습니다. 팀원들이 별도 worktree에 배치되는 것은 아닙니다.

"두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생합니다." — Claude Code 에이전트 팀 모범 사례, Anthropic (source: Agent teams documentation)

따라서 팀을 사용할 때는 파일 소유권을 나누고, 두 에이전트가 겹치는 코드를 만질 가능성이 있다면 --worktree나 /batch를 사용하세요. Anthropic은 대부분의 워크플로에서 팀원 3~5명을 권장하며, 엄격한 상한은 없습니다 .

주의할 점: 격리만으로는 중복 작업이나 리소스 충돌을 막을 수 없습니다

worktree가 격리하는 것은 딱 두 가지, 작업 디렉터리와 인덱스뿐입니다. 두 에이전트가 경합할 수 있는 나머지 항목, 즉 개발 서버 포트, 로컬 데이터베이스, 캐시, 백그라운드 프로세스, CI 용량, 구독 할당량은 그대로 공유됩니다. 그래서 서드파티 러너 TaskYou는 각 작업에 자체 WORKTREE_PORT를 부여하며, 예시에서는 3100–4099 범위를 사용합니다. 여기에 WORKTREE_TASK_ID와 WORKTREE_PATH도 함께 둡니다 (source: TaskYou, GitHub). Cline의 Kanban은 한 걸음 더 나아가 node_modules처럼 gitignore 처리된 디렉터리를 각 임시 worktree에 symlink합니다. 깨끗한 checkout은 그렇지 않으면 에이전트마다 새로 의존성을 설치해야 한다는 뜻이기 때문입니다 (source: cline/kanban).

비용은 사람들이 가장 늦게 알아차리는 충돌 지점입니다. 백그라운드 세션도 대화형 세션과 같은 방식으로 구독 할당량을 소모하므로, 병렬 에이전트 10개는 대략 10배 빠르게 할당량을 태웁니다 (source: Claude Code power user tips, Anthropic). 에이전트 팀의 각 팀원도 자체 컨텍스트 창을 가진 완전한 인스턴스입니다 (source: Agent teams). dynamic-workflows 런타임도 비슷한 주의를 코드화합니다. 예약된 에이전트 25개 또는 예상 토큰 150만 개를 넘으면 경고하고, 동시성은 동시 에이전트 16개(실행당 1,000개)로 제한합니다 (source: Dynamic workflows).

계획할 때 가장 신경 써야 할 것은 의미상의 간극입니다. 서로 다른 브랜치에서 작업하는 두 에이전트도 여전히 호환되지 않는 변경을 내보내거나, CI를 밀어 넣거나, 한 명의 작업자가 리뷰할 수 있는 양보다 더 많은 diff를 만들어낼 수 있습니다. 파일시스템 격리는 안전성을 사주는 것이지, 조율까지 사주는 것은 아닙니다.

워크트리는 격리만으로 부족합니다. 공유 작업 목록과 함께 써야 합니다

파일시스템은 워크트리에 맡기고, claim 의미론을 갖춘 작업 목록으로 의미상의 빈틈을 줄이세요. Claude Code의 실험적 agent teams(CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 활성화)는 리드 세션과 팀원에게 pending, in progress, completed 세 가지 상태의 공유 작업 목록과 명시적 의존성을 제공합니다. 해결되지 않은 의존성이 있는 pending 작업은 그 의존성이 완료되기 전까지 claim할 수 없고, 완료되면 의존 작업이 자동으로 unblock됩니다. claim에는 파일 잠금이 사용되므로 두 팀원이 같은 작업을 가져갈 수 없습니다 . 경계도 분명히 알아두세요. teams는 팀원을 워크트리에 넣어주지 않으므로, 여전히 파일을 나누거나 각 세션을 직접 --worktree로 실행해야 합니다 .

서드파티 보드는 이 두 축을 한 번에 처리합니다. TaskYou는 각 Kanban 카드를 ~/.local/share/task/worktrees/{project}/task-{id} 아래의 자체 워크트리에서 실행하고, 각 작업에 WORKTREE_PORT를 부여합니다 . Cline의 Kanban은 모든 카드에 자체 터미널과 임시 워크트리를 제공하고, node_modules를 심볼릭 링크하며, 카드별로 자동 커밋합니다 .

그다음에는 fan-out 규모를 현실적으로 잡아야 합니다. Anthropic은 대부분의 워크플로에서 팀원 3~5명을 권장하며 하드 캡은 없다고 설명하고, dynamic-workflows 런타임은 동시 실행 에이전트 16개와 실행 1회당 총 1,000개 에이전트를 허용합니다 . 의존성을 인식하는 작업 목록 하나 뒤에 워크트리 세 개로 시작해 merge와 review 처리량을 측정하고, 그 숫자가 병목이 아니게 된 뒤에만 에이전트를 추가하세요.

자주 묻는 질문

Git 워크트리는 두 에이전트가 같은 파일을 수정하는 것을 막아주나요?

파일시스템 수준에서는 그렇습니다. 각 linked worktree는 자체 checkout과 자체 index를 가지며, Git은 기본적으로 같은 브랜치를 두 워크트리에서 checkout하지 못하게 합니다 . 하지만 이것이 막아주지 못하는 것도 있습니다. 서로 다른 워크트리에 있는 두 에이전트가 같은 티켓을 동시에 해결하거나, merge했을 때 논리적으로 충돌하는 변경을 작성하는 경우입니다. Claude Code의 문서도 이 두 문제를 분리합니다. 워크트리는 병렬 세션에 별도 checkout을 제공하고, subagents, agent view, agent teams가 조율 계층을 담당합니다 . 중복된 범위를 막는 것은 공유된, 의존성 인식 작업 목록뿐입니다.

Claude Code의 agent teams 기능은 팀원을 자동으로 워크트리에 격리하나요?

아니요. agent team의 팀원은 기본적으로 하나의 checkout을 공유합니다. 그래서 Anthropic은 "각 팀원이 서로 다른 파일 집합을 소유하도록 작업을 나누라"고 안내하고, agent-teams best practices도 "두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생한다"고 경고합니다 . team 계층이 제공하는 것은 논리적 상호 배제입니다. 공유 작업 목록, 세 가지 작업 상태, 의존성, 파일 잠금 기반 작업 claim이지 파일시스템 격리는 아닙니다. 둘을 함께 결합하는 first-party 모드는 /batch입니다. 하나의 큰 변경을 워크트리로 격리된 subagent 5~30개로 나누고, 각 subagent가 pull request를 여는 방식으로 문서화되어 있습니다 . 단일 subagent라면 frontmatter의 isolation: worktree가 같은 역할을 합니다.

병렬 코딩 에이전트는 실제로 몇 개까지 동시에 돌릴 수 있나요?

도구가 기술적으로 허용하는 수보다 적게 잡는 편이 현실적입니다. Anthropic은 대부분의 워크플로에서 팀원 3~5명을 권장하며 하드 제한은 없다고 밝히고, 독립 작업 15개를 팀원 3명에게 나눠 각자 5~6개씩 맡기는 것이 합리적인 시작점이라고 설명합니다 . dynamic-workflows 런타임은 동시 에이전트 최대 16개(CPU 코어가 제한적이면 더 적음)와 실행 1회당 총 1,000개 에이전트를 허용합니다 . Cursor의 Background Agent API는 API 키당 활성 에이전트 최대 256개를 지원한다고 문서화합니다 . 실제 상한은 보통 플랫폼 한도가 아니라 한 명의 운영자가 검토할 수 있는 diff 양입니다.

워크트리가 격리하지 않는 것은 무엇인가요?

워크트리는 working directory, index, HEAD를 격리합니다. 런타임 리소스는 격리하지 않습니다. dev-server 포트, 로컬 데이터베이스, 캐시, 백그라운드 프로세스는 여전히 공유되고, 새 checkout에는 node_modules가 없으므로 각 워크트리에는 자체 의존성 설치도 필요합니다. 워크트리 위에 만들어진 도구들은 이 문제를 명시적으로 우회합니다. TaskYou는 WORKTREE_TASK_ID, WORKTREE_PATH와 함께 작업별 WORKTREE_PORT(예시는 3100~4099 범위)를 할당합니다 . Cline의 Kanban은 node_modules 같은 gitignored 디렉터리를 각 임시 워크트리에 심볼릭 링크합니다 . 직접 만든다면 포트와 데이터베이스를 에이전트별로 직접 할당하세요.

병렬 에이전트를 더 많이 실행하면 비용도 늘어나나요?

네, 대략 선형으로 늘어납니다. 백그라운드 세션은 인터랙티브 세션과 같은 방식으로 구독 quota를 소비하므로, 병렬 에이전트 10개는 1개보다 약 10배 빠르게 quota를 소진합니다 . agent team의 각 팀원은 자체 context window를 가진 완전한 인스턴스이므로, context 비용도 전체 fleet에 걸쳐 상각되지 않습니다 . dynamic-workflows 런타임은 예약된 에이전트가 25개를 넘거나 예상 토큰이 1.5M을 넘으면 경고를 표시해 이 점을 직접 드러냅니다 . CI minutes를 예산화하듯 fan-out도 예산화하세요.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기