코덱스 툴 사용법 15: Worktrees로 배경 작업 격리하기 | DAKER 커뮤니티
코덱스 툴 사용법 15: Worktrees로 배경 작업 격리하기
Codex에게 기능 하나를 맡기고 싶은데, 지금 내 로컬 checkout에는 하던 작업이 남아 있을 때가 있습니다. 이때 바로 같은 폴더에서 실행하면 Codex가 만든 diff와 내 미완성 diff가 섞입니다. 테스트 서버, IDE, 브라우저 상태까지 같이 쓰면 어디서 문제가 생겼는지 구분하기 어려워집니다.
Codex app의 Worktree는 이 문제를 줄이기 위한 작업 표면입니다. OpenAI Codex 문서 기준으로 worktree는 Git worktree를 사용해 같은 저장소의 별도 checkout을 만들고, Codex가 독립 작업을 진행할 수 있게 합니다. 자동화도 Git 저장소에서는 local project 또는 전용 background worktree 중 하나를 선택해 실행할 수 있습니다.
한 줄 요약
Worktree는 Codex를 더 똑똑하게 만드는 기능이 아니라, 내 foreground 작업과 Codex의 background 작업을 섞이지 않게 하는 장치입니다.
Local과 Worktree의 차이
Codex 문서의 용어를 단순화하면 이렇게 볼 수 있습니다.
표면 | 의미 | 잘 맞는 상황 |
|---|---|---|
Local checkout | 내가 직접 열어 둔 원래 저장소 | 지금 바로 IDE, 서버, 브라우저로 확인해야 하는 작업 |
Worktree | Git worktree 기반의 별도 checkout | 내 작업을 건드리지 않고 Codex가 배경에서 진행할 작업 |
Handoff | thread와 코드를 Local 또는 Worktree로 옮기는 흐름 | 배경 작업을 내 로컬에서 직접 검토해야 할 때 |
Permanent worktree | 오래 유지할 별도 worktree 프로젝트 | 장기 실험, 별도 브랜치 환경, 반복 검증 환경 |
Worktree는 복사본처럼 보이지만 단순 복사 폴더가 아닙니다. Git worktree를 기반으로 하므로 저장소 metadata를 공유하고, branch checkout 규칙도 Git의 제한을 따릅니다.
언제 Worktree를 쓰나
기준은 간단합니다. “내 현재 checkout을 더럽히면 안 되는가?”와 “검증을 내 로컬 환경에서 해야 하는가?”입니다. 둘 다 예라면 Worktree에서 시작하고 Handoff로 가져오는 방식이 좋습니다.
Worktree가 특히 좋은 작업
작업 | Worktree가 좋은 이유 | 주의점 |
|---|---|---|
기능 초안 만들기 | 내 로컬 변경과 섞이지 않음 | 나중에 Handoff 또는 branch 생성 필요 |
큰 리팩터링 탐색 | 실패해도 Local을 건드리지 않음 | 테스트 환경이 worktree에도 있어야 함 |
자동화 초안 생성 | 반복 실행 결과를 격리할 수 있음 | 너무 자주 실행하면 worktree가 늘어남 |
라이브러리 업그레이드 실험 | lockfile, build cache 변화를 분리 | 설치/빌드 시간이 별도로 듦 |
대안 구현 비교 | 여러 thread를 병렬로 진행 가능 | 어떤 결과를 채택할지 사람이 결정해야 함 |
반대로 지금 켜 둔 로컬 서버 하나에서만 재현되는 UI 버그, 개인 .env가 필요한 수동 QA, 파일 하나 고치는 작은 수정은 Local이 더 빠를 수 있습니다.
결정 그리드
Worktree 선택은 “격리 필요성”과 “검증 마찰”의 tradeoff입니다.
격리 필요 | 검증 마찰 | 추천 |
|---|---|---|
높음 | 낮음 | Worktree에서 끝까지 진행 |
높음 | 높음 | Worktree에서 만들고 Handoff로 Local 검증 |
낮음 | 낮음 | Local에서 바로 진행 |
낮음 | 높음 | Local 유지, 작은 단계로 진행 |
좋은 기준은 “Codex가 실패해도 내 현재 작업이 안전한가?”입니다. 실패 비용이 크면 Worktree가 맞고, 이동 비용이 더 크면 Local이 맞습니다.
Handoff를 언제 쓰나
Codex 문서는 Handoff를 Local과 Worktree 사이에서 thread와 코드를 옮기는 흐름으로 설명합니다. 중요한 이유는 Git branch가 동시에 여러 worktree에서 checkout될 수 없기 때문입니다. Codex가 Handoff를 처리하면 그 Git 이동 절차를 안전하게 다룹니다.
Handoff가 필요한 순간은 보통 세 가지입니다.
Worktree에서 만든 결과를 내 IDE에서 직접 보고 싶을 때
Local에서만 실행 가능한 앱 서버나 브라우저 QA가 필요할 때
배경 작업을 foreground로 가져와 이어서 협업하거나 커밋하고 싶을 때
반대로 worktree 안에서 테스트와 리뷰가 충분하다면, worktree에서 branch를 만들고 PR로 이어가도 됩니다.
자동화와 Worktree
Codex Automations 문서는 Git 저장소에서 자동화를 local project 또는 dedicated background worktree에서 실행하도록 선택할 수 있다고 설명합니다. Worktree는 자동화 결과를 내 미완성 작업과 분리해 주지만, 공짜는 아닙니다.
자동화 실행 위치 | 장점 | 위험 |
|---|---|---|
Local project | 결과가 바로 내 checkout에 생김 | 내가 작업 중인 파일과 섞일 수 있음 |
Background worktree | 반복 작업이 격리됨 | 의존성 설치, 빌드 cache, worktree 정리 필요 |
매일 글 초안을 만들거나 정기 리포트를 생성하는 자동화는 worktree와 잘 맞습니다. 반대로 “현재 열려 있는 브라우저 세션으로 게시까지 완료”처럼 로그인된 UI 상태가 핵심인 작업은 Local/Chrome 표면과 이어지는 검증이 필요할 수 있습니다.
바로 복사할 프롬프트
Worktree를 쓸 때는 환경 선택과 Handoff 기준을 같이 적는 편이 좋습니다.
이 작업은 내 Local checkout과 분리해서 Codex app Worktree에서 시작해줘.
목표:
- <기능/수정/조사 목표>
규칙:
- 내 Local의 미완성 변경과 섞이지 않게 한다.
- worktree 안에서 가능한 테스트를 먼저 실행한다.
- 검증에 내 로컬 서버나 브라우저 세션이 필요하면 Handoff가 필요한 이유를 요약한다.
- 결과는 변경 파일, 실행한 테스트, 남은 위험으로 보고한다.
- branch를 만들기 전에 diff가 작고 검토 가능한지 확인한다.자동화라면 이렇게 더 구체화할 수 있습니다.
이 자동화는 Git 저장소에서 background worktree로 실행한다.
매 실행마다 초안을 만들고 payload를 생성한다.
완료 전 공개 API로 게시 결과를 확인한다.
실패하면 blocker와 수동 복구 절차를 memory에 남긴다.선임 엔지니어 관점
Worktree는 병렬 작업의 흥분보다 운영 위생에 가깝습니다. Codex가 여러 일을 동시에 잘할수록, 어떤 일이 어느 checkout에서 일어났는지 분리하는 능력이 더 중요해집니다.
처음에는 큰 기능 개발, 리팩터링 실험, 정기 자동화처럼 실패해도 Local을 건드리면 안 되는 작업부터 Worktree로 보내세요. 반대로 작은 수정과 로컬 상태 의존 QA는 Local에 두세요. 좋은 워크플로우는 모든 일을 배경으로 보내는 것이 아니라, foreground와 background의 경계를 의식적으로 고르는 것입니다.
참고: OpenAI Codex manual의 Worktrees, Automations, Local environments 섹션을 기준으로 작성했습니다.