Git Worktree로 AI 에이전트 작업을 격리하고 안전하게 되돌리는 방법

AI 에이전트에게 긴 작업을 맡겨 두고 같은 디렉터리에서 다른 작업을 하면, 에이전트의 수정과 사람의 수정이 같은 파일에서 섞인다. 결과가 마음에 들지 않을 때 어디까지가 에이전트의 변경인지 가려내기도 어렵다. git worktree는 하나의 저장소에서 브랜치별로 별도 작업 디렉터리를 만들어 이 문제를 해결한다. 에이전트는 자기 worktree에서만 일하고, 결과가 나쁘면 디렉터리와 브랜치를 통째로 지우면 된다.

worktree가 공유하는 것과 분리하는 것

항목	공유 여부	의미
커밋 객체 데이터베이스	공유	저장소를 다시 클론하지 않아 디스크와 시간이 적게 든다
브랜치·태그(refs/)	공유	한 worktree에서 만든 커밋을 다른 곳에서 바로 볼 수 있다
HEAD, 인덱스(스테이징 영역)	worktree별	체크아웃과 스테이징이 서로 섞이지 않는다
작업 파일	worktree별	에이전트의 수정이 본 디렉터리에 나타나지 않는다
.env 같은 추적되지 않는 파일	복사되지 않음	필요하면 따로 준비해야 한다

git 문서는 같은 브랜치를 두 worktree에서 동시에 체크아웃할 수 없다고 명시한다. 그래서 에이전트용 worktree는 항상 새 브랜치로 만든다.

1단계: 에이전트용 worktree 만들기

# 현재 main을 기준으로 새 브랜치 agent/order-cancel과 작업 디렉터리 생성
git worktree add -b agent/order-cancel ../repo-agent-order-cancel main

# 의존성은 worktree마다 따로 설치
cd ../repo-agent-order-cancel
npm ci

# 현재 worktree 목록 확인
git worktree list

새 worktree는 깨끗한 체크아웃이라 node_modules나 .env가 없다. 에이전트가 테스트를 돌려야 한다면 의존성 설치와 환경 파일 준비를 먼저 해 둔다. 운영용 비밀값이 든 .env를 그대로 복사하지 말고 개발용 값만 두는 것이 원칙이다.

2단계: Claude Code의 --worktree 옵션 쓰기

Claude Code는 이 과정을 옵션 하나로 처리한다. worktree 문서에 따르면 claude --worktree 이름은 저장소 루트의 .claude/worktrees/이름/에 worktree-이름 브랜치로 worktree를 만들고 그 안에서 세션을 시작한다.

claude --worktree order-cancel

# .gitignore에 추가해 worktree 내용이 본 체크아웃에 보이지 않게 한다
echo ".claude/worktrees/" >> .gitignore

추적되지 않는 설정 파일이 필요하면 저장소 루트에 .worktreeinclude를 둔다. .gitignore 문법을 쓰며, 패턴에 맞고 동시에 git이 무시하는 파일만 새 worktree로 복사된다.

# .worktreeinclude
.env.development
config/local.json

세션을 끝낼 때 worktree에 변경이 없으면 이름 없는 세션은 worktree와 브랜치가 자동으로 지워지고, 변경이 있으면 유지할지 지울지 묻는다. 기본값으로 새 worktree는 원격 기본 브랜치에서 갈라지며, 설정 worktree.baseRef를 "head"로 바꾸면 현재 로컬 HEAD에서 시작한다.

3단계: 결과를 검토하고 병합하거나 버리기

1. 본 디렉터리에서 git diff main...agent/order-cancel로 에이전트의 변경 전체를 확인한다.
2. worktree 안에서 테스트를 실행해 결과를 기록한다.
3. 받아들일 변경이면 PR을 만들어 일반 리뷰 절차를 거친다.
4. 버릴 변경이면 아래 명령으로 worktree와 브랜치를 함께 삭제한다.

# 수정 사항이 남아 있는 worktree도 강제로 삭제
git worktree remove --force ../repo-agent-order-cancel
git branch -D agent/order-cancel

# 디렉터리를 직접 지운 경우 남은 관리 파일 정리
git worktree prune

일부만 살리고 싶다면 필요한 커밋만 git cherry-pick으로 가져온다. 에이전트가 만든 큰 변경을 리뷰 가능한 크기로 나누는 방법은 스택 PR 워크플로우 글에서, 병렬 에이전트 실행 환경 전반은 클라우드 코딩 에이전트 환경 설계 글에서 다뤘다.

운영 중 자주 만나는 문제

증상	원인	해결
is already checked out 오류	같은 브랜치가 다른 worktree에 체크아웃됨	새 브랜치(-b)로 생성
worktree 삭제 거부	수정·추적되지 않는 파일 존재 또는 잠금	--force 사용, 잠금은 git worktree unlock 후 삭제
테스트가 worktree에서만 실패	의존성·환경 파일 누락	설치 명령 실행, .worktreeinclude 설정
목록에 사라진 경로가 남음	디렉터리를 직접 삭제	git worktree prune

여러 에이전트를 동시에 돌릴 때의 운영 규칙

worktree의 진가는 여러 작업을 병렬로 돌릴 때 드러난다. 다만 병렬 작업이 늘수록 정리하지 않은 디렉터리와 브랜치가 빠르게 쌓인다. 다음 규칙을 정해 두면 상태를 추적하기 쉽다.

• 이름 규칙: 브랜치는 agent/작업명, 디렉터리는 ../저장소명-agent-작업명처럼 한눈에 에이전트 작업임을 알 수 있게 짓는다.
• 작업당 하나의 worktree: 한 worktree에서 여러 요청을 이어 처리하면 변경의 출처가 다시 섞인다.
• 포트 충돌 확인: 개발 서버를 동시에 띄우면 같은 포트를 쓰려 한다. worktree별로 PORT 환경 변수를 다르게 둔다.
• 주기적 정리: 하루 작업이 끝나면 git worktree list로 남은 항목을 확인하고, 병합되었거나 버린 작업은 삭제한다.
• 잠금 활용: 오래 보존할 worktree는 git worktree lock --reason "검토 대기"로 잠가 정리 명령에 지워지지 않게 한다.