Git Worktree: 여러 AI 에이전트를 충돌 없이 다루기

전략 테크

2시간 전

조회수

AI 에이전트를 활용하기 위해 Worktree로 에이전트별 작업 공간을 나누고 있습니다.

AI 코딩 에이전트가 보편화되면서 Git의 오래된 기능 하나가 다시 주목받고 있습니다. 바로 ‘Worktree'입니다.

여러 에이전트가 기능 개발, 버그 수정, 테스트 작성처럼 서로 다른 작업을 동시에 처리하는 환경에서, 각 에이전트의 작업 공간을 분리해 충돌을 막아주는 기능으로 그 중요성이 커지고 있습니다.

이 글에서는 Git Worktree가 무엇인지 개념부터 짚고, AI 에이전트 환경에서 왜 중요해졌는지, 도구들이 이를 어떻게 활용하는지, 그리고 직접 다룰 때의 방법과 주의점까지 정리해보겠습니다.

Worktree의 핵심 요약

에이전트끼리 파일을 덮어쓰는 충돌 | 여러 에이전트가 한 폴더에서 일하면 같은 파일을 동시에 건드려 작업이 엉킵니다. Worktree는 에이전트마다 다른 폴더를 줘서 이 충돌을 원천 차단합니다.
누구 작업이 최종본인지 모르는 혼란 | 각 에이전트의 결과가 별도 공간에 따로 쌓이므로, 작업물을 하나씩 검토하고 필요한 것만 골라 합칠 수 있습니다.
실패한 시도를 되돌리는 부담 | 마음에 안 드는 작업은 그 공간만 지우면 됩니다. 메인 작업에는 흔적도 남지 않아, 실험적인 시도를 부담 없이 맡길 수 있습니다.
도구가 알아서 해주는 경우가 많음 | Claude Code 데스크톱이나 Antigravity는 에이전트를 띄울 때 Worktree를 자동으로 만듭니다. 그래서 개념만 이해하면 명령어를 몰라도 됩니다.
필요하면 직접 만들 수도 있음 | 자동 지원이 없는 환경에서는 git worktree 명령으로 직접 공간을 나눌 수 있습니다. Git 2.5(2015년)부터 기본 내장된 기능이라 별도 설치가 필요 없습니다.

Git Worktree란?

Git Worktree란 무엇인지 정리했습니다.

Git Worktree는 하나의 Git 저장소에서 여러 브랜치를 서로 다른 폴더에 동시에 펼쳐 두고 작업할 수 있게 해주는 기능입니다. 같은 저장소를 공유하면서 브랜치마다 독립된 폴더를 따로 두는 방식으로, 브랜치를 전환하지 않고도 여러 작업을 동시에 열어둘 수 있습니다.

저장소를 통째로 복제하는 clone과는 다르게 Worktree는 커밋 이력이 담긴 .git 저장소 하나를 공유하면서, 거기에 연결된 작업 폴더만 여러 개 추가합니다. 그래서 한 폴더에서 만든 커밋이 같은 저장소의 다른 폴더에도 반영되고, 저장소 전체를 복제하지 않아 가볍습니다.

덕분에 여러 에이전트가 서로 다른 작업을 동시에 처리해야 하는 AI 에이전트 작업 환경에서 없어서는 안 될 필수 요소로 꼽히고 있습니다.

Worktree는 왜

AI 에이전트 환경의 필수 요소가 되었을까?

에이전트끼리 같은 폴더에서 부딪히는 걸 방지합니다

Worktree는 에이전트마다 독립된 폴더와 브랜치를 배정해 이 충돌을 막습니다. 각자 다른 폴더에서 일하니 애초에 같은 파일을 동시에 건드릴 수 없고, 그래서 작업이 서로 엉킬 일이 없습니다.

사람 혼자 개발할 때는 하나의 폴더로 충분합니다. 한 번에 한 가지 작업에 집중하기 때문입니다. 하지만 AI 에이전트는 다릅니다. 에이전트 하나에게 UI 수정을, 다른 하나에게 API 수정을, 또 다른 하나에게 테스트 작성을 동시에 맡기면, 이 에이전트들이 같은 폴더에서 동시에 일하게 됩니다.

이때 한쪽이 저장한 파일을 다른 쪽이 덮어쓰면 어느 코드가 최종본인지 추적하기 어려워지는데, Worktree가 작업 공간을 나눠 이런 충돌을 방지하는 것입니다.

사용자의 작업과 에이전트의 작업이 분리됩니다

Worktree는 사용자와 에이전트의 작업 공간도 나눕니다. 에이전트가 별도 브랜치에서 코드를 수정하고 테스트하는 동안, 사용자는 원래 폴더에서 아무 영향 없이 자기 작업을 계속할 수 있습니다. 에이전트가 무언가를 망쳐도 내 메인 작업 공간은 그대로이기 때문에, 안심하고 에이전트에게 일을 맡길 수 있습니다.

작업 결과를 따로 검토하고 골라서 합칩니다

Worktree는 충돌을 막는 데서 그치지 않습니다. 각 에이전트의 결과가 별도 폴더와 브랜치에 따로 쌓이기 때문에, 한꺼번에 합치는 대신 작업물을 하나씩 검토하고 필요한 것만 골라 메인에 병합할 수 있습니다. 마음에 들지 않는 작업은 그 폴더만 지우면 메인에는 흔적도 남지 않아, 실험적인 시도도 부담 없이 맡길 수 있습니다.

Worktree를 사용함으로써 작업 공간을 나누고 결과를 따로 관리할 수 있기 때문에, 여러 에이전트가 서로 부딪히지 않고 각자의 작업을 안전하게 병렬로 진행할 수 있습니다.

Worktree는 어떻게 공간을 나눌까?

AI 에이전트를 활용할 때 worktree가 어떻게 공간을 나누는지에 대한 내용을 정리했습니다.

여기서 한 가지 의문이 들 수 있습니다. "에이전트마다 폴더를 따로 줄 거면, 그냥 프로젝트를 여러 번 복사(clone)하면 되지 않나?" Worktree가 단순 복사와 어떻게 다른지를 이해하면, 이 기능의 진짜 가치가 보입니다.

저장소를 여러 번 clone하면, 프로젝트의 모든 것이 통째로 복제됩니다. 코드뿐 아니라 그동안의 모든 변경 이력까지요. 그래서 용량을 많이 차지하고, 더 중요하게는 각 복사본의 이력이 서로 따로 놉니다. A 복사본에서 만든 커밋을 B 복사본은 모릅니다.

Worktree는 다르게 작동합니다. 프로젝트의 '이력 저장소'(.git이라고 부릅니다)는 하나만 두고, 거기에 연결된 작업 폴더만 여러 개 펼치는 방식입니다. 그래서 한 폴더에서 만든 커밋이 같은 이력 저장소에 기록되고, 다른 폴더에서도 그 이력을 볼 수 있습니다.

이 차이가 에이전트 작업에서 중요한 이유는 두 가지입니다. 하나는 가볍다는 점입니다. 이력을 복제하지 않으니 폴더를 여러 개 만들어도 용량 부담이 적습니다.

다른 하나는 결과를 한 곳에서 합칠 수 있다는 점입니다. 각 에이전트가 자기 폴더에서 일하지만 이력은 하나로 묶여 있으니, 작업이 끝난 뒤 필요한 변경만 골라 메인으로 모으기가 깔끔합니다.

AI 도구들은 Worktree를 어떻게 사용할까?

Claude Code

Claude Code는 Worktree를 공식 지원합니다. 데스크톱 앱은 새 세션을 시작할 때마다 자동으로 격리된 작업 공간을 만들어 줍니다.

터미널(CLI)에서는 claude --worktree 형태로 실행하면 그 세션만의 독립 공간이 생깁니다. 여러 에이전트(서브에이전트)를 함께 돌릴 때도 각자 격리되도록 설정할 수 있습니다.

Claude Code Desktop에서도 Worktree를 사용할 수 있습니다. 기본적으로 Worktree는 프로젝트 루트의 .claude/worktrees/ 아래에 저장되며, 설정에서 Worktree 위치나 브랜치 접두어를 변경할 수 있습니다. 작업이 끝난 세션은 사이드바에서 아카이브해 정리할 수 있습니다.

▶ Claude Code 사용법 보러가기

Codex

Codex는 앱에서 새 작업을 시작할 때 ‘기존 폴더에서 작업할지, 새 Worktree에서 작업할지’ 작업 범위를 고르게 고르게 합니다. Worktree를 선택하면 독립 공간이 만들어집니다. 다만 Codex의 터미널 버전은 이 자동 기능이 없어서, 직접 공간을 나눠야 합니다.

▶ Codex CLI 사용법 보러가기

Google Antigravity

Google Antigravity는 여러 에이전트를 병렬로 돌릴 때 각 에이전트에 독립된 Worktree를 자동 배정합니다. 그래서 사용자가 충돌을 신경 쓰지 않아도 각 결과가 따로 관리됩니다.

▶ 안티그래비티 2.0 사용법 보러가기

도구마다 Worktree를 다루는 방식은 다르지만 핵심 원리는 같습니다. 에이전트마다 독립된 공간을 줘서 충돌을 막고, 결과를 따로 검토한 뒤 합치는 것입니다. 그래서 어떤 도구를 쓰든 Worktree의 작동 방식을 이해하면 에이전트의 작업을 더 정확히 따라갈 수 있습니다.

Worktree 직접 작성해보기

Worktree의 원리를 더 정확히 이해하고 싶다면 직접 git worktree 명령을 써볼 수 있습니다. 외울 필요는 없고, 흐름만 눈에 익혀두면 충분합니다.

처음 쓰는 저장소라면 git init과 첫 커밋이 먼저 필요합니다. Worktree는 커밋이 하나 이상 있어야 만들 수 있기 때문입니다. 이미 Git을 쓰고 있던 프로젝트라면 이 단계는 건너뛰면 됩니다.

git worktree list

현재 어떤 작업 공간들이 열려 있는지 확인합니다.

git worktree add ../agent-ui feature/ui

새 작업 공간을 만드는 핵심 명령은 이것입니다. 폴더 경로와 브랜치명을 함께 넘깁니다. 이 한 줄이 feature/ui 브랜치를 ../agent-ui라는 별도 폴더에 펼칩니다. 그 폴더로 이동해 에이전트를 실행하면, 에이전트는 그 안의 파일만 보고 작업합니다.

cd ../agent-ui

해당 폴더로 이동합니다. 작업 성격에 맞춰 폴더를 나눠두면 한눈에 관리하기 좋습니다.

project/

├── main/ # 사람이 확인하는 기본 공간

├── agent-ui/ # UI 담당 에이전트

├── agent-api/ # API 담당 에이전트

└── agent-test/ # 테스트 담당 에이전트

git worktree remove ../agent-ui

작업이 끝나면 결과를 합치거나 커밋한 뒤 공간을 정리합니다. 실패한 시도는 합치지 않고 바로 지워도 됩니다.

AI 에이전트를 활용할 때,

Worktree에서 무엇을 확인해야할까?

에이전트마다 다른 브랜치가 배정됐는지 확인하세요.

Worktree는 하나의 브랜치를 한 작업 공간에만 연결합니다. 두 에이전트에 같은 브랜치를 주면 오류가 납니다. UI 작업은 feature/ui, API 작업은 feature/api처럼 에이전트마다 브랜치를 나눠야 합니다. 작업을 맡기기 전에 ‘이 에이전트는 어떤 브랜치에서 일하는지’를 정해두는 것이 충돌을 막는 첫 단계입니다.

새 작업 공간에 .env 같은 파일이 들어갔는지 확인하세요.

Worktree는 Git이 추적하는 파일만 가져오기 때문에, .env나 node_modules처럼 제외 설정된 파일은 새 공간에 없습니다. 그래서 에이전트가 시작하자마자 환경 변수를 못 찾고 실패하는 일이 흔합니다.

에이전트가 이유 없이 멈춘다면 이 부분을 가장 먼저 의심하고, 필요한 파일을 새 공간에 복사하거나 도구의 자동 복사 설정을 켜야 합니다.

결과를 합치기 전에 각 공간에서 검토했는지 확인하세요.

작업 공간이 나뉘어 있다는 건 결과도 따로 검토할 수 있다는 뜻입니다. 각 폴더에서 테스트를 돌리고 변경된 파일을 확인한 뒤, 필요한 것만 메인에 합치세요. 특히 여러 에이전트가 동시에 작업했다면 작업 범위가 겹치지 않는지, package.json이나 .env 같은 공통 설정 파일이 의도치 않게 바뀌지 않았는지 반드시 살펴야 합니다.