Codex 플러그인 워크플로우 (시범 — 보류 상태로 이관)

🔴 시범이 보류된 상태로 이관됐다. 켜기 전에 아래 체크리스트를 통과시켜라.
프로젝트 지침의 워크플로우 스위치가 기본값(codex-delegate)이면 이 스킬은 쓰지 않는다.
stop-review-gate 도 함께 꺼 두는 것이 기본이다(§6 — 모든 턴을 소모한다).
지금 위임할 일이면 [[codex-delegate]] 로 간다.

🔴 재개 체크리스트 — 이 넷을 통과하기 전에는 다시 켜지 마라

시범 기간에 위임은 0건이었고 게이트만 4건 돌았다. 취지의 본체는 실행되지 않았다.
그대로 재개하면 같은 것을 또 재게 된다.

[ ] 1. 사용자가 재개를 지시했는가          — 보류는 사용자 판단이었다
[ ] 2. §취지 대조 를 읽었는가              — 이 스킬은 취지와 어긋나 있었다(아래)
[ ] 3. 시범의 정의를 다시 잡았는가
       "지시서 없이 transfer + rescue 로 위임 1건 → 기존 지시서 방식과 결과 비교"
[ ] 4. Codex 한도에 여유가 있는가          — 게이트를 켜면 관리자의 모든 턴이
                                            Codex 턴을 하나씩 먹는다(§6, 실측)

⚠️ 2번이 핵심이다. 사용자가 대체하려던 것은 "지시서-보고서 문서 왕복" 인데
이 스킬 §2 는 "계약을 없애지 마라" 로 그 대체 대상을 유지한다고 못박고 있다.
둘 중 무엇을 택할지부터 사용자와 정한 뒤 재개한다.

🔴 이것은 [[codex-delegate]] 의 복제·개조판이다. 기존 워크플로우를 대체하지 않는다.
둘은 공존하며, 어느 것을 쓰는지는 프로젝트 CLAUDE.md 의 스위치가 정한다.
별로면 스위치를 되돌리면 끝이다 — 기존 스킬과 스크립트는 그대로 살아 있다.

왜 만들었나

기존 방식에서 실제로 겪은 실패다(2026-09-08~09).

resume 인자를 잘못된 위치에 둬서 실행 실패
resume 시 모델이 기본값으로 되돌아간 것을 로그를 보고서야 발견
한도 소진을 사용량 도구가 아니라 에러 메시지로 뒤늦게 인지
로그를 grep 으로 폴링하며 진행을 확인
관리자가 직접 짠 코드에 검수자가 없었다

🔴 앞의 넷은 도구가 없어서가 아니라 있는 도구를 안 써서 생겼다.
codex_task.py 가 있었는데 2026-09-03 이후 안 쓰고 CLI 를 직접 조립했다.
관리자가 기억해야 작동하는 절차는 신뢰할 수 없다 — 그래서 슬래시 명령으로 옮긴다.

역할은 바뀌지 않는다

사용자 ↔ 관리자(Claude)   대화·방향 결정        ← 그대로
관리자                     맥락·계약·판단·문서화  ← 그대로
Codex                      구현                  ← 그대로
                          + 리뷰                 ← 추가되는 부분

바뀌는 것은 호출 방식과 검증 위치뿐이다.

무엇을 플러그인에 넘기고 무엇을 남기나

	담당	비고
위임 호출	/codex:rescue	스레드 관리 자동
진행 확인	/codex:status · /codex:result	로그 grep 폴링 없앰
중단	/codex:cancel
맥락 전달	/codex:transfer	🔴 구현 위임에만. 검증에는 쓰지 마라(아래 §검증)
코드 리뷰	/codex:review · /codex:adversarial-review	읽기 전용이 기본
자동 검문	stop-review-gate	⚠️ 모든 턴에 발동한다(아래 §6 정정)
계약(지시서)	관리자가 직접 작성 — 유지	완료기준·금지사항·중간게이트
사용량 확인	codex_usage.py — 유지	플러그인에 없는 기능
Codex 세션 압축	codex_compact.py — 유지	플러그인에 없는 기능

절차

1. 착수 전 — 사용량부터 본다

PY="${CODEX_DELEGATE_PY:-python}"
$PY "$HOME/.claude/skills/codex-delegate/scripts/codex_usage.py"

한도가 임박했으면 새 턴을 시작하지 않는다. 턴 중간에 끊기면 산출물이 0 일 수 있다.

2. 계약을 쓴다 — 짧게

지시서는 여전히 파일로 남긴다. 다만 맥락을 다시 기술하지 않는다(그건 transfer 몫).

목표        한 문단
완료 기준   "돌렸다"가 아니라 "파일이 생겼고 열린다". 체크리스트로
금지사항    바꾸면 안 되는 것 · 승인 범위 밖인 것
중간 게이트  착수 전에 한 번에 보고할 항목
진행 기록   PROGRESS.md 를 **작업 시작 직후 먼저** 만들 것

🔴 계약을 없애지 마라. 턴이 도는 중에는 개입할 수 없으므로 처음에 다 넣어야 한다.
승인 범위를 지킨 것도(5,000회에서 멈춤), 잘못된 지시를 되물은 것도 계약이 있었기 때문이다.

3. 맥락을 넘긴다 — 구현 위임일 때만

/codex:transfer

현재 대화를 Codex 스레드로 이전한다. 왜 하는지를 알면 Codex 가 스스로 판단한다 —
실제로 관리자의 잘못된 지시(gradient accumulation)를 Codex 가 맥락에서 잡아냈다.

4. 위임한다

/codex:rescue --background <작업 요청 + 계약 파일 경로>
/codex:status
/codex:result

오래 걸리는 작업은 --background. 진행은 status 로 본다.

5. 🔴 검증은 맥락을 주지 않는다

/codex:review              변경분 읽기 전용 리뷰
/codex:adversarial-review  설계·가정까지 압박 검증

⚠️ 검증에는 transfer 를 쓰지 마라. 배경·가설·기대치를 주면 작업을 만든 것과 같은
가정으로 검증하게 되어 맹점을 그대로 통과시킨다.

구현 위임   맥락 많이   왜 하는지 알아야 스스로 판단한다
검증 위임   맥락 적게   diff 와 완료기준만.  다른 가정으로 봐야 값이 있다

리뷰어에게 쓰기 권한을 주지 않는다. 플러그인 review 는 읽기 전용이 기본이다.

6. 관리자가 코드를 만졌으면 검문을 받는다

node "$CLAUDE_PLUGIN_ROOT/scripts/codex-companion.mjs" setup --enable-review-gate

🔴 정정(2026-09-11 실측). 앞서 여기 적혀 있던 "코드를 고친 턴에만 발동하고
평소에는 부담이 없다" 는 틀렸다.

hooks.json      Stop -> stop-review-gate-hook.mjs   조건 없음, timeout 900s
훅 본문 184줄    git diff·변경 감지 분기가 없다
"코드를 고쳤을 때만 보라" 는 훅의 분기가 아니라 Codex 에게 주는 프롬프트 문장이다
기록 4/4        문서·보고 턴인데도 Codex job 생성 (10s / 28s / 71s / 129s)

즉 관리자의 모든 턴이 Codex 턴을 하나씩 소모한다. 한도가 빠듯하면 켜지 마라.
끄는 명령: ... codex-companion.mjs setup --disable-review-gate

🔴 왜 필요한가: 2026-09-09 야간에 Codex 한도로 관리자가 직접 구현했고 검수자가 없었다.
한도 해제 후 Codex 에 검증을 맡겨 보고서 수치 오류 12건 + 코드 결함 1건을 찾았다.
그건 즉흥 대응이었고, 이 게이트는 그것을 상시화한다.

그대로 가져오는 것 — [[codex-delegate]] 에서

호출 방식만 바뀌었을 뿐 아래는 전부 유효하다. 그 스킬을 함께 읽는다.

진행의 증거는 산출물 개수뿐이다      방황 판정
완료 보고는 2층이다                  섞지 말 것
권한 경계 — 양방향
감시의 진짜 목적은 지시서를 고치는 것

되돌리기

프로젝트 CLAUDE.md 의 "Codex 워크플로우 스위치" 를 기존 으로 바꾼다. 그게 전부다.
이 스킬도, 플러그인도 지우지 않는다. codex-delegate 와 codex_task.py 는 손대지 않았다.

🔴 취지 대조 — 재개 전에 반드시 읽을 것

원문(2026-09-09 08:48, 사용자):

*"제가 하려고 했던건 기존 지시서-보고서 형태를 codex-plugin-cc로 대체해서
사용하는 방안이었어요."* (보강 09-10: "코덱스가 맥락을 충분히 이해하고 움직이면
더 좋은 결과물을 낼 수도 있어요")

대체 대상은 "지시서-보고서 문서 왕복" 이었다. 그런데 이 스킬 §2 는
"계약을 쓴다 — 지시서는 여전히 파일로 남긴다", "계약을 없애지 마라" 로
그 대체 대상을 유지한다고 못박았다. 취지와 어긋난 지점이다.

실제로 돌아간 것도 반대였다.

stop-review-gate   4건   취지에 없던 것 (관리자가 09-10 07:16 에 권고해 추가)
/codex:rescue      0건   취지의 본체
/codex:transfer    0건   취지의 본체

⚠️ 재개하면 시범의 정의부터 다시 잡아라 — "지시서 없이 transfer + rescue
로 위임 1건을 하고, 기존 지시서 방식과 결과를 비교" 가 원래 재려던 것이다.
아래 판정 기준은 그 정의 위에서만 의미가 있다.

시범 판정 기준 — 무엇을 보고 결정하나

"좋아 보인다"로 판단하지 않는다. 아래를 실측해 기존과 비교한다.

항목	기존 실측(2026-09-08~09)	시범에서 볼 것
호출 실패	2건 (인자 위치·모델 복귀)	0 이어야 한다
진행 확인	로그 grep 폴링	status 로 대체됐는가
한도 인지	에러 메시지로 사후	착수 전에 알았는가
계약 작성량	지시서 200~300줄	줄었는가. 완료기준은 남았는가
검증에서 잡은 문제	12건 + 1건 (즉흥 위임)	게이트가 자동으로 잡는가

⚠️ 작성량이 줄었는데 완료기준·금지사항이 흐려졌다면 실패다. 그건 계약을 잃은 것이다.

이력 (필수 기록)

• 생성일: 2026-09-10
• 업데이트 횟수: 0
• 사용 이력:
  • 2026-09-11 — 🔴 보류. 사용자 지시로 스위치를 기본값으로 되돌리고
    stop-review-gate 를 껐다 — "기존에 사용하던 워크플로우로 되돌립시다",
    급한 일이 밀려 시범을 뒤로 미룬다는 판단이었다.
    되돌리며 사실 오류 2건을 정정했다 — ① 게이트는 모든 턴에 발동한다(§6)
    ② 이 스킬이 취지(지시서-보고서 대체)와 어긋나 있었다(§취지 대조).
    시범 기간에 실제로 돈 것은 게이트 4건뿐이고 위임은 0건이라 판정 기준은 아직 비어 있다.
  • 2026-09-10 — 신규 생성. [[codex-delegate]] 를 복제·개조했다.
    사용자 지시: "기존 워크플로우는 그대로 두고, 복제해서 수정한 새로운 워크플로우를
    만드는 형식으로 갈거에요. 별로라면 기존걸로 돌려놓을겁니다."
    🔴 역할 분담은 바꾸지 않는다 — 사용자와 대화하는 것도, 맥락·판단·문서화도 관리자 몫이다.
    바뀌는 것은 호출 방식(슬래시 명령)과 검증 위치(Codex 리뷰) 뿐이다.