Worktree로 병렬 스레드 운영

한 줄 요약

이 페이지에서 배우는 것

Worktree가 무엇인지 쉬운 비유로 이해하기
Worktree가 왜 필요한지 실제 상황으로 알아보기
Local Checkout과 Worktree의 관계 파악하기
Handoff 개념 이해하기 (작업 결과를 원본에 반영하는 방법)
실전 시나리오로 Worktree 사용법 익히기
Local과 Worktree 비교표로 차이점 정리하기
자주 묻는 질문(FAQ)으로 궁금증 해결하기
생산성 향상 팁 배우기

Worktree가 뭔가요?

쉬운 비유로 이해하기

여러분이 중요한 보고서 폴더를 가지고 있다고 상상해 보세요.

이 보고서를 대폭 수정하고 싶지만, 혹시 망칠까 봐 걱정됩니다. 이때 어떻게 하시나요? 보통은 폴더 전체를 복사해서 "보고서_실험용" 같은 이름으로 만들죠.

복사본에서는 마음껏 실험할 수 있습니다. 내용을 바꿔보고, 구조를 뒤집어 보고, 새로운 시도를 해봅니다. 이 과정에서 원본 폴더는 전혀 영향을 받지 않습니다.

실험이 성공하면? 복사본의 내용을 원본에 반영(합치기)하면 됩니다.
실험이 실패하면? 복사본을 그냥 삭제하면 끝입니다. 원본은 안전합니다.

Worktree가 바로 이 "복사본 폴더"입니다.

Codex app에서 Worktree를 만들면, 현재 프로젝트의 독립적인 복사본이 생깁니다. AI(Codex)가 이 복사본에서 작업하는 동안, 여러분의 원본 프로젝트는 그대로 유지됩니다. 작업이 끝나면 결과를 원본에 합칠 수도 있고, 마음에 안 들면 버릴 수도 있습니다.

왜 Worktree가 필요한가요?

시나리오 1: 급한 버그 수정

로그인 페이지의 새 디자인을 열심히 만들고 있는데, 갑자기 팀장님이 "결제 페이지에 심각한 버그가 있어! 지금 바로 고쳐야 해!"라고 합니다.

Worktree 없이: 지금 하던 작업을 임시 저장(stash)하거나, 커밋하지 않은 변경사항을 어떻게든 정리한 뒤 브랜치를 바꿔야 합니다. 실수로 작업이 섞이거나 날아갈 수 있습니다.

Worktree 사용: 새 Worktree를 만들어서 Codex에게 "결제 버그 수정해줘"라고 요청합니다. Codex가 Worktree에서 버그를 수정하는 동안, 여러분은 원래 하던 로그인 페이지 작업을 계속할 수 있습니다. 둘 다 동시에 진행됩니다!

시나리오 2: AI에게 실험적 리팩터링 맡기기

코드가 점점 복잡해져서 구조를 개선(리팩터링)하고 싶습니다. 하지만 AI가 코드를 크게 바꾸다가 현재 작업을 망가뜨릴까 걱정됩니다.

Worktree 없이: AI가 현재 프로젝트에서 직접 코드를 수정합니다. 만약 결과가 마음에 안 들면, 되돌리기가 복잡합니다.

Worktree 사용: Worktree를 만들고 Codex에게 "이 모듈을 리팩터링해줘"라고 요청합니다. AI가 복사본에서 마음껏 코드를 바꿉니다. 결과가 좋으면 원본에 합치고, 아니면 Worktree를 삭제하면 됩니다. 원본은 처음부터 끝까지 안전합니다.

Local Checkout vs Worktree 관계도

Architecture - Repository 구조

Repository (Git)

Local Checkout

사용자 기본 작업 영역
(여러분이 직접 코딩하는 곳)

Worktree

Codex 병렬 체크아웃
(AI가 독립적으로 작업하는 복사본)

Handoff로 양방향 이동 가능

그림 쉽게 이해하기:

- Repository(Git): 프로젝트의 전체 역사와 코드가 저장된 곳입니다. 하나의 "금고"라고 생각하세요.
- Local Checkout: 금고에서 꺼낸 "원본 서류"입니다. 여러분이 평소에 작업하는 곳이에요.
- Worktree: 금고에서 꺼낸 "복사본 서류"입니다. AI(Codex)가 이 복사본에서 별도로 작업합니다.
- 두 서류는 같은 금고에서 나왔지만, 서로 독립적입니다. 한쪽을 바꿔도 다른 쪽에 영향이 없습니다.
- Handoff를 사용하면 복사본의 작업 결과를 원본으로 옮기거나, 반대로 원본 상태를 복사본으로 보낼 수 있습니다.

Handoff란?

Handoff = 작업 결과를 건네주는 것

Handoff는 "인수인계"라는 뜻입니다. Worktree에서 작업한 결과를 Local(원본)로 옮기거나, 반대로 Local의 상태를 Worktree로 가져오는 것을 말합니다.

비유: 복사본 폴더에서 실험이 성공했을 때, 그 결과물을 원본 폴더에 붙여넣는 과정이 바로 Handoff입니다.

어떻게 사용하나요?
- Codex app에서 Worktree 스레드의 작업이 완료되면, "Handoff" 버튼이나 옵션을 통해 결과를 Local로 보낼 수 있습니다.
- 반대로, Local에서 진행하던 작업을 Worktree로 넘겨서 AI에게 이어서 작업하도록 할 수도 있습니다.
- Handoff는 단순히 파일을 복사하는 것이 아니라, Git 브랜치를 기반으로 변경 사항을 안전하게 이동시킵니다.

Handoff에서 자주 부딪히는 두 가지 함정 (공식 문서 안내)

1. .gitignore에 등록된 파일은 따라오지 않습니다. 예: .env, node_modules/, 빌드 산출물. 새 worktree에서 의존성이 없거나 환경변수가 비어 있다면 이 때문입니다 — Local 쪽에서 다시 설치/복사하세요.
2. 나중에 다시 같은 worktree로 handoff하면 동일한 background environment로 돌아갑니다. Codex는 어떤 worktree에 어떤 스레드가 있었는지 기억하므로, "다른 worktree로 가서 다른 환경으로 시작"하고 싶다면 명시적으로 새 worktree를 선택해야 합니다.

실전 시나리오: Worktree 사용하기

아래는 Worktree를 처음부터 끝까지 사용하는 전체 과정입니다. 한 단계씩 따라해 보세요.

새 스레드 생성

Codex app에서 새로운 스레드(대화창)를 엽니다. 스레드를 만들 때 환경 설정 옵션이 나타납니다.

Worktree 환경 선택

환경 설정에서 "Worktree"를 선택합니다. 이렇게 하면 Codex가 원본이 아닌 별도 복사본에서 작업하게 됩니다.

시작 브랜치 선택

어떤 브랜치를 기반으로 복사본을 만들지 선택합니다. 보통은 main 또는 현재 작업 중인 브랜치를 선택합니다. 예: "main 브랜치에서 시작"을 선택하면 main의 최신 코드를 복사해서 작업합니다.

작업 요청

Codex에게 할 일을 알려줍니다. 예: "로그인 API의 에러 처리를 개선해줘" 또는 "이 컴포넌트를 TypeScript로 변환해줘". Codex는 Worktree(복사본)에서 작업하므로 원본은 안전합니다.

결과 확인

Codex가 작업을 마치면 변경된 파일 목록과 diff(수정 내역)를 확인할 수 있습니다. 코드를 리뷰하고, 테스트가 통과하는지 확인하세요.

Handoff로 메인에 반영

결과가 마음에 들면 Handoff를 통해 Worktree의 변경 사항을 Local(원본)로 가져옵니다. 마음에 안 들면 Worktree를 그냥 삭제하면 됩니다. 원본에는 아무 영향이 없습니다.

Local Checkout vs Worktree 비교

항목	Local Checkout	Worktree
동작 범위	사용자가 만든 기본 저장소 예: 내 컴퓨터의 ~/projects/my-app 폴더	Codex가 파생한 별도 체크아웃 예: 자동 생성된 ~/projects/my-app-worktree 폴더
안전성	직접 수정 - 충돌 가능 예: AI가 내가 편집 중인 파일을 동시에 수정하면 충돌 발생	격리된 환경 - 메인 브랜치 보호 예: AI가 뭘 하든 내 작업 파일은 그대로
사용 사례	현재 브랜치에서 즉시 작업 예: 간단한 오타 수정, 작은 스타일 변경	병렬 기능 개발, 리팩터링, 조사 예: 새 기능 개발, 코드 구조 개선, 기술 조사
병렬 작업	제한적 한 번에 하나의 작업만 가능	독립적 병렬 실행 여러 Worktree에서 동시에 여러 작업 가능
Handoff	해당 없음 이미 원본이므로 이동 불필요	Local과 Worktree 간 이동 가능 결과를 원본으로 안전하게 옮기기
실패 시 복구	Git revert 등 수동 복구 필요 예: 잘못된 커밋을 되돌리는 작업이 필요	Worktree 삭제로 간단히 해결 예: 폴더 삭제하면 끝, 원본은 무사

Worktree 장점

격리성 메인 브랜치와 완전히 분리된 작업 환경. 실험이 실패해도 원본은 안전합니다.

병렬성 여러 태스크를 동시에 독립 실행. 버그 수정과 새 기능 개발을 동시에!

안전성 로컬 작업을 건드리지 않는 비파괴 작업. 내 코드에 손대지 않습니다.

유연성 Handoff로 언제든 Local과 전환 가능. 결과가 좋으면 합치고, 아니면 버리세요.

핵심 포인트

Worktree는 Git 저장소에서만 동작합니다. Git으로 관리되지 않는 프로젝트에서는 사용할 수 없습니다. 프로젝트 폴더에서 git status를 실행해서 Git이 초기화되어 있는지 먼저 확인하세요.
Local checkout은 사용자가 만든 기본 저장소이고, worktree는 Codex가 파생한 별도 체크아웃입니다. 같은 Git 저장소를 공유하지만 파일 시스템에서는 별도 폴더로 존재합니다.
Handoff를 통해 Local과 Worktree 사이에서 스레드를 이동할 수 있습니다. "이 작업을 AI에게 넘기고 싶다" 또는 "AI 작업 결과를 내 환경으로 가져오고 싶다"는 경우에 사용하세요.
새 스레드에서 Worktree를 선택하고 시작 브랜치를 선택할 수 있습니다. 보통은 main 브랜치 또는 현재 작업 중인 feature 브랜치를 기반으로 시작합니다.

Worktree는 Git 저장소에서만 동작합니다. 프로젝트가 Git으로 초기화되어 있는지 먼저 확인하세요. 터미널에서 git status를 실행했을 때 에러가 나오면 Git이 설정되지 않은 것입니다.

자주 묻는 질문 (FAQ)

Worktree와 Git Branch의 차이는?

Branch(브랜치)는 코드의 "버전 이름표"입니다. 같은 폴더 안에서 브랜치를 바꾸면 파일 내용이 바뀝니다.

Worktree는 브랜치를 별도 폴더에 펼쳐놓는 것입니다. 즉, main 브랜치는 A 폴더에, feature 브랜치는 B 폴더에 동시에 열어놓을 수 있습니다.

브랜치 = 이름표, Worktree = 이름표가 붙은 별도 작업 공간이라고 이해하면 쉽습니다.

Worktree에서 작업한 내용이 원본에 영향을 주나요?

아니요, 전혀 영향을 주지 않습니다.

Worktree는 완전히 독립된 폴더에서 동작합니다. Worktree 안에서 파일을 수정하거나 삭제해도, Local Checkout(원본)의 파일은 그대로입니다.

원본에 반영하려면 반드시 Handoff나 Git merge를 직접 실행해야 합니다. 자동으로 반영되는 일은 없습니다.

Worktree를 여러 개 만들 수 있나요?

네, 여러 개 만들 수 있습니다.

예를 들어, Worktree A에서는 "로그인 기능 개선"을, Worktree B에서는 "결제 버그 수정"을 동시에 진행할 수 있습니다. 각 Worktree는 서로 독립적이라 서로 영향을 주지 않습니다.

다만, 각 Worktree는 서로 다른 브랜치를 사용해야 합니다. 같은 브랜치를 두 개의 Worktree에서 동시에 사용할 수는 없습니다.

Worktree에서 npm install 같은 설치가 필요한가요?

네, 필요할 수 있습니다.

Worktree는 별도 폴더이기 때문에, node_modules 같은 의존성 폴더는 자동으로 복사되지 않습니다. 프로젝트가 npm, pip 등의 패키지 매니저를 사용한다면, Worktree 폴더에서 별도로 설치해야 합니다.

Codex app에서는 Local Environment 설정을 통해 Worktree 전용 환경 준비 명령(setup command)을 지정할 수 있습니다. 예: npm install을 setup command로 설정해두면 자동으로 실행됩니다.

Worktree 작업이 마음에 안 들면 어떻게 하나요?

그냥 버리면 됩니다!

Worktree의 가장 큰 장점 중 하나입니다. AI가 작업한 결과가 마음에 들지 않으면, Worktree를 삭제하면 끝입니다. 원본 프로젝트에는 아무런 변경도 일어나지 않습니다.

부담 없이 "한번 해봐"라고 AI에게 시킬 수 있는 이유가 바로 이것입니다. 실패해도 손해 볼 것이 없으니까요.

Worktree는 언제 Local 대신 써야 하나요?

간단한 규칙:

- 작업이 작고 간단하면 (오타 수정, 변수명 변경 등) Local에서 바로 하세요.
- 작업이 크거나 실험적이면 (새 기능 개발, 대규모 리팩터링, 확실하지 않은 시도) Worktree를 사용하세요.
- 현재 하던 작업을 중단하고 싶지 않으면 Worktree를 사용하세요.

생산성 향상 팁

리팩터링은 Worktree에서

장시간 걸리는 리팩터링 작업은 항상 Worktree에서 진행하세요. 예: "모든 클래스 컴포넌트를 함수형 컴포넌트로 바꿔줘"처럼 큰 변경을 요청할 때, Worktree를 사용하면 현재 작업에 영향 없이 결과를 받아볼 수 있습니다.

코드 리뷰 전용 Worktree

다른 팀원의 PR을 리뷰해야 할 때, Worktree를 만들어서 해당 브랜치를 체크아웃하세요. 내 작업을 중단하지 않고 리뷰할 수 있습니다. 리뷰 중에 수정 사항이 발견되면 Worktree에서 바로 수정할 수도 있습니다.

여러 실험을 동시에

"이 문제를 해결하는 방법이 3가지 있는데, 뭐가 좋을지 모르겠어"라면? Worktree를 3개 만들어서 각각 다른 방법으로 시도해 보세요. 결과를 비교한 뒤 가장 좋은 것만 Handoff로 가져오면 됩니다.

Local Environment와 함께 사용

의존성 설치나 빌드가 필요한 프로젝트라면, Worktree 전용 Local Environment를 설정해 두세요. setup command에 npm install && npm run build 같은 명령을 등록하면, Worktree가 생성될 때 자동으로 환경이 준비됩니다.

다음 단계

Worktree를 이해했다면, 다음 단계로 넘어가세요!

1. Local Environment 설정하기: Worktree에서 의존성 설치와 빌드를 자동화하는 방법을 배웁니다. Local Environment 페이지로 이동

2. Automations 알아보기: PR이 올라올 때 자동으로 Worktree에서 리뷰하는 등 반복 작업을 자동화할 수 있습니다. Automations 페이지로 이동

3. 직접 해보기: Codex app에서 새 스레드를 열고, Worktree 환경을 선택해서 간단한 작업을 맡겨 보세요. 예를 들어 "README.md에 프로젝트 설명을 추가해줘" 같은 가벼운 요청부터 시작하면 좋습니다.

저장 위치와 보존 정책

저장 경로 — Codex가 만드는 worktree는 $CODEX_HOME/worktrees 아래에 생성됩니다(기본 ~/.codex/worktrees).
기본 보존 — 가장 최근 15개의 Codex 관리 worktree만 유지됩니다. 한도를 넘으면 가장 오래된 항목부터 자동 정리됩니다.
예외 — 활성 스레드가 점유 중이거나, pinned·permanent로 표시된 worktree는 자동 삭제 대상에서 제외됩니다.
브랜치 — Codex가 만드는 worktree는 기본 detached HEAD 상태입니다. 이유: Git은 같은 브랜치를 두 곳에서 동시에 체크아웃할 수 없기 때문에, 사용자의 로컬 체크아웃과 충돌하지 않도록 worktree는 detached HEAD로 시작합니다. 변경을 새 브랜치로 보존하려면 "Create branch here" 버튼을 사용하세요.

Worktree 두 가지 유형

Codex-managed (disposable)

스레드 전용으로 자동 생성·정리되는 일회성 worktree. Handoff 시 자동으로 회수되며 위 15개 한도 안에서 회전합니다.

Permanent

사이드바의 프로젝트 항목에 있는 ⋯ (점 3개) 메뉴에서 "Add permanent worktree"로 생성합니다(공식 worktrees 문서). 다중 스레드를 한 worktree에서 운영할 수 있고 자동 정리에서 제외됩니다.

장점 / 단점 / 한계점

✅ 장점

원본 브랜치를 건드리지 않고 안전하게 실험 가능
여러 작업을 독립 브랜치에서 동시에 진행
Worktree 생성과 PR 연동이 자동화
실패한 실험은 간단히 삭제 가능

❌ 단점

Worktree가 많아지면 디스크 공간을 추가로 사용
각 Worktree별 의존성을 별도로 설치해야 할 수 있음
여러 Worktree 간 변경사항 병합 시 충돌 가능성

⚠️ 한계점

같은 브랜치를 여러 worktree에서 동시 체크아웃할 수 없음 (fatal: 'branch' is already used by worktree at '<PATH>')
Handoff로 체크아웃을 전환할 때 git-ignored 파일(예: .env, node_modules/)은 자동으로 따라가지 않음
Worktree 간 실시간 동기화 기능 없음 (각각 독립적으로 동작)

공식 출처

Worktrees developers.openai.com
Automations developers.openai.com