Codex 서브에이전트와 Git worktree 비교: 병렬 코드 작업은 어떻게 나눌까
TL;DR
같은 코드 변경을 보안·테스트·유지보수 관점에서 동시에 검토하려면 Codex 서브에이전트를 고릅니다. 여러 에이전트가 각 관점의 근거를 찾습니다. Codex는 결과를 한 답변으로 모아 줍니다.
서로 다른 코드 변경을 같은 저장소에서 동시에 진행하려면 Git worktree를 고릅니다. ChatGPT 데스크톱 앱의 Codex에서 독립된 채팅과 작업 디렉터리를 만들 수 있어 현재 로컬 작업을 건드리지 않고 변경을 분리할 수 있습니다.
핵심 3줄 요약
서브에이전트는 한 요청을 여러 역할로 나누고 결과를 통합하는 기능입니다.
Worktree는 같은 Git 저장소에 독립된 체크아웃을 만들어 여러 변경 작업을 분리합니다.
분석에는 서브에이전트를, 독립 수정에는 Worktree를 먼저 고려합니다. 마지막 통합 검증은 사람이 승인합니다.
이 글에서 다룰 내용
하나의 저장소에서 병렬 코드 작업을 맡길 때 무엇을 고를지 판단하는 기준을 다룹니다. 현재 PR을 여러 관점에서 검토하는 순서와 독립된 수정 작업을 Worktree 채팅으로 나누는 순서도 살펴봅니다. 그대로 복사해 쓸 요청문과 통합 전 주의점까지 확인할 수 있습니다.
어떤 문제를 해결하는 기능인가
통합된 분석이 필요하면 서브에이전트, 독립된 코드 변경 공간이 필요하면 Worktree를 먼저 고려합니다.
병렬 작업의 결과가 뒤섞이면 오히려 검토 시간이 길어집니다. 같은 PR을 여러 관점에서 읽는 일과 서로 다른 파일을 실제로 고치는 일은 처음부터 나누는 방식이 달라야 합니다.
Codex 서브에이전트는 큰 요청의 독립된 부분을 여러 전문 에이전트에 병렬로 맡기고 결과를 하나로 모으는 기능입니다. OpenAI 공식 문서는 코드베이스 탐색·테스트·로그 분석처럼 병렬화하기 쉬운 작업에서 주 대화의 맥락을 지키는 용도로 설명합니다.
Codex의 Git worktree는 같은 Git 프로젝트에 독립된 작업 디렉터리를 만들어 여러 채팅의 변경을 서로 방해하지 않게 하는 기능입니다. ChatGPT 데스크톱 앱에서 Worktree를 선택하면 기준 브랜치에서 별도 체크아웃을 만들고 백그라운드 작업을 진행할 수 있습니다.
두 기능은 우열을 가릴 대체재가 아닙니다. 서브에이전트는 역할과 조사 관점을 나눕니다.
Worktree는 채팅별 코드 변경 공간을 나눕니다. 이번 작업에서 필요한 것이 통합된 분석인지 독립된 코드 변경인지부터 판단하면 됩니다.
서브에이전트를 고를 때
1. 같은 변경을 여러 관점에서 검토할 때
현재 브랜치와
main
의 차이를 보안·테스트 공백·유지보수성 관점으로 검토한다면 서브에이전트가 맞습니다. OpenAI 공식 예시도 관점마다 에이전트 한 명을 배정하고 모두 끝날 때까지 기다린 뒤 파일 근거와 함께 결과를 요약하도록 요청합니다.
각 에이전트에는 원시 로그 대신 판단과 근거 파일을 짧게 요약하도록 요청하세요. 주 대화에는 요구사항과 결정이 남습니다. 최종 결과도 주 대화에 두고 중간 탐색 내용은 별도 스레드에 머물게 합니다.
2. Codex에서 서브에이전트를 실행하는 순서
- 검토할 브랜치와 비교 기준을 확정합니다.
- 보안·테스트 공백·유지보수성처럼 서로 독립된 관점을 정합니다.
- Codex에 “관점마다 서브에이전트 한 명을 생성하라”고 직접 요청합니다.
- 모든 에이전트가 끝날 때까지 기다린 뒤 파일 경로와 근거를 포함해 통합하라고 지시합니다.
- 지적된 내용을 실제 diff와 테스트 결과로 사람이 확인합니다.
Codex의 현재 로컬 릴리스는 서브에이전트 기능이 기본 활성화되어 있습니다. 활동은 ChatGPT 데스크톱 앱·Codex CLI·IDE 확장에서 확인할 수 있습니다. 에이전트마다 모델과 도구 작업을 수행하므로 단일 에이전트 실행보다 토큰을 더 쓸 수 있다는 점도 공식 문서에 명시되어 있습니다.
Git worktree를 고를 때
3. 독립된 코드 변경을 동시에 진행할 때
한 채팅은 인증 오류를 수정하고 다른 채팅은 관련 없는 문서 빌드를 고치는 식으로 결과가 각각 코드 변경이어야 한다면 Worktree가 맞습니다. ChatGPT 데스크톱 앱의 Codex Worktree는 같은 프로젝트에서 여러 독립 채팅을 실행하되 서로 간섭하지 않도록 분리합니다.
Worktree는 Git 저장소에서만 사용할 수 있습니다. 각 Worktree는 파일의 별도 복사본을 갖고 커밋과 브랜치에 관한 Git 메타데이터는 공유합니다. 이 구조 덕분에 여러 브랜치를 병렬로 다룰 수 있습니다.
4. ChatGPT 데스크톱 앱에서 Worktree를 여는 순서
- Git 저장소인 프로젝트를 ChatGPT 데스크톱 앱에서 엽니다.
- 새 채팅 입력창 아래에서 Worktree를 선택합니다.
-
main이나 기능 브랜치 또는 현재 브랜치 가운데 시작 기준을 고릅니다. - 독립된 수정 목표·허용 파일·검증 명령·완료 조건을 입력합니다.
- 결과가 나오면 Worktree에서 직접 확인하거나 Handoff로 Local에 옮겨 평소 환경에서 검증합니다.
Codex는 선택한 브랜치의
HEAD
를 기준으로 Worktree를 만듭니다. 기본 상태는
detached HEAD
입니다. Worktree에서 계속 작업하려면 Create branch here로 브랜치를 만든 뒤 커밋과 PR 흐름을 이어갈 수 있습니다.
한 작업에서 무엇을 고를까
5. 결과물의 형태로 결정합니다
코드를 바꾸지 않고 현재 PR의 위험을 여러 관점에서 찾는다면 서브에이전트를 사용합니다. 결과는 하나의 통합 검토표로 모입니다. 각 작업이 실제 diff를 만들고 따로 테스트되어야 한다면 Worktree 채팅이 맞습니다. 이때 결과는 독립된 작업 디렉터리와 변경 묶음입니다.
두 기능을 함께 쓰고 싶다면 순서를 나눕니다. 먼저 서브에이전트로 현재 PR의 보안·테스트·유지보수 위험을 분석합니다. 분석 결과에서 서로 의존하지 않는 수정만 골라 별도의 Worktree 채팅에 맡깁니다.
서브에이전트 하나가 Worktree 하나를 자동으로 배정받는다고 가정하지 마세요. 공식 문서는 두 기능을 별도 흐름으로 설명합니다.
6. 최종 통합 전에 다시 검증합니다
서브에이전트의 요약은 근거 파일과 diff를 대조합니다. Worktree의 변경은 각 환경에서 지정 테스트를 실행합니다. Local로 가져온 최종 상태에서는 전체 테스트와 정적 검사를 다시 실행합니다.
Worktree 안에서 성공한 결과가 Local 통합 뒤에도 그대로 작동한다고 단정하면 안 됩니다. Handoff나 브랜치 생성 뒤 실제 변경을 읽으세요. 충돌과 테스트 결과를 확인한 다음 사람이 병합을 승인합니다.
그대로 복사해 쓸 프롬프트
허용 입력: 현재 브랜치와 main의 diff·저장소 안의 코드와 테스트·실행이 허용된 읽기 및 테스트 명령·사용자가 제공한 요구사항.
제외 입력: 저장소 밖의 개인정보·비밀번호와 인증 토큰·승인하지 않은 네트워크 접근·제공하지 않은 제품 요구사항·근거 없는 성능 수치.
출력 형식: 먼저 보안·테스트 공백·유지보수성 관점마다 서브에이전트 한 명을 실행한다. 모두 끝나면 항목 | 근거 파일 | 영향 | 독립 수정 가능 여부 | 권장 다음 행동 순서로 통합한다.
완료 기준: 모든 지적에 파일 또는 diff 근거가 있어야 한다. 독립 수정 가능 항목과 선행 의존 항목을 구분하고 실행한 테스트와 실패 결과를 기록한다.
추정 금지: 파일을 읽지 않고 문제를 만들지 않는다. 확인하지 못한 동작·테스트 통과·Worktree 생성·병합 완료를 사실처럼 쓰지 않는다.
승인 지점: Worktree 채팅 생성·코드 수정·브랜치 생성·Handoff·커밋·병합은 각 단계에서 사람이 검토하고 승인한 뒤 진행한다.
이 요청문은 분석 결과를 먼저 만드는 용도입니다. 실제 Worktree 생성과 수정은 독립성이 확인된 항목만 따로 맡기세요. 변경 범위와 테스트 명령은 각 채팅에 다시 적습니다.
실전 활용 팁
“에이전트 수”보다 “결과물의 경계”를 먼저 적으세요. 보안 검토처럼 같은 diff를 읽는 작업은 관점을 나누고 하나의 요약으로 합칩니다. 코드 수정처럼 결과가 서로 달라야 하는 작업은 Worktree별 허용 파일과 완료 조건을 분리합니다.
Worktree에서 로컬 설정 파일이 필요하다면 공식 문서의
.worktreeinclude
동작을 먼저 확인하세요. Git이 무시하는 파일 가운데 명시한 경로만 복사됩니다.
비밀값이 든
.env
를 편의상 복사하기 전에 해당 작업에 정말 필요한지와 접근 범위를 사람이 검토해야 합니다.
주의할 점
- Worktree 기능은 현재 ChatGPT 데스크톱 앱의 Codex에서만 제공되며 Git 저장소가 필요합니다.
- 서브에이전트는 병렬 실행만으로 정확성이 보장되지 않습니다. 각 결과의 파일 근거와 테스트를 다시 확인합니다.
- 서브에이전트는 개별 모델·도구 작업으로 토큰 사용량이 늘 수 있습니다.
- Worktree는 기본적으로
detached HEAD에서 시작합니다. 변경을 보존할 경로를 정하지 않은 채 작업을 끝내지 마세요. - 같은 브랜치는 한 번에 한 Worktree에서만 체크아웃할 수 있습니다. Local과 Worktree 사이 이동은 Handoff 흐름을 따릅니다.
- 계정·앱 버전·조직 정책에 따라 화면이 다를 수 있으므로 현재 UI와 관리자 정책을 확인합니다.
자주 묻는 질문
서브에이전트가 Worktree를 자동으로 만들어 주나요?
공식 문서는 서브에이전트와 ChatGPT 데스크톱 앱의 Worktree를 별도 기능으로 설명합니다. 자동 연결을 전제로 하지 말고 분석과 독립 수정 단계를 나눠 운영하세요.
코드 리뷰에도 Worktree가 필요한가요?
읽기 중심으로 같은 PR을 여러 관점에서 검토한다면 서브에이전트만으로 시작할 수 있습니다. 실제 수정이 여러 갈래로 나뉠 때 Worktree를 추가합니다.
Worktree 결과는 어떻게 Local로 가져오나요?
채팅 헤더의 Handoff로 Worktree와 Local 사이를 이동할 수 있습니다. Worktree에서 계속 작업한다면 Create branch here로 브랜치를 만들 수 있습니다. 이동 뒤 diff와 테스트를 다시 확인하세요.
서브에이전트 결과를 그대로 승인해도 되나요?
아니요. 요약에 나온 파일과 줄을 실제 diff에서 확인하세요. 테스트를 다시 실행한 뒤 사람이 수정 또는 병합을 승인해야 합니다.
출처
마무리
Codex 서브에이전트는 같은 작업을 여러 관점으로 나눠 통합된 분석을 만들 때 유용합니다. Git worktree는 독립된 코드 변경을 별도 체크아웃에서 진행할 때 맞습니다.
먼저 결과물이 분석인지 코드 변경인지 정하세요. 분석은 서브에이전트로 모읍니다. 서로 의존하지 않는 수정은 Worktree 채팅으로 분리합니다. 마지막에는 실제 diff와 전체 테스트를 확인하고 사람이 병합을 승인해야 병렬 작업이 끝납니다.
