AI 코딩 에이전트와 함께 Git 워크트리 사용하는 방법

두 AI 코딩 에이전트를 같은 체크아웃에 붙여 놓으면 결국 오후 하나를 날려먹게 된다. 한쪽이 다른 쪽이 편집 중인 파일을 덮어쓰고, 한쪽이 다른 쪽 발밑에서 브랜치를 바꿔버린다. 둘 다 같은 node_modules를 상대로 npm install을 돌려서, 아무도 작성하지 않은 lockfile을 남긴다. 문제는 조용히 진행되다가 어느 순간 터지고, 그때가 되면 두 에이전트 모두 설명하지 못하는 엉망진창을 두고 이분 탐색을 하고 있는 자신을 발견한다.

표준 해법은 git worktree다. worktree는 하나의 공유 저장소 위에서 각 에이전트에게 자체 작업 디렉터리와 자체 체크아웃된 브랜치를 부여하므로, 병렬 작업이 서로 충돌하지 않는다. 이 가이드에서는 실제 명령어, 실무에서 발목을 잡는 함정, 그리고 아무도 알려주지 않는 정리 규율을 차례대로 살펴본다. 이어서 직접 만든 worktree 스크립트가 어디서부터 확장되지 않는지, 그리고 Sharkly가 어떻게 모든 Task를 자동으로 자체 worktree에서 실행하여 결과가 여러 터미널에 흩어지지 않고 하나의 공유 기록으로 돌아오게 하는지 보여준다.

에이전트 하나만 돌리고 있다면 아직 이런 게 필요 없다. 둘을 돌리는 순간, 격리는 선택 사항이 아니게 된다.

TL;DR

git worktree는 같은 저장소에 연결된 두 번째 작업 디렉터리로, 자체 브랜치와 인덱스를 가진다. 각 AI 코딩 에이전트에게 자체 worktree를 주면 서로를 덮어쓰거나 현재 브랜치를 두고 다투지 않고 병렬로 편집, 빌드, 테스트를 할 수 있다. 명령어는 간단하다. 문제는 운영 비용(worktree별 설치, 정리, 디스크, 조율)이 늘어난다는 것이다. Sharkly는 모든 Task마다 격리된 worktree를 자동으로 준비하고 각 결과를 검토용으로 해당 Task에 돌려보내 그 비용을 관리한다.

왜 하나의 체크아웃이 두 에이전트를 담을 수 없는가

일반적인 git 체크아웃에는 작업 디렉터리 하나, 인덱스 하나, HEAD 하나만 있다. 한 사람이 한 가지 일을 할 때는 문제없다. 하지만 두 에이전트가 동시에 작업하는 순간 무너진다. 이 세 가지가 모두 공유 상태이기 때문이다.

같은 저장소에서 돌아가는 두 에이전트를 상상해 보자. 에이전트 A는 auth-refactor라는 브랜치에서 인증 모듈을 리팩터링하고 있다. 에이전트 B는 로깅 버그를 고치라는 지시를 받고 git checkout -b fix-logging을 실행한다. 이 명령 하나가 체크아웃 전체의 HEAD를 옮겨버린다. 에이전트 A의 커밋되지 않은 변경 사항은 이제 엉뚱한 브랜치 위에 얹혀 있고, 다음 커밋은 잘못된 곳에 쌓이며, 빌드는 이유도 모른 채 실패하기 시작한다. 그러고는 20분을 "디버깅"에 허비하게 된다. 아무것도 크래시하지 않았다. 상태가 조용히 잘못된 것뿐이다.

파일 문제는 더 심각하다. 두 에이전트가 하나의 작업 디렉터리를 공유하므로, 에이전트 B가 설정 파일을 다시 생성하거나 포매터를 재실행하면 에이전트 A가 열어 둔 편집 내용이 디스크에서 덮여 사라진다. 코딩 에이전트는 "다른 녀석이 뭔가 작업 중"이라는 멘탈 모델을 갖고 있지 않다. 파일을 읽고, 행동하고, 다시 쓴다. 작성자 둘, 파일 하나, 잠금 없음. 전형적인 갱신 손실(lost update) 문제인데, 작성자가 자율적이고 빠르다는 점만 다르다.

이것이 바로 "git worktrees"라는 키워드가 계속 떠오르는 이유다. 사람들은 브랜치가 흥미로워서 worktree를 검색하지 않는다. 에이전트를 병렬로 돌리려다 크게 당해서 검색한다. 그렇다면 병렬 실행 쪽은 여러 Claude Code 에이전트를 병렬로 실행하기 가이드에서 깊이 다루고 있으니 참고하길 바란다. 이 글은 그 아래에 깔린 격리 기본 요소에 관한 것이다.

git worktree란 실제로 무엇인가

정의부터 보자. 이 문장은 외워둘 가치가 있다.

git worktree는 같은 저장소에 연결된 추가 작업 디렉터리로, 자체 체크아웃된 브랜치, 인덱스, HEAD를 가지며 하나의 오브젝트 데이터베이스를 공유한다.

마지막 절이 핵심이다. worktree는 클론이 아니다. 클론은 오브젝트 저장소 전체를 복제한다. 모든 커밋, 모든 blob, 모든 태그가 두 번째 .git으로 복사된다. worktree는 하나의 오브젝트 저장소를 공유하고 가벼운 두 번째 작업 디렉터리만 추가한다. 아래에 히스토리가 하나뿐이므로, 커밋이 만들어지는 즉시 모든 worktree에서 보인다. worktree마다 다른 것은 체크아웃이다. 어떤 브랜치가 나와 있는지, 무엇이 스테이징되었는지, 디스크에서 무엇이 변경되었는지다.

에이전트 입장에서는 이 구조가 문제에 딱 들어맞는다. 각 에이전트가 worktree를 하나씩 받는다. 각 worktree는 자체 브랜치와 자체 파일을 가진다. 물리적으로 다른 디렉터리에 있으므로 서로를 덮어쓸 수 없고, 각 worktree가 자체 HEAD를 고정하므로 서로의 브랜치를 발밑에서 빼낼 수도 없다. 충돌은 원래 있어야 할 곳, 즉 리뷰 아래에서 의도적으로 수행하는 병합 시점으로 옮겨가고, 편집 도중에 우연히 발생하지 않는다.

실제로 쓰게 될 worktree 명령어

일반 저장소에서 시작하자. 아래 명령은 모두 그 안에서 실행한다.

새 브랜치로 worktree 만들기. 가장 자주 쓰게 될 명령이다:

git worktree add -b fix-logging ../myproject-fix-logging main

../myproject-fix-logging에 디렉터리를 만들고, main에서 시작하는 새 브랜치 fix-logging을 생성한 뒤 그곳에 체크아웃한다. 에이전트를 이 디렉터리로 향하게 하면 깨끗하고 격리된 작업 공간이 생긴다.

기존 브랜치용 worktree 만들기:

git worktree add ../myproject-auth auth-refactor

열려 있는 worktree 목록 보기:

git worktree list

/Users/you/myproject              9f3c1a2 [main]
/Users/you/myproject-fix-logging  9f3c1a2 [fix-logging]
/Users/you/myproject-auth         3b7e0d4 [auth-refactor]

worktree마다 한 줄씩, 경로와 체크아웃된 커밋, 브랜치가 표시된다. 에이전트 무리를 돌리고 있을 때 이 목록이 누가 어디 있는지 알려주는 기준이 된다.

작업이 병합되거나 폐기되면 worktree 제거:

git worktree remove ../myproject-fix-logging

worktree 디렉터리를 수동으로 삭제한 뒤에는 오래된 메타데이터 정리(prune)를 실행하자(에이전트와 스크립트가 생각보다 자주 이렇게 한다):

git worktree prune

이게 전부다. 명령어는 다섯 개뿐이다. 어려움은 명령어에 있지 않다.

실제로 발목을 잡는 함정들

명령어는 간단하다. 오후를 통째로 날리는 건 운영 현실이다. 다음은 실제 에이전트를 실제 worktree에서 돌릴 때 나타나는 실패 유형이다.

추적되지 않는 파일과 gitignore된 파일은 따라오지 않는다. worktree는 요청한 브랜치의 추적 중인 파일만 체크아웃한다. node_modules, .env, venv, 빌드 캐시, 그 밖에 git이 무시하는 파일은 복사하지 않는다. 따라서 Node 프로젝트의 새 worktree는 그 안에서 설치를 실행하기 전까지는 구동되지 않는다. 모든 worktree가 자체 의존성 설치, 자체 환경 파일, 자체 빌드 비용을 치른다. "저장소는 이미 세팅되어 있다"고 가정하는 에이전트는 설정을 명시적으로 처리하기 전까지 새 worktree에서 첫 명령부터 실패한다.

같은 브랜치를 두 번 체크아웃할 수 없다. Git은 하나의 브랜치가 두 worktree에서 동시에 체크아웃되는 것을 거부하며, 그 판단이 옳다. 두 에이전트 모두 main을 체크아웃해야 한다면 한쪽은 브랜치를 새로 따야 한다. 이는 제약이 아니라 기능이지만, worktree가 자유롭게 떠다니는 복사본일 거라 기대한 사람에게는 의외로 다가온다.

디스크가 빠르게 불어난다. 오브젝트 저장소는 공유되므로 히스토리는 저렴하다. 작업 디렉터리와 그 안의 설치는 그렇지 않다. node_modules가 900MB인 프로젝트의 worktree 열 개면 중복된 의존성이 9GB다. 에이전트 몇 개를 돌리는 노트북이라면 점심때쯤이면 체감된다.

변경 사항이 남은 worktree는 제거를 거부한다. git worktree remove는 커밋되지 않은 변경 사항이 있으면 거부하는데, 이는 에이전트가 끝내지 못한 작업을 실수로 버리는 것을 막아준다. 정말로 없애고 싶다면 git worktree remove --force를 쓴다. 하지만 이제는 그 커밋되지 않은 작업이 중요했는지 여부를 모든 worktree마다 손으로 판단해야 한다.

삭제된 디렉터리는 유령으로 남는다. worktree 폴더를 rm -rf로 지워도 git worktree prune을 하기 전까지 git은 그대로 나열한다. 정리보다 빠르게 worktree를 만드는 스크립트는 오래된 항목을 쌓아두고, 그 항목은 브랜치 이름 재사용을 막는 잠금을 쥐고 있다. 정리는 선택이 아니다. 다만 git worktree list가 무덤이 되기 전까지 잊기 쉽다는 것뿐이다.

중첩된 에이전트 캐시는 네 것이 아니다. 일부 런타임은 자체 worktree 캐시를 유지한다. 예를 들어 ~/.claude/worktrees 같은 곳이다. 여기에 자체 정리 스크립트를 겨누지 말자. 캐시를 소유한 도구가 관리하게 두자.

하나하나는 어렵지 않다. 문제는 이것들이 겹친다는 것이다. worktree 두 개면 손으로 관리한다. 다섯 개가 되면 스크립트를 짠다. 저장소 두 개에 걸쳐 에이전트 열두 개를 돌리면 그 스크립트는 자체 버그를 가진 작은 인프라가 되고, 당신이 그 담당자가 된다.

스크립트가 확장을 멈추는 지점

솔직한 흐름은 이렇다. git worktree add를 감싸고, 새 디렉터리에 에이전트를 떨어뜨리고, 설정을 실행하는 셸 함수로 시작한다. 잘 돌아간다. 디렉터리가 충돌하지 않도록 명명 규칙을 추가한다. 정리 명령도 추가한다. 그러다 요구 사항이 쌓인다.

지금 어느 에이전트가 어느 worktree에 있는지, 그 브랜치가 어떤 상태인지 알고 싶어진다. git worktree list는 에이전트에 대해서는 모르고 디렉터리에 대해서만 안다. 매핑 파일을 얹는다. worktree별 의존성 설치가 디스크를 마구 휘젓지 않게 하고 싶어 캐싱 로직을 넣는다. 에이전트의 출력, diff, 테스트 결과가 닫히는 터미널에 갇히지 않고 사람이 검토할 수 있는 곳에 남길 원한다. 이제 결과 수집기를 만들고 있다. 두 에이전트가 큐에서 같은 작업을 동시에 가져가지 않게 하고 싶다. 이제 잠금을 만들고 있다.

어느 시점이 되면 셸 스크립트로 오케스트레이션 계층을 다시 구현해 놓은 상태가 되고, 그걸 유지 보수하는 건 아무의 일도 아니다. 바로 이 지점에서 vibe kanban 대안 논의가 이루어지며, 에이전트 수가 임계점을 넘으면 팀이 제대로 된 관리 계층을 찾게 되는 이유다. worktree는 애초에 어려운 부분이 아니었다. 여러 격리된 실행을 조율하고 결과를 한곳으로 모으는 것이 어려운 부분이다.

Sharkly가 모든 Task를 자체 worktree에서 실행하는 방식

Sharkly는 올인원 Agent 명령 및 관리 플랫폼이다. Claude Code, Codex 등 에이전트가 이미 사용하는 실행 도구를 대체하지 않는다. 그 도구들 둘레에 공유 Task, Computer, 컨텍스트, 리뷰 계층을 더한다. worktree 격리는 그 계층에 내장되어 있어 직접 만들 필요가 없다.

작동 방식은 직관적이다. 각 Task는 격리된 디렉터리를 받는다. 저장소 기반 작업의 경우 Sharkly는 캐시된 저장소 데이터에서 실행마다 새 worktree를 준비하므로, 여러 Task가 하나의 공유 체크아웃에 쓰지 않고 같은 소스를 상대로 작업할 수 있다. git worktree add를 실행하지 않아도 된다. 명명 규칙, 정리 작업, 매핑 파일을 작성하지 않아도 된다. Task를 할당하면 격리는 이미 마련되어 있다.

이러한 관심사 분리가 모든 것을 차분하게 만든다. Agent는 작업을 어떻게 처리할지 정의한다. Computer는 호스트와 로컬 리소스를 제공한다. Runtime은 실제 에이전트 세션을 수행한다. Task는 팀을 위한 공유 기록으로 남는다. 각 실행이 자체 worktree에서 이루어지므로 프런트엔드, 백엔드, 버그 수정, 새 테스트 커버리지가 서로 밟지 않고 동시에 진행될 수 있다. 수동 접근이 애초에 노렸던 바로 그 병렬성이다.

그리고 결과가 갈 곳도 있다. 실행, 장애 요인, 결과, 후속 논의가 모두 Task 타임라인으로 돌아온다. 에이전트의 diff가 확인해야 할 터미널에 남아 있는 대신, 변경 요약, 검증 출력, 알려진 한계가 Task로 돌아오고, 사람이 이를 수락하거나 변경을 요청하거나 병합을 결정한다. 컨텍스트, 진행 상황, 장애 요인, 결과, 사람의 리뷰가 비공개 프롬프트와 터미널 세션에 흩어지지 않고 요청부터 릴리스까지 하나의 공유된 장소에서 계속 보인다. 이 모델이 처음이라면 AI 코딩 에이전트에게 첫 Task 할당하기가 가장 빠른 입문 경로다.

이미 쓰는 도구는 그대로 유지한다. 모델 사용은 그 도구에 설정된 구독이나 API 키를 통해 계속된다. Sharkly는 그 둘레에 격리, 조율, 리뷰를 더한다.

수동 worktree 대 관리 계층

두 접근 방식 모두 같은 기본 요소를 쓴다. 차이는 운영 부담을 누가 지느냐다.

에이전트 한두 개를 돌리는 개발자 한 명이고 셸을 완전히 통제하고 싶다면 수동 worktree를 쓰자. 그 세팅은 정말로 괜찮고, 어떤 상위 계층이 무슨 일을 하는지 메커니즘을 배울 수 있어 익힐 가치가 있다. 에이전트 수가 늘거나, 한 명 이상이 작업을 봐야 하거나, 닫힌 터미널에서 에이전트 결과를 잃어버려 실제로 손해를 봤다면 관리 계층을 쓰자. 이는 AI 에이전트 오케스트레이션 가이드의 솔직한 판단 기준과 같다. 병렬 작업이 실제가 되기 전에는 조율 장치를 추가하지 말고, 실제가 된 뒤에는 계속 직접 만들지 말자.

인간-에이전트 계약은 여전히 유효하다

격리는 작업이 일어나는 장소를 바꿀 뿐, 누가 결정하는지는 바꾸지 않는다. worktree 덕분에 에이전트는 충돌 없이 병렬로 조사하고, 실행하고, 테스트하고, 보고할 수 있다. 방향을 정하고, 권한을 부여하고, 결과를 수락하는 것은 여전히 사람의 몫이다. 자동화는 팀의 판단이 필요한 지점에서 멈춘다. 에이전트마다 새 worktree를 주는 것이 그 경계를 강제 가능하게 만든다. 각 에이전트의 작업은 공유 체크아웃에 뒤섞인 추적 불가능한 편집이 아니라, 자체 브랜치 위의 뚜렷하고 검토 가능한 변경으로 도착한다. 혼돈이 아니라 브랜치를 리뷰하는 것이다. 이 변화가 일상에서 무엇을 의미하는지 더 넓은 그림은 에이전틱 코딩 해설에서 맥락을 잡을 수 있고, Sharkly란 무엇인가에서 플랫폼 전반을 다룬다.

수동 worktree를 위한 검증된 접근법 몇 가지

당분간 수동으로 간다면, 다음 습관이 대부분의 고통을 막아준다:

• worktree 디렉터리 이름은 순번이 아니라 브랜치나 작업 기준으로 짓자. myproject-auth-refactor는 무엇인지 알려주지만 myproject-wt3는 그렇지 않다.
• worktree는 메인 체크아웃 안에 중첩하지 말고 형제 디렉터리로 두자. 중첩은 트리를 순회하는 도구를 혼란스럽게 하고 ignore 규칙을 부풀린다.
• worktree별 설정은 에이전트가 가장 먼저 실행하는 단일 스크립트로 자동화하자. 그래야 새 worktree가 설치 누락으로 실패하지 않고 한 단계로 구동된다.
• 정리는 기분 내킬 때가 아니라 일정에 따라 하자. 매일 git worktree prune을 돌리고 git worktree list를 점검하면 유령 항목이 줄어든다.
• ~/.claude/worktrees 같은 중첩 런타임 캐시는 자체 스크립트로 절대 삭제하지 말자. 런타임이 소유하게 두자.
• 제거하기 전에 커밋하거나 stash하자. --force는 확신할 때 쓰는 것이지 기본값이 아니다.

결론

Git worktree는 병렬 AI 코딩 에이전트를 안전하게 만드는 격리 기본 요소다. 핵심 개념은 기억해 둘 가치가 있다:

• 하나의 체크아웃에는 브랜치 하나, 인덱스 하나, HEAD 하나만 있고 두 에이전트를 동시에 담을 수 없다.
• worktree는 같은 공유 히스토리 위에 두 번째 작업 디렉터리를 추가하므로 각 에이전트가 자체 브랜치와 파일을 갖는다.
• 다섯 개 명령어(add, list, remove, prune, 정말 필요할 때의 --force)는 간단하다.
• 운영 비용(worktree별 설치, 디스크, 정리, 조율, 결과 수집)이 늘어난다.
• 수동 worktree는 에이전트 한두 개에 적합하고, 수와 위험이 커지면 관리 계층이 제 역할을 한다.
• Sharkly는 모든 Task마다 새 worktree를 자동으로 준비하고 각 결과를 사람의 리뷰를 위해 Task로 돌려보낸다.

먼저 수동 명령어를 익히자. 그러면 어떤 상위 계층이 무슨 일을 하는지 알게 된다. 관리 업무가 실제 작업보다 더 많은 비용을 치르기 시작하면, Sharkly가 worktree, 조율, 리뷰를 대신 맡아준다. Computer 하나를 연결하고, Agent 하나를 만들고, 지루한 일을 하나 할당해 보자.

FAQ

git worktree를 쉽게 설명하면 무엇인가? 같은 저장소에 연결된 두 번째 작업 디렉터리로, 자체 체크아웃된 브랜치와 자체 스테이징/비스테이징 변경 사항을 가진다. 메인 체크아웃과 하나의 커밋 히스토리를 공유하므로 클론보다 훨씬 가볍다. AI 에이전트 입장에서는 각 에이전트가 남의 파일을 건드리지 않고 작업할 사적인 공간을 갖는 것이다.

AI 코딩 에이전트에게 왜 worktree가 필요한가? 하나의 체크아웃을 공유하는 두 에이전트는 서로의 파일을 덮어쓰고 서로의 브랜치를 바꿔버리기 때문이다. 에이전트마다 worktree를 두면 충돌이 편집 도중 상태를 조용히 망가뜨리는 곳이 아니라, 눈에 보이고 검토 가능한 병합 시점으로 옮겨간다. 전체 병렬 설정은 여러 Claude Code 에이전트를 병렬로 실행하기 가이드를 참고하자.

worktree는 클론과 같은가? 아니다. 클론은 오브젝트 데이터베이스 전체를 별도 저장소로 복사한다. worktree는 하나의 오브젝트 데이터베이스를 공유하고 새 작업 디렉터리와 브랜치 체크아웃만 추가한다. 어느 worktree에서 만든 커밋이든 즉시 모든 worktree에서 보이고, 디스크 사용량도 훨씬 적다.

두 worktree가 같은 브랜치를 체크아웃할 수 있는가? 없다. Git은 같은 브랜치에 대한 충돌하는 쓰기로부터 보호하기 위해 하나의 브랜치가 두 worktree에서 동시에 체크아웃되는 것을 거부한다. 두 에이전트 모두 그 브랜치를 기반으로 필요로 한다면 한쪽이 그 브랜치에서 새 브랜치를 만들어야 한다.

worktree를 안전하게 정리하려면 어떻게 하는가? 먼저 작업을 커밋하거나 stash한 뒤 git worktree remove <path>를 실행한다. worktree 디렉터리를 손으로 삭제했다면 git worktree prune을 실행해 오래된 메타데이터를 정리한다. ~/.claude/worktrees 같은 런타임 자체 캐시에 정리 스크립트를 겨누지 말자.

언제 worktree를 손으로 관리하는 것을 그만둬야 하는가? 에이전트 두어 개 이상을 조율할 때, 한 명 이상이 작업을 봐야 할 때, 닫힌 터미널에서 결과를 잃어 시간을 낭비했을 때다. 그 시점에는 각 실행을 격리하고 추적하는 관리 계층이 스스로 값을 한다. 언제 그 전환을 해야 하는지는 AI 에이전트 오케스트레이션 가이드에서 다룬다.