git worktree: 여러 AI 에이전트를 충돌 없이 돌리기 위한 기반

같은 저장소에 에이전트 두 개를 띄웁니다. 하나가 package.json을 고치는데, 다른 하나도 같은 파일을 고칩니다. 30초 뒤, 코드는 아무도 머지할 수 없는 상태가 됩니다.

이건 에이전트의 버그가 아닙니다. 에이전트들이 전부 같은 폴더에서 일하기 때문입니다.

해법은 Git이 몇 년 전부터 갖고 있었지만 거의 아무도 안 쓰는 기능, 바로 git worktree입니다.

문제: 에이전트 3개, 저장소 1개, 머지 불가능

일반적인 Git 저장소는 한 번에 브랜치 하나만 체크아웃된 폴더 하나입니다. main에서 작업하다가 브랜치를 바꾸면 폴더 전체가 그쪽으로 뒤집힙니다.

이제 그 폴더에 자율 에이전트 세 개를 던져 넣어 봅시다. 동시에 파일을 씁니다. 에이전트 A가 파일을 만드는데, 에이전트 B가 깨끗하게 시작하려고 git checkout을 돌려서 A가 작업 중이던 내용을 날려 버립니다. 그러면 반쯤 쓰다 만 파일, 엉망이 된 인덱스, 그리고 직접 코딩하는 것보다 푸는 데 더 오래 걸리는 충돌만 남습니다.

병렬화는 에이전트들이 서로를 건드리지 않을 때만 시간을 아껴 줍니다.

git worktree란

worktree는 같은 저장소에 붙은 두 번째 작업 폴더입니다.

히스토리도 같고 원격도 같지만, 각 worktree는 자기만의 브랜치가 체크아웃되어 있고 디스크에 자기만의 파일을 갖습니다. 다섯 개를 나란히 두고 각각 다른 브랜치에 올려놔도 서로 방해하지 않습니다.

.git은 하나, 작업 공간은 여러 개. 그게 전부입니다.

에이전트 하나당 worktree 하나, 실전

설정은 이렇습니다. 저장소에서:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-billing -b feature/billing
git worktree add ../project-export -b feature/export

방금 폴더 세 개를 만들었고, 각각 자기 브랜치에 올라가 있습니다. 각 폴더에서 에이전트를 띄웁니다:

cd ../project-auth && claude
cd ../project-billing && codex

에이전트마다 자기 폴더, 자기 브랜치, 자기 파일이 있습니다. auth 에이전트는 billing 에이전트가 뭘 하는지 절대 보지 못합니다. 충돌이 일어날 수가 없죠.

기능이 준비되면 해당 브랜치를 리뷰하고 머지합니다. 그다음 정리합니다:

git worktree remove ../project-auth

폴더는 사라지고, 브랜치는 히스토리에 남습니다. 깔끔하죠.

알아 둬야 할 함정 3가지

첫 번째 함정, 다 같이 쓰는 핵심 파일. 두 기능이 모두 같은 routes.ts나 같은 데이터베이스 스키마를 건드려야 한다면, worktree로도 못 막습니다. 머지할 때 충돌이 납니다. 모두가 공유하는 파일을 한 에이전트가 건드리는 동안 나머지는 기다리거나 우회해야 합니다.

두 번째, 멀어지는 브랜치. 에이전트들이 일하는 사이 main은 계속 앞으로 나아갑니다. 사흘 뒤면 브랜치들이 뒤처져 있고 머지가 고통스러워집니다. 일찍 그리고 자주 rebase하거나, 세션을 짧게 가져가세요.

세 번째, 잊어버린 정리. worktree 하나하나가 디스크에 실제로 존재하는 폴더입니다. 하루에 열 개씩 만들고 정리를 안 하면 부모 폴더는 알아보기 힘들어집니다. git worktree list로 뭐가 굴러다니는지 확인하고, git worktree prune으로 죽은 것들을 치웁니다.

네 번째 함정: worktree는 텅 빈 채로 시작한다

worktree에는 Git이 추적하는 파일만 들어 있습니다. git worktree add가 주는 것은 소스 코드일 뿐, node_modules도, .venv도, 로컬 비밀 값이 담긴 .env도, 빌드 캐시도 아닙니다. 새 worktree에서 시작한 에이전트는 테스트를 돌릴 수 없고, 개발 서버를 띄울 수 없으며, 왜 그런지 말해 주지 않는 경우도 많습니다. npm test는 모듈이 없어서 실패하고, 앱은 환경 변수가 없어서 실패하고, 에이전트는 처음 10분을 티켓이 아니라 배관 작업에 씁니다.

저희도 여기에 당했습니다. 한 사용자가 지적하기를, AgentsRoom의 worktree 옵션이 에이전트 폼의 고급 옵션 안에 숨어 있었고, worktree에서 띄운 에이전트는 의존성이 하나도 없어서 테스트를 단 하나도 돌릴 수 없었다는 것이었습니다. 둘 다 사실이었습니다. 격리 기능은 있었지만, 아무도 기억하지 못하는 수동 단계 없이는 쓸 수가 없었습니다.

버전 1.194.0부터 이 옵션은 에이전트 폼의 격리 블록에 있어서 아무것도 펼치지 않아도 보이고, 새 worktree에서 처음 실행되는 에이전트는 이미 준비된 worktree에서 시작합니다. AgentsRoom은 메인 체크아웃에서 패턴에 맞는 무시된 파일을 복사하고(기본값은 모든 .env*이며, 절대 덮어쓰지 않고, node_modules나 .git 안으로는 절대 복사하지 않습니다), 이어서 lockfile에서 감지한 설치 명령(bun, pnpm, yarn, npm, uv, poetry, pipenv, bundle, composer)이나 프로젝트 설정에서 지정한 명령을 실행합니다. 명령은 에이전트 자신의 터미널에서 돌아가므로 눈으로 볼 수 있고, 설치가 실패해도 에이전트 시작은 막히지 않습니다. 이 과정은 worktree당 한 번만 일어납니다. worktree의 비공개 git 폴더에 남긴 표식 덕분에 다음 실행에서는 이 단계를 건너뜁니다.

직접 손으로 한다면 방법은 같고, 스크립트 하나에 다 들어갑니다. .env*를 복사하고, 설치를 실행한 다음, 에이전트를 시작합니다. git worktree add를 그 스크립트로 감싸 두세요. 그렇지 않으면 세 번째 에이전트쯤에서 잊어버립니다.

진짜 문제: 그 다섯 폴더는 누가 지켜보나

worktree는 파일 충돌을 해결합니다. 하지만 머릿속 부담까지 해결해 주진 않습니다.

폴더 다섯 개, 에이전트 다섯 개, 터미널 다섯 개가 있습니다. 어느 게 내 리뷰를 기다리고 있죠? 어느 게 내가 딴 데 보는 사이 10분 전에 끝났죠? 어느 게 죽었죠?

터미널에만 머물러 있으면 바로 여기서 에이전트 하나당 worktree 하나라는 방식이 한계에 부딪힙니다. 기술적인 충돌은 해결했지만, 지켜봐야 할 창을 늘려 놓은 셈이죠.

AgentsRoom은 각 에이전트를 어느 worktree에서 돌든 상관없이 타일 하나에 올려놓고, 상태와 색으로 보여 줍니다. 대기 중인 에이전트는 빨갛게 변하면서 알림을 보냅니다. worktree 위에 얹는 전체 방법론은 에이전트 3~8개를 놓치지 않고 병렬로 돌리는 법에서 확인하세요.

정리

에이전트 하나, worktree 하나, 브랜치 하나. 이게 제대로 된 멀티 에이전트 작업의 기본 원칙입니다.

명령어는 세 줄이면 끝나고, 효과는 즉시 나타납니다. 에이전트들이 더 이상 서로의 작업을 덮어쓰지 않습니다. 여기에 어느 에이전트가 나를 필요로 하는지 알려 주는 화면까지 더하면, 정신줄 놓지 않고 다섯 가지 작업을 진짜로 동시에 끌고 갈 수 있습니다.