Codex worktree로 병렬 수정 격리하기
같은 저장소에서 UI 수정과 오류 재현을 동시에 하려면 파일 상태를 분리할 필요가 있습니다. 대화를 fork해도 두 작업이 같은 폴더를 쓰면 덮어쓰기 위험은 남습니다. Git worktree는 같은 저장소의 별도 작업 디렉터리를 두는 방식입니다.
공식 문서를 참고한 비공식 한국어 가이드입니다. 이 글의 생성·handoff·정리는 실행 미검증입니다. 기존 변경과 디스크 공간, 브랜치 정책을 확인하고 worktree 생성 자체가 허용된 작업인지 먼저 판단합니다.
어떤 작업을 분리할까
한쪽은 원인 조사만 하고 다른 쪽은 코드를 고치는 경우, 변경 권한을 구분하거나 별도 worktree를 선택합니다. 예컨대 검색 오류 재현과 결과 카드 개선을 나눌 수 있지만 두 작업이 같은 공통 훅을 수정하면 최종 통합 충돌은 여전히 생길 수 있습니다.
두 작업은 별도 worktree에서 수행해 줘.
A는 검색 오류 재현 테스트만, B는 결과 카드의 키보드 동작만 맡아 줘.
공통 상태 훅 수정이 필요하면 바로 진행하지 말고 영향과 통합 순서를 알려 줘.
기존 폴더·브랜치·미커밋 변경은 삭제하거나 되돌리지 마.
이는 사용자가 worktree 생성을 허용한 상황의 합성 요청입니다. Codex가 임의로 다른 사람의 worktree를 정리해도 된다는 지시가 아닙니다.
시작과 handoff에서 확인할 것
공식 앱의 Local/Worktree 선택과 handoff 경로를 따라 실행 위치를 정합니다. 생성 후에는 실제 작업 경로·기준 커밋·브랜치를 확인하고 필요한 도구가 있는지 봅니다. Git에서는 같은 브랜치를 여러 worktree에 동시에 checkout하는 제약이 있으므로 이름을 재사용하기 전에 상태를 확인합니다.
작업을 Local로 가져오는 handoff는 ‘대화 이동’과 ‘변경 통합’을 함께 생각해야 합니다. 대상 폴더에 이미 수정이 있으면 이를 보존한 채 적용할 방법을 검토합니다. 테스트 통과가 다른 폴더의 파일에 대한 결과라면 현재 폴더의 성공으로 보고하지 않습니다.
ignored 파일과 환경 준비
.env나 의존성 디렉터리는 Git에 없으므로 새 worktree에 자동으로 준비된다고 보장할 수 없습니다. 공식 문서에는 관리 worktree에 ignored 파일을 포함하는 .worktreeinclude, 로컬 setup script와 actions가 나옵니다.
이때 비밀값을 편하게 복사하려고 .env* 전체를 포함하거나 스크립트에서 인증값을 출력하지 않습니다. 필요한 파일만 선택하고 실제 어느 worktree에 복제되는지 확인합니다. setup script는 저장소 코드 실행이므로 읽어 보고 신뢰한 뒤 사용합니다. 패키지 설치가 필요한지도 먼저 판단합니다.
결과 통합과 정리
각 작업의 완료 기록에는 worktree 경로, 기준/결과 SHA, 변경 파일, 실행한 검증을 남깁니다. 통합 후에는 합쳐진 결과에서 테스트를 다시 실행합니다. 따로 통과했던 두 변경이 함께 동작한다는 보장은 없습니다.
정리 전에는 진행 중인 채팅, 미커밋 파일, 생성된 산출물, 다른 곳에 없는 커밋을 확인합니다. ‘자동 생성 worktree’라는 이유로 귀중한 결과가 없다고 가정하지 마세요. 삭제는 사용자의 승인과 복구 가능한 상태를 확인한 뒤 수행합니다. 반복 작업의 worktree 수명은 예약 작업, 여러 에이전트의 책임 분리는 서브에이전트에서 이어갑니다.
공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며 계정 조건과 요금은 공식 안내를 우선합니다.
추가 공식 참조
다음은 관련 세부 기능과 전체 참조 문서입니다. 아래 항목은 원문 전체를 한국어로 설명하거나 실행 검증한 범위가 아닙니다. 적용 조건과 정확한 옵션은 공식 원문을 확인하세요.