빠른 흐름

핵심 흐름
1. 새 스레드에서 Worktree 모드 선택
2. 시작 브랜치 선택
3. Codex가 별도 worktree 생성
4. 백그라운드에서 작업 진행
5. 필요하면 Handoff로 Local로 가져와 검증

이동 흐름

Worktree가 현재 로컬 작업을 건드리지 않고 병렬 작업을 가능하게 하는 이유

공식 문서에서 Worktree는 같은 저장소 안에서 여러 독립 작업을 동시에 돌리기 위한 Codex app의 핵심 기능입니다. Worktree는 Git worktree 위에 만들어지므로 Git 저장소에서만 쓸 수 있고, 현재 Local 체크아웃을 건드리지 않은 채 별도 작업 공간을 만듭니다. Local을 전경 작업, Worktree를 배경 작업으로 생각하면 이해가 쉽습니다. 지금 보고 있는 IDE와 개발 서버는 Local에 두고, 장시간 수정은 Worktree에 맡기는 식입니다.

잘 맞는 상황
- 지금 Local에서 게임을 직접 실행 중이고, 다른 수정 작업은 백그라운드로 돌리고 싶다.
- 기능 A를 건드리는 동안, 기능 B 리팩터링을 별도 체크아웃에서 병렬로 맡기고 싶다.
- Worktree에서 만든 변경을 마지막 검증은 내 평소 IDE와 로컬 서버에서 보고 싶다.

Handoff가 Worktree와 Local 사이의 안전한 이동을 담당하는 방식

Handoff는 Worktree와 Local 사이에서 스레드와 코드를 안전하게 옮기는 흐름입니다. Codex가 필요한 Git 작업을 처리해 줍니다. Worktree에서 작업을 마친 뒤 최종 검증을 평소 IDE와 로컬 서버에서 하고 싶을 때, 직접 Git 브랜치를 옮기는 대신 Handoff를 쓰면 코드와 스레드 맥락이 함께 이동합니다. "결과물은 백그라운드 Worktree에서, 최종 확인은 내 로컬 환경에서"라는 흐름을 자연스럽게 연결하는 도구입니다.

Local
  -> 전경 작업

Worktree
  -> 병렬 작업

Handoff
  -> 둘 사이 안전한 이동

같은 브랜치를 두 곳에서 동시에 체크아웃할 수 없다는 Git 제약

중요한 제한도 있습니다. Git은 같은 브랜치를 두 체크아웃에서 동시에 잡는 것을 허용하지 않으므로, 같은 브랜치를 Local과 Worktree에서 동시에 유지하려 하지 말고 Handoff를 쓰는 편이 맞습니다. 이 제약을 모르고 같은 브랜치를 두 곳에서 쓰려 하면 Git 오류가 발생하고 작업이 중단됩니다. Worktree를 만들 때는 새 브랜치를 시작 브랜치로 선택하거나, 기존 브랜치를 쓴다면 Local에서 체크아웃하지 않은 브랜치를 골라야 합니다.

.gitignore 파일이 Handoff 후 빠지는 이유를 미리 알아야 한다

Handoff는 Git 기반으로 움직이기 때문에 .gitignore에 들어간 파일은 함께 이동하지 않습니다. 로컬 개발 서버 설정이나 생성 파일에 의존하는 작업이라면, Handoff 후 어떤 파일이 빠지는지 먼저 확인하는 것이 중요합니다. Local environments의 setup script를 활용하면 Handoff 후 자동으로 빠진 파일을 재생성하거나 의존성을 다시 설치하는 준비 단계를 자동화할 수 있습니다.

언제 worktree를 쓸까

주의할 점

❌ Local과 Worktree에서 같은 브랜치를 동시에 잡으려 함
❌ Handoff 후 .env.local, generated 파일이 자동으로 올 줄 기대

이 패턴은 Git 제약으로 바로 막히거나, 이동 후 환경이 불완전해져 검증 단계에서 혼선을 만듭니다.