Agent Worktree란? AI 에이전트 작업을 git worktree로 분리하기

Agent worktree는 AI 코딩 에이전트가 작업할 때 쓰는 독립된 git worktree를 말한다. 도구마다 구현은 다르지만, 핵심은 사용자의 작업 공간과 에이전트의 작업 공간을 분리하는 것이다. 여러 에이전트(예: 프론트엔드 담당, 백엔드 담당)가 동시에 코드를 고쳐야 하는 단계에서 특히 필요하다.

git worktree

git worktree는 하나의 저장소로 여러 작업 디렉터리를 동시에 쓰게 해 주는 git 기능이다.

repo/            # 기본 작업 디렉터리 (main)
repo-feature/    # 별도 작업 디렉터리 (feature 브랜치)
repo-bugfix/     # 별도 작업 디렉터리 (bugfix 브랜치)

각 worktree는 서로 다른 브랜치를 체크아웃하고, .git의 객체 데이터는 공유한다. 저장소를 여러 번 clone할 필요가 없다. 같은 브랜치를 두 worktree에서 동시에 체크아웃할 수는 없다(git이 막는다).

브랜치만 나누면 안 되는 이유

"브랜치를 나눴으니 병렬 작업이 된다"고 생각하기 쉽지만, 한 작업 디렉터리에는 한 번에 하나의 브랜치만 체크아웃된다. worktree 없이 같은 디렉터리에서 두 에이전트가 git switch task-a / git switch task-b를 번갈아 실행하면:

한쪽이 브랜치를 바꾸는 순간 다른 쪽이 작업하던 파일이 통째로 바뀐다. 커밋하지 않은 변경은 충돌하거나 유실될 수 있다.
사실상 순차 작업만 가능해져 병렬의 의미가 없다.
타입 검사·테스트도 그 순간 체크아웃된 브랜치 기준으로 돌아가 결과가 뒤섞인다.

worktree는 브랜치마다 별도의 디스크 경로를 만들어 주므로, 두 에이전트가 동시에 파일을 읽고 쓰고 빌드·테스트해도 서로 간섭하지 않는다.

브랜치 분리는 커밋 기록을 나누는 것이고, worktree 분리는 여러 브랜치를 동시에 체크아웃해 병렬 작업을 가능하게 하는 것이다.

AI 에이전트가 worktree를 쓰는 이유

에이전트가 사용자의 현재 작업 디렉터리에서 바로 파일을 고치면, 사용자가 진행 중인 변경과 섞이거나 충돌할 수 있다.

project/                         # 사용자 작업 공간
project/.claude/worktrees/xxx/   # 에이전트 작업 공간 (예: Claude Code)

사용자의 작업 파일을 보호한다.
에이전트가 독립적으로 수정·테스트한다.
여러 에이전트가 서로 다른 작업을 동시에 처리한다.

기본 흐름

# 작업 브랜치와 worktree를 한 번에 생성
git worktree add -b agent/fix-login ../agent-fix-login

# 에이전트는 ../agent-fix-login 안에서만 수정·테스트·커밋

# 원래 디렉터리에서 결과 병합
git merge --no-ff agent/fix-login

# 정리
git worktree remove ../agent-fix-login
git branch -d agent/fix-login

기준 브랜치를 확인한다.
작업용 브랜치와 worktree를 만든다.
에이전트는 그 worktree 안에서만 수정·테스트한다.
사용자(또는 오케스트레이터 에이전트)가 검토 후 공유 브랜치에 병합한다.
worktree와 브랜치를 정리한다.

자주 쓰는 명령어

git worktree add ../feature-a feature/a   # 기존 브랜치로 생성
git worktree list                         # 목록 확인
git worktree remove ../feature-a          # 제거
git worktree prune                        # 디렉터리가 사라진 worktree 정보 정리

여러 에이전트가 한 기능을 나눠 구현할 때

<worktree 루트>/
├── task-frontend/   # 프론트엔드 담당 worktree
└── task-backend/    # 백엔드 담당 worktree

각 담당자는 자기 worktree 안에서만 읽고 쓰며, 다른 worktree나 원본 디렉터리는 건드리지 않는다. 둘 다 끝나면 오케스트레이터가 공유 브랜치에 순서대로 병합하고(--no-ff로 병합 기록을 남김), 재검증을 마친 뒤 worktree를 정리한다.

주의할 점

worktree는 샌드박스가 아니다. 분리되는 것은 "git 변경이 어느 디렉터리에 반영되는가"뿐이다. 프로세스는 여전히 다른 경로에 접근할 수 있으므로, 에이전트에게 자기 worktree 밖을 건드리지 않도록 규칙을 둔다.
git stash, git reset --hard, git clean 같은 저장소 전체 명령은 금지한다. 다른 worktree나 사용자의 변경까지 영향을 줄 수 있다.
의존성은 worktree마다 따로 설치된다. node_modules가 worktree마다 생기므로 디스크를 더 쓰고, 테스트 러너가 다른 worktree 경로까지 스캔하지 않도록 제외 설정을 해 둔다.

요약

Agent worktree는 에이전트 작업을 사용자 작업 공간에서 분리하는 독립 git worktree다.
작업 중인 파일을 보호하고, 여러 에이전트를 병렬로 돌릴 수 있게 한다.
clone보다 가볍고, 결과는 병합으로 검토 후 반영한다.