[AI] 1. Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

1. [AI] Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

2. [AI] Claude Code 병렬 처리로 효율 극대화하기 (claude --worktree)

3. [AI] Claude Code 병렬 처리로 효율 극대화하기 - tmux 활용하기

4. [AI] Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

5. Claude Code 병렬 처리로 효율 극대화하기 - cmux, worktree, omc 병렬 처리하기 (.omc/handoffs, .omc/shared_memory.json)

worktree가 왜 중요한가

• Claude Code나 GitHub Copilot CLI 같은 터미널 기반 AI 도구를 쓸 때 아쉬운 점이 있음.
• AI에게 무거운 리팩토링이나 테스트 코드 작성을 시켜두면, 작업이 끝날 때까지 해당 브랜치에서 키보드를 놓고 대기해야 함. 중간에 브랜치를 바꾸면 코드가 뒤엉키기 때문
• 이러한 컨텍스트 스위칭 비용과 병목 현상을 해결해 주는 Git 기능이 바로 git worktree
• Claude Code를 병렬로 띄워두고 멀티태스킹을 하기 위한 핵심 전제 조건인 Git Worktree의 개념과 기본 사용법을 정리

1. Git Worktree란?

• 일반적인 git clone 환경에서는 단 하나의 작업 디렉토리(Working Directory)만 존재
• git checkout으로 브랜치를 바꾸면 하나의 폴더 안에서 파일이 순간적으로 바뀌므로, 동시에 펼쳐놓고 작업할 수 있는 브랜치는 늘 단 1개뿐
• 반면, Git Worktree는 하나의 Git 저장소(.git)를 공유하면서, 서로 다른 브랜치를 바라보는 '물리적인 폴더'를 여러 개 생성하는 기능

💡 개념 구분하기: worktree와 branch 차이?

 

• 기존 브랜치 방식: main에서 파일 코드를 10줄쯤 고치던 중, 급하게 bugfix 브랜치로 넘어가야 하면 그냥 바꿀 수 없음. Git이 "작업 중인 파일이 있으니 커밋하거나 stash(임시 저장)하라"고 에러를 뱉음. 하던 맥락을 끊고 git stash를 한 뒤 넘어가야 함.
• Worktree 방식: 폴더 자체가 분리되어 있으므로 하던 작업을 저장하거나 커밋할 필요가 없음. main 폴더에 작업 중인 코드를 그대로 켜둔 채로, 그냥 옆 폴더(bugfix)로 이동해서 바로 코딩하면 됨.

 

2. 왜 Claude Code와 함께 쓸 때 강력할까?

프로젝트 구조가 물리적으로 분리되기 때문에 완벽한 격리가 가능함.

• 인간과 AI의 작업 분리: 폴더 A(main 브랜치)에서는 내가 원래 하던 피처 개발을 진행하고, 동시에 폴더 B(feature 브랜치)를 새로 만들어 Claude Code에게 "이 폴더 버그 좀 잡아줘"라고 던져놓을 수 있음.
• 의존성 격리: Claude가 코드를 대대적으로 수정하면서 발생하는 빌드 깨짐이나 임시 파일들이 내 작업 공간에 전혀 영향을 주지 않음.

3. Git Worktree 핵심 명령어

① 새로운 워크트리 생성

현재 프로젝트 폴더의 상위 경로에 새로운 폴더를 만들고, 새 브랜치를 연결하는 명령어.

# 사용법: git worktree add [생성할 폴더 경로] -b [새 브랜치명]
$ git worktree add ../my-app-claude -b feature-claude-task

Preparing worktree (new branch 'feature-claude-task')
HEAD is now at a1b2c3d Initial commit

• 현재 폴더 바로 바깥에 my-app-claude라는 물리적인 폴더가 실제로 생겨남.
• 해당 폴더로 이동(cd ../my-app-claude)해 보면 브랜치가 자동으로 feature-claude-task로 전환되어 있음.

② 워크트리 목록 확인

현재 저장소에 연결된 워크트리 경로와 브랜치 목록을 확인

$ git worktree list

/Users/developer/Desktop/my-app         a1b2c3d [main]
/Users/developer/Desktop/my-app-claude  a1b2c3d [feature-claude-task]

③ 워크트리 삭제

AI가 작업을 끝내고 원격 저장소에 푸시(Push)까지 완료했다면 워크트리를 삭제함. (반드시 원래 메인 프로젝트 폴더로 돌아와서 수행)

# 메인 폴더로 이동 후 삭제
$ cd ../my-app
$ git worktree remove ../my-app-claude

• 연결이 해제되면서 상위에 생성되었던 my-app-claude 폴더도 자동으로 삭제됨.
• .git 저장소 자체는 공유하고 있었기 때문에, 옆 폴더에서 작업하고 커밋했던 내역은 메인 폴더의 git log에서도 그대로 조회됨.

요약

• git worktree는 하나의 저장소를 공유하며 여러 브랜치를 독립된 폴더로 동시에 펼쳐놓는 기능임.
• 브랜치를 전환할 때 작업 내역을 stash하거나 기다릴 필요가 없음.
• 이 격리 공간을 활용하면 인간과 AI(Claude Code)가 서로의 컨텍스트를 깨뜨리지 않고 완벽한 병렬 작업을 수행할 수 있음.

다음 글에서는 Claude Code의 내장 명령어(claude --worktree)를 활용해 이 과정을 한 줄로 자동화하는 방법을 알아볼 예정