Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기

공식 참고 자료: Codex Worktrees · Subagents · Best Practices

커리큘럼 흐름

1. Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
2. Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
3. Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
4. Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
5. Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
6. Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
7. Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
8. Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
9. Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기 ← 현재 문서
10. Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
11. Codex 검증 루프 — 머지 전에 동작을 증명하기
12. Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
13. Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
14. Codex 팀 딜리버리 플레이북 — 중급 레인 운영
15. Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
16. Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
17. Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
18. Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
19. Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
20. Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
21. Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기

이 문서에서 참고한 공식 문서

• Codex와 Git 저장소에서 worktree를 다루는 기본 동작 — Codex Worktrees
• 서브에이전트 병렬성과의 차이점 — Subagents
• 작업 분해와 워크플로우 크기 조절 원칙 — Best Practices

왜 Codex에서 worktree가 중요한가

Codex를 자주 쓰다 보면 병목은 코딩 속도가 아니라 브랜치 컨텍스트 관리에서 생깁니다.

우리는 보통 이런 상황을 동시에 겪습니다.

• 지금 하던 작업은 안정적으로 유지하고 싶다
• 다른 작업을 병렬로 돌리고 싶다
• stash/pop를 반복하며 컨텍스트를 흔들고 싶지 않다

git worktree는 같은 저장소를 여러 작업 디렉터리로 체크아웃해서, 각 디렉터리마다 독립 브랜치를 가질 수 있게 해줍니다.

핵심은 이렇게 기억하면 쉽습니다.

• 서브에이전트: 병렬 사고
• 워크트리: 병렬 실행(격리된 파일/브랜치)

worktree vs subagent 선택 기준

실무에서는 두 방식을 함께 쓰는 경우가 많습니다.

1. 서브에이전트로 후보 접근법을 빠르게 탐색
2. 선택한 접근법을 전용 worktree로 이동
3. 해당 worktree에서 Codex로 구현·검증

실전 셋업 패턴

1) 작업명 기반으로 worktree 생성

git fetch origin
git worktree add ../wt-auth-retry -b feat/auth-retry origin/main

네이밍 팁:

• 디렉터리: wt-{주제}
• 브랜치: feat/{주제} 또는 fix/{주제}

이 규칙만 지켜도 정리/리뷰 난이도가 확 내려갑니다.

2) 해당 worktree에서 Codex 실행

Codex를 worktree 디렉터리에서 시작해야 수정/테스트/커밋이 해당 작업 경계 안에 머뭅니다.

cd ../wt-auth-retry
codex

3) 머지 전 검증

worktree 안에서:

• lint/typecheck/tests 실행
• diff가 작업 범위 파일만 포함하는지 확인
• 커밋 후 push, PR 생성

자주 쓰는 최소 명령어

# 현재 활성 worktree 목록
git worktree list
 
# 끝난 worktree 디렉터리 제거
git worktree remove ../wt-auth-retry
 
# 머지 후 브랜치 정리
git branch -d feat/auth-retry

Git이 "branch is checked out"를 표시하면 먼저 git worktree list로 해당 브랜치를 점유한 worktree를 확인하세요.

운영 가드레일

worktree 하나 = 작업 하나

서로 무관한 변경을 섞지 마세요. worktree 하나는 리뷰 가능한 단일 태스크와 매핑되어야 합니다.

AGENTS.md 적용 범위를 확인

Codex는 디렉터리 스코프의 instruction 파일을 따릅니다. 중첩 AGENTS.md를 쓰는 저장소라면 worktree 경로에서도 의도한 규칙이 상속되는지 확인하세요.

오래된 worktree를 방치하지 않기

오래된 worktree는 브랜치 드리프트와 머지 마찰을 키웁니다. 짧고 목적이 분명한 수명 주기를 유지하세요.

팀 운영 예시

• main repo: 핫픽스 트리아지/릴리스 준비
• wt-feature-a: 신규 기능 구현
• wt-migration-b: 마이그레이션 + 검증
• wt-docs-c: 문서/릴리스 노트 업데이트

각 레인은 분리되지만, 동일한 원격 저장소와 리뷰 파이프라인으로 합류합니다.

자주 하는 실수

하나의 worktree를 여러 작업에 재사용

결국 worktree를 쓰기 전의 컨텍스트 충돌 문제를 다시 만들게 됩니다.

정리를 미루기

안 쓰는 worktree가 쌓이면 브랜치 소유권과 진행 상태가 빠르게 혼탁해집니다.

탐색 단계와 실행 단계를 한 레인에 섞기

여전히 접근법을 비교 중이라면 먼저 서브에이전트로 좁히고, 구현 확정 후 worktree를 만드세요.

바로 가져다 쓰는 프롬프트 템플릿

템플릿 A — 구현 레인

이번 작업은 ../wt-{topic} worktree 안에서만 진행해.
 
Goal:
- <feature/fix>를 가장 작은 리뷰 가능한 diff로 구현
 
Constraints:
- <directories> 밖 파일은 수정하지 않기
- 커밋 제안 전 lint + tests 실행
- 리스크와 롤백 경로 요약

템플릿 B — 검증 레인

이 검증용 worktree에서 <branch-name> 브랜치를 점검해.
 
Check:
- 실패 테스트
- 타입/린트 회귀
- 보안 민감 diff 구간
 
Return:
- PASS/FAIL
- 파일/라인 근거
- 최소 수정 계획

템플릿 C — 문서/릴리스 레인

이 docs worktree에서는 문서와 릴리스 노트만 수정해.
 
Do:
- <date> 이후 머지된 PR 읽기
- 사용자 영향 기준으로 묶기
- 간결한 릴리스 노트 초안 작성
 
애플리케이션 소스 파일은 수정하지 마.

실패 복구 플레이북

worktree 이슈의 대부분은 코드 문제가 아니라 운영 문제입니다.

케이스 1: dirty 상태라 remove가 막힘

git -C ../wt-auth-retry status
git -C ../wt-auth-retry stash -u   # 또는 commit
git worktree remove ../wt-auth-retry

케이스 2: 브랜치 드리프트가 너무 커짐

git -C ../wt-auth-retry fetch origin
git -C ../wt-auth-retry rebase origin/main

충돌이 과하면 새 worktree를 만들고 유효한 커밋만 선별해서 재적용하는 편이 안전합니다.

케이스 3: 잘못된 base로 worktree 생성

억지 rebase 체인을 만들기보다 빨리 닫고, 올바른 base에서 worktree를 다시 생성하세요.

팀 도입 효과를 확인하는 지표

아래 지표를 가볍게 추적하면 worktree 운영 효과가 보입니다.

• PR review lead time (격리로 리뷰 속도가 빨라졌는가)
• review 이후 재작업 비율 (scope 분리로 왕복이 줄었는가)
• 컨텍스트 충돌 사건 수 (stash 난립, 작업 간 오염 수정)
• 열린 worktree 평균 수명 (오래된 트리는 머지 마찰의 전조)

2~4주 단위로 개선이 보이면 worktree 습관이 자리 잡고 있다는 신호입니다.

규모가 커져도 버티는 네이밍 매트릭스

동시 worktree가 3~4개를 넘어가면 즉흥 네이밍은 빠르게 가독성을 잃습니다. 아래처럼 짧은 매트릭스로 고정하세요.

경로만 봐도 의도를 읽을 수 있어야 리뷰 라우팅과 정리 속도가 올라갑니다.

레인 간 핸드오프 계약

병렬 레인이 흔들리는 이유는 구현 난이도보다 핸드오프 품질 편차인 경우가 많습니다. 각 레인이 반드시 넘겨야 할 항목을 고정하세요.

• Goal 상태: done / partial / blocked
• Evidence: lint/test/build 출력(또는 생략 사유)
• Diff 범위: 어떤 디렉터리가 왜 바뀌었는지
• Risk 노트: 롤백 계획과 미해결 edge case
• 다음 오너: reviewer / verifier / release 레인 중 누가 이어받는지

레인 간 핸드오프를 내부 API처럼 다루면 조율 비용이 크게 줄어듭니다.

주간 운영 리듬 예시

팀에 바로 적용 가능한 단순 리듬:

• 월: 구현/마이그레이션 worktree 오픈
• 화~수: 구현 레인 진행 + 검증 레인 일일 체크
• 목: branch-vs-base 중심 머지 준비 리뷰
• 금: docs/release 레인 정리 + stale worktree 청소

핵심은 요일 자체가 아니라 반복 가능한 리듬입니다. 같은 박자를 유지하면 컨텍스트 소모가 줄어듭니다.

단일 레인 vs 서브에이전트 vs worktree 결정표

실행 방식 의견이 갈릴 때 아래 표로 빠르게 합의할 수 있습니다.

권장 순서:

1. 불확실성이 높으면 서브에이전트로 탐색
2. 경로가 정해지면 worktree에서 실행
3. 위험/범위가 중간 이상이면 별도 검증 레인에서 확인

팀 정책 템플릿(복붙용)

엔지니어링 핸드북이나 AGENTS.md 보조 문서에 바로 붙일 수 있습니다.

### Worktree 정책
 
- worktree 하나는 리뷰 가능한 단일 목표와 매핑한다.
- worktree 이름은 승인된 네이밍 매트릭스를 따른다.
- 모든 핸드오프는 상태, 근거, diff 범위, 리스크 노트를 포함한다.
- 모든 핸드오프는 다음 오너(리뷰어/검증/릴리스 레인)를 명시한다.
- 생성 후 14일이 지난 worktree는 머지/정리 여부를 점검한다.
- 마이그레이션, 인증, 결제, 보안 민감 변경은 검증 레인을 필수로 둔다.

이렇게 명문화하면 worktree 사용이 개인 취향이 아니라 팀 운영 계약이 됩니다.

빠른 체크리스트

worktree를 만들기 전에:

• 이 작업은 한 번의 짧은 세션보다 길어질 가능성이 높은가?
• 현재 작업과 브랜치 격리가 필요한가?
• 작업명과 종료 조건을 명확히 줄 수 있는가?

worktree를 삭제하기 전에:

• 브랜치가 머지되었거나 안전하게 push 되었는가?
• lint/tests 검증과 근거를 남겼는가?
• 관련 PR/이슈가 연결되었는가?

worktree는 Codex의 병렬 실행을 깔끔하게 만드는 가장 실전적인 습관 중 하나입니다.