| name | codex-review |
| description | OpenAI Codex (gpt-5.5)를 경유한 2차 리뷰 게이트. Claude 1차 리뷰는 그대로 유지하고 동일 모델 맹점을 보완. Stage 분기 (plan/code/test/final/bugfix) · AUTO_STAGES 환경변수 정책 · OAuth 모드 비용 0 · P3/P4/P5/P6/P7 자동 호출. 자동 트리거 시점 - Spec 또는 Plan 작성 후 (stage=plan, blocking), 코드 변경 PR (stage=code, 권고), E2E 시나리오 작성 후 (stage=test, 권고, P6 Check 6-TX), PR 머지 직전 통합 검수 (stage=final, blocking high-effort, P7 Check 7-X), 버그 수정 patch 후 (stage=bugfix, 수동). 본 절차 실행은 ~/forge/.claude/commands/codex-review.md를 참조한다. |
Codex Review
Claude 1차 리뷰의 동일 모델 맹점 보완용 2차 게이트. SDD·PGE·Forge Dev 모든 단계에서 사용 가능.
역할
Claude 1차 리뷰의 동일 모델 맹점을 보완하는 OpenAI Codex(gpt-5.5) 경유 2차 리뷰 게이트. 대체가 아니라 추가 검증이며 stage(plan/code/test/final/bugfix)별로 차등 blocking을 적용한다.
컨텍스트
SDD·PGE·Forge Dev 파이프라인 전 단계에서 호출 가능. Forge Dev 통합 지점은 P3/P4(plan, blocking) / P5 Check P5.7-X(code, 권고) / P6 Check 6-TX(test, 권고) / P7 Check 7-X(final, blocking high-effort) / 버그 patch 후(bugfix, 수동). ~/forge/.env의 CODEX_REVIEW_AUTO_STAGES로 자동 발동 stage를 제어한다.
출력
docs/reviews/{stage}/{date}-{slug}.{md,json} 표준 스키마 리포트(Claude vs Codex delta_vs_claude 필드 포함) + INDEX 갱신 + blocking stage는 [STOP] 여부.
Workflow 통합 (계획서 P2-8)
단독 호출 = 현행 유지. cr-multi Workflow에 흡수 가능 (mode='double' — Claude+Codex).
실행: Workflow({ script: Bash("cat ~/.claude/skills/cr-multi/workflow.js"), args: { targetPath, mode: 'double', stage } })
단독 Codex만 필요 시 → 기존 /codex-review 그대로 사용. CLAUDE_CODE_DISABLE_WORKFLOWS=1 시 기존 방식.
Quick Start
/codex-review --stage plan --target docs/spec/feature-x.md --blocking
/codex-review --stage code --target src/auth.ts
/codex-review --stage test --target tests/e2e/login.spec.ts
/codex-review --stage final --target PR-1234 --effort high --blocking
/codex-review --stage bugfix --target patches/fix-token-leak.diff
단축 래퍼: /cr-plan, /cr-code, /cr-test, /cr-final, /cr-bug.
상세 호출 절차·JSON 스키마·diff 처리는 ~/forge/.claude/commands/codex-review.md 참조.
Stage 분기
| Stage | 호출 시점 | Effort | Blocking |
|---|
plan | Spec/PRD 작성 직후 | medium | YES |
code | P5 Check P5.7-X | medium | NO |
test | P6 Check 6-TX | medium | NO |
final | P7 Check 7-X (PR 직전) | high | YES |
bugfix | 버그 patch 작성 후 (수동) | medium | NO |
AUTO 발동 여부는 이 표에 없다 — CODEX_REVIEW_AUTO_STAGES(정본 = commands/codex-review.md Step 1.5, 기본값 off)로만 결정된다. Blocking 열은 "그 stage가 auto/수동으로 발동됐을 때" 결과가 [STOP]을 유발하는지를 뜻하며, 발동 자체를 보장하지 않는다.
code vs final 영역 차이:
code = 단위 변경의 로직·보안·성능 (함수·클래스 수준)final = 통합 검증 (Spec 추적·롤백·UX·보안 통합·마이그레이션, 변경 전체)
동일 영역 재검증 시 final 효과 0. 호출 시 stage별 평가 기준 인입 의무.
AUTO_STAGES 정책
정본 = .claude/commands/codex-review.md (Step 1.5 게이트). 이 절은 요약이며,
값이 어긋나면 커맨드를 따른다. 2026-07-14 실측에서 두 문서의 기본값이 서로 달랐다
(커맨드 off vs 스킬 plan,final) — 리뷰 게이트가 돌기도 하고 조용히 안 돌기도 했다.
~/forge/.env 환경변수:
CODEX_REVIEW_AUTO_STAGES="${CODEX_REVIEW_AUTO_STAGES:-off}"
- 미설정 →
off (기본). 자동 호출 없음 — 명시적으로 켜야 돈다.
"all" → 모든 stage 자동 (비용 주의)"plan,final" → 핵심만 자동, code/test는 수동 권고- 매칭 stage만 자동 호출. 미매칭은 즉시 exit 0
--cr on 인자로 호출당 override 가능
비용 (OAuth 모드 — 현재)
ChatGPT OAuth (Plus/Pro 한도) → 모든 stage $0.00. API key fallback 시만 비용 발생 ($CODEX_REVIEW_MODEL 설정).
| Stage | OAuth | API key fallback |
|---|
| plan | $0.00 | gpt-5.5 $0.010.03 |
| code | $0.00 | gpt-5.5 $0.020.05 |
| test | $0.00 | gpt-5.5 $0.010.03 |
| final | $0.00 | gpt-5.5 high $0.100.30 |
| bugfix | $0.00 | gpt-5.5 $0.020.05 |
상세 정책 (스킵 패턴·다운그레이드·diff 처리): ~/forge/dev/rules/codex-review-policy.md.
효과 측정 (OAuth 모드)
비용 0이므로 일치율·발견 가치 측정이 핵심. 매 호출 JSON에 delta_vs_claude 자동 기록 (commands/codex-review.md Step 5).
월별 통계:
~/forge/shared/scripts/codex-monthly-stats.sh
임계값:
agreement_rate > 90% 3개월 연속 → 해당 stage AUTO OFF 권고 (중복)extension_rate > 30% → AUTO ON 권고 (효과 입증)disagreement_rate > 10% → 정책 재검토
Codex-Probe 하드닝 (LN-09)
Codex CLI 호출 전 4단계 probe 필수 (commands/codex-review.md Step 2에 앞서 실행):
1. Version Check
codex --version 2>&1 | grep -E "^[0-9]+\.[0-9]+" || { echo "[CODEX-PROBE] version check failed"; exit 1; }
버전 확인 실패 = CLI 미설치 또는 PATH 문제 → TELEMETRY_ERROR_CLASS=codex_missing 기록 후 Opus 단독 폴백.
2. Timeout Wrapper
timeout 120 codex "$@"
EXIT_CODE=$?
[ $EXIT_CODE -eq 124 ] && { _record_hang; exit 1; }
타임아웃: 120초 (final stage는 240초). 초과 시 → hang 기록 + 폴백.
3. Hang Recording
타임아웃(exit 124) 또는 행(≥120s 무응답) 발생 시:
_record_hang() {
export TELEMETRY_OUTCOME=FAIL TELEMETRY_ERROR_CLASS=codex_hang TELEMETRY_FAILED_STEP=codex_cli_exec
echo "{\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"codex_hang\",\"stage\":\"$STAGE\"}" >> .claude/usage.log
}
hang 3회 연속 → AUTO_STAGES에서 해당 stage 자동 제거 + 사용자 경고.
4. Auth Detection
Codex CLI 응답에서 인증 오류 분류:
if echo "$CODEX_OUTPUT" | grep -qiE "unauthorized|invalid.*api.*key|auth.*fail|401|forbidden"; then
TELEMETRY_ERROR_CLASS=codex_auth_fail
echo "[CODEX-PROBE] auth failure detected — check OPENAI_API_KEY or OAuth session"
exit 1
fi
auth fail vs timeout vs model_unavailable 구분 → 오류별 대응 경로 분기.
Forge Dev 통합 지점
| Phase | Stage | Blocking |
|---|
| P4 (Spec 작성) | plan | YES |
| P3 (계획서) | plan | YES |
| P5 Check P5.7-X (코드 리뷰 1차 후) | code | NO (default OFF) |
| P6 Check 6-TX (QA Loop 후) | test | NO (default OFF) |
| P7 Check 7-X (PR 직전 통합) | final | YES (effort=high) |
핵심 원칙
- 이중 게이트: Claude 1차는 항상 유지. Codex는 추가 (대체 X).
- 단계별 차등:
final은 high effort + blocking. code/test는 medium + 권고.
- 비용 통제: OAuth 모드 무빌링. API key 모드만 daily/monthly 한도 적용.
- diff 자동 기록: Claude 결과 존재 시
delta_vs_claude 자동 채움. 월별 통계 의사결정 입력.
호출처는 commands에 있음
본 스킬은 의미 트리거·정책 요약 전용. 실제 호출 절차는 ~/forge/.claude/commands/codex-review.md:
- Step 1: 대상 + diff 추출
- Step 1.5: AUTO_STAGES 게이트
- Step 2: Codex 호출 (codex CLI exec)
- Step 3: JSON 표준 스키마 정규화
- Step 4: 저장 (
forge-outputs/docs/reviews/{stage}/{date}-{slug}.{md,json})
- Step 5: Claude vs Codex Delta 자동 기록 (
delta_vs_claude 필드)
- Step 6: INDEX 갱신
- Step 7: Blocking 처리
관련
- 정책:
~/forge/dev/rules/codex-review-policy.md
- Claude 1차:
~/.claude/agents/code-reviewer/agent.md
- 비교 스크립트:
~/forge/shared/scripts/codex-delta-compute.py
- 월별 통계:
~/forge/shared/scripts/codex-monthly-stats.sh
- Forge Dev 게이트:
~/forge/pipeline.md (Check P5.7-X / P6-TX / P7-X)
자동 평가 (eval-rubric 통합)
본 스킬 결과 산출 후 자동으로 eval-rubric 호출 → 4축 Rubric 채점 (clarity/consistency/completeness/safety) → eval_cases.jsonl 누적.
호출 시점
- 본 스킬 핵심 산출물 저장 직후 — codex-review JSON (
docs/reviews/{stage}/{date}-{slug}.json)
절차
- 스킬 산출물 저장 후 다음 호출:
/eval-rubric --target {산출물 경로}
- eval-rubric의 verdict (PASS/WARN/FAIL) + 4축 점수 + rationale 수신
eval_cases.jsonl append:
- 위치:
~/.claude/skills/codex-review/eval_cases.jsonl
- case_id:
EC-codex-review-{N} (auto-increment)
- split: holdout 결정 (
hash(case_id) % 100 < 20 → holdout, 그 외 sample)
- dedupe key:
sha256(skill+input.context+input.args) 충돌 시 observed_count++
자동 비활성 조건
- 환경변수
EVAL_RUBRIC_AUTO=off 설정 시 스킵
- 본 스킬 frontmatter에
eval_cases: off 명시 시 스킵 (특수 케이스)
통합 효과
- FAIL 케이스 자동 누적 → 회귀 평가 데이터셋 구축
- WARN 시 사용자 알림 (자동 차단 X — 본 스킬 verdict 우선)
- 분기별 Harness GC 사이클의 Quality Audit 입력으로 활용
보안 / 데이터 보호
- eval-rubric의 입력 redaction 정책 자동 적용 (
~/.claude/skills/eval-rubric/SKILL.md "보안 정책" 참조)
- 산출물에 secret/PII 의심 시 → eval-rubric STOP fail-safe 발화 → 본 스킬도 STOP
출처: 하네스 백과사전 제5장 평가 하네스, eval_cases.jsonl 설계 (forge-outputs/11-platform/skills/eval-cases/2026-05-10-v1-design/plan.md)
Evaluator (Wave 2.5)
독립 Evaluator subagent가 산출물 품질을 검증합니다.
Evaluator 역할: 산출물 독립 검증
모델: claude-haiku-4-5 (경량, 편향 최소화)
격리: 메인 컨텍스트 오염 방지
판정 기준:
- PASS: 모든 핵심 기준 충족, 즉시 사용 가능
- WARN: 사용 가능하나 개선 권장, 사용자 확인 후 진행
- FAIL: 핵심 기준 미충족, 재실행 필요
eval_cases.jsonl에 결과 자동 누적.
