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는 파일 충돌을 해결합니다. 하지만 머릿속 부담까지 해결해 주진 않습니다.

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

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

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

정리

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

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