Git Worktree 사용법: Claude Code·Codex 작업 폴더 분리하기

Claude Code나 Codex를 한 번에 하나만 실행할 때는 같은 프로젝트 폴더를 사용해도 큰 문제가 없습니다. 하지만 문서 수정과 테스트 작성을 동시에 맡기는 순간 상황이 달라집니다. 한 세션이 브랜치를 바꾸거나 파일을 고치는 동안 다른 세션도 같은 파일을 읽고 있으면, 변경 주체와 기준 시점이 뒤섞입니다.

Git Worktree 사용법을 알아두면 이 문제를 줄일 수 있습니다. 저장소를 여러 번 복제하지 않고도 에이전트마다 별도 작업 폴더와 브랜치를 만들 수 있기 때문입니다. 이번 글에서는 문서 담당과 테스트 담당 worktree를 실제로 만든 뒤, 두 Codex 세션을 병렬 실행해 main과 서로의 변경이 분리되는지 확인했습니다. Claude Code에서 제공하는 자동 worktree 방식과 Codex CLI에서 수동으로 나누는 방식도 함께 구분합니다.

기존 Herdr 사용 가이드는 여러 에이전트의 터미널 화면과 세션을 관리하는 방법을 다룹니다. 이번 글은 화면을 나누는 법이 아니라, 각 세션이 수정할 Git 작업 폴더와 브랜치를 나누는 데 집중합니다.

같은 폴더에서 AI 작업이 섞이는 이유

AI 코딩 에이전트는 현재 폴더를 작업 범위로 삼아 파일을 읽고 수정합니다. 두 세션이 같은 폴더를 공유하면 다음과 같은 일이 생길 수 있습니다.

• 첫 번째 에이전트가 수정 중인 파일을 두 번째 에이전트가 다시 덮어씁니다.
• 한 세션이 git switch를 실행해 다른 세션의 기준 브랜치가 바뀝니다.
• git status에 두 세션의 변경이 한꺼번에 표시됩니다.
• 테스트 실패가 코드 문제인지, 다른 세션의 미완성 변경 때문인지 구분하기 어렵습니다.
• 에이전트 하나를 중단해도 어느 변경까지 되돌려야 하는지 판단하기 어렵습니다.

터미널 창만 두 개 여는 것으로는 해결되지 않습니다. 두 창의 현재 경로가 같다면 결국 같은 작업 파일과 Git 인덱스를 바라봅니다. 병렬 작업에는 터미널 분리보다 작업 폴더 분리가 먼저입니다.

Git Worktree의 역할

Git 공식 문서는 하나의 저장소에 여러 working tree를 연결하고, 서로 다른 브랜치를 동시에 체크아웃할 수 있다고 설명합니다. 원래 git clone으로 만든 폴더는 main worktree가 되고, git worktree add로 만든 폴더는 linked worktree가 됩니다.

구조를 단순화하면 다음과 같습니다.

my-project/                 → main 브랜치
my-project-agent-docs/      → agent/docs 브랜치
my-project-agent-tests/     → agent/tests 브랜치

각 폴더에는 작업 파일과 HEAD, 인덱스가 따로 있습니다. 반면 커밋 객체와 브랜치 같은 Git 저장소 정보는 연결돼 있습니다. 그래서 파일 작업은 분리하면서도 한 저장소의 브랜치로 결과를 관리할 수 있습니다.

따라서 worktree는 파일과 인덱스를 나누지만 Git 명령 전체를 격리하는 보안 샌드박스는 아닙니다. 브랜치 삭제·강제 이동과 push는 저장소나 원격에 함께 영향을 줍니다. 에이전트에는 브랜치 전환·삭제·push를 맡기지 말고, 사람이 결과를 확인한 뒤 실행하는 편이 안전합니다.

worktree는 “에이전트를 많이 실행하는 기능”이 아니라, 각 에이전트가 건드릴 파일 상태와 브랜치를 분리하는 Git 기능입니다.

따라 하기 전 버전 확인

이번 흐름은 아래 환경에서 확인했습니다. 버전이 달라도 Git의 기본 명령은 비슷하지만, Claude Code와 Codex의 자동화 옵션은 달라질 수 있습니다.

항목	확인 환경
운영체제	Linux 6.8.0
Node.js	v22.23.1
Git	2.43.0
Codex CLI	0.146.0
Claude Code	2.1.218
확인일	2026-08-05

실제 파일 변경 검증은 로그인돼 있던 Codex CLI 세션 두 개로 진행했습니다. Claude Code는 현재 CLI 도움말과 공식 문서에서 --worktree 옵션을 확인했으며, 아래에서 자동 생성 방식과 수동 방식의 차이를 따로 설명합니다.

worktree를 만들기 전 확인할 것

worktree를 추가하기 전에 main 작업 폴더부터 확인합니다.

git status --short --branch
git remote -v
git branch --show-current
git branch -r
git fetch origin
git log -3 --oneline --decorate

main에 수정 중인 파일이 있어도 새 worktree를 만들 수 있습니다. 다만 어느 변경이 어느 작업에 속하는지 혼동하지 않도록 현재 상태를 확인하고, 필요한 변경은 커밋하거나 안전하게 보관해 두는 편이 좋습니다. worktree가 기존 변경을 자동으로 치워 주지는 않습니다. 새 작업 브랜치의 기준을 최신 원격 main으로 맞추려면 git fetch origin도 먼저 실행합니다.

아래 예시는 원격 이름이 origin, 기준 브랜치가 main인 저장소를 가정합니다. git remote -v와 git branch -r의 출력이 다르면 origin/main을 실제 원격과 브랜치 이름으로 바꿉니다.

이 글의 명령은 origin/main에서 새 브랜치를 만들기 때문에, 해당 원격 브랜치가 가리키는 커밋이 먼저 있어야 합니다. 반면 기준 커밋을 생략하고 유효한 로컬 브랜치도 없으면 Git 2.43은 orphan worktree를 자동으로 추론할 수 있습니다. 아래처럼 존재하지 않는 origin/main을 명시한 명령에는 이 동작이 적용되지 않으므로, 입문자는 첫 커밋을 만든 뒤 따라가는 편이 단순합니다.

에이전트별 작업 폴더 만들기

문서 수정과 테스트 작성을 나눈다고 가정해 보겠습니다. 프로젝트 폴더에서 다음 명령을 실행합니다.

git worktree add --no-track -b agent/docs ../my-project-agent-docs origin/main
git worktree add --no-track -b agent/tests ../my-project-agent-tests origin/main

명령을 나눠 보면 의미가 분명합니다.

• git worktree add: linked worktree를 추가합니다.
• --no-track: 새 작업 브랜치가 origin/main을 upstream으로 자동 추적하지 않게 합니다.
• -b agent/docs: 새 브랜치를 함께 만듭니다.
• ../my-project-agent-docs: 새 작업 폴더 위치입니다.
• origin/main: 새 브랜치가 출발할 기준 커밋입니다.

원격 저장소가 없는 로컬 프로젝트라면 마지막 기준을 main으로 바꿀 수 있습니다.

git worktree add -b agent/docs ../my-project-agent-docs main

생성이 끝나면 목록을 확인합니다.

git worktree list

이번 검증에서는 다음처럼 main과 두 작업 브랜치가 별도 폴더로 표시됐습니다.

목록에서 폴더, 현재 커밋, 브랜치 이름이 각각 보이면 기본 분리는 끝난 상태입니다.

Claude Code와 Codex 실행 위치

수동으로 만든 worktree는 도구에 관계없이 사용할 수 있습니다. 각 터미널에서 서로 다른 폴더로 이동한 뒤 에이전트를 실행합니다.

아래 명령은 각 도구를 수동 worktree에서 시작하는 사용 예시입니다. 이번 파일 격리 실험은 두 폴더 모두 Codex CLI로 진행했습니다. Claude Code는 실제 파일 변경에 사용하지 않고 현재 CLI 도움말과 공식 문서로 worktree 지원 범위만 확인했습니다.

문서 작업 폴더

cd ../my-project-agent-docs
claude

테스트 작업 폴더

cd ../my-project-agent-tests
codex

중요한 것은 도구 이름보다 현재 경로입니다. 프롬프트를 보내기 전에 pwd와 git branch --show-current를 확인하면 잘못된 폴더에서 작업을 시작하는 실수를 줄일 수 있습니다.

pwd
git branch --show-current
git status --short

에이전트에게도 처음부터 범위를 좁혀 전달합니다.

현재 worktree에서 app.test.js만 작성하고 테스트해줘.
다른 파일 수정, 브랜치 전환, 커밋과 푸시는 하지 마.
완료 후 git status --short와 테스트 통과 개수를 보여줘.

브랜치를 만들었으니 알아서 안전하겠지라고 생각하기보다 허용 파일, 금지 작업, 완료 확인 명령을 같이 주는 편이 안전합니다. 역할과 결과 형식을 더 자세히 나누는 방식은 AI에게 작업을 나눠 맡길 때 역할 정의서 쓰는 법에서 확인할 수 있습니다.

Claude Code의 자동 worktree 옵션

현재 Claude Code 공식 문서는 다음처럼 별도 worktree 세션을 시작하는 방법을 안내합니다.

claude --worktree feature-auth

현재 설치된 Claude Code 2.1.218의 도움말에서도 -w, --worktree [name] 옵션을 확인할 수 있었습니다. 이 방식은 Claude Code가 새 worktree를 만들고 그 안에서 세션을 시작하므로 편리합니다.

공식 문서 기준 기본 경로는 저장소 안의 .claude/worktrees/<name>/, 브랜치 이름은 worktree-<name>입니다. 기준은 기본적으로 원격 저장소의 기본 브랜치이며, 설정하면 현재 HEAD에서 시작할 수도 있습니다. 이 자동 방식은 출발할 기존 커밋이 필요하므로 커밋이 전혀 없는 저장소에서는 먼저 첫 커밋을 만들어야 합니다.

다만 여러 도구를 함께 쓰거나 폴더 이름과 출발 브랜치를 직접 통제하려면 앞에서 설명한 git worktree add 방식이 더 투명합니다. Git 명령으로 먼저 구조를 만든 뒤 Claude Code와 Codex를 각각 해당 폴더에서 실행하면, 어느 도구가 어느 브랜치에 연결됐는지 git worktree list로 한 번에 확인할 수 있습니다.

ChatGPT 데스크톱 앱의 Codex와 CLI 차이

OpenAI 공식 문서에는 ChatGPT 데스크톱 앱에서 Codex 채팅을 worktree로 시작해 여러 작업을 병렬 실행하는 흐름이 있습니다. 이 자동 기능은 데스크톱 앱의 Codex에서 제공되며 Codex CLI 전용 옵션은 아닙니다.

확인한 Codex CLI 0.146.0의 도움말에는 Claude Code와 같은 전용 --worktree 옵션이 없었습니다. 이 버전에서는 Git으로 worktree를 먼저 만든 뒤 해당 폴더에서 실행할 수 있습니다.

git worktree add --no-track -b agent/tests ../my-project-agent-tests origin/main
codex -C ../my-project-agent-tests

ChatGPT 데스크톱 앱의 자동 worktree 기능과 Codex CLI의 현재 명령을 같은 기능처럼 설명하면 헷갈릴 수 있습니다. 데스크톱 앱에서는 새 Codex 채팅에서 Worktree를 선택할 수 있지만, 공식 문서 기준 앱이 만든 worktree는 기본적으로 detached HEAD에서 시작합니다. 처음부터 이름 있는 브랜치를 만드는 이 글의 수동 git worktree add -b 흐름과 다른 부분입니다.

두 작업이 정말 분리됐는지 확인

검증용 저장소에는 README.md, app.js, package.json 세 파일만 두었습니다. 첫 번째 Codex 세션에는 README.md의 Usage 문단만 수정하도록 했고, 두 번째 세션에는 app.test.js만 만들고 테스트를 실행하도록 했습니다.

두 세션이 끝난 뒤 각 폴더의 상태는 다음처럼 달랐습니다.

main worktree
(no output)

docs worktree
 M README.md

tests worktree
?? app.test.js

추가로 문서 worktree에 app.test.js가 없는지, 테스트 worktree의 README.md에 Usage 변경이 없는지도 확인했습니다. 테스트 worktree에서는 Node 테스트 1건이 통과했습니다.

# tests 1
# pass 1
# fail 0

같은 브랜치를 두 번 열 수 없는 이유

이미 agent/docs 브랜치가 연결된 상태에서 같은 브랜치를 다른 worktree에 추가하면 Git이 거부합니다.

fatal: 'agent/docs' is already used by worktree at '.../my-project-agent-docs'

이 제한은 불편한 것이 아니라 안전장치에 가깝습니다. 같은 브랜치를 두 폴더에서 동시에 수정하면 어느 작업 폴더가 최신인지 다시 헷갈릴 수 있기 때문입니다. detached HEAD worktree도 만들 수 있지만, 이 글의 named branch 흐름에서는 에이전트마다 브랜치를 하나씩 배정하는 편이 단순합니다. 같은 목적의 세션을 다시 열어야 한다면 기존 worktree 폴더에서 이어갑니다.

--force로 이 제한을 억지로 우회하기보다 브랜치와 역할을 다시 확인하세요.

worktree가 분리하지 않는 것

worktree는 작업 파일과 Git 상태를 분리하지만 컴퓨터 전체를 가상머신처럼 나누지는 않습니다. 이 차이를 놓치면 파일 충돌은 피했는데 실행 충돌이 생깁니다.

개발 서버 포트

두 worktree에서 모두 기본 포트 3000으로 서버를 띄우면 두 번째 서버가 실패할 수 있습니다.

# 첫 번째 worktree
npm run dev -- --port 3001

# 두 번째 worktree
npm run dev -- --port 3002

프로젝트마다 포트 전달 방식은 다르므로 실제 스크립트의 도움말을 먼저 확인합니다.

의존성과 빌드 캐시

node_modules, .venv, 빌드 결과처럼 Git에 추적되지 않는 폴더는 새 worktree에 자동으로 준비되지 않습니다. 각 worktree에서 필요한 설치 명령을 실행하고, 대용량 캐시를 억지로 심볼릭 링크로 공유하기 전에는 도구가 동시 접근을 안전하게 처리하는지 확인해야 합니다.

환경변수와 비밀값

.env가 .gitignore에 들어 있다면 새 worktree에 나타나지 않을 수 있습니다. 필요한 값을 복사할 때는 테스트용 자격증명을 우선하고, 비밀값을 Git에 추가하지 않았는지 확인합니다.

git status --short
git check-ignore -v .env

데이터베이스와 외부 서비스

두 worktree가 같은 로컬 데이터베이스 파일이나 같은 테스트 계정을 바라보면 데이터가 섞일 수 있습니다. DB 파일 경로, 컨테이너 이름, 테스트 스키마, 메시지 전송 대상을 에이전트별로 나눕니다. 특히 메일 발송·배포·결제처럼 되돌리기 어려운 작업은 병렬 세션의 첫 실습으로 적합하지 않습니다.

결과 검토와 병합

worktree에서 커밋했다고 main에 자동으로 합쳐지는 것은 아닙니다. 이번 검증에서도 두 브랜치에 커밋한 뒤 main은 그대로였고, git branch --no-merged main에 두 브랜치가 남았습니다.

각 worktree에서 먼저 변경을 확인합니다.

git status --short
git diff
git diff --check
npm test

커밋 전 변경은 각 worktree 안에서 git diff로 볼 수 있습니다. 아래처럼 main 작업 폴더에서 브랜치 ref를 기준으로 결과를 비교하려면 변경을 먼저 각 브랜치에 커밋합니다. 세 점 diff는 main과 작업 브랜치의 merge-base부터 작업 브랜치 tip까지를 보여 줍니다.

git -C ../my-project-agent-docs add README.md
git -C ../my-project-agent-docs commit -m "docs: add usage example"

git -C ../my-project-agent-tests add app.test.js
git -C ../my-project-agent-tests commit -m "test: cover greet function"

그다음 main 작업 폴더에서 브랜치별 diff를 봅니다.

git diff main...agent/docs
git diff main...agent/tests

팀 저장소라면 각 브랜치를 원격에 올려 Pull Request로 검토하는 편이 안전합니다. 로컬에서 병합하더라도 한 브랜치씩 합치고 매번 테스트를 실행해야 어느 변경에서 문제가 생겼는지 찾기 쉽습니다.

안전한 worktree 정리

이 글처럼 Git 명령으로 직접 만든 작업 폴더는 파일 탐색기나 rm -rf로 먼저 지우지 않습니다. Git이 연결 정보를 함께 정리하도록 git worktree remove를 사용합니다.

git worktree list
git -C ../my-project-agent-docs status --short --untracked-files=all --ignored
git -C ../my-project-agent-docs clean -ndx
git worktree remove ../my-project-agent-docs

수정된 tracked 파일이나 일반 untracked 파일이 남아 있으면 기본 remove가 거부됩니다. 그러나 .gitignore에 걸린 .env, 캐시, 빌드 결과는 거부 사유가 되지 않고 worktree와 함께 삭제될 수 있습니다. 위의 status --ignored와 삭제 미리보기인 git clean -ndx로 ignored 파일까지 확인한 뒤, 남길 파일을 따로 보관하고 제거합니다. 이때 곧바로 --force를 붙이면 안 됩니다.

Claude Code의 --worktree 대화형 세션은 종료할 때 자체 정리 절차를 제공하고, ChatGPT 데스크톱 앱의 Codex 관리 worktree는 앱의 보관·자동 삭제 정책을 따릅니다. 이 절의 명령은 git worktree add로 직접 만든 worktree를 정리할 때 사용합니다.

worktree를 제거해도 브랜치는 자동으로 삭제되지 않습니다. 병합이 끝난 브랜치인지 확인한 뒤 따로 지웁니다.

git branch --merged main
git branch -d agent/docs

폴더를 수동으로 삭제해 목록에 오래된 항목이 남았다면 다음 명령으로 정리 대상을 미리 확인합니다.

git worktree prune --dry-run
git worktree prune

prune --dry-run 결과를 먼저 보는 습관이 안전합니다.

자주 만나는 오류

이미 사용 중인 브랜치

fatal: 'agent/docs' is already used by worktree at '...'

해당 브랜치가 연결된 기존 폴더를 git worktree list로 찾습니다. 새 에이전트에는 다른 브랜치를 만들거나 기존 폴더에서 세션을 이어갑니다.

폴더가 이미 존재함

fatal: '.../my-project-agent-docs' already exists

같은 이름의 폴더가 남아 있는지 확인합니다. 내용이 있는 폴더를 무조건 삭제하지 말고, 이전 작업 결과와 worktree 목록부터 확인하세요.

worktree 제거 거부

fatal: '.../my-project-agent-docs' contains modified or untracked files

해당 폴더에서 git status --short를 실행합니다. 필요한 변경이면 커밋하고, 불필요한 파일이어도 어떤 파일인지 확인한 뒤 정리합니다.

테스트 서버 포트 충돌

address already in use

Git 문제가 아니라 실행 환경 충돌입니다. 각 worktree의 포트와 컨테이너 이름을 다르게 지정합니다.

병렬 작업 체크리스트

정리

Git Worktree는 여러 AI 코딩 에이전트를 무조건 빠르게 만드는 기능은 아닙니다. 대신 각 세션의 작업 폴더와 브랜치를 분리해 변경 주체를 명확하게 만들고, main에 들어오기 전 diff와 테스트를 따로 확인하게 해 줍니다.

처음에는 문서 수정과 테스트 작성처럼 서로 다른 파일을 다루는 작업 두 개로 시작하는 편이 좋습니다. git worktree add로 폴더를 나누고, 각 폴더에서 Claude Code나 Codex를 실행한 뒤, git status --short와 테스트 결과를 비교해 보세요. 파일 격리가 확인되면 그다음에만 더 큰 병렬 작업으로 넓히면 됩니다.

참고 자료

• Git 공식 문서 — git-worktree
• Anthropic 공식 문서 — Claude Code worktrees
• Anthropic 공식 문서 — Claude Code common workflows
• OpenAI 공식 문서 — ChatGPT 데스크톱 앱의 Codex Worktrees
• OpenAI 공식 문서 — Codex CLI 명령과 옵션