[AI] Git Worktree를 활용한 개발 워크플로우 개선

Git Worktree를 활용한 개발 워크플로우 개선

stash 없이, 충돌 없이 — 여러 작업을 동시에 진행하는 방법

개발하다 보면 유독 타이밍이 나쁜 순간이 있다.

신규 기능 한창 개발 중인데 라이브 버그가 터진다. AI에게 리팩토링을 맡겼더니 생각보다 파일을 많이 건드려서 메인 브랜치가 불안해진다. 동료 PR을 리뷰해야 하는데 내 작업을 멈추기도 애매하다.

이럴 때 보통은 git stash로 작업을 임시 저장하고 브랜치를 옮기고, 끝나면 다시 복귀하는 흐름을 반복한다. 번거롭기도 하고, 복귀 후에 "어디까지 했더라"를 다시 파악하는 컨텍스트 스위칭 비용도 크다.

Git Worktree는 이 구조 자체를 바꿔준다. Git 2.5(2015)부터 있던 기능인데, AI 코딩 도구가 일상화되면서 다시 주목받고 있다.

1. Git Worktree

단순하게 말하면, 같은 Git 저장소를 여러 폴더에서 동시에 열어두는 기능이다. 기존 Git은 작업 디렉터리가 하나뿐이고 브랜치를 바꾸면 그 폴더 안의 파일이 통째로 교체된다. Worktree는 이 제약을 없애준다. 브랜치마다 별도의 폴더를 만들어서, 각각 독립적으로 작업할 수 있게 해준다.

• .git 데이터베이스는 하나만 존재하고, Worktree는 그걸 공유하면서 작업 공간만 따로 갖는다.
• 프로젝트를 통째로 clone하는 것과 달리, 코드 히스토리를 중복 저장하지 않아서 디스크도 훨씬 덜 쓴다.

my-project/        ← main 브랜치 (메인 작업 공간)
  └── .git/        ← Git 데이터베이스 (히스토리, 커밋 전부 여기 있음)

../my-project-fix/ ← hotfix 브랜치 (Worktree)
  └── .git         ← 파일 하나 — 위 .git 폴더를 가리키는 포인터

2. 사용

기본 명령어

명령어	설명
git worktree add <경로> <브랜치>	Worktree 생성
git worktree list	전체 목록 조회
git worktree remove <경로>	안전 삭제
git worktree prune	유령 Worktree 정리
git worktree lock <경로>	prune 보호 (USB 등 외장 드라이브 사용 시)
git worktree repair	폴더 이동 후 연결 복구

프로젝트 폴더와 동일한 위치에 만들기

프로젝트 폴더 안에 Worktree를 만들면 Git이 그 폴더를 추적 안 된 파일로 인식해서 git status 출력이 계속 오염된다.

# 이렇게 하면 git status가 지저분해짐
git worktree add ./my-worktree main

# 프로젝트 폴더 바깥, 나란한 위치에 만드는 게 맞음
git worktree add ../my-worktree main

같은 브랜치는 한 곳에서만 수정하기

Git은 동일 브랜치를 두 폴더에서 동시에 수정하는 상황을 막아준다. 이미 main을 열고 있는 상태에서 새 Worktree에도 main을 체크아웃하려 하면 Fatal 에러가 난다. 읽기만 할 목적이라면 --detach 옵션을 쓰면 된다.

git worktree add ../just-looking --detach

의존성 폴더는 따로 설치하기

node_modules, venv 같은 의존성 폴더는 자동으로 복사되지 않기 때문에 각 Worktree마다 따로 설치해야 한다. pnpm을 쓰면 파일을 복사하지 않고 링크를 걸기 때문에 디스크 사용량과 설치 시간을 크게 줄일 수 있다.

cd ../my-worktree
npm install   # 빠뜨리면 실행이 안 됨

3. 활용

stash 없이 핫픽스 대응 

stash pop 없이, IDE 재색인 없이, 컨텍스트도 그대로다.

# 기능 개발 중인 상태 그대로 두고
# 메인 기준으로 핫픽스 폴더만 따로 오픈

git worktree add ../hotfix main
cd ../hotfix

git checkout -b hotfix/critical-bug
# 수정 작업
git commit -m "fix: 긴급 버그 수정"
git push origin hotfix/critical-bug

# 원래 폴더로 돌아오면 작업 상태 그대로
cd ../my-project

동시 다발 작업

세 가지 일이 한꺼번에 주어진 상황을 가정해보자. 세 서버가 동시에 뜬다. 포트는 각 프로젝트 설정에서 수동으로 지정해야 하지만, 작업 간 간섭은 전혀 없다.

터미널 A: ~/projects/my-app/          → 기능 개발 중 (3000 포트)
터미널 B: ~/projects/my-app-review/   → 동료 PR 리뷰 (3001 포트)
터미널 C: ~/projects/my-app-hotfix/   → 긴급 버그 수정 (3002 포트)

PR 리뷰 전용 환경

동료 PR을 내 로컬에서 직접 돌려보고 싶을 때

git fetch origin pull/42/head:pr-42
git worktree add ../review-pr42 pr-42

cd ../review-pr42
npm install && npm test
# 코드 이것저것 건드려봐도 내 작업엔 영향 없음

# 리뷰 끝나면 깔끔하게 정리
cd ../my-project
git worktree remove ../review-pr42
git branch -D pr-42

접근법 비교

같은 문제를 두 가지 방식으로 AI에게 시켜보고 결과를 나란히 비교할 수 있다.

claude --worktree approach-a -p "이벤트 시스템을 옵저버 패턴으로 리팩토링해줘"
claude --worktree approach-b -p "이벤트 시스템을 메시지 버스 구조로 리팩토링해줘"

# 두 결과를 diff로 비교
git diff worktree-approach-a..worktree-approach-b

4. Claude Code와 함께 쓰기

Claude Code(v2.1.49+)에는 --worktree 플래그가 내장되어 있다. Git 명령을 직접 치지 않아도 Claude가 Worktree를 알아서 만들고 작업한다.

1. .claude/worktrees/<n>/ 에 Worktree 자동 생성
2. worktree-<n> 브랜치를 분기해서 그 안에서만 파일 수정
3. 세션 종료 시, 변경사항이 없으면 자동 삭제 / 있으면 선택

# 이름 지정
claude --worktree refactor-battle-system

# 이름 생략 (랜덤 이름 자동 생성)
claude --worktree

# Claude Code Worktree 폴더가 Git에 추적되지 않도록
.claude/worktrees/

에이전트 정의 파일에 isolation: worktree를 넣으면 해당 에이전트는 항상 격리된 환경에서만 실행된다.

---
name: safe-refactor
description: 격리된 환경에서 리팩토링을 수행하는 에이전트
isolation: worktree
---

여러 에이전트를 동시에 돌릴 때도 각자 다른 Worktree에서 작업하므로 서로 간섭이 없다.

claude --worktree ai-auth  --dangerously-skip-permissions -p "인증 모듈 개선" &
claude --worktree ai-db    --dangerously-skip-permissions -p "쿼리 최적화" &
claude --worktree ai-api   --dangerously-skip-permissions -p "API 타입 정리" &
wait

Claude Code 외에도 Cursor의 Parallel Agents(최대 8개), OpenAI Codex CLI 모두 같은 원리로 Worktree 기반 병렬 실행을 지원한다.

5. 게임 클라이언트에서 활용하기

게임 클라이언트는 전투, 인벤토리, 네트워크, 렌더링처럼 시스템 간 의존성이 복잡하게 얽혀 있다. 한 브랜치에서 여러 작업이 뒤섞이면 리뷰도 머지도 어려워진다. 위 패턴들을 그대로 적용할 수 있고, 특히 아래 상황에서 유용하다.

시스템별 AI 병렬 리팩토링

• 전투, 퀘스트, 인벤토리처럼 독립성이 높은 시스템을 각각 다른 Worktree에서 AI에게 동시에 맡길 수 있다
• 서로 다른 폴더에서 작동하므로 파일 충돌 없음
• 결과는 시스템마다 개별 검토 후 선택적으로 머지

라이브 핫픽스 대응

• 빌드 서버에서 크래시 리포트가 올라와도 진행 중인 피처 브랜치를 stash 없이 그대로 둘 수 있다
• 핫픽스 Worktree를 별도로 열어 바로 대응 → 완료 후 정리하고 원래 작업으로 복귀

로컬 환경 초기화 스크립트화

• 코드 생성, 리소스 빌드, 프로토 업데이트 등 로컬 세팅이 복잡한 프로젝트일수록 효과적
• Worktree를 새로 열 때마다 반복하게 되므로 초기화 스크립트를 미리 만들어두는 것을 권장

주의!

에디터 실행이 필요한 작업은 주의가 필요하다. Worktree는 파일 시스템상 별도 폴더이기 때문에, 게임 엔진이 관리하는 캐시 폴더가 Worktree마다 새로 생성된다.

문제	내용
캐시 재생성	에셋 데이터베이스, 임포트 캐시, 셰이더 캐시 등이 Worktree마다 새로 만들어짐
재임포트 시간	에디터 첫 오픈 시 전체 에셋 재임포트 발생 — 규모에 따라 수 분~수십 분 소요
동시 오픈 충돌	같은 프로젝트를 두 Worktree에서 동시에 에디터로 열면 캐시·라이선스 충돌 가능

참고

https://goddaehee.tistory.com/521

Claude Code v2.1.49 신기능 리뷰 : --worktree로 멀티 에이전트 안전하게 쓰기, 병렬 작업 환경 구축 하기

https://velog.io/@nova-kim/Git-Worktree%EB%A1%9C-AI-%EC%9B%8C%ED%81%AC%ED%94%8C%EB%A1%9C-%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0-%ED%98%91%EC%97%85%EA%B3%BC-%EC%BB%A8%ED%85%8D%EC%8A%A4%ED%8A%B8-%EB%B6%84%EB%A6%AC-%EC%A0%84%EB%9E%B5

Git Worktree로 AI 워크플로 관리하기: 협업과 컨텍스트 분리 전략

https://www.youtube.com/watch?v=JtA2JeqlTnI