OpenAI Codex 완전가이드 3편 — Git Worktree 병렬 에이전트: 기능 3개 동시 구현, 충돌 없이 머지까지

같은 폴더에서 두 Codex 세션을 동시에 돌리면 어떻게 될까요? 한 세션이 수정한 파일을 다른 세션이 덮어쓰면서 충돌이 납니다. 이게 Git Worktree를 써야 하는 이유입니다. Worktree는 같은 레포에서 브랜치마다 별도 폴더를 만들어 에이전트들이 서로 건드리지 않고 병렬로 작업하게 합니다. Codex의 가장 강력한 차별점이고, 혼자 쓰는 개발자도 생산성이 2~3배 달라집니다.

---

핵심 요약

Git Worktree는 같은 .git 히스토리를 공유하면서 각기 다른 폴더와 브랜치로 체크아웃하는 기능입니다. 병렬 작업의 핵심 원칙은 파일이 겹치지 않는 작업끼리만 동시에 진행하는 것이며, 겹치면 반드시 충돌이 발생합니다.

Codex CLI에서는 Worktree를 수동으로 만들고 각 폴더에서 터미널을 실행합니다. Codex App은 UI에서 Thread 생성 시 Worktree를 자동으로 관리해줍니다(4편 상세). 기본 패턴은 기능 A 폴더, 기능 B 폴더, main 폴더(머지 허브) 3개로 구성하며, 머지 전략은 Rebase Before PR이 충돌이 가장 적습니다. 충돌 예방을 위해 같은 파일은 두 Worktree에서 절대 동시 수정하지 않고, package.json과 config 파일은 main에서만 수정하며, AGENTS.md에 Worktree별 수정 허용 경로를 명시해두는 것이 핵심입니다. clash 툴(github.com/clash-sh/clash)로 충돌을 조기 감지할 수 있으며, 작업 전에는 항상 git commit으로 롤백 기준점을 만들어두세요.

---

실전 1 — Git Worktree가 뭔지 정확히

일반 git clone 방식에서는 한 번에 브랜치 하나만 체크아웃됩니다. 다른 브랜치 작업이 필요하면 git stash로 현재 작업을 임시 저장하고 브랜치를 전환해야 하며, 그 순간 파일 전체 상태가 바뀝니다. 에이전트를 병렬로 돌리기에는 구조적으로 맞지 않습니다.

Worktree 방식은 같은 .git 히스토리를 공유하면서 브랜치마다 완전히 독립된 폴더를 만드는 구조입니다.

# 일반 방식: 브랜치 하나만 체크아웃
my-project/
  .git/
  src/

# Worktree 방식: 브랜치마다 독립 폴더
my-project/           ← main 브랜치
  .git/               ← 히스토리 공유 (한 군데)
  src/

my-project-login/     ← feature/login 브랜치 (별도 폴더)
  .git                ← 포인터 파일 (폴더 아님)
  src/                ← 완전히 독립된 파일 상태

my-project-dashboard/ ← feature/dashboard 브랜치
  .git
  src/

핵심 포인트는 세 가지입니다. 파일이 별도 폴더에 분리되어 있어 에이전트끼리 충돌이 없고, 히스토리는 공유하기 때문에 불필요한 용량 낭비가 없으며, 여러 브랜치를 동시에 체크아웃한 상태로 유지할 수 있어 기능 3개를 진짜 동시에 진행할 수 있습니다.

---

실전 2 — 사전 체크: Git 버전 확인

Worktree는 Git 2.5에서 도입된 기능입니다. 시작 전에 버전을 확인하고, 낮으면 업데이트해야 합니다.

# Git 2.5 이상 필요
git --version
# git version 2.43.x 이상이면 OK

# macOS 업데이트
brew upgrade git

# Ubuntu/Debian 업데이트
sudo apt update && sudo apt install git

버전 확인 후 2.43.x 이상이면 아래 실전 단계로 바로 넘어가면 됩니다. 2.5 미만이라면 업데이트 후 git --version으로 재확인하세요.

---

실전 3 — 기본 Worktree 명령어

Worktree의 생성·조회·삭제 세 가지 명령어를 알면 충분합니다. 자주 쓰는 패턴 위주로 정리했습니다.

Worktree 생성

기존 브랜치를 새 폴더로 체크아웃하거나, -b 플래그로 새 브랜치를 만들면서 동시에 Worktree를 생성할 수 있습니다.

# 기본 문법
git worktree add <새폴더경로> <브랜치명>

# 기존 브랜치 체크아웃
git worktree add ../my-project-login feature/login

# 새 브랜치 만들면서 Worktree 생성 (-b)
git worktree add -b feature/dashboard ../my-project-dashboard main
#                                                              ↑ main에서 분기

Worktree 목록 확인

현재 활성화된 Worktree 전체를 한 번에 볼 수 있습니다. 폴더 경로, 커밋 해시, 브랜치명이 함께 표시됩니다.

git worktree list

# 출력 예시:
# /Users/cell/my-project           abc1234 [main]
# /Users/cell/my-project-login     def5678 [feature/login]
# /Users/cell/my-project-dashboard ghi9012 [feature/dashboard]

Worktree 삭제

작업이 완료되면 Worktree를 삭제하고, prune으로 남은 레퍼런스도 정리합니다.

# 정상 삭제
git worktree remove ../my-project-login

# 강제 삭제 (수정사항 있어도)
git worktree remove --force ../my-project-login

# 이미 삭제된 폴더의 레퍼런스 정리
git worktree prune

---

실전 4 — 3개 병렬 에이전트 실전 플로우

Node.js API에 독립적인 기능 3개를 동시에 추가하는 시나리오입니다. 인증 API, 상품 목록 API, 기존 테스트 업데이트가 각각 다른 파일을 건드리기 때문에 병렬 실행이 가능합니다.

Step 1. 시작 전 상태 정리

병렬 작업 전에 반드시 현재 상태를 깨끗하게 커밋해두어야 합니다. 나중에 문제가 생겼을 때 롤백할 기준점이 됩니다.

cd ~/projects/my-api

git status
# → "nothing to commit" 이어야 함

git add -A && git commit -m "before parallel work: stable state"
git pull origin main

Step 2. Worktree 3개 생성

각 기능마다 main에서 분기한 별도 브랜치와 폴더를 만듭니다. 모두 같은 main 커밋 상태에서 시작하기 때문에 초기 코드베이스가 동일합니다.

git worktree add -b feature/auth     ../my-api-auth     main
git worktree add -b feature/products ../my-api-products main
git worktree add -b feature/tests    ../my-api-tests    main

git worktree list
# /Users/cell/my-api           (main)
# /Users/cell/my-api-auth      (feature/auth)
# /Users/cell/my-api-products  (feature/products)
# /Users/cell/my-api-tests     (feature/tests)

Step 3. 각 폴더에서 Codex 실행

터미널 3개를 열고 각 Worktree 폴더에서 Codex를 실행합니다. 세 세션이 완전히 독립된 폴더에서 동시에 돌기 때문에 파일 충돌이 발생하지 않습니다.

# 터미널 1: 인증 기능
cd ~/projects/my-api-auth
codex -a auto-edit "JWT 기반 로그인/로그아웃 API 구현해줘.
POST /auth/login, POST /auth/logout
bcrypt 비밀번호 해싱, 토큰 만료 24시간
에러 처리 포함, Jest 테스트도 작성해줘"

# 터미널 2: 상품 기능
cd ~/projects/my-api-products
codex -a auto-edit "상품 목록 API 구현해줘.
GET /products (페이지네이션: page, limit)
GET /products/:id
응답 형식: { data, total, page, totalPages }
Jest 테스트 포함"

# 터미널 3: 테스트 업데이트
cd ~/projects/my-api-tests
codex -a auto-edit "기존 테스트 파일 전체 검토해서
실패하는 테스트 수정하고 커버리지 80% 이상으로 올려줘"

Step 4. 진행 상황 모니터링

세션이 돌아가는 동안 메인 터미널에서 전체 상태를 모니터링할 수 있습니다. watch 명령으로 5초마다 자동 갱신해두면 각 브랜치 커밋 현황을 실시간으로 확인할 수 있습니다.

watch -n 5 'git worktree list && echo "---" && git log --oneline --all --graph | head -20'

# 개별 브랜치 커밋 현황
git log --oneline feature/auth | head -5
git log --oneline feature/products | head -5
git log --oneline feature/tests | head -5

Step 5. 완료된 것부터 diff 검토

각 세션이 완료되면 변경사항을 검토하고 테스트를 통과시킨 뒤 머지 단계로 넘어갑니다.

cd ~/projects/my-api-auth

git diff main..feature/auth            # 전체 변경사항 확인
git diff main..feature/auth --name-only  # 변경 파일 목록만 확인

npm test  # 테스트 통과 확인 후 다음 단계 진행

---

실전 5 — 머지 전략: Rebase Before PR (권장)

병렬 작업 후 머지할 때 Rebase Before PR 패턴이 충돌이 가장 적습니다. 각 브랜치를 최신 main 위로 재정렬한 뒤 PR을 올리는 방식입니다.

cd ~/projects/my-api-auth

# 최신 main 반영
git fetch origin
git rebase origin/main
# 충돌 시: 수동 해결 → git add → git rebase --continue

npm test  # 테스트 통과 확인

# GitHub CLI로 PR 생성
gh pr create \
  --title "feat: JWT 인증 API 추가" \
  --body "로그인/로그아웃 API, bcrypt 해싱, JWT 토큰 발급" \
  --base main

PR 대신 직접 머지할 경우에는 하나씩 순서대로 진행해야 합니다. 한 번에 다 머지하면 충돌이 복잡해지기 때문에, 머지할 때마다 테스트를 통과시키면서 하나씩 진행하는 것이 안전합니다.

cd ~/projects/my-api

git merge --no-ff feature/auth
npm test  # 통과 확인

git merge --no-ff feature/products
npm test  # 통과 확인

git merge --no-ff feature/tests
npm test  # 최종 통과 확인

전체 테스트가 통과하면 Worktree와 브랜치를 정리합니다. prune까지 실행해야 레퍼런스가 깔끔하게 정리됩니다.

git worktree remove ../my-api-auth
git worktree remove ../my-api-products
git worktree remove ../my-api-tests

git branch -d feature/auth feature/products feature/tests
git worktree prune

git worktree list
# /Users/cell/my-api  (main) 만 남아야 함

---

실전 6 — 충돌 예방 3가지 규칙

병렬 개발에서 가장 큰 위험은 두 에이전트가 같은 파일을 동시에 수정하는 것입니다. 시작 전 10분을 투자해 파일 겹침을 체크하면 수시간의 충돌 해결을 막을 수 있습니다.

규칙 1: 작업 전 파일 겹침 체크

각 기능이 건드릴 파일 목록을 미리 작성하고 교집합을 확인합니다. 교집합이 있으면 해당 작업은 순차 실행하거나 역할을 재분배해야 합니다.

기능 A (인증): src/auth/*, tests/auth/*        ← 겹침 없음 ✅
기능 B (상품): src/products/*, tests/products/*
기능 C (공통 미들웨어): src/middleware/*        ← A, B 둘 다 쓸 수 있음 ⚠️

→ 기능 C는 A, B 완료 후 순차 실행

규칙 2: 공유 파일은 main에서만 수정

package.json, package-lock.json, tsconfig.json, .eslintrc, .env, 모든 에이전트가 공통으로 import하는 유틸 파일은 Worktree에서 절대 수정하면 안 됩니다. 이런 파일 수정이 필요하면 main에서 수정하고 커밋한 뒤, 각 Worktree에서 rebase로 반영하는 순서를 지켜야 합니다.

규칙 3: AGENTS.md에 수정 허용 경로 명시

각 Worktree 폴더에 AGENTS.md를 만들어 수정 가능한 경로와 수정 금지 경로를 명시해두면 에이전트가 경계를 넘지 않습니다. 아래는 인증 기능 Worktree용 예시입니다.

cat > ~/projects/my-api-auth/AGENTS.md << 'EOF'
# 인증 기능 Worktree 규칙

## 수정 가능한 경로
- src/auth/
- src/middleware/auth.ts
- tests/auth/

## 수정 절대 금지
- package.json (main에서만 수정)
- src/products/ (다른 Worktree 담당)
- .env

## 작업 완료 기준
- npm test 통과
- src/auth/ 함수 전부 타입 힌트 있음
- auth 관련 테스트 커버리지 80% 이상
EOF

이 파일은 에이전트가 세션 시작 시 자동으로 읽습니다. 역할 범위를 코드로 명시해두는 것만으로 많은 충돌을 예방할 수 있습니다.

---

실전 7 — 충돌 조기 감지: clash 툴

clash는 여러 Worktree 간 머지 충돌을 미리 감지하는 오픈소스 CLI 툴입니다. 에이전트가 파일을 쓰기 전에 자동으로 충돌 체크를 실행해서, 실제 머지 전에 문제를 발견할 수 있습니다.

# 설치
npm install -g @clash-sh/clash

# 현재 Worktree들 간 충돌 확인
cd ~/projects/my-api
clash check

실행 결과는 Worktree 쌍별로 충돌 여부를 보여줍니다. 충돌이 감지된 쌍은 상세 diff로 어떤 줄이 겹치는지 확인할 수 있어, 미리 역할을 재분배할 수 있습니다.

# 충돌 상세 확인
clash diff feature/auth feature/tests
# → 충돌하는 줄 표시 → 역할 재분배 결정 가능

---

실전 8 — 자주 겪는 문제 해결

문제 1: "branch is already checked out" 오류

해당 브랜치가 이미 다른 Worktree에서 사용 중일 때 발생합니다. 다른 브랜치명을 사용하거나, 기존 Worktree를 삭제 후 재생성하면 됩니다.

# 다른 브랜치명 사용
git worktree add -b feature/login-v2 ../my-project-login2 main

# 또는 기존 Worktree 삭제 후 재생성
git worktree remove ../my-project-login
git worktree add ../my-project-login feature/login

문제 2: Worktree에서 node_modules 없음

각 Worktree는 독립 폴더이기 때문에 node_modules를 별도로 설치해야 합니다. Worktree 생성 직후에 npm install을 실행하는 습관을 들이는 것이 좋습니다.

cd ../my-project-login
npm install

문제 3: rebase 도중 충돌

rebase 중 충돌이 발생하면 git status로 충돌 파일을 확인하고 수동으로 해결한 뒤 git rebase --continue로 진행합니다. 해결이 복잡하다면 git rebase --abort로 rebase 전 상태로 돌아갈 수 있습니다.

git rebase origin/main

# 충돌 발생 시
git status                              # 충돌 파일 확인
# 파일 편집해서 충돌 해결
git add src/utils/validator.ts
git rebase --continue

# 포기하고 원상복구
git rebase --abort

문제 4: Worktree 폴더 실수로 삭제

폴더가 삭제되어도 git 레퍼런스는 남아있습니다. git worktree prune으로 정리하고, 필요하면 같은 브랜치로 Worktree를 다시 생성하면 됩니다.

git worktree list
# /Users/cell/my-project-login  (deleted)

git worktree prune
git worktree add ../my-project-login feature/login  # 재생성

---

실전 9 — 혼자 쓰는 개발자를 위한 실용 패턴

패턴 A: 핫픽스 + 기능 동시 작업

기능 개발 중에 버그 수정 요청이 들어오는 상황에 가장 효과적인 패턴입니다. 기존에는 git stash로 현재 작업을 임시 저장하고 브랜치를 전환해야 했는데, Worktree를 쓰면 기능 개발 세션을 그대로 두고 별도 폴더에서 버그만 수정할 수 있습니다.

# 버그 수정 요청이 왔을 때 (터미널 2에서)
git worktree add -b hotfix/login-null ../my-app-hotfix main
cd ../my-app-hotfix
codex -a auto-edit "login() 함수에서 user가 null일 때 크래시 수정해줘"

# 버그 수정 완료 → 머지 → Worktree 삭제
cd ~/projects/my-app
git merge --no-ff hotfix/login-null
git worktree remove ../my-app-hotfix

# 터미널 1의 기능 개발 세션은 아무 영향 없이 그대로 진행 중

패턴 B: 실험적 리팩토링

리팩토링이 잘 될지 모르는 상황에서 안전하게 실험할 수 있는 패턴입니다. 결과가 마음에 들면 머지하고, 마음에 들지 않으면 Worktree를 삭제하면 main에 아무 영향이 없습니다.

git worktree add -b experiment/refactor-auth ../my-app-exp main
cd ../my-app-exp

codex -a full-auto "인증 모듈 전체를 클래스 기반에서 함수형으로 리팩토링해줘.
테스트 다 통과하면 성공, 아니면 원인 알려줘"

# 결과 별로면 → 흔적 없이 삭제
git worktree remove --force ../my-app-exp
git branch -D experiment/refactor-auth

패턴 C: A/B 구현 비교

같은 기능을 두 가지 방법으로 동시에 구현해서 비교하는 패턴입니다. REST vs GraphQL처럼 선택이 어려운 경우에 실제로 둘 다 만들어보고 git diff로 비교한 뒤 더 나은 쪽을 머지합니다.

git worktree add -b approach/rest-api ../my-app-rest main
git worktree add -b approach/graphql  ../my-app-graphql main

# 터미널 1·2에서 동시에 Codex 실행 후
git diff approach/rest-api approach/graphql  # 비교

# 마음에 드는 쪽 머지
git merge --no-ff approach/rest-api
git worktree remove ../my-app-rest
git worktree remove ../my-app-graphql

---

실전 10 — 유용한 셸 함수

자주 쓰는 Worktree 패턴을 셸 함수로 만들어두면 매번 긴 명령어를 입력할 필요가 없습니다. ~/.zshrc 또는 ~/.bashrc에 추가하면 됩니다.

# Worktree 생성 + 이동 + Codex 실행 한 번에
function codex-new() {
  local branch=$1
  local task=$2
  local worktree_path="../$(basename $(pwd))-${branch//\//-}"
  
  git worktree add -b "$branch" "$worktree_path" main
  cd "$worktree_path"
  
  if [ -n "$task" ]; then
    codex -a auto-edit "$task"
  else
    codex
  fi
}
# 사용: codex-new feature/auth "JWT 인증 API 구현해줘"

# Worktree 전체 상태 한눈에 보기
function wt-status() {
  git worktree list
  echo ""
  git log --oneline --all --graph | head -20
}

# 완료된 Worktree 머지 + 삭제 한 번에
function wt-done() {
  local branch=$1
  local worktree_path="../$(basename $(pwd))-${branch//\//-}"
  
  cd $(git rev-parse --show-toplevel)
  git merge --no-ff "$branch"
  git worktree remove "$worktree_path"
  git branch -d "$branch"
  git worktree prune
  echo "Done: $branch merged and cleaned up"
}
# 사용: wt-done feature/auth

추가 후 source ~/.zshrc로 적용하면 바로 사용할 수 있습니다.

---

마무리

Worktree는 에이전트 간 파일 충돌 문제를 구조적으로 해결합니다. Git에 내장되어 있어 별도 설치가 필요 없고, 설정은 5분이면 충분합니다. 가장 중요한 원칙은 하나입니다 — 병렬 작업은 파일이 겹치지 않는 작업끼리만. 이 원칙을 지키는 것만으로 대부분의 충돌을 예방할 수 있습니다. 에이전트를 동시에 두 개 이상 쓰면서 Worktree를 쓰지 않고 있다면, 5분 설정 투자로 수시간의 충돌 디버깅을 막을 수 있습니다.

4편에서는 Codex App(데스크탑 UI)과 Codex Cloud를 다룹니다. CLI에서 수동으로 관리하는 것과 달리 App에서는 UI 클릭 몇 번으로 Worktree가 처리되고, MCP 연동으로 GitHub, DB 등 외부 도구를 Codex에 연결하는 방법까지 정리합니다.

---

관련 글

• OpenAI Codex 완전가이드 1편 — 설치부터 첫 실행까지
• OpenAI Codex 완전가이드 2편 — 승인 모드, 샌드박스, AGENTS.md
• OpenAI Codex 완전가이드 4편 — Codex App, Cloud, MCP 연동
• OpenAI Codex 완전가이드 5편 — 가격, CI/CD 자동화, Claude Code vs Codex 최종 비교