한 에이전트가 기능 파일을 고치는 동안 다른 에이전트가 버그를 수정한다.

둘을 같은 폴더에서 실행하면 한쪽이 만든 변경과 git status가 다른 쪽에도 그대로 보인다. 에이전트가 둘이라서가 아니라 작업 폴더가 하나라서 생기는 문제다.

Git worktree는 같은 저장소에 별도 작업 폴더를 연결한다. 에이전트마다 폴더와 브랜치를 하나씩 주면 서로의 수정 중인 파일을 바로 덮어쓰지 않는다.

필요한 것은 worktree를 만드는 명령, 두 에이전트에 나눠 주는 흐름, 끝난 폴더를 정리할 때 주의할 점이다.

하나의 Git 저장소에서 두 AI 에이전트의 작업 폴더와 브랜치를 나눈 뒤 차이를 확인하고 합치는 흐름

worktree는 저장소를 다시 복제하지 않는다

보통 Git 저장소를 clone하면 코드를 펼쳐 놓은 작업 폴더가 하나 생긴다. Git 공식 문서는 하나의 저장소에 여러 작업 폴더를 연결해 둘 이상의 브랜치를 동시에 여는 방식을 설명한다.

각 worktree에는 자기 파일, HEAD, index가 있다. commit 기록과 branch 정보처럼 저장소가 관리하는 데이터의 상당 부분은 함께 쓴다. 저장소 전체를 매번 새로 복제하는 방식과 다른 점이다.

AI 에이전트 작업에 붙이면 구분이 쉬워진다.

  • 에이전트 A는 기능 작업용 폴더와 branch를 쓴다.
  • 에이전트 B는 버그 수정용 폴더와 branch를 쓴다.
  • 원래 checkout은 검토와 통합을 위해 그대로 둔다.

Codex, Claude Code, GitHub Copilot app도 병렬 에이전트 세션의 파일을 분리하는 데 Git worktree를 사용한다.

폴더와 브랜치를 한 쌍으로 만든다

현재 checkout의 HEAD를 기준으로 기능 작업과 버그 수정용 worktree를 만든다고 해보자.

git worktree add -b agent/feature ../project-feature
git worktree add -b agent/bugfix ../project-bugfix
git worktree list

첫 명령은 ../project-feature 폴더와 agent/feature branch를 만든다. 두 번째 명령도 같은 방식으로 별도 폴더와 branch를 만든다. git worktree list는 각 폴더가 가리키는 commit과 branch를 보여준다.

이제 에이전트를 서로 다른 폴더에서 시작한다.

project-feature  -> 에이전트 A -> 기능 작업
project-bugfix   -> 에이전트 B -> 버그 수정

중요한 것은 에이전트 수가 아니라 시작 위치다. 두 세션을 열어도 둘 다 원래 폴더에서 시작하면 파일은 분리되지 않는다.

병렬 실행 자체가 언제 필요한지는 서브에이전트와 병렬 에이전트, 뭐가 다를까에서 따로 설명했다. worktree는 병렬로 하기로 정한 뒤 작업 폴더를 나누는 단계다.

파일은 나뉘어도 합치는 일은 남는다

worktree를 쓰면 한 에이전트의 저장 중인 파일이 다른 작업 폴더에 바로 나타나지 않는다. 그렇다고 merge conflict까지 없어지는 것은 아니다.

두 에이전트가 같은 코드의 같은 줄을 다르게 고치면 나중에 branch를 합칠 때 충돌할 수 있다. 한쪽이 만든 API를 다른 쪽이 모른 채 바꾸는 논리 충돌도 남는다.

그래서 작업을 시작할 때 맡을 범위를 함께 나눈다.

  • 기능 작업은 agent/feature에서 진행한다.
  • 버그 수정은 agent/bugfix에서 진행한다.
  • 각 폴더에서 diff와 테스트 결과를 확인한다.
  • 검토가 끝난 branch만 원래 checkout에서 합친다.

worktree는 방을 나눌 뿐이다. 누가 어느 파일을 맡고 어떤 순서로 합칠지는 사람이 정해야 한다.

같은 branch를 두 폴더에서 열지 않는다

Git은 같은 branch를 여러 worktree에서 동시에 checkout하는 일을 기본적으로 막는다. 한 branch를 두 폴더가 함께 움직이면 어느 작업이 branch의 최신 상태인지 모호해지기 때문이다.

따라서 폴더만 둘로 만들고 branch 하나를 공유하면 안 된다.

작업 폴더 A + branch A
작업 폴더 B + branch B

Codex의 관리형 worktree는 여러 작업 공간을 만들 때 기본적으로 detached HEAD를 사용한다. 직접 명령으로 만들 때는 앞의 예시처럼 새 branch를 함께 만드는 편이 흐름을 이해하기 쉽다.

새 폴더에는 로컬 설정이 없다

worktree는 새 checkout이다. Git이 추적하지 않는 .env, 로컬 설정 파일, 설치된 node_modules는 원래 폴더에서 자동으로 따라오지 않는다.

에이전트를 실행하기 전에 각 폴더에서 필요한 준비를 확인한다.

  • dependency 설치가 필요한가.
  • 개발 서버가 같은 port를 쓰지 않는가.
  • Git에 넣지 않은 환경 설정을 안전하게 주입할 방법이 있는가.
  • 테스트가 별도 폴더에서도 같은 방식으로 실행되는가.

Codex와 Claude Code는 관리형 worktree에 일부 무시 파일을 복사하는 .worktreeinclude 기능을 문서화한다. 이것은 제품이 관리하는 worktree용 보조 기능이다. 비밀 파일을 Git에 commit하라는 뜻은 아니다.

끝난 worktree는 상태를 보고 지운다

작업이 끝났다고 폴더부터 삭제하면 Git의 worktree 관리 정보가 남는다. 먼저 상태와 등록 목록을 확인한다.

git -C ../project-feature status --short
git worktree list
git worktree remove ../project-feature
git worktree prune --dry-run

git worktree remove는 변경 파일이나 추적하지 않는 파일이 남은 worktree를 기본적으로 거부한다. 이 보호 장치를 억지로 건너뛰기보다 commit, diff, 필요한 파일을 먼저 확인한다.

git worktree prune --dry-run은 폴더를 수동으로 옮기거나 지워서 남은 관리 정보가 있는지 실제 삭제 없이 보여준다.

독립 작업일 때만 나누면 된다

worktree는 두 작업이 서로 독립적일 때 가장 이해하기 쉽다. 기능 개발과 별도 문서 정리, 서로 다른 버그 두 건처럼 결과를 각각 검토할 수 있는 작업이 잘 맞는다.

앞 작업의 결과가 있어야 다음 작업을 시작할 수 있거나, 두 에이전트가 계속 같은 파일을 고쳐야 한다면 동시에 나누는 이점이 작다. 작업 폴더가 늘면 dependency 설치, 테스트 실행, diff 검토 비용도 함께 늘어난다.

선택 기준은 짧다.

동시에 진행해도 되는 독립 작업인가?
그렇다면 에이전트마다 폴더와 branch를 하나씩 준다.
끝나면 각 diff를 따로 검토한 뒤 합친다.

Git worktree는 여러 에이전트를 알아서 조율하지 않는다. 다만 같은 저장소에서 일하는 에이전트들이 서로의 작업 중인 파일부터 밟는 문제는 막아 준다.

확인한 공식 자료

위 자료는 2026년 7월 31일에 확인했다.

주제 선정 단계에서는 X의 worktree 사용 사례와 Reddit의 다중 에이전트 worktree 논의에서 독자가 실제로 묻는 표현을 확인했다. 기술 사실은 위 공식 자료를 기준으로 썼다.