깃 워크트리(Git Worktree)와 병렬 세션: 여러 에이전트를 충돌 없이 돌리는 법

🤔 두 에이전트가 같은 폴더에서 서로의 변경을 덮을 때

코딩 에이전트 두 개를 같은 프로젝트 폴더에서 동시에 돌려 보면 곧 이상한 일이 생깁니다. 한 에이전트가 고친 파일을 다른 에이전트가 모른 채 다시 고치고, 한쪽이 테스트를 돌리는 동안 다른 쪽이 파일을 바꿔 테스트 결과가 뒤섞입니다. 브랜치를 나눠 보려 해도 한 폴더에서는 한 번에 한 브랜치만 꺼낼 수 있어서, 한쪽이 브랜치를 바꾸는 순간 다른 쪽의 작업 환경이 통째로 바뀝니다.

이 문제를 푸는 도구가 깃 워크트리입니다. 클로드 코드와 코덱스, 오르카처럼 여러 에이전트를 동시에 돌리는 도구들이 모두 이 기능을 바탕으로 병렬 세션을 만듭니다. 이 편에서는 워크트리가 무엇을 나누고 무엇을 공유하는지, 도구별로 어떻게 쓰는지, 워크트리를 만든 뒤 무엇을 챙겨야 하는지를 정리합니다. 깃 자체가 낯설다면 깃 이해하기부터 보는 편이 이해가 빠릅니다.

🔑 깃 워크트리의 정의

깃 워크트리는 한 저장소에 연결된 작업 폴더를 여러 개 두어 폴더마다 다른 브랜치를 동시에 꺼내 쓰게 하는 기능입니다.

깃 공식 문서는 워크트리를 같은 저장소에 붙은 여러 작업 트리를 관리하는 기능으로 설명합니다. 원래 있던 작업 폴더를 메인 워크트리, 새로 만든 폴더를 연결된 워크트리라고 부릅니다.

한 가게가 창고 하나를 함께 쓰면서 작업대만 여러 개 둔 모습과 같습니다. 창고, 즉 커밋 기록과 브랜치 목록은 모든 작업대가 함께 보고, 작업대 위에 펼쳐 놓은 재료는 작업대마다 따로입니다.

그래서 한 워크트리에서 커밋하면 다른 워크트리에서도 그 커밋이 바로 보입니다. 저장소를 여러 번 새로 복제하는 것과 달리 기록을 따로 내려받지 않아도 되고, 브랜치를 합치는 일도 한 저장소 안에서 끝납니다.

🧰 기본 명령과 꼭 알아 둘 제약

도구가 알아서 만들어 주더라도 기본 명령은 알아 두는 편이 정리할 때 편합니다.

깃 문서가 밝힌 제약 가운데 에이전트 운영에 바로 걸리는 것은 두 가지입니다.

• 같은 브랜치는 한 곳에서만 꺼냅니다: 지정한 브랜치가 이미 다른 워크트리에 꺼내져 있으면 새 워크트리 만들기를 거부하고, --force를 써야만 넘어갑니다. 에이전트마다 새 브랜치를 주는 이유입니다
• 정리된 워크트리만 지워집니다: 추적하지 않는 파일이나 고친 파일이 남아 있으면 remove가 거부되고, 강제로 지우려면 --force가 필요합니다. 메인 워크트리는 지울 수 없습니다

🤖 도구별로 병렬 세션을 만드는 방식

2026년 9월 28일 각 공식 문서 기준입니다.

클로드 코드는 서브에이전트에도 워크트리를 붙일 수 있습니다. 서브에이전트 설정에 isolation: worktree를 적으면 서브에이전트마다 임시 워크트리에서 일하고, 변경 없이 끝나면 자동으로 지워집니다. 같은 변경을 파일 여러 개에 나눠 적용할 때 쓰는 /batch 명령은 일을 5개에서 30개의 서브에이전트로 쪼개고, 각 서브에이전트가 자기 워크트리에서 일한다고 공식 문서가 설명합니다.

-p로 실행하는 비대화형 세션은 종료 때 묻는 단계가 없어서 워크트리를 자동으로 정리하지 않습니다. 자동화 스크립트로 워크트리를 여러 개 만든다면 정리 단계도 스크립트에 함께 넣어야 합니다. 여러 에이전트를 한 화면에서 관리하는 방법은 오르카 이해하기 편에 정리되어 있습니다.

⚙️ 워크트리를 만든 뒤 챙길 것

클로드 코드 문서는 워크트리가 새로 꺼낸 폴더이므로 그 안에서 개발 환경을 다시 준비하라고 안내합니다. 실제로 막히는 곳은 대개 세 군데입니다.

1. 저장소에 올리지 않은 파일이 없습니다

.env 같은 비밀 설정 파일은 보통 깃에 올리지 않기 때문에 새 워크트리에는 없습니다. 클로드 코드와 코덱스, 오르카는 모두 .worktreeinclude 파일을 지원합니다. 프로젝트 맨 위에 이 파일을 두고 복사할 파일을 적으면 워크트리를 만들 때 함께 복사하는데, 클로드 코드 문서 기준으로 적힌 패턴과 맞으면서 깃이 무시하도록 설정된 파일만 복사됩니다.

2. 의존성이 설치되어 있지 않습니다

node_modules 같은 폴더도 워크트리마다 따로라서 설치 명령을 다시 돌려야 합니다. 워크트리가 늘면 디스크 공간도 그만큼 씁니다. 지침 파일에 워크트리를 만든 뒤 돌릴 준비 명령을 적어 두면 에이전트가 알아서 챙깁니다.

3. 워크트리가 어느 지점을 기준으로 만들어졌는지 확인합니다

클로드 코드는 기본값에서 원격 저장소의 기본 브랜치를 기준으로 새 워크트리를 만들고, 설정을 바꾸면 지금 로컬의 위치를 기준으로 만듭니다. 아직 원격에 올리지 않은 변경 위에서 이어 작업해야 한다면 이 기준을 확인하지 않으면 에이전트가 오래된 코드에서 출발합니다.

여러 워크트리에서 개발 서버를 함께 띄우면 같은 포트를 두고 부딪히는 경우도 있어서, 워크트리마다 다른 포트를 쓰도록 명세에 적어 두는 편이 안전합니다.

🔀 병렬 세션의 결과를 합치는 순서

워크트리는 작업을 나눠 주는 것까지만 해결합니다. 합치는 일은 여전히 메인의 몫입니다.

1. 한 워크트리씩 변경 내역을 봅니다: 명세에 적은 소유 파일 밖이 바뀌지 않았는지부터 확인합니다
2. 한 번에 하나씩 합칩니다: 두 브랜치를 한꺼번에 합치면 충돌이 났을 때 원인을 찾기 어렵습니다
3. 합칠 때마다 검사를 다시 돌립니다: 각 워크트리에서 통과한 테스트도 합친 뒤에는 실패할 수 있습니다
4. 끝난 워크트리를 지웁니다: git worktree list로 남은 것을 확인하고 정리합니다

충돌을 줄이는 근본 방법은 합치는 단계가 아니라 나누는 단계에 있습니다. 클로드 코드 에이전트 팀 문서는 두 팀원이 같은 파일을 고치면 덮어쓰기가 생긴다며 팀원마다 다른 파일 묶음을 소유하도록 일을 나누라고 권합니다. 나누는 기준은 멀티 에이전트 작업 설계에서 다뤘습니다.

⚠️ 워크트리를 쓸 때 자주 하는 실수

• 워크트리만 나누고 파일 소유는 나누지 않습니다: 폴더가 달라도 두 에이전트가 같은 파일을 고치면 합칠 때 충돌이 납니다
• 워크트리를 정리하지 않습니다: 자동 정리가 되지 않는 실행 방식에서는 폴더와 브랜치가 쌓여 디스크와 브랜치 목록을 어지럽힙니다
• 폴더를 직접 지웁니다: 폴더만 지우면 깃에 워크트리 정보가 남으므로 git worktree remove를 쓰거나 지운 뒤 prune을 돌립니다
• 메인 폴더에서도 에이전트를 돌립니다: 사람이 확인하는 메인 폴더는 비워 두고 에이전트는 워크트리에서만 돌리면 섞일 일이 줄어듭니다

❓ 자주 묻는 질문

브랜치를 바꿔 가며 쓰는 것과 무엇이 다른가요?

한 폴더에서 브랜치를 바꾸면 그 폴더의 파일 전체가 바뀌어서, 다른 에이전트가 쓰던 작업 환경도 함께 바뀝니다. 워크트리는 브랜치마다 폴더를 따로 두므로 여러 브랜치를 동시에 꺼내 두고 각자 작업할 수 있습니다.

저장소를 여러 번 복제하는 것과 무엇이 다른가요?

복제는 저장소 기록을 폴더마다 따로 가지므로 한쪽에서 커밋한 내용을 다른 쪽에서 보려면 주고받는 과정이 필요합니다. 워크트리는 기록을 함께 쓰기 때문에 한 워크트리의 커밋이 다른 워크트리에서도 바로 보이고, 합치는 일도 한 저장소 안에서 끝납니다.

워크트리가 있으면 에이전트를 몇 개든 늘려도 되나요?

파일 충돌은 줄지만 다른 비용은 그대로입니다. 워크트리마다 의존성 설치와 디스크 공간이 필요하고, 에이전트 수만큼 사용량이 나가며, 합치는 시간도 늘어납니다. 비용 계산은 비용과 토큰 예산에서 다룹니다.

📋 3줄 요약

1. 깃 워크트리는 한 저장소에 연결된 작업 폴더를 여러 개 두어 폴더마다 다른 브랜치를 동시에 꺼내 쓰게 하는 기능이고 커밋 기록은 함께 쓰되 파일과 HEAD는 폴더마다 따로 가집니다.

2. 클로드 코드는 --worktree 플래그로 .claude/worktrees 아래에 새 브랜치의 워크트리를 만들고, 코덱스와 오르카도 작업마다 워크트리를 만들어 병렬 세션이 서로의 파일을 덮지 않게 합니다.

3. 워크트리는 새로 꺼낸 폴더라 환경 파일과 의존성 설치를 다시 챙겨야 하고, 같은 브랜치는 두 워크트리에서 동시에 쓸 수 없으며, 끝난 워크트리는 합친 뒤 git worktree remove로 지웁니다.

📚 참고 자료

• Git 공식 문서, git-worktree: https://git-scm.com/docs/git-worktree
• 클로드 코드 문서, Worktrees: https://code.claude.com/docs/en/worktrees
• 클로드 코드 문서, Common workflows: https://code.claude.com/docs/en/common-workflows
• 클로드 코드 문서, Agent teams: https://code.claude.com/docs/en/agent-teams
• 코덱스 문서, Git worktrees: https://learn.chatgpt.com/docs/environments/git-worktrees
• 오르카 문서, Worktrees: https://www.onorca.dev/docs/model/worktrees