git worktree로 여러 AI 코딩 에이전트를 병렬 실행하기 — 충돌 없는 핸즈온

Claude Code, Codex CLI, OpenCode와 같은 **터미널 상주형 AI 코딩 에이전트 (AI Coding Agent)**를 하나의 리포지토리(Repository)에서 여러 개 동시에 실행하면, 동일한 작업 디렉토리를 두고 다투게 되어 파일 충돌, 빌드 파괴, 브랜치 혼선이 발생한다.

이를 해결하는 정석적인 방법이 바로 git worktree이다. .git 오브젝트 스토어(Object Store)를 공유하면서, **브랜치마다 독립된 작업 디렉토리 (Working Directory)**를 분리해낼 수 있다. 풀 클론(Full Clone)과 달리 디스크 공간이나 히스토리를 이중으로 사용하지 않는다.

본 기사에서는 표준 git worktree를 사용하여 두 개의 에이전트를 충돌 없이 병렬 실행하는 최단 워크플로우(누구나 재현 가능)를 제시하며, git worktree 명령어만으로 node_modules / .env 관련 주의사항, 차분(Diff) 리뷰 및 머지(Merge), 뒷정리까지 핸즈온으로 정리한다.

마지막으로, 이 절차를 GUI / CLI로 자동화하는 OSS 툴(parallel-code 등)도 소개한다. 툴을 사용하기 전에 순수 git으로 원리를 이해해 두면 어떤 에이전트에서도 응용이 가능하다.

AI 코딩 에이전트는 파일 읽기/쓰기, 테스트 실행, 커밋(Commit)까지를 작업 디렉토리 상에서 직접 수행한다. 하나의 태스크라면 문제없지만, "기능 A 구현", "버그 B 수정", "리팩토링 C"를 동시에 서로 다른 에이전트에게 맡기고 싶을 때 벽에 부딪힌다.

단순하게 같은 디렉토리에서 두 개의 에이전트를 실행하면 다음과 같은 일이 발생한다.

• 에이전트 A가 편집 중인 파일을 에이전트 B가 다른 의도로 덮어씀
• 한쪽이 git checkout으로 브랜치를 전환하면, 다른 쪽의 작업 중인 파일이 되돌아감
• npm run build나 pytest가 서로의 미완성된 변경 사항을 포함하여 실패함

대책으로 "태스크마다 리포지토리를 통째로 git clone 하는" 방법도 있지만, 히스토리와 오브젝트를 매번 복사하기 때문에 디스크를 낭비하고 의존성(Dependency) 재설치 시간도 오래 걸린다.

git worktree는 이 문제를 위해 존재하는 Git 표준 기능이다. 하나의 리포지토리가 가진 .git 오브젝트 스토어를 공유한 채로, 추가적인 작업 디렉토리(Worktree)를 원하는 위치에 전개할 수 있다. 각 워크트리는 독립된 브랜치를 HEAD로 가지기 때문에, 에이전트별로 작업을 완전히 분리하면서도 커밋 히스토리는 한 곳으로 집약된다. 여러 실전 사례에서는 Git worktree가 "동일 코드베이스에서 여러 AI 코딩 에이전트를 병렬 실행하기 위한 지배적인 분리 프리미티브(Primitive)"라고 지적하고 있다.

여기서는 표준 git worktree 명령어만을 사용한다. 특정 툴에 의존하지 않으므로 Claude Code든 Codex CLI든, 사용 중인 원하는 에이전트로 재현할 수 있다.

기존 리포지토리의 루트(Root)에서, 태스크별로 새로운 브랜치가 포함된 워크트리를 만든다.

# 프로젝트 루트에 있다고 가정 (예: ~/work/myapp)
cd ~/work/myapp
# 기능 A의 워크트리를 리포지토리 외부의 인접 디렉토리에 생성
...

git worktree add <path> -b <branch_name>은 지정한 경로에 작업 디렉토리를 만들고, 그곳에서 새 브랜치를 체크아웃(Checkout)한다. -b를 붙이지 않으면 기존 브랜치를 해당 워크트리에 할당한다.

포인트: 워크트리는 리포지토리 외부(인접 디렉토리)에 두는 것이 안전하다. 리포지토리 내부에 만들면 에이전트가 실수로 자신의 워크트리를 결과물로서 커밋 대상에 포함해 버릴 수 있기 때문이다.

현재 워크트리 목록은 언제든 확인할 수 있다.

git worktree list

/home/user/work/myapp a1b2c3d [main]
/home/user/work/myapp-feature-a e4f5a6b [feature-a]
/home/user/work/myapp-fix-b 7c8d9e0 [fix-b]

터미널을 두 개 열고, 각 워크트리 디렉토리에서 서로 다른 에이전트를 실행한다.

# 터미널 1
cd ../myapp-feature-a
claude # 기능 A 구현 요청
...

두 작업은 물리적으로 별도의 디렉토리 (physically separate directories) 에서 동작하기 때문에, 파일 점유 경쟁이나 브랜치 전환으로 인한 작업 되돌림(rollback)이 발생하지 않는다. .git 디렉토리는 공유하므로, 한쪽에서 커밋한 내용은 다른 쪽에서도 git fetch 없이 (동일한 로컬 저장소의 참조로서) 볼 수 있다.

이 부분이 병렬 워크트리 (worktree) 운용 시 가장 큰 걸림돌이다. git worktree add로 생성되는 것은 추적 대상 파일의 체크아웃 (checkout) 뿐이며, .gitignore에 등록된 node_modules/나 .env는 새로운 워크트리에 포함되지 않는다.

이 상태 그대로 두면 각 워크트리마다 npm install을 다시 실행해야 하므로 시간과 디스크 공간이 낭비된다. 실무에서는 다음 두 가지 방법 중 하나로 해결한다.

방법 A: 빌드된 의존성을 재사용하고 싶을 때
메인 워크트리의 node_modules를 심볼릭 링크 (symlink) 한다.

cd ../myapp-feature-a
ln -s ../myapp/node_modules ./node_modules

단, 워크트리 간에 의존성 버전이 서로 다른 태스크 (task) 를 실행해야 한다면 공유하는 것은 위험하다. 그럴 경우에는 방법 B를 택한다.

방법 B: 의존성이 다른 경우
.env와 같은 작은 설정 파일은 복사하고, 의존성은 각 워크트리에 개별적으로 설치한다.

cd ../myapp-feature-a
cp ../myapp/.env ./.env # 기밀 정보는 커밋하지 말 것
npm install # 이 워크트리 전용 의존성을 설치

parallel-code와 같은 자동화 도구는 이 "node_modules 등 ignore 처리된 디렉토리를 워크트리로 symlink 하는" 처리를 태스크 생성 시 자동으로 수행한다. 수동으로 운용하더라도 위의 1~2줄을 워크트리 생성 직후의 정형 작업으로 만들어 두면 실수를 줄일 수 있다.

보안 주의: .env나 인증 토큰을 포함하는 파일을 여러 워크트리에 전개할 경우, 해당 파일들이 각 워크트리의 .gitignore에서도 제외되어 있는지 반드시 확인해야 한다. 워크트리가 늘어날수록 기밀 정보를 실수로 커밋하게 되는 경로도 늘어난다.

병렬 에이전트의 강점은 여러 안을 동시에 실행하여 좋은 것만 채택할 수 있다는 점에 있다. 각 워크트리는 브랜치이므로, 리뷰와 머지 (merge) 모두 일반적인 Git 플로우 (flow)와 동일하다.

# 기능 A 브랜치의 변경 사항을 메인 워크트리에서 차이(diff) 확인
cd ~/work/myapp
git diff main..feature-a --stat
...

채택하기로 결정한 브랜치를 main에 머지한다.

git switch main
git merge --no-ff feature-a # 기능 A 채택

채택되지 않은 워크트리는 정리 단계(다음 절)에서 브랜치째로 폐기하면 된다. "안 좋은 안은 워크트리째 버리고, 좋은 안만 main에 집약한다" —— 이것이 병렬 워크트리 운용의 기본 리듬이다.

태스크가 끝나면 워크트리를 삭제한다. 디렉토리를 rm -rf로 지우기만 하면 Git의 관리 정보가 남기 때문에 전용 명령어를 사용해야 한다.

# 워크트리 삭제 (미커밋 변경 사항이나 추적되지 않는 파일이 있으면 거부됨 = 안전)
git worktree remove ../myapp-feature-a
# 디렉토리를 수동으로 삭제해 버린 경우 관리 정보를 정리
...

git worktree remove는 미커밋 변경 사항이나 추적되지 않는 파일이 남아 있는 'clean 하지 않은' 워크트리를 기본적으로 삭제하지 않으므로, 실수로 작업 내용을 잃어버리는 사고를 방지할 수 있다. 강제로 삭제하고 싶을 때만 --force를 붙인다.

순수 git worktree로 원리를 파악했다면, 정형 작업(워크트리 생성 → 의존성 링크 → 에이전트 기동 → 차이 리뷰)을 자동화하는 도구를 사용하면 훨씬 빠르다. 대표적인 OSS를 소개한다.

• parallel-code (MIT 라이스): 태스크를 생성하면 자동으로 "main에서 브랜치 생성 → 워크트리 전개 → node_modules...

등을 symlink(심볼릭 링크) → 에이전트 기동」까지 수행하여, 여러 태스크의 차이점(diff)을 나란히 놓고 리뷰 및 머지(merge)할 수 있다. Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Antigravity CLI를 지원한다3. 데스크톱 앱(Electron)으로 동작한다. -

기타 CLI / 병렬 러너(Parallel Runner):
agentree

・ccswarm

・각종 worktree 러너 등, 터미널에서 git worktree 기반의 병렬 실행을 다루는 도구들이 갖춰지고 있다. 최신 목록은 CLI 코딩 에이전트를 망라한 큐레이션 awesome-cli-coding-agents를 참고하면 된다4.

도구 선정 지침은 간단하다. GUI를 통한 차이점(diff) 리뷰를 중시한다면 parallel-code 계열, 터미널 내에서 완결하고 싶다면 CLI 러너 계열을 선택하면 된다. 두 방식 모두 내부적으로 수행하는 작업은 본 기사의 핸즈온과 동일한 git worktree이므로, 동작을 예측하기 어려워지면 순수 git 명령어로 돌아가면 된다.

증상	원인	대책
새 워크트리에서 빌드가 통과되지 않음	node_modules는 worktree에 포함되지 않음	symlink(방법 A) 또는 개별 npm install(방법 B)
에이전트가 자신의 워크트리를 커밋하려고 함	워크트리를 리포지토리 내부에 생성함	리포지토리 외(outside)의 인접 디렉토리에 생성
git worktree remove가 실패함	커밋되지 않은 변경 사항이 남아 있음 (안전 장치)	변경 사항을 확인/커밋한 후 삭제. 버릴 경우 --force 사용
디렉토리를 삭제했는데 worktree list에 남아 있음	관리 정보가 잔존함	git worktree prune으로 정리
브랜치를 삭제할 수 없음 (-d 거부됨)	해당 브랜치가 어딘가의 워크트리에서 HEAD로 설정되어 있음	먼저 워크트리를 remove한 후 삭제
동일한 브랜치를 두 개의 워크트리에서 열 수 없음	Git의 사양 (1 브랜치 = 1 워크트리)	태스크마다 별도의 브랜치를 생성

• 여러 AI 코딩 에이전트를 하나의 리포지토리에서 병렬로 실행하려면, git worktree로 태스크마다 독립된 작업 디렉토리를 생성하고 브랜치를 나누는 것이 충돌을 방지하는 정석이다. 절차는 「git worktree add로 브랜치 생성 → 각 디렉토리에서 에이전트 기동 → 차이점을 리뷰하여 좋은 안만 main에 머지 → git worktree remove로 정리」의 4단계로 요약된다.

• 주로 node_modules나 .env 주변에서 문제가 발생한다. symlink 또는 개별 설치를 워크트리 생성 직후의 정형화된 작업으로 삼아두면 사고를 크게 줄일 수 있다.

• 자동화 도구(parallel-code 등)는 편리하지만, 본질은 동일한 git worktree이다. 순수 git으로 원리를 이해해 두는 것이 어떤 에이전트나 도구를 사용하더라도 응용이 가능한 최단 경로가 된다.

---

1. git-worktree 공식 문서 (명령어 사양: add/list/remove/prune 동작). https://git-scm.com/docs/git-worktree ↩
2. "Git worktrees for parallel AI coding agents" — Upsun Developer. git worktree가 병렬 AI 에이전트 실행의 분리 프리미티브(primitive)로 정착하고 있는 점을 설명함. https://developer.upsun.com/posts/ai/git-worktrees-for-parallel-ai-coding-agents ↩
3. johannesjo/parallel-code (MIT). 태스크 생성 시 브랜치 생성, 워크트리 전개, node_modules 등을 symlink로 연결하여 에이전트를 기동하고, 여러 태스크의 차이점을 나란히 리뷰/머지할 수 있음. ↩

등의 symlink(심볼릭 링크) 및 에이전트 기동을 자동화함. 대응 에이전트 목록을 포함. https://github.com/johannesjo/parallel-code ↩ ↩2↩3 -
bradAGI/awesome-cli-coding-agents — CLI 코딩 에이전트(CLI coding agents), 병렬 러너(parallel runners), 자율 루프(autonomous loops) 큐레이션 (2026-06-15 업데이트). https://github.com/bradAGI/awesome-cli-coding-agents ↩