Codex Worktree 실전 가이드: 여러 AI 개발 작업을 병렬로 진행해도 리포지토리를 오염시키지 않는 방법

같은 리포지토리에서 세 가지 작업을 동시에 돌리고 있다고 해봅시다. fix/auth-expired-session, test/payment-webhook, docs/setup-node20. main checkout의 git status에는 로그인 bug 수정, 테스트 fixture 파일, README의 Node 20 설명이 한꺼번에 섞입니다. 세 종류의 변경이 하나의 checkout에 들어가면, 어느 부분을 독립적으로 커밋할 수 있는지, 어느 부분이 다른 작업에 영향을 줄지 구분하기 어렵습니다.

이건 추상적인 병렬 작업 문제가 아닙니다. Git checkout이 오염됐을 때 실제로 생기는 결과입니다. Codex app의 Worktree 모드는 서로 다른 작업을 서로 다른 디렉터리와 브랜치로 나눕니다. 각 작업 라인의 diff를 검토하고, 머지하고, 필요하면 되돌릴 수 있게 하기 위해서입니다.

Local / Worktree / Cloud: 세 가지 모드를 어떻게 고를까

Codex app은 세 가지 실행 모드를 지원합니다. Local과 Worktree는 모두 로컬 컴퓨터에서 실행됩니다. 공식 문서도 “Both Local and Worktree threads will run on your computer”라고 명확히 설명합니다. Cloud는 원격 환경에서 실행됩니다.

모드	실행 위치	수정 대상	적합한 상황	위험과 비용
Local	로컬 컴퓨터	main checkout	단일 작업, 안정적인 개발	메인 디렉터리를 직접 수정하므로 미완성 작업이 섞일 수 있음
Worktree	로컬 컴퓨터	독립 디렉터리 + branch	병렬 작업, 새 아이디어 실험	setup scripts와 .worktreeinclude 설정 필요
Cloud	원격	Cloud 환경	CI/CD, 원격 빌드	별도 글에서 다룸

Worktree 모드는 독립 작업을 병렬로 진행하거나 새 아이디어를 시험할 때 적합합니다. 각 thread가 자기 디렉터리와 branch를 가지므로 main checkout은 영향을 받지 않습니다. Local 모드는 단순하지만, 여러 작업이 섞이면 commit을 나누기 어려워집니다. Cloud 모드는 로컬 컴퓨터에서 완전히 벗어나며 CI/CD와 원격 빌드에 맞습니다.

선택 기준은 단순합니다. 단일 작업은 Local, 병렬 작업이나 실험은 Worktree, 원격 작업은 Cloud를 사용합니다.

Codex app의 Worktree 모드 자세히 보기

Worktree 생성과 Handoff

Codex app에서 Worktree thread를 만드는 흐름은 다음과 같습니다.

1. 새 thread를 만듭니다
2. Worktree 모드를 선택합니다(UI 진입 이름은 2026-06-18 이후 바뀔 수 있습니다)
3. 시작 branch를 선택하거나 기본 detached HEAD에서 작업합니다
4. 첫 prompt를 보냅니다
5. Codex가 독립 디렉터리에서 작업을 시작합니다

기본적으로 Codex는 detached HEAD에서 작업합니다. 이렇게 하면 worktree 안에서 계속 작업하다가 결과를 보존해야 할 때 branch를 만들 수 있습니다. Handoff는 Local과 Worktree 사이에서 thread와 코드를 이동하는 기능입니다.

Handoff 시나리오:

Worktree에서 Local로: 작업이 끝난 뒤 아직 detached HEAD라면 먼저 worktree 안에서 branch를 만듭니다. 그다음 Handoff로 Local로 옮기고, 마지막에 merge하거나 PR을 만듭니다.

Local에서 Worktree로: 미완성 작업을 격리 환경으로 옮겨 main checkout 오염을 피하고 싶을 때 사용합니다.

Handoff는 단순한 디렉터리 전환이 아닙니다. 현재 thread context, prompt 이력, 미완성 변경까지 함께 이동합니다.

Codex-managed worktree의 특징

Codex-managed worktrees에는 몇 가지 특수 동작이 있습니다.

기본 위치: $CODEX_HOME/worktrees

기본 보관 개수: 15개(2026-06-18 기준 공식 문서). 초과분은 자동으로 정리될 수 있습니다.

Permanent worktree: 수동으로 만든 worktree는 자동 삭제되지 않습니다.

Branch 제한: Git은 같은 branch가 여러 worktree에서 동시에 checkout되는 것을 허용하지 않습니다. 시도하면 오류가 납니다.

규칙 상속: AGENTS.override.md가 worktree로 자동 복사되어 프로젝트 규칙을 일관되게 유지합니다.

즉, worktree 개수에는 제한이 있고 오래된 항목은 정리될 수 있습니다. 같은 branch는 병렬로 사용할 수 없습니다. 프로젝트 규칙은 자동으로 이어받습니다.

.worktreeinclude로 ignored files 문제 해결하기

Worktree는 기본적으로 Git tracked files만 이어받습니다. .gitignore에 들어간 파일은 Handoff 때 자동으로 이동하지 않습니다. 자주 빠지는 항목은 .env, .env.local, 의존성 캐시, 로컬 설정 파일입니다.

해결 방법은 프로젝트 루트에 .worktreeinclude 파일을 만들고, 복사해야 할 ignored files를 명시하는 것입니다. 예:

.env
.env.local
node_modules/.cache

이렇게 하면 Handoff 때 .gitignore에 있는 파일도 worktree로 복사할 수 있습니다.

Setup scripts: worktree 안에서 프로젝트가 실행되게 만들기

Worktree는 다른 디렉터리에 있기 때문에 의존성이나 check in되지 않은 파일이 빠질 수 있습니다. Setup scripts는 새 worktree나 새 thread가 시작될 때 자동 실행되어 환경을 사용할 수 있게 만듭니다.

설정 단계:

1. Codex app의 Local environments에서 setup steps를 설정합니다
2. 설정 파일을 둘 .codex 디렉터리를 만듭니다
3. 플랫폼별 스크립트를 작성합니다

Node.js 프로젝트 예:

# .codex/setup.sh
npm install
npm run build

Python 프로젝트 예:

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Setup scripts는 새 worktree가 만들어질 때마다 실행됩니다. 의존성을 매번 수동 설치하는 부담을 줄입니다. 다만 설정 UI와 파일 형식은 2026-06-18 이후 바뀔 수 있으므로 현재 공식 문서와 대조해야 합니다.

Codex app 없이도 Plain Git worktree로 격리할 수 있다

CLI나 터미널 중심으로 작업한다면 Git worktree 명령으로 직접 격리 디렉터리를 만들고, 해당 디렉터리에서 Codex를 시작할 수 있습니다. Codex app의 관리 기능은 필요 없지만, 관리는 직접 해야 합니다.

Git Worktree에서 자주 쓰는 명령:

# 공식 use case 스타일로 새 worktree와 branch 만들기
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# 기존 branch 기반으로 새 worktree 만들기
git worktree add ../task-b existing-branch

# 모든 worktrees 나열하기
git worktree list

# worktree 삭제하기
git worktree remove ../task-a

# 오래된 worktree 메타데이터 정리하기
git worktree prune

Codex-managed와 Plain Git 비교:

특성	Codex-managed	Plain Git
생성 방식	App UI에서 자동	git worktree add
위치 관리	$CODEX_HOME/worktrees	수동 지정
정리 정책	기본적으로 15개 자동 보관	수동 prune
Handoff	App 안에서 전환	수동으로 cd 이동
Setup scripts	자동 실행	수동 설정

Plain Git worktree는 CLI를 선호하는 개발자에게 맞습니다. 하지만 의존성 설치, 환경 설정, 정리를 직접 처리해야 합니다. Codex-managed worktree는 이 과정을 더 많이 자동화합니다.

Automations 백그라운드 작업에 worktree가 필요할까

Git 리포지토리의 automation은 local project 또는 dedicated background worktree에서 실행할 수 있습니다. 어떤 방식을 고를지는 작업 유형과 위험 관리에 달려 있습니다.

판단 기준:

Local 모드는 단발성 작업이나 임시 테스트에 적합합니다. main checkout을 직접 수정하므로 미완성 작업이 오염될 수 있습니다. 사용자가 어떤 파일을 편집 중이라면 백그라운드 automation이 같은 파일을 직접 수정할 수도 있습니다.

Worktree 모드는 반복 작업이나 정기 작업에 적합합니다. automation changes와 unfinished local work를 분리합니다. automation은 독립 디렉터리에서 실행되고 main checkout에 영향을 주지 않습니다.

위험 참고:

Automations는 default sandbox settings를 사용합니다(2026-06-18 이후 바뀔 수 있습니다).

Full access 권한에서는 백그라운드 automation 위험이 더 커지므로 worktree를 사용하는 편이 좋습니다.

반복 실행되는 백그라운드 작업을 Local에서 직접 돌리지 마세요.

원칙은 이렇습니다. 단발성 임시 작업은 Local도 괜찮습니다. 반복 작업과 full access 백그라운드 작업은 Worktree로 보내는 편이 안전합니다.

병렬에 맞는 작업과 반드시 순차로 해야 하는 작업

공식 use case는 서로 다른 탐색을 별도 worktree로 나누라고 권장합니다. 실제 운영에서는 작업 사이의 파일 충돌과 의존 관계를 판단해야 합니다.

작업 병렬 전략 판단표:

작업 유형	병렬 가능성	이유	권장
독립 파일 수정(다른 모듈)	병렬에 적합	파일 충돌 위험이 낮음	여러 worktree를 동시에 열기
새 기능 개발(독립 컴포넌트)	병렬에 적합	모듈 경계가 명확함	컴포넌트마다 worktree 하나
같은 파일의 여러 변경	반드시 순차 진행	머지 때 충돌 발생	우선순위에 따라 하나씩 완료
의존 관계가 있는 작업	반드시 순차 진행	앞 작업이 뒤 작업의 입력	선행 작업 완료 후 시작
문서 업데이트	병렬에 적합	보통 독립 파일을 수정	다른 작업과 병렬 가능

병렬 원칙:

서로 의존하지 않는 작은 작업 2개부터 시작합니다. 처음부터 5~6개를 열지 않습니다.

작업 수는 3~4개 안팎으로 제한합니다. 리뷰 비용을 낮추기 위해서입니다.

각 작업에는 명확한 검증 기준이 있어야 합니다.

과도한 병렬은 권장하지 않습니다. 병렬 작업이 많아질수록 리뷰 비용과 merge conflict 위험이 함께 올라갑니다.

작업 카드 템플릿: 각 worktree가 무엇을 할지 명확히 쓰기

각 worktree를 시작하기 전에 작업 설명을 명확히 작성하면 검증과 추적이 쉬워집니다.

작업 카드 예시:

Goal: "auth 모듈의 session expired bug 수정"
Context:
  - "사용자 session은 30분 후 만료되지만 프론트엔드에 안내가 표시되지 않음"
  - "관련 파일: src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "데이터베이스 schema를 변경하지 않음"
  - "새 의존성을 추가하지 않음"
Done when:
  - "session 만료 시 프론트엔드가 안내를 표시함"
  - "npm test 통과"
  - "로그인 플로우 수동 테스트"

Branch/Worktree: "fix/auth-expired-session"
검증 명령: "npm test && npm run lint"

작성 포인트:

Goal: 목표를 한 문장으로 설명합니다

Context: 파일, 모듈, 배경을 제공합니다

Constraints: 변경하지 않을 항목을 포함해 경계를 명확히 합니다

Done when: 검증 가능한 완료 기준을 적습니다

Branch/Worktree: task-type/module-description처럼 명확하게 이름을 붙입니다

검증 명령: 실제 실행 가능한 명령을 적습니다

이렇게 하면 각 worktree의 경계가 분명해집니다. 검토할 때 Done when과 결과를 대조하면 됩니다.

머지 큐: 하나씩 review, test, merge 하기

병렬 작업이 끝난 뒤 결과를 한꺼번에 main에 밀어 넣지 마세요. 위험도에 따라 정렬한 뒤 하나씩 review, test, merge하는 편이 좋습니다.

머지 큐 단계:

1. worktree를 위험도 순으로 정렬합니다(가장 낮은 위험부터)
2. 첫 번째 worktree에서:
   • 검증 명령을 실행합니다(테스트, lint)
   • diff를 확인하고 변경 범위를 검토합니다
   • 아직 detached HEAD라면 branch를 만듭니다
   • PR review 기준에 따라 diff를 리뷰합니다
3. Local로 머지하거나 PR을 만듭니다:
   • Local merge: Handoff로 Local로 돌아온 뒤 merge
   • PR merge: PR을 만들고 CI와 review를 기다림
4. 다음 worktree에서도 같은 단계를 반복합니다
5. 모든 작업이 끝나면 main branch로 머지합니다

검증 체크리스트:

검증 명령 통과(테스트, lint)

Diff 확인: 변경 범위가 기대와 일치

Review guidelines: 민감 파일이나 hard-coded secrets 없음

CI 통과(있는 경우)

수동 테스트 플로우

위험 참고:

여러 worktree 결과가 자동으로 머지된다고 가정하지 않습니다

같은 파일을 여러 작업이 수정했다면 충돌은 수동으로 해결합니다

항상 사람의 review와 테스트를 남깁니다

머지 큐의 핵심은 각 작업 라인의 diff를 검토 가능하고 되돌릴 수 있게 만드는 것입니다. 모든 변경을 한 번에 제출하는 것이 아닙니다.

트러블슈팅 체크리스트

"branch already used by worktree" 오류

원인: branch가 다른 worktree에서 사용 중입니다.

해결 방법:

git worktree list로 어떤 branch가 점유되어 있는지 확인합니다.

다른 branch를 선택하거나 해당 branch를 사용하는 worktree를 삭제합니다.

worktree 안에서 코드가 실행되지 않음

원인: 의존성 또는 설정 파일이 없습니다.

확인 단계:

.env, .env.local이 있는지 확인합니다. 복사되지 않았을 수 있습니다.

node_modules, venv 같은 의존성이 설치되어 있는지 확인합니다.

설정 파일이 완전한지 확인합니다.

해결 방법:

.worktreeinclude를 설정해 ignored files를 복사합니다.

Setup scripts를 설정해 의존성을 자동 설치합니다.

worktree 디스크 사용량이 커짐

원인: automations가 자주 실행되며 많은 worktrees를 만듭니다.

해결 방법:

더 이상 필요 없는 automation runs를 archive합니다.

수동으로 git worktree prune을 실행해 오래된 worktree를 정리합니다.

Codex app 설정의 worktree 보관 정책을 확인합니다(2026-06-18 이후 바뀔 수 있습니다).

agent가 만든 worktree와 UI/thread context가 맞지 않음

원인: agent가 자동으로 worktree를 만들면 App UI를 우회할 수 있습니다.

해결 방법:

git worktree list로 모든 worktrees를 확인합니다.

App 안에서 thread와 worktree 연결을 수동 확인합니다.

agent에게 worktree를 자동 생성하게 하지 말고 App UI에서 직접 만듭니다.

트러블슈팅의 핵심은 먼저 git worktree list로 worktree 상태를 확인한 뒤 오류 유형에 따라 처리하는 것입니다.

비용 판단: 병렬 작업은 quota를 더 빨리 소모하기 쉽다

병렬 작업은 더 많은 turns 또는 quota를 소모하기 쉽습니다. 각 worktree는 독립 session이고, Codex는 각 session을 별도로 계산합니다.

비용 판단:

병렬 작업 수는 3~4개 정도로 제한합니다.

리뷰 비용을 낮추기 위해 서로 독립적인 작은 작업 2개부터 시작합니다.

무제한 반복을 피하려면 각 작업에 명확한 검증 기준을 둡니다.

구체적인 가격, quota, plan 정보는 이후 Cost & Quota 관리 글에서 다루는 편이 좋습니다. 여기서는 검증하지 않은 숫자를 적지 않습니다.

다음 단계와 이어서 읽을 글

상위 글:

Codex 진입점 선택: Local / Worktree / Cloud 모드 간단 소개

AGENTS.md 프로젝트 규칙: 각 worktree가 같은 규칙을 어떻게 상속하는지