Codex worktree란? 여러 코딩 작업을 나누는 방법과 주의점

요약: worktree를 사용하면 같은 Git 프로젝트의 작업 폴더를 분리해 여러 변경을 진행할 수 있습니다. 폴더가 나뉘어도 결과를 합칠 때는 변경 내용과 검증을 다시 확인해야 합니다.

1. worktree를 이해하는 간단한 예시

메모 앱에서 직접 화면 색상을 수정하고 있는데, Codex에는 검색 기능을 고치고 싶다고 해 봅시다. 두 작업이 같은 폴더를 수정하면 어떤 변경이 누구의 작업인지 구분하기 어려울 수 있습니다. worktree는 이런 상황에서 각각 별도의 작업 폴더를 사용하도록 만드는 방법입니다.

OpenAI 공식 문서는 worktree가 Git 저장소의 별도 체크아웃이며, 파일 사본은 따로 두고 커밋과 브랜치 등 Git 정보를 공유한다고 설명합니다. Codex에서는 같은 프로젝트의 독립된 작업을 병렬로 진행하는 데 활용할 수 있습니다. 단순히 폴더를 복사하는 것과 Git이 작업 폴더를 관리하는 방식은 구분해야 합니다.

2. 브랜치와 폴더의 차이부터 이해하기

브랜치는 Git 이력에서 작업이 이어지는 지점을 구분하고, worktree는 파일을 실제로 편집할 위치를 분리합니다. 처음 사용할 때는 “현재 내가 보고 있는 폴더가 어느 작업의 코드인가”를 확인하는 것이 중요합니다. 같은 파일 이름이라도 다른 작업 폴더에 있는 파일이면 내용이 다를 수 있습니다.

가상의 메모 앱에서 주 작업 폴더는 색상 변경, 별도 worktree는 검색 수정에 쓴다고 정했다면, 브라우저에서 어느 폴더의 개발 서버를 보고 있는지도 기록하세요. 화면이 바뀌지 않는다고 코드를 다시 수정하기 전에 실행 중인 서버가 수정한 폴더를 가리키는지 확인할 수 있습니다. 이런 확인은 AI 도구와 관계없이 여러 체크아웃을 사용할 때 필요한 습관입니다.

3. 나눌 작업의 경계를 먼저 정하기

폴더를 분리하는 것만으로 작업의 책임이 정해지지는 않습니다. 검색 수정과 화면 색상 변경이 같은 컴포넌트를 크게 바꾼다면 나중에 합칠 때 조정이 필요합니다. 독립성이 높은 작업부터 나누고, 공통으로 수정할 부분이 있다면 서로의 요구를 먼저 정리하세요.

검색 결과가 없을 때 안내 문구를 표시하는 수정만 진행해 주세요.
작업은 별도 worktree에서 진행하고 시작 기준을 알려 주세요.
주 작업 폴더에서는 색상 변경을 진행 중입니다.
공통 스타일과 다른 작업자의 변경은 덮어쓰지 마세요.
완료 후 변경 파일, 관련 검증 결과, 합칠 때 확인할 점을 정리해 주세요.

이 예시는 특정 버튼을 누르는 UI 설명이 아니라 작업 경계를 전달하는 요청입니다. 사용 중인 앱에서 worktree 기능을 사용할 수 있는지, 어떤 기준에서 생성되는지는 실제 생성 결과와 현재 공식 안내로 확인하세요. 진행 중인 미저장 수정이 다른 폴더에도 자동으로 나타날 것이라고 가정하지 않는 편이 좋습니다.

4. 생성 직후와 합치기 직전에 확인하기

생성 직후에는 작업 경로, 시작한 Git 상태, 필요한 개발 환경을 확인합니다. 새 폴더에 소스가 있다고 해서 패키지나 로컬 설정까지 모두 준비되었다고 단정할 수 없습니다. 환경 파일이 필요하다면 내용을 대화에 붙여 넣기보다 프로젝트의 안전한 설정 방법을 따르세요.

작업을 합치기 전에는 수정된 파일의 차이를 읽습니다. 검색 기능 변경이 색상 변경과 같은 줄을 건드렸는지, 공개 함수의 형식이 달라졌는지, 의도하지 않은 생성 파일이 포함되었는지 확인하세요. 개별 작업에서 검증한 결과는 유용하지만, 두 변경을 함께 적용한 상태에서도 필요한 확인을 해야 합니다. 각각 정상이어도 조합에서 문제가 생길 수 있기 때문입니다.

5. 자주 생기는 혼동과 해결 체크

• 화면이 그대로임: 개발 서버의 작업 경로와 접속 중인 주소를 확인합니다.
• 필요한 명령이 실패함: 새 작업 폴더에 필요한 의존성과 설정이 준비되었는지 확인합니다.
• 변경이 섞임: 파일 차이를 보고 작업별 책임과 공통 수정 부분을 다시 정리합니다.
• 폴더 정리가 필요함: 보관할 커밋과 파일을 확인한 뒤 사용 중인 앱의 정리 절차를 따릅니다.

사용하지 않는 작업 폴더를 바로 삭제하기보다는 결과가 어디에 보관되는지 확인하세요. OpenAI 문서는 Codex의 작업 이동과 정리 흐름도 안내합니다. 해당 앱이 관리하는 worktree라면 일반 폴더처럼 임의 이동하는 것보다 공식 관리 절차를 확인하는 편이 현재 작업을 찾기 쉽습니다.

6. 작업 폴더와 Git 상태를 눈으로 구분하기

가상의 memo-app에서 현재 폴더는 색상 변경, 별도 폴더는 검색 기능 수정에 사용한다고 가정하겠습니다. 작업을 시작할 때는 기억에 의존하지 말고 경로와 Git 상태를 읽습니다. 아래 명령은 Git 저장소에서 현재 폴더, 저장소 루트, 변경 파일, 연결된 worktree를 조회하는 예시입니다. PowerShell에서 실행할 수 있으며 실제 폴더 경로는 바꾸어야 합니다.

Get-Location
git rev-parse --show-toplevel
git branch --show-current
git rev-parse --short HEAD
git status --short
git worktree list

git worktree list는 여러 작업 폴더와 연결된 Git 상태를 함께 살펴볼 때 유용합니다. 같은 프로젝트 이름이 보여도 경로가 다르면 별도 작업 폴더입니다. branch --show-current가 비어 있다면 이름 있는 브랜치를 체크아웃하지 않은 상태일 수 있으므로 Git 상태를 함께 읽으세요. 공식 앱 문서는 관리 worktree가 기본적으로 detached HEAD에서 시작하는 흐름을 설명합니다. 브랜치 이름이 없다는 사실만으로 생성 실패라고 판단하지 않습니다.

기록할 항목	가상의 작업 A	가상의 작업 B
작업 목적	화면 색상 조정	빈 검색 결과 안내
폴더	C:\Projects\memo-app	별도 worktree의 실제 경로
시작 상태	현재 변경 포함 여부 기록	선택한 기준과 시작 커밋 기록
수정 책임	공통 색상	검색 표시 조건

시작 커밋과 로컬 변경 포함 여부를 남기는 이유는 나중에 차이를 해석하기 위해서입니다. 최신 작업이라고 생각했는데 이전 기준에서 시작했다면 검색 수정 외에 다른 차이가 섞여 보일 수 있습니다. 앱에서 시작 브랜치와 로컬 변경을 선택한 경우에는 그 선택을 기록하세요. 직접 Git으로 만든 worktree와 앱이 관리하는 worktree의 생성·정리 절차를 같은 것으로 가정하지 않는 것도 중요합니다.

7. 폴더가 분리되어도 공유될 수 있는 실행 환경

소스 폴더가 나뉘었다고 실행 중인 서버와 외부 데이터가 자동으로 분리되지는 않습니다. 두 개발 서버가 같은 포트를 사용하면 뒤에 실행한 서버가 실패하거나 다른 포트로 뜰 수 있습니다. 두 폴더가 같은 테스트 데이터베이스에 연결되면 한쪽의 데이터 변경이 다른 쪽 결과에 영향을 줄 수 있습니다. worktree로 분리된 범위와 프로젝트가 공유하는 자원을 나누어 기록해야 합니다.

1. 각 폴더의 README와 lock 파일을 보고 같은 패키지 관리자를 사용합니다.
2. 의존성이 준비되어 있는지 살펴보고 프로젝트의 설치 절차를 따릅니다.
3. 개발 서버를 시작할 때 출력된 주소를 작업 이름과 함께 기록합니다.
4. 환경 변수의 이름과 연결 대상을 확인해 테스트용 서비스가 공유되는지 파악합니다.
5. 브라우저에서 보고 있는 주소가 수정한 폴더의 서버인지 연결합니다.

예를 들어 색상 작업 서버를 5173, 검색 작업 서버를 5174로 정했다면 각 주소에서 어느 화면을 확인하는지 작업 기록에 적습니다. 이 숫자는 가상 배치 예시이며 모든 도구가 이 포트를 사용한다는 뜻은 아닙니다. 프로젝트의 서버 설정과 시작 출력에 맞추세요. 화면이 바뀌지 않을 때는 코드를 더 고치기 전에 접속 주소와 서버 실행 폴더부터 비교하는 것이 빠른 진단입니다.

새 worktree의 실행 환경을 점검해 주세요.
현재 경로, 시작 커밋, 관련 실행·검증 명령을 알려 주세요.
의존성과 필요한 설정 파일이 준비되어 있는지 확인하세요.
주 작업 폴더와 개발 서버 포트·데이터 연결이 겹칠 수 있는지 설명하세요.
환경 변수의 실제 비밀값은 출력하지 말고 이름과 준비 상태만 보고하세요.

8. Git에서 제외된 로컬 설정을 어떻게 준비할까?

새 폴더에 코드가 있지만 실행이 안 되는 흔한 이유는 Git이 추적하지 않는 로컬 설정이 없기 때문입니다. 먼저 프로젝트에 환경 변수 예시 파일이나 설정 안내가 있는지 확인하고, 그 절차로 준비하세요. 기존 폴더를 통째로 복사하면 필요 없는 의존성·캐시·빌드 산출물도 옮겨질 수 있으므로 필요한 설정을 구분하는 편이 좋습니다.

현재 공식 문서는 저장소 루트에 .worktreeinclude 파일을 두고, 로컬 관리 worktree를 만들 때 복사할 ignored 파일의 경로나 패턴을 적는 기능을 안내합니다. 적용 대상은 앱이 만든 로컬 관리 worktree입니다. 직접 Git 명령으로 만든 폴더나 원격 환경에도 같은 방식이 자동 적용된다고 생각하지 마세요. 추적 중인 소스는 이미 checkout에 포함되므로 복사 목록에 다시 넣을 필요가 없습니다.

# .worktreeinclude의 가상 예시
.env.local
config/development.local.json

위 파일명을 무조건 추가하지는 마세요. 실제로 Git에서 제외되어 있고 새 작업 환경에 필요한 파일인지부터 판단합니다. 운영 서비스의 설정을 개발 worktree로 복사하는 방식이 맞는지도 검토해야 합니다. 예시 파일만으로 준비할 수 있다면 그 방법을 우선 사용할 수 있습니다. 새 worktree 생성 시 적용되는 복사 설정을 바꾼 뒤에는 실제 생성 결과에서 필요한 파일이 준비되었는지 확인하세요.

설정을 찾지 못한 Codex가 임의의 빈 파일을 만들어 명령만 통과시키지 않게 하려면, 필요한 환경을 알 수 없는 경우 작업을 미실행으로 표시하고 준비 절차를 설명하도록 요청하세요. 설정 준비 문제와 기능 결함을 분리하면 소스 코드를 불필요하게 변경하는 일을 줄일 수 있습니다.

9. 두 변경을 합칠 때의 전후 확인 사례

검색 작업과 색상 작업이 각각 검증되었다고 가정해 보겠습니다. 검색 작업은 결과 0개 안내를 추가했고 색상 작업은 공통 메시지 색을 바꿨습니다. 줄 단위 충돌이 없어도 두 변화가 합쳐진 뒤 안내 문구의 대비가 부족할 수 있습니다. Git이 합칠 수 있다는 것과 제품 동작이 맞다는 것은 서로 다른 판단입니다.

시점	확인할 내용	문제가 있으면
합치기 전	각 변경 목적·파일·검증 결과	기능과 관계없는 변경을 먼저 분리
차이 비교	공통 컴포넌트·스타일·API 접점	같은 조건을 다르게 바꿨는지 조정
합친 후	정상 검색과 빈 결과 화면	조합에서 생긴 문제를 별도 재현
정리 전	보관할 결과와 로컬 설정 위치	누락된 파일을 확보한 뒤 정리

검색 수정과 색상 변경을 함께 적용한 상태를 검토해 주세요.
각각의 의도는 유지하고 공통 메시지 표시 부분을 확인하세요.
정상 결과·결과 0개·로딩·오류 상태를 구분해 검증하세요.
충돌 해결 과정에서 빠진 기능과 관련 없는 변경이 있는지 살펴보세요.
개별 작업에서 통과한 검사와 조합 상태에서 실행한 검사를 나누어 보고하세요.

앱에서 worktree의 작업을 Local로 옮길 때는 공식 Hand off 흐름을 사용할 수 있습니다. 이는 작업을 다른 checkout에서 계속하도록 이동하는 흐름이며, 두 독립 작업의 변경이 의도대로 결합되었는지 확인하는 일을 대신하지 않습니다. 현재 로컬 변경이 있다면 그 상태를 파악한 뒤 이동 결과를 읽으세요. 관리 worktree는 앱의 보관·복원 흐름을 사용하면 작업 기록과 폴더의 연결을 유지하기 쉽습니다.

10. 자주 묻는 질문

Git을 사용하지 않아도 되나요? 이 글에서 다루는 worktree는 Git 저장소를 전제로 합니다. 일반 프로젝트 폴더를 나누는 작업과 같은 기능으로 보지 마세요.

worktree를 쓰면 충돌이 없어지나요? 편집하는 폴더는 분리되지만 같은 코드의 변경을 합칠 때 충돌이나 의미상의 조정이 필요할 수 있습니다.

여러 작업을 무조건 나누는 게 좋나요? 서로 독립적인 작업에 유용합니다. 매우 작은 수정 하나라면 새 환경을 준비하고 정리하는 부담까지 고려하세요. 작업 수보다 각 결과를 이해하고 검증할 수 있는지가 더 중요합니다.

공식 출처 및 확인일: OpenAI 공식 문서: Worktrees. 2026년 10월 3일 확인. 명령과 기능은 현재 환경 및 권한을 확인한 뒤 사용하세요.