서론

Claude Code와 같은 코딩 에이전트에게 구현을 맡기고 있으면, 다음과 같은 상황을 자주 마주하게 됩니다.

• 규모가 큰 태스크를 던져두고, 출력이 끝날 때까지 몇 분에서 십수 분을 기다려야 한다
• 그동안 터미널만 바라보게 되어, 다음 작업에 착수할 수 없다
• 도중에 다른 버그 수정을 떠올려도, 지금 실행 중인 브랜치를 망치고 싶지 않아 손을 댈 수 없다

원인은 Git의 브랜치가 하나의 작업 디렉토리(working directory)를 공유하고 있기 때문입니다. 브랜치를 전환할 때마다 작업 디렉토리의 내용이 바뀌므로, 어떤 브랜치에서 에이전트가 실행 중인 동안에는 동일한 디렉토리에서 다른 브랜치의 작업을 할 수 없습니다.

이 제약을 해제하는 메커니즘이 바로 **워크트리 (worktree)**입니다. 이 기사에서는 워크트리의 구조와 기본 조작법을 설명한 뒤, AI 에이전트를 사용한 개발에서 왜 워크트리가 효과적인지 정리합니다.

워크트리란 무엇인가

**워크트리 (worktree)**란, 하나의 Git 리포지토리(repository)에 대해 여러 개의 작업 디렉토리를 동시에 가질 수 있는 메커니즘입니다. 통상적으로 git clone을 한 직후의 디렉토리는 '메인 워크트리'라고 불리며, 그곳에 .git 디렉토리(커밋 히스토리나 브랜치 정보를 저장하는 장소)가 놓여 있습니다. git worktree add 명령어를 사용하면, 이 .git을 공유하면서 다른 경로에 추가적인 워크트리를 만들 수 있습니다.

git worktree add ../myapp-feature-a feature/a

이 명령어는 ../myapp-feature-a라는 새로운 디렉토리를 만들고, 그곳에 feature/a 브랜치를 체크아웃(checkout)합니다. 원래의 디렉토리는 그대로 남아 있으며 내용도 변하지 않습니다. 즉, 동일한 리포지토리의 서로 다른 브랜치가 서로 다른 디렉토리에 동시에 존재하는 상태가 됩니다.

이 점이 브랜치 전환(git checkout이나 git switch)과의 결정적인 차이점입니다. 브랜치 전환은 하나의 디렉토리 내용을 써 내려가는 작업이며, 어느 순간에는 하나의 브랜치만 존재합니다. 반면 워크트리는 디렉토리를 추가함으로써 브랜치를 병존시킵니다. 커밋 히스토리, 원격 설정, Git 훅(hook)과 같은 리포지토리 정보는 .git을 통해 모두 공유되므로, 디스크 용량도 clone을 여러 개 만드는 만큼 늘어나지는 않습니다 [1].

기본 조작

워크트리 관리는 git worktree 서브 명령어로 완결됩니다.

새로운 브랜치를 만들면서 워크트리를 생성하는 경우에는 -b 옵션을 사용합니다.

git worktree add -b feature/b ../myapp-feature-b main

이는 "main을 기점으로 feature/b라는 새로운 브랜치를 만들고, ../myapp-feature-b에 체크아웃한다"는 의미입니다. 기존 브랜치를 사용하는 경우에는 앞선 예시처럼 브랜치 이름만 전달합니다.

현재 존재하는 워크트리 목록은 다음 명령어로 확인할 수 있습니다.

git worktree list

/Users/you/myapp abcd123 [main]
/Users/you/myapp-feature-a ef01234 [feature/a]
/Users/you/myapp-feature-b 5678901 [feature/b]

작업이 끝난 워크트리는 디렉토리를 직접 rm -rf로 삭제하는 것이 아니라, git worktree remove로 삭제합니다.

git worktree remove ../myapp-feature-a

.git 측의 관리 정보도 함께 정리해주기 때문에, 나중에 git worktree list를 했을 때 사라졌어야 할 디렉토리가 남아있는 것과 같은 불일치를 방지할 수 있습니다.

왜 AI 에이전트와 궁합이 좋은가

지금까지의 조작만 보면, 워크트리는 "여러 브랜치의 작업을 병행하고 싶은 사람을 위한, 다소 숙련자용 기능"처럼 보일지도 모릅니다. 실제로 지금까지 워크트리가 주로 사용되어 온 것은 리뷰 대기 중인 PR을 만지면서 다른 구현을 진행하는 등, 인간의 수작업이 필요한 상황이었습니다.

이 기능의 사용 편의성이 한층 더 달라지는 지점은 코딩 에이전트 (Coding Agent)를 사용한 개발입니다. 그 이유는 에이전트에게 구현을 맡기고 있는 시간의 성격에 있습니다.

에이전트에게 태스크를 던지고 응답이 돌아오기까지의 몇 분 동안, 개발자는 해당 브랜치의 작업 디렉토리 (Working Directory)를 건드릴 수 없습니다. 에이전트가 파일을 읽고 쓰는 도중에 동일한 디렉토리에서 다른 변경을 가하면, 에이전트가 참조하는 파일의 상태와 개발자가 의도한 상태가 어긋나기 때문입니다. 브랜치 전환이라는 '1 디렉토리 · 1 브랜치'의 제약은 인간이 직접 손을 움직이는 개발에서는 큰 장애물이 되지 않았습니다. 하나의 태스크에 집중하는 동안 다른 브랜치를 만질 필요가 그리 많지 않았기 때문입니다. 하지만 에이전트에게 작업을 위임하는 개발에서는 이 '대기 시간' 자체가 새롭게 생겨난 자원이 됩니다.

워크트리 (Worktree)는 이 대기 시간을 허비하지 않고 사용할 수 있게 해줍니다. 버그 수정용 워크트리에서 에이전트를 실행하는 동안, 별도의 워크트리를 생성하여 다음 기능 추가 태스크를 던지는 식의 운용이 가능해지기 때문입니다.

git worktree add ../myapp-bugfix bugfix/login-crash
git worktree add ../myapp-feature feature/dashboard

각각의 디렉토리에서 별도로 에이전트를 실행하면, 두 개의 태스크가 독립된 파일 시스템 상에서 동시에 진행됩니다. 한쪽 에이전트의 출력을 기다리는 동안, 다른 쪽 워크트리로 이동하여 진행 상황을 확인하거나 지시 사항을 추가할 수 있습니다. 브랜치 전환으로 이를 수행하려 하면, 한쪽의 변경 사항을 매번 커밋 (Commit)하거나 스태시 (Stash)해야만 전환할 수 있어, 대기 시간마다 번거로운 작업이 발생합니다.

Claude Code의 Agent View와 같이 여러 개의 백그라운드 세션을 한 화면에서 관리하는 기능[2]도, 내부적으로는 이 워크트리의 병존을 전제로 하는 경우가 많습니다. 세션마다 독립된 디렉토리가 있기 때문에, 여러 에이전트가 서로의 작업을 망가뜨리지 않고 동시에 실행될 수 있습니다.

운용상의 주의점

병렬 작업을 늘릴수록 워크트리의 수도 늘어납니다. 방치하면 git worktree list의 출력이 길어져, 어떤 디렉토리가 어떤 태스크용인지 알 수 없게 되기 쉽습니다. 디렉토리 이름에 브랜치 명이나 태스크 내용을 포함해 두거나, 작업이 끝난 워크트리는 수시로 git worktree remove를 하는 등의 운용을 철저히 하면 혼란을 방지할 수 있습니다.

또 하나 주의해야 할 점은 워크트리 간의 파일 공유입니다. .env와 같은 환경 변수 파일은 Git 관리 외 ( .gitignore 대상)인 경우가 많아, 새로운 워크트리를 만들어도 복사되지 않습니다. 에이전트를 실행한 곳에서 "환경 변수를 찾을 수 없다"는 에러를 마주한다면, 우선 이 점을 의심해 보는 것이 좋습니다. 빌드 결과물이나 의존성 패키지 (node_modules 등)도 마찬가지로 워크트리마다 존재하므로, 처음에는 다시 설치해야 합니다.

마치며

워크트리는 Git이 본래 가지고 있던 "하나의 리포지토리에 여러 개의 작업 디렉토리를 갖게 하는" 기능입니다. 아주 새로운 기능은 아니지만, AI 에이전트에게 구현을 맡기고 출력을 기다리는 개발 스타일과 맞물리면서 활용의 의미가 달라졌습니다. 에이전트의 손이 비기를 기다리는 것이 아니라, 다른 워크트리에서 다음 태스크에 즉시 착수할 수 있습니다. 이러한 병렬 작업의 용이함이야말로 지금 워크트리를 다시 익힐 가치가 있는 이유입니다.

정확히는, 추가 워크트리의 .git은 본체에 대한 포인터를 포함하는 파일 하나이며, 오브젝트 데이터베이스 (Object Database) 자체는 복제되지 않습니다. ↩︎
여러 AI 세션을 나열하고 묶는 기능에 대해서는, Claude Code의 Agent View: 여러 AI 세션을 한 화면에 묶기에서 다루고 있습니다. ↩︎

Discussion