Quick Flow

Local에서 개발 서버·IDE를 계속 쓴다       -> 병렬 Codex 작업은 Worktree
Worktree 결과를 기존 IDE에서 검증해야 한다 -> Hand off to Local
Worktree에서 계속 검증·커밋한다           -> Create branch here 후 작업 유지
새 Worktree에 .env가 필요하다             -> .worktreeinclude + setup script

Worktree는 같은 Git repository의 별도 checkout에서 독립 chat을 실행한다. 현재 Local checkout을 건드리지 않고 여러 chat을 병렬로 돌릴 수 있다. Git repository가 아닌 프로젝트에는 만들 수 없다.

Local과 Worktree를 나누는 이유

새 chat에서 Worktree를 선택하고 시작 branch를 고르면 Codex가 worktree를 만든다. 시작 branch는 main, feature branch, unstaged 변경이 있는 현재 branch 중에서 고를 수 있고, 기본적으로 worktree는 detached HEAD에서 작업한다. 이 상태로 검증이 끝나면 chat header의 Create branch here로 branch를 만들어 commit·push·PR을 이어 갈 수 있다.

Local: 지금 쓰는 IDE, 개발 서버, 사람이 하는 전경 검증
Worktree: 다른 변경과 파일 상태가 섞이지 않는 병렬 Codex 작업

Git은 같은 branch를 두 checkout에서 동시에 checkout하지 못한다. Local에서 branch를 직접 checkout하려 하면서 Worktree에도 같은 branch를 유지하지 말고 Handoff를 쓴다. 여기서 발생하는 오류는 Codex의 동시성 문제가 아니라 Git의 branch ownership 제약이다.

Handoff와 ignored 파일

Handoff는 chat과 코드를 Local과 Worktree 사이에서 옮기며 필요한 Git 작업을 처리한다. Local로 가져오면 평소 IDE와 현재 개발 서버에서 결과를 검증할 수 있고, 다시 Worktree로 보내면 같은 chat이 연결돼 있던 background environment로 돌아간다.

Git checkout에는 tracked file만 있으므로 .env, .env.local, config/secrets.json처럼 ignored된 local file은 기본적으로 새 managed worktree에 복사되지 않는다. 필요한 ignored file은 repository root의 .worktreeinclude에 넣는다.

# .worktreeinclude
.env
.env.local
config/secrets.json

이 복사는 ChatGPT desktop app이 만드는 local managed worktree에만 적용된다. source symlink는 건너뛰고, 새 checkout에 이미 있는 파일은 덮어쓰지 않는다. 의존성 설치나 생성 파일 준비는 local environment의 setup script로 처리하되, 비밀값을 무심코 shared worktree에 복사하지 않도록 목록을 최소화한다.