Codex 위임 — 세션 유지 + 구조화 완료보고

이 스킬은 "어떻게 넘기는가"(메커니즘)만 다룬다. 나머지는 위임한다.

• 누가 할지 가르는 법 → [[role-split]] (이 스킬로 오기 전 단계)
• 지시서를 쓰는 법 → [[task-brief]]
• 받은 결과를 검증하는 법 → [[work-review]]

왜 이 방식인가

에이전트는 못 하면 멈추는 게 아니라 그럴듯하게 틀린 걸 내놓는다. 자유 서술로
"완료했습니다"를 받으면 검증할 수가 없다. 그래서 두 가지를 강제한다.

1. 같은 세션 유지 — 매번 새 세션이면 맥락을 다시 설명해야 하고, Codex는 앞 턴에
   자기가 뭘 했는지 모른다. thread_id를 붙들고 이어간다.
2. 구조화 완료보고 — consulted_sources, modified_files, commands_run,
   tests.ran, unfinished를 JSON 스키마로 강제한다.
   특히 unfinished가 비어 있지 않으면 그게 진짜 상태다.
   • 🔴 consulted_sources 는 "무엇을 읽고 그렇게 판단했나" 다(2026-09-17 추가).
     산출물만 받으면 결론은 보이는데 근거가 안 보인다 — 검토하는 쪽이 같은 자료를 열어
     판단을 되짚을 수 있어야 한다. 지시서 자체는 여기 넣지 않는다.
   • 스키마는 additionalProperties:false 다. 필드를 늘리려면 스키마를 먼저 고쳐야
     Codex 가 적을 자리가 생긴다. 규칙 문서에만 쓰면 아무 일도 일어나지 않는다.

받은 보고를 사용자에게 보일 때는 --table 을 쓴다(2026-09-17).

$PY "$S" report <작업명> --dir <작업디렉토리> --table

참고한 소스   | 소스 | 확인한 것 |
산출물        | 파일 | 크기 | 변경 |      ← 크기는 하네스가 실제 파일에서 읽는다
실행·검증     명령 N건 · 실패 M건 · 테스트 실행 여부
미완          있을 때만
작업 요약:     한 줄

🔴 JSON 을 손으로 표에 옮기지 마라. 옮기다 빠뜨리면 그게 곧 검토 누락이다.
blocked:true 면 맨 위에 경고가 먼저 나온다 — 그 경우 검토를 건너뛰고 사용자에게 직행한다.

작업 흐름

작업 명세 → 사용자와 논의 → 역할 구분
                              ├─ 설계·계획·조율 → Claude가 직접  ─┐
                              └─ 정밀 코드·모듈  → Codex(같은 세션) ┤→ 완료보고
                                    │                              │
                                    └─ blocked:true → 사용자에게 직행 (검토를 건너뜀)
                                                                   ↓
                                                            검토  ← work-review
                                        ├─ NO 재작업 → 작업 진행 단계로
                                        ├─ NO 재설계 → 역할 구분으로
                                        ├─ OK·Claude 몫  → 작업문서·skills 갱신 → 종료
                                        └─ OK·Codex 몫   → 문서·skills 갱신 하달
                                                            → Codex 결과 재검토
                                                              ├─ NO → 다시 하달
                                                              └─ OK → 종료

Claude가 직접 한 작업(설계·계획)도 동일하게 완료보고 → 검토를 거친다.
"내가 했으니 검토 생략"은 하지 않는다 — [[work-review]] §6.

Codex에게 문서·skill 갱신을 하달한 뒤에도 끝이 아니다. 하달 자체를 완료로 착각하지
않도록, 실제로 뭘 고쳤는지 재검토 루프를 한 번 더 거친다.

---

사용법

🔴 codex 명령을 직접 조립하지 마라. 헬퍼 스크립트가 CLI 함정을 흡수한다(§함정).
직접 조립했다가 resume 인자 위치 오류·모델 기본값 복귀·한도를 에러로 뒤늦게 인지 하는
실패가 반복됐다(2026-09-07~09).

PY="${CODEX_DELEGATE_PY:-python}"    # 필요하면 이 환경변수로 인터프리터 지정
D="${CODEX_DELEGATE_DIR:-$HOME/.claude/skills/codex-delegate/scripts}"   # 설치 위치가 다르면 이 변수로

0. 🔴 착수 전 — 사용량을 먼저 본다

$PY "$D/codex_usage.py" --dir <작업디렉토리>
# 종료코드  0 = 착수 가능 · 2 = 한도 임박(새 턴을 시작하지 마라) · 3 = 기록 없음

한도가 임박했으면 새 턴을 시작하지 않는다. 시작한 뒤 한도로 끊기면 그 턴의 토큰은
산출물 없이 사라진다(실측: 116,033 토큰 소모 · 산출물 0).

1. 위임·이어가기

# 새 작업 — 지시서는 반드시 파일로 (긴 지시서는 명령행 한도에 걸린다)
$PY "$D/codex_task.py" start <작업명> --dir <작업디렉토리> --prompt-file 지시서.md

# 같은 세션에 이어서 (검토 피드백, 추가 지시, 문서·skill 갱신 하달)
$PY "$D/codex_task.py" send  <작업명> --dir <작업디렉토리> --prompt-file 피드백.md

$PY "$D/codex_task.py" status <작업명> --dir <작업디렉토리>
$PY "$D/codex_task.py" report <작업명> --dir <작업디렉토리> --turn -1

--sandbox = read-only / workspace-write(기본) / danger-full-access.
조사·검토만 시킬 때는 read-only로 시작한다.

🔴 전달 성공은 종료 코드로 확인한다. 파이프에 먹이지 마라.
| tail 로 받으면 실패가 exit 0 으로 보인다(2026-09-03 실측 — 지시서가 가지 않았는데
성공으로 읽었다). ...; echo "EXIT=$?" 또는 파이프 없이 실행한다.

오래 걸리는 작업은 백그라운드로 돌린다. Bash 도구의 run_in_background를 쓰면
Codex가 끝나는 시점에 알림이 와서 대화가 자동으로 재개된다. 폴링할 필요 없다.

2. 🔴 한도로 끊기면 그 턴에 재개를 예약한다

한도 메시지에는 해제 시각이 적혀 있다(try again at 9:47 PM). 그것을 읽은 그 턴에
재개를 예약한다. 나중에 하지 않는다 — 나중이 없어서 최대 14시간을 방치한 적이 있다.

상태 관리

<작업디렉토리>/.claude-codex/state.json

tasks.<작업명> = { thread_id, work_dir, sandbox, created_at, turns[] }
turns[] = { at, kind(start|send), events(로그경로), report(완료보고 JSON) }

작업마다 세션이 분리되므로 여러 작업을 병행해도 맥락이 섞이지 않는다.
프롬프트 원문과 이벤트 로그는 .claude-codex/<작업명>/ 에 타임스탬프로 남는다.

⚠️ modified_files는 세션 전체 누적이다(1턴에 고친 파일이 3턴 보고에도 나온다).
이번 턴에 무엇이 바뀌었는지 보려면 git status나 파일 수정시각과 대조한다.

---

실행 중 감시 — 10분마다 로그를 본다

위임하고 완료 알림만 기다리면 실패를 늦게 안다. 이벤트 로그는 실시간으로 쌓이므로
지금 무엇을 하고 있는지 볼 수 있다. 병렬로 여러 작업이 돌면 전부 본다.

$PY "$D/codex_watch.py" --dir <작업디렉토리> --once                      # 지금 한 번
$PY "$D/codex_watch.py" --dir <작업디렉토리> --interval 600 \
         --out <프로젝트>/results/logs/codex_watch.log                    # 10분마다, 로그에 축적

작업명을 주지 않으면 .claude-codex/ 아래 전부를 훑는다.
로그는 프로젝트 폴더에 남긴다 — 나중에 "언제부터 막혔나"를 되짚을 수 있다.

=== sim-cell   (4320초 전 기록 · events_20260831_160832.jsonl)
    명령 38 · 파일변경 20 · 웹검색 0 · agy 2 · 메시지 8
    컨텍스트 204,290/258,400 (79%) · 5시간한도 92% (47분 뒤 초기화) · 주간 14%   [07:24:42 UTC 기준]
    ⚠ 5시간 한도 92% — 곧 끊긴다. 새 턴을 시작하지 마라

컨텍스트·한도 값은 codex exec --json 스트림에 없다. Codex가 따로
~/.codex/sessions/<날짜>/rollout-*-<thread_id>.jsonl 에 남기는 것을 감시기가 읽는다.

🔴 대괄호 안 시각을 보라 — 마지막 모델 호출 시점의 값이지 지금 값이 아니다.
세션이 몇 시간 쉬었다면 5시간 창은 이미 리셋됐고, 그때는 (지난 창의 값 — 현재값 아님)
이라고 찍히며 한도 경고도 올리지 않는다. 하루 전 92%를 보고 "곧 끊긴다"고 말하면 안 된다.

무엇을 방황으로 보는가

신호	의미
같은 명령 4회 이상 반복	같은 벽에 부딪히는 중. 읽기 명령 + 최근 파일 변경이면 검증 루프이므로 제외
명령 20건 이상인데 파일 변경 0	조사만 하고 쓰지 못하고 있다
15분 넘게 기록 없음 (완료보고 없이)	멈췄거나 아주 긴 작업
웹검색 12회 이상에 산출물 0	찾는 것이 존재하지 않을 수 있다
🔴 웹검색 이 1 이상	규약 위반이다. 검색은 agy 헤드리스로만 한다 — 아래 §검색 규약
🔴 같은 파일에 apply patch 반복인데 그 파일의 mtime 이 안 바뀜	내용이 같아 실질 변화가 0이다. 쓰기 명령이라 위의 "검증 루프 제외" 조항에 걸리지 않는다
🔴 경과 시간에 비해 산출물 개수가 0	가장 확실한 신호 — 아래
blocked 보고	결정 요청이다. 즉시 확인한다

이건 확정이 아니라 "열어볼 이유"다. 신호가 뜨면 이벤트 로그의 최근 명령과
agent_message를 직접 읽는다. 판정은 사람이 한다.

⚠️ 감시기의 판정 기준을 바꾸면 그 자리에서 실제 로그에 돌려본다. 오탐이 네 번
나왔고 전부 정상을 이상으로 보거나 그 반대였다 — 완료된 작업에 "기록 없음" 경고,
래퍼 접두사 때문에 서로 다른 명령 12건이 하나로 뭉침, 종료 직전 검증 루프를 반복으로
오인, 지난 턴의 보고서가 남아 새 작업이 시작부터 "완료"로 보임.

🔴 진행의 증거는 산출물 개수뿐이다

로그가 자란다        ✗ 증거 아님 — 같은 패치를 43번 써도 174 KB → 360 KB 로 자란다
"진행 중" 자기보고   ✗ 증거 아님 — 실제로 그렇게 보고하면서 21분간 산출물이 0이었다
파일이 존재한다      ✗ 증거 아님 — mtime 이 멈춰 있었다
🔴 산출물을 직접 센다  ✅ 이것만이 증거다

감시할 때 로그를 읽기 전에 산출물부터 세라. ls | wc -l, 생성된 폴더 개수,
결과 파일의 mtime. 숫자가 안 늘면 로그가 아무리 활발해도 진행이 아니다.

🔴 검색 규약 점검 — 웹검색 칸과 agy 칸을 같이 본다

검색은 Antigravity(agy) 헤드리스로만 한다. Codex 자체 웹검색은 쓰지 않는다
(프로젝트 지침 문서의 원칙 — 실행자용 AGENTS.md·관리자용 CLAUDE.md 등).
검색 도구가 다른 프로젝트라면 그 도구 이름으로 바꿔 읽는다 — 요점은 도구가 아니라
"출처 확인 고리가 남는 경로로만 검색한다" 이다.

웹검색 0 · agy 3     ✅ 규약대로다
웹검색 5 · agy 0     🔴 위반. Codex 가 제 검색을 썼다
웹검색 0 · agy 0     검색이 필요 없는 작업이었는가? 지시서를 다시 본다

🔴 횟수가 적어도 봐주지 않는다. 한 번이라도 자체 검색을 쓰면 출처 확인 경로가
규약 밖으로 샌다 — 우리는 "인용 URL 을 전량 직접 열어봐야 근거가 된다"
([[work-review]] §2-1)를 지켜야 하는데, Codex 내장 검색은 그 확인 고리가 남지 않는다.

⚠️ 2026-09-14 이전 로그에는 이 규약이 없었으므로 소급 지적하지 마라.

🔴 감시의 진짜 목적은 지시서를 고치는 것이다

방황은 대개 실행자의 무능이 아니라 지시서에 없던 맥락 때문이다.
위반·방황을 발견하면 실행자를 탓하기 전에 지시서를 먼저 본다.
지시서에 그 문구가 없었다면 그건 관리자 잘못이다.

• 헤매는 지점을 발견하면 그때그때 문서에 남긴다. 끝난 뒤 몰아서 적으면 이유가 사라진다
• 지시서가 원인이면 지시서를 고치고 그 사실을 이력에 남긴다
• 개입은 막힌 것이 확인된 뒤에 한다. 조금 헤맨다고 바로 끼어들면 맥락만 흐트러진다

⚠️ "없다"와 "내가 못 간다"는 다른 문제다. 자산 서버 접근 실패로 멈춘 보고를 받았는데
자산은 멀쩡했고 실행 환경의 네트워크가 막혀 있었다. 실행자는 "없다"로 보고할 수밖에
없다 — 불가 보고는 이 둘을 갈라서 받는다([[work-review]] §3).

실행자가 실행 단계로 못 넘어가면 관리자가 실행해도 된다

같은 사례에서 스크립트 자체는 멀쩡했다. 중단시키고 그대로 직접 실행하자 30초 만에
21분간 못 하던 지점을 넘겼다.

역할 분담 위반이 아니다. 코드는 여전히 실행자의 산출물이고 관리자는 실행만 한다.
다만 실행 전에 코드를 읽어야 한다 — 안 읽고 돌리면 무엇을 돌렸는지 모른 채 결과를 받는다.

---

컨텍스트 압축을 우리가 고른 시점에 건다

Codex 는 컨텍스트가 한도의 88~89% 에 닿으면 알아서 압축하는데, 그 시점이 대개 작업
한복판이다. 무엇을 남길지 고를 수 없고, 잘린 자리가 중요한 결정 근처면 다음 턴에 같은
것을 다시 묻는다.

$PY "$D/codex_compact.py" --dir <작업디렉토리> --task <작업명> --dry-run   # 항상 먼저
$PY "$D/codex_compact.py" --dir <작업디렉토리> --task <작업명>
$PY "$D/codex_compact.py" ... --min-percent 60    # 기준 미만이면 알아서 건너뛴다

걸어라	걸지 마라
한 게이트·단계가 완료 보고까지 끝났을 때	작업이 진행 중일 때
검수를 통과시켜 다음 지시서로 넘어가기 직전	점유율이 50% 아래일 때 (얻는 것이 없다)
점유율이 70% 를 넘겼고 다음 턴이 길어질 때	방금 압축한 뒤

압축은 되돌릴 수 없다. 항상 --dry-run 으로 점유율을 먼저 본다.

codex exec 에는 압축 명령이 없어서, 이 스크립트는 codex app-server 를 띄워
initialize → thread/resume → thread/compact/start 로 말한다. 완료 신호는
thread/compacted 가 아니라 item/completed 의 type: "contextCompaction" 이다.

창이 곧 초기화되면 fast 모드로 태운다

fast 모드는 속도 1.5배 · 크레딧 2.5배라 평소엔 손해다. 그런데 5시간 창이 곧
초기화되면 남은 할당량은 어차피 사라진다. codex_task.py 가 실행 직전에 스스로
판단한다 — 기본 기준은 사용량 30% 이상 + 초기화까지 15분 이내, 둘 다 맞을 때만.

--no-fast-gate                 # 사용량과 무관하게 항상 표준 모드
--fast-min-percent 50          # 기준 사용량 조정
--fast-within-minutes 10       # 기준 시간 조정

한도는 계정 단위라 가장 최근 롤아웃을 본다(이 작업의 세션이 아니어도 된다).
기록이 없거나 창이 이미 지났으면 켜지 않는다 — 옛 창의 사용량으로 2.5배를 태우면 안 된다.

⚠️ 92%에서 켜면 남은 8%를 더 빨리 소진해 턴이 죽을 수 있다. 그 턴이 죽어도 아까울
것이 없을 때만 쓰는 설정이다 — 긴 작업을 새로 시작하는 자리에서는 --no-fast-gate.

---

완료 보고는 2층이다 — 섞지 말 것

같은 "완료 보고"라는 이름의 산출물이 두 개 있다. 역할이 다르므로 둘 다 필요하다.

	JSON 완료보고	마크다운 완료 보고서
정본	이 스킬의 --output-schema	[[codex-completion-report]] — 프로젝트에 더 구체적인 스킬이 있으면 그쪽 우선
목적	기계 검증 — 검토자가 필드로 대조	사람이 읽는 상세 기록 — 근거·수치·재현 방법
위치	.claude-codex/state.json 의 turns[].report	<프로젝트루트>/reports/YYYY-MM-DD_<작업명>/report.md
누가	스키마가 강제 (Codex가 못 빠뜨림)	Codex가 스킬에 따라 작성

JSON이 검토의 입구다. [[work-review]] §1의 필드 점검은 JSON을 전제로 한다.
마크다운 보고서만 오고 JSON이 없으면 검토 절차가 헛돈다 — 그때는 완료로 처리하지 말고
같은 세션에 JSON 보고를 다시 요구한다.

마크다운 보고서 경로는 JSON의 modified_files 에도 잡힌다. 두 산출물이 서로를
가리키므로, 한쪽만 있으면 그 자체가 이상 신호다.

권한 경계 — 양방향

Codex → 관리자 (실행자가 결정하려 할 때)

결정은 위임하지 않는다. 아키텍처·범위·우선순위·데이터셋/모델 선택은 사람과 관리자가
정하고, Codex에는 이미 정해진 것만 넘긴다. 선택지를 물으면 그럴듯한 답을 만들어낸다.

Codex가 스스로 멈추게 하려면 지시서에 트리거를 박아야 한다 —
[[task-brief]] §6의 문구를 지시서에 그대로 넣는다. 넣지 않으면 추측하고 진행한다.
보고에 blocked: true가 오면 대신 결정하지 말고 사용자에게 올린다.

관리자 → Codex (내가 구현하려 할 때)

반대 방향도 경계 침범이다. 다음이면 손을 떼고 이 스킬로 넘긴다.

• 모델 학습·평가 스크립트, 파이프라인, 대규모 실행 코드
• 프로젝트의 구현 코드 자산이 되는 것

예외는 문서 변환용 소규모 스크립트나 분석을 위한 즉석 조회다.
기준은 "결과물이 프로젝트의 구현 코드 자산인가". 애매하면 위임한다([[role-split]]).

🔴 관리자가 직접 구현한 구간에는 검수자가 없다. 한도로 막혀 직접 짰다면,
위임처가 살아난 뒤 가장 먼저 시킬 일은 다음 구현이 아니라 직전 구간의 검증이다
(실측: 그렇게 해서 보고서 수치 오류 12건 + 코드 결함 1건을 잡았다).

되돌릴 수 없는 작업(삭제·배포·외부 전송)은 --sandbox로 막거나 사람이 직접 한다.

함정 — 직접 CLI를 칠 때만 해당 (스크립트가 이미 처리함)

1. 옵션은 resume 앞에 와야 한다.
   codex exec resume <id> --sandbox ... → error: unexpected argument '--sandbox', exit 2.
   반드시 codex exec --sandbox ... resume <id> "<프롬프트>" 순서.
2. stdin을 닫아야 한다. 안 닫으면 Reading additional input from stdin...에서 대기한다.
3. thread_id는 --json 스트림 첫 줄에만 나온다.
   {"type":"thread.started","thread_id":"..."} — 놓치면 세션을 이어갈 수 없다.
4. 출력 스키마는 properties의 모든 키가 required에 있어야 한다.
   빠지면 invalid_json_schema 400. 선택 필드는 "type": ["string","null"]로 표현한다.
5. 턴이 실패하면 보고 파일이 아예 안 생긴다. null 보고를 성공으로 기록하면
   "요청은 갔는데 아무 일도 없었던" 상태를 완료로 착각한다.
6. Windows 콘솔 cp949 — 스크립트는 stdout을 UTF-8로 올린다. 직접 짤 때는 빠뜨리기 쉽고,
   이상을 보고하는 경로에서만 죽어 조용한 로그를 "문제 없음"으로 오해하게 만든다.

스크립트를 고칠 때

🔴 형제 파일을 전부 세어 본다. codex_task · codex_watch · codex_compact ·
codex_usage 는 한 계열이다. 같은 결함을 고치면서 하나를 빠뜨린 사고가 두 번 있었다 —
cp949 수정에서 정작 일을 넘기는 codex_task.py 만 빠졌고, 진입점(main()) 추가에서
codex_usage.py 만 빠져 출력 0줄·exit 0 으로 조용히 아무 일도 안 했다.

🔴 스킬이 시키는 명령은 한 번은 직접 돌려본다. "있다"와 "실행된다"는 다르다.
🔴 감시·경고 경로를 먼저 시험한다. 이상을 만났을 때의 경로가 가장 안 도는 경로다.

이력 (필수 기록)

• 생성일: 2026-08-26
• 업데이트 횟수: 9
• 최근 업데이트: 2026-09-17 (완료보고 consulted_sources · report --table 표 출력)
• 사용 이력 — 교훈은 전부 본문에 반영됐다. 여기는 언제 무엇이 바뀌었는지만 남긴다.
  • 2026-09-17 — 하네스에 report --table 을 넣었다. 관리자가 JSON 을 손으로 표에
    옮기면 형식이 어긋나고 빠뜨린 항목이 곧 검토 누락이 된다. 사용자 응답 형식
    (참고 소스 → 산출물 → 작업 요약)과 같은 모양으로 나온다.
  • 2026-09-17 — 완료보고에 consulted_sources 를 넣었다. 산출물(modified_files)은
    처음부터 있었으나 근거로 삼은 자료가 없어 검토하는 쪽이 판단을 되짚을 수 없었다.
    스키마가 additionalProperties:false 라 규칙 문서만 고쳤으면 Codex 가 적을 자리가 없었다 —
    schema/completion_report.json · AGENTS.md 작업내역 골격을 같이 고쳤다.
  • 2026-09-15 — 이력 102줄을 본문 규칙으로 녹이고 압축. 함께 두 가지를 고쳤다:
    ① CLAUDE.md 에만 있던 착수 전 사용량 확인이 스킬 §사용법에 없어 실질적으로 안 읽혔다 → 0번으로 신설
    ② 형제 스크립트 누락 사고 2건이 이력에만 묻혀 있어 §스크립트를 고칠 때로 승격.
    원본 SKILL.md.bak_20260915
  • 2026-09-14 — 검색 규약 변경("검색은 agy 에요. 이건 codex 에게도 해당됩니다").
    codex_watch.py 가 agy 호출을 세고 자체 web_search 1회 이상이면 규약 위반으로 깃발.
    원본 codex_watch.py.bak_20260914. 도구가 바뀌면 감시 기준도 같이 바꾼다.
  • 2026-09-11 — codex_usage.py 진입점 부재 발견·수정(CLI·startup_decision()·종료코드 0/2/3).
    원본 codex_usage.py.bak_20260911
  • 2026-09-07 — 21분·43회 patch·산출물 0 사고 → 방황 신호 2줄과 §진행의 증거 신설
  • 2026-09-03 — codex_task.py cp949 크래시로 지시서 전달 실패. 종료코드 파이프 함정 발견
  • 2026-09-01 — fast 게이트 신설. 한도 기록이 옛 창일 수 있다는 함정 → codex_usage.py 로 통합
  • 2026-08-31 — 롤아웃 파일에 컨텍스트·한도가 있음을 확인해 앞선 결론 3건을 뒤집음.
    codex_compact.py 신설. 도구가 stdout 으로 주는 것이 그 도구가 아는 것의 전부가 아니다
  • 2026-08-28 — §실행 중 감시·codex_watch.py 신설(10분 주기·병렬이면 전부)
  • 2026-08-27 — 워크플로우 정의에 맞춰 흐름도 갱신(blocked 직행·NO 2분기·재검토 루프)
  • 2026-08-26 — 신규 생성. 지시서·검증을 [[task-brief]]·[[work-review]] 로 분리하고 메커니즘만 남김