공식 참고 자료: Review · Automations · Worktrees · How OpenAI uses Codex
커리큘럼 흐름
- Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
- Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
- Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
- Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
- Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
- Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
- Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
- Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영 ← 현재 문서
- Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
- Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
- Codex 검증 루프 — 머지 전에 동작을 증명하기
- Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
- Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
- Codex 팀 딜리버리 플레이북 — 중급 레인 운영
- Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
- Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
- Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
- Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
- Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
- Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
- Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기
이 문서에서 참고한 공식 문서
- review pane이 기본적으로 uncommitted changes를 보는 방식 — Review
- 반복 작업을 cadence와 실행 환경으로 스케줄링하는 automations — Automations
- worktree를 이용해 충돌 없이 병렬 작업하는 방법 — Worktrees
- Best-of-N과 반복 엔지니어링 운영 — How OpenAI uses Codex
Codex의 진짜 레버리지는 반복 작업에서 나온다
한 번 잘 써보는 것보다 더 중요한 건, 반복 가능하게 운영하는 것입니다. 리뷰, 반복 점검, 문서 업데이트, 안전한 리팩토링처럼 경계가 분명한 일에서 Codex는 특히 강합니다.
좋은 운영은 “AI가 무엇을 할 수 있나”보다 어떤 단계까지 맡기고 어디서 사람이 다시 본다를 정하는 일에 가깝습니다.
/review를 습관으로 만들자
Review 문서에 따르면 review pane은 Git 저장소 상태를 기준으로 보여줍니다. 기본 초점은 uncommitted changes이고, 필요하면 아래 범위로 바꿀 수 있습니다.
- base branch 대비 전체 변경
- 마지막 assistant turn 변경
- 로컬에서는 staged / unstaged 구분
이건 단순 UI 팁이 아니라, Codex가 만든 diff를 “내가 지금 실제로 머지할 것” 기준으로 다시 보게 하는 장치입니다.
review pane scope를 언제 어떻게 써야 하나
| review 범위 | 언제 보기 좋은가 | 확인할 것 |
|---|---|---|
| uncommitted changes | 방금 끝낸 작업 직후 | 의도치 않은 파일 수정, debug 잔여물 |
| staged only | commit 직전 | 실제로 올릴 diff만 남았는지 |
| unstaged only | review 후 수정 반복 중 | 방금 손본 보정 diff가 과한지 |
| last assistant turn | 긴 세션 중 최근 수정만 보고 싶을 때 | 마지막 요청이 scope를 벗어나지 않았는지 |
| base branch diff | PR 전 최종 검토 | 누적 변경 전체가 위험하지 않은지 |
실무적으로는 작게 볼 때와 크게 볼 때를 구분하세요. 작업 중에는 last assistant turn이나 unstaged를 보고, 머지 전에는 base branch diff로 넓게 보면 됩니다.
추천 review 루틴
작업 후 루틴을 짧게 만들면 좋습니다.
- 구현 완료
- lint/build/test
/review로 최근 변경 범위 확인- scope가 맞는지 보고 stage / revert / 수정 반복
- commit 또는 PR 생성 전 base branch diff 재확인
문서 한 장을 고치는 작은 작업도 이 루틴을 붙이면 품질이 훨씬 안정됩니다.
review가 특히 중요한 변경
아래는 사람이 한 번 더 반드시 봐야 합니다.
- API 계약 변경
- 스키마, migration, 배포 설정
- auth / billing / security 로직
- 사용자 노출 copy
- 대규모 삭제나 rename
- CI 설정, automation 프롬프트, 배포 조건 변경
Codex는 초안을 빠르게 만들 수 있지만, irreversible judgment는 여전히 사람 몫입니다.
worktree는 병렬성과 안전을 함께 준다
Worktrees 문서는 Codex app에서 여러 독립 작업을 같은 프로젝트 안에서 병렬로 다루게 해준다고 설명합니다. 자동화도 Git 저장소라면 dedicated background worktree에서 돌릴 수 있습니다.
이게 좋은 이유:
- 메인 작업 트리와 충돌 감소
- 실험성 작업을 격리
- 장시간 작업과 자동화를 분리
- 병렬 브랜치 작업을 더 안전하게 운영 가능
즉, worktree는 “속도 기능”이면서 동시에 “충돌 방지 기능”입니다. 서브에이전트가 병렬 추론이라면, worktree는 격리된 병렬 파일 작업입니다.
언제 subagent보다 worktree가 더 맞나
아래처럼 Git 수준 격리가 중요하면 worktree가 더 적합합니다.
- 서로 다른 브랜치 초안을 병렬로 만들 때
- background automation이 장시간 수정할 수 있을 때
- main worktree를 깨뜨리지 않고 실험해야 할 때
- 검증 중 생성되는 산출물이 커서 작업 디렉터리를 분리하고 싶을 때
반대로 단순 탐색, 비교, 아이디어 분할은 Codex 서브에이전트가 더 가볍습니다. 정리하면:
- subagent = 병렬 탐색/분석/비교
- worktree = 격리된 병렬 실행과 Git 충돌 방지
automations는 안정화된 흐름에만 올려라
Automations 문서는 반복 작업을 background에서 스케줄링할 수 있다고 설명합니다. project, prompt, cadence, execution environment를 선택하고, skill도 함께 호출할 수 있습니다.
하지만 중요한 순서가 있습니다.
- 수동으로 여러 번 해 봄
- 작업 shape를 Skills로 고정
- 검증 명령을 기계적으로 판단 가능하게 만듦
- worktree나 격리 환경에서 반복 실행해 봄
- 그 다음에 automation으로 승격
즉, manual workflow가 안정화되기 전에는 automation을 올리지 마세요. 불안정한 절차를 자동화하면 실패만 더 빨리 반복합니다.
automation 후보와 비후보
좋은 automation 후보:
- 최근 커밋 요약
- release note 초안 생성
- docs drift 점검
- 버그 후보 스캔
- 낮은 위험도의 정적 점검
- 반복적인 문서/메타데이터 정리
좋지 않은 후보:
- 매번 설계 판단이 필요한 기능 개발
- 시크릿/운영 권한을 크게 요구하는 변경
- 실패 시 영향이 큰 배포 단계 직접 실행
- 사람이 승인해야 하는 copy나 정책 변경을 자동 반영하는 작업
CI/CD와 Codex를 연결하는 현실적인 방식
가장 실용적인 패턴은 완전 자율 merge가 아니라 반복 엔지니어링 자동화입니다.
예:
- PR diff에 대해 리뷰 초안 생성
- 특정 라벨이 붙은 issue를 정형 작업으로 처리
- 대량 문서 수정 초안 생성
- 테스트 누락 영역 후보 제안
- runbook이나 changelog 드리프트 감지
핵심은 “머지까지 자동화”보다 사람 검토 전 단계의 기계적 작업을 자동화하는 데 있습니다.
CI/CD에는 human gate를 남겨둬라
CI가 초록불이라고 해서 바로 merge나 배포까지 넘기면 안 되는 종류의 변경이 있습니다. 특히 아래는 human gate를 두는 편이 좋습니다.
- 배포 설정 변경
- 운영 권한, 시크릿, 승인 정책 변경
- 고객 노출 문구나 가격 정책 변경
- migration / rollback 설계가 필요한 변경
- 보안 민감 영역 변경
실전 패턴은 대개 이렇습니다.
- Codex가 초안 생성 또는 반복 작업 수행
- CI가 정적 검증과 테스트 수행
- 사람이
/review, PR review, 환경별 승인으로 최종 판단 - 그 후 merge 또는 deploy
좋은 운영은 AI를 불신해서 막는 것이 아니라, 비가역 구간 앞에 인간 판단을 남기는 것입니다.
skill + automation + worktree + /review 조합
반복 작업이 안정되면 아래 조합이 강합니다.
- skill = 절차 캡슐화
- automation = 스케줄링
- worktree = 격리
/review= 최종 검토
이 네 가지가 붙으면 Codex는 개인 비서가 아니라 반복 엔지니어링 시스템에 가까워집니다.
조합 1: skill + /review
문서 frontmatter 정리, changelog 초안, 릴리즈 노트 정리처럼 사람이 마지막으로 문장을 봐야 하는 작업에 적합합니다.
조합 2: skill + automation
입출력이 안정된 주간 보고, 커밋 요약, docs drift 점검에 적합합니다. 단, 사람이 여러 번 수동으로 돌려 안정성을 확인한 뒤에만 올리세요.
조합 3: skill + worktree + /review
메인 브랜치를 건드리기 전에 별도 worktree에서 초안을 만들고, review pane으로 최종 범위를 확인하는 흐름입니다. 문서 대량 수정, 코드모드, 리팩터링 보조 작업에 유용합니다.
조합 4: skill + automation + worktree + human gate
가장 운영적인 형태입니다. 자동화가 dedicated worktree에서 초안을 만들고, 사람이 /review와 PR review로 승인합니다. 릴리즈 노트, dependency change 요약, 티켓 triage 같은 반복 업무에 잘 맞습니다.
도입 단계는 천천히 올려라
1단계
로컬 작업 + /review
2단계
skill화된 반복 작업 도입
3단계
worktree 기반 병렬 작업
4단계
automation / background 운영
5단계
좁은 범위의 CI/CD 통합
이렇게 가면 문제를 어디서 통제해야 하는지 계속 보입니다. 무엇보다, automation을 뒤로 미루면 실패 원인을 찾기가 쉬워집니다.
자동화를 너무 일찍 올리고 있다는 신호
- 실행할 때마다 프롬프트를 손으로 다시 고쳐야 한다
- 결과물이 실행마다 들쭉날쭉하다
- 리뷰어가 무엇을 봐야 할지 모른다
- 탐색, 구현, 최종 판단이 한 run 안에 섞여 있다
- 한 번 실패했을 때 영향 범위가 너무 넓다
이 신호가 여러 개 보이면 cadence를 늘리기보다, task design / skill / manual loop를 먼저 다듬는 편이 낫습니다.
운영 체크리스트: 자동화 전에 확인할 것
- task shape가 충분히 좁은가?
- sandbox와 approval이 맞는가?
- 검증 명령이 기계적으로 통과/실패를 판정하는가?
- 결과를
/review나 human gate로 다시 볼 수 있는가? - main worktree와 충돌하지 않게 격리되는가?
- 실패 시 누가 어디서 중단 결정을 내리는가?
- rollback이 필요한 경우 책임 경계가 명확한가?
바로 써먹는 운영 레시피
반복 문서 업데이트
- skill로 입력 형식과 산출물 형식 고정
- worktree에서 초안 생성
- lint/검증 스크립트 실행
/review로 문장과 링크 확인- 사람 승인 후 merge
PR triage 자동화
- issue/PR 메타데이터를 읽는 절차를 skill에 고정
- automation이 주기적으로 실행
- dedicated worktree에 결과 저장
- 사람이 review 후 라벨/코멘트/후속 조치 결정
장시간 리팩터링 보조
- main worktree는 개발자가 유지
- 별도 worktree에서 Codex가 후보 diff 생성
- 필요한 경우 subagent로 병렬 탐색
- 결과를 base branch diff와
/review범위로 재검토 - 작은 단위로 cherry-pick 또는 수동 통합
마지막 운영 체크리스트
자동화나 리뷰 흐름을 올리기 전 아래를 다시 확인하세요.
- task shape가 충분히 좁은가?
- 인간 승인 없는 자동 실행이 비가역 단계까지 가지 않는가?
- skill, worktree, automation의 역할이 섞여 있지 않은가?
- 검증과 review 범위가 팀에 의해 이해 가능한가?
- main worktree와 background worktree의 책임이 분리되어 있는가?
흔한 실패 패턴
“automation이 그럴듯한 잡음만 만든다”
프롬프트가 너무 넓거나 성공 기준이 기계적으로 판정되지 않을 때 자주 생깁니다.
“background run이 active work와 자꾸 엉킨다”
dedicated worktree가 없거나 범위가 너무 넓을 가능성이 큽니다.
“review가 너무 비싸다”
한 번의 검증 루프에 담기엔 작업이 너무 컸거나 constraints가 약했을 수 있습니다.
“팀이 automation이 어디까지 결정해도 되는지 모른다”
human gate가 문서화되지 않았거나 skill/automation 역할이 섞여 있을 가능성이 큽니다.
빠르게 기억할 운영 조언
여섯 가지만 기억한다면 아래를 기억하세요.
/review범위는 질문에 맞게 고른다.- worktree는 격리와 병렬성 둘 다를 위한 도구다.
- manual workflow가 boring해진 뒤에만 automation으로 올린다.
- merge, deploy, migration 같은 큰 결정에는 human gate를 남긴다.
- skill + automation + worktree +
/review를 함께 설계하면 반복 가능성이 커진다. - 좋은 CI/CD Codex 운영은 판단을 대체하지 않고 판단을 더 빠르게 만든다.
Codex를 오래 잘 쓰는 팀은 “가장 강한 권한”을 가진 팀이 아니라, review와 자동화를 적절한 경계 안에서 반복하는 팀입니다.