【Claude Code】Codex에 리뷰를 의뢰하는 Skill

이번에는 최근 화제가 되고 있는, 「Claude Code에서 Codex를 호출하여 리뷰를 의뢰하는」 Skill을 만들어 보았습니다.

Codex의 설정 방법(Setup)에 관해서는 이쪽을 참조해 주세요.

이 조합이 많이 채택되고 있는 이유를 간결하게 정리해 보았습니다.

「구현 담당」과 「리뷰 담당」을 완전히 분리할 수 있기 때문에 사고 편향(Thinking Bias)이 이어지지 않는다.
Claude Code의 강점인 「장문 이해, 오케스트레이션(Orchestration), 대화(모호한 지시에 대해 역질문을 해주는 기능)」와, Codex의 강점인 「구현 속도, 생성 코드의 품질, 비판적 리뷰 관점」을 각각 활용할 수 있는 형태가 되어 있다.
서로 다른 AI에게 상호 리뷰를 시킴으로써 할루시네이션(Hallucination)이나 간과하는 부분을 줄일 수 있다.
Claude Code와 Codex를 연계하는 공식 MCP나 플러그인이 정비되어 왔다.
컨텍스트(Context)/토큰(Token) 사용량을 각각의 AI에 분산할 수 있다.

MCP나 플러그인(내부에서 MCP를 사용)과 같은 선택지가 있지만, 다음과 같은 이유로 직접 만든 Skill을 사용하기로 했습니다.

・ MCP를 경유하면 응답이 느리거나/불안정하다

・ 진행 내용을 확인할 수 없다

・ 업데이트에 의해 예기치 않은 설정이나 사양 변경이 가해질 위험도 있다

Skill을 직접 만들면 이러한 문제를 해결할 뿐만 아니라,

모델/추론 강도/승인 정책/Sandbox 설정/fast_mode...와 같은 세부 설정을 커스터마이징할 수 있다

는 점이 가장 큰 혜택이라고 생각합니다 (보안 대책 측면에서도).

이쪽은 이번에 Skill을 직접 만들게 된 계기가 된 기사입니다!

※ skill-creator를 사용하고 있습니다.

※ 과거에 작성한 Skill이 일부 반영되어 있습니다.

「과거에 작성한 Skill」

일부 마크다운(Markdown) 사양상, [```] 앞에 #을 넣었습니다.

---
name: codex-review
description: Claude Code로 구현한 미커밋 변경 사항(git diff HEAD)을 커밋 전에 Codex CLI(gpt-5.5 / model_reasoning_effort=high / web_search=live / sandbox=read-only)에 리뷰 의뢰하여, 적대적 리뷰·보안 체크·리팩터링·베스트 프랙티스 준수를 포함한 모든 관점에서 정밀 조사한 결과를, 지적 사항 1건씩 「적용 / 스킵 / 추가 논의」의 3가지 선택지로 사용자와 대화하며 판단·반영해 나가는 스킬. 사용자가 `/codex-review`라고 입력했을 때, 또는 「커밋 전에 Codex에게 리뷰시켜줘」 「Codex로 적대적 리뷰해줘」 「Codex에게 보안 체크 부탁해」 「Codex에게 리팩터링 지적받고 싶어」 「Codex에게 베스트 프랙티스를 봐달라고 해줘」 「미커밋 변경 사항을 Codex로 리뷰해줘」 「Codex로 모든 관점 리뷰해줘」 등, Claude Code 구현 직후에 Codex를 통한 독립적인 제3자 관점의 리뷰를 얻고 싶은 상황에서 반드시 사용한다. `codex exec`를 **단 한 번의 명령**으로 호출하는 자기 완결형 구성(`config.toml` 이나 profile에 의존하지 않음), `--sandbox read-only`를 통한 비파괴 실행, 미커밋 변경 사항(`git diff HEAD`)을 대상 범위로 하는 운용, 커밋이나 push는 수행하지 않고 작업 트리(Working Tree)에 대한 수정 반영까지 담당하는 방침이 필요한 모든 케이스에서 본 스킬을 우선적으로 호출할 것.
---
# codex-review
Claude Code에 의한 구현이 일단락된 「커밋 전」 타이밍에, 미커밋 변경 사항(`git diff HEAD`)을 Codex CLI에 **독립적인 제3자 리뷰어**로서 정밀 조사하게 하고, 그 결과를 1건씩 사용자와의 대화를 통해 반영해 나가는 스킬.

이 스킬이 목표로 하는 것

Claude Code가 작성한 코드를 Claude Code 자신이 아닌 별도의 모델 (OpenAI Codex / gpt-5.5) 이 리뷰함으로써 다음과 같은 효과를 노립니다:

적대적 리뷰 (Adversarial Review): "작성자 본인이 놓치기 쉬운" 경계 조건(Boundary conditions), 예외 경로(Exception paths), 계약 위반(Contract violations)을 다른 관점과 다른 모델의 눈으로 포착
보안 체크 (Security Check): OWASP 계열의 취약점, 비밀 정보 혼입, 안전하지 않은 기본값, 의존성 라이브러리의 CVE 관점 (Web Search live)
리팩터링 지적 (Refactoring Feedback): 차분(Diff) 내의 코드 품질, 명명 규칙(Naming), 중복, 추상화
베스트 프랙티스 준수 (Best Practice Compliance): 언어/프레임워크 관습, 리포지토리의 기존 패턴, 테스트 커버리지, 로그 및 관측성(Observability)

최종 판단은 반드시 사용자가 수행합니다. Codex의 지적은 "채택 / 스킵 / 추가 논의"의 3가지 선택지 중 하나로 1건씩 검토하며, 채택한 것만 작업 트리(Working tree)에 반영합니다. 커밋(Commit) 및 푸시(Push)는 본 스킬에서 일절 수행하지 않습니다.

채택하는 Codex 호출 방침

단 한 번의 명령으로 호출합니다. ~/.codex/config.toml이나 --profile에 의존하지 않는 자기 완결적(Self-contained) 구성입니다. skill 내의 동작을 재현 가능하게 하기 위해, 필요한 설정은 모두 --config로 명시합니다.

입력: git diff HEAD를 stdin으로 전달 (프롬프트 본문이 비대해지는 것을 방지)
출력: .codex/review.md에 Markdown 형식으로 작성하며, skill 측에서 Read 도구로 읽음
모델: gpt-5.5 / reasoning_effort=high / verbosity=기본값(medium)
샌드박스 (Sandbox): read-only (리뷰는 읽기 전용)
승인 방침: never (비대화형 실행)
Web Search: live (CVE 및 최신 사양 확인에 필요)
Codex 내부 처리(프롬프트 지시)는 영어로, 사용자용 최종 리포트(findings의 값)는 일본어로 작성

실행 절차

Step 1: 전제 조건 및 현재 상태 일괄 취득

다음 사항을 병렬로 실행합니다:
#bash command -v codex #
#bash git rev-parse --is-inside-work-tree #
#bash git branch --show-current #
#bash git status --short #
#bash git diff HEAD --stat #

전제 조건이 충족되지 않을 경우

codex를 찾을 수 없음 → "Codex CLI가 설치되어 있지 않습니다. npm i -g @openai/codex 등으로 설치하고, codex login으로 인증한 후 다시 실행해 주세요"라고 알리고 종료.
git 리포지토리가 아님 → 해당 내용을 알리고 종료.
git diff HEAD --stat이 비어 있음 (미커밋 변경 사항 없음) → "미커밋 변경 사항이 없습니다. 리뷰 대상이 없으므로 종료합니다"라고 알리고 종료.

차분이 극도로 큰 경우

git diff HEAD --stat의 출력에서 변경 행 수 합계가 3,000행을 초과하는 경우, 사용자에게 다음과 같이 확인합니다:
#```
이번 차분은 <N> 파일 / <+X> -<Y> 행으로 규모가 큽니다.
Codex의 리뷰에는 시간과 토큰 비용이 소요됩니다.

이대로 전체를 리뷰 (권장도: 상황에 따라 다름)
...

"2"를 선택한 경우, 필터링할 경로(Path)를 물어본 뒤 이후의 `git diff HEAD`를 `git diff HEAD -- <paths...>`로 교체합니다.

### Step 2: 리뷰 대상 차분의 요약을 사용자에게 제시
`git diff HEAD --stat` 결과를 정렬하여 제시하고, 리뷰 시작 확인을 받습니다:
#```
## Codex에 의한 리뷰 준비가 완료되었습니다
- 브랜치: `<branch>`
- 대상: 미커밋 변경 사항 (`git diff HEAD`)
...

사용자가 OK 하면 Step 3로 진행합니다.

Step 3: Codex에 대한 일회성 호출

다음 사항을 1개의 명령으로 실행합니다. 출력 디렉토리 .codex/를 생성하며, .gitignore에 기재되어 있지 않다면 추가를 제안합니다 (자동 추가는 하지 않음).

#bash mkdir -p .codex #
#```bash
git diff HEAD | codex exec
--skip-git-repo-check
--ephemeral
...

# Codex Review Summary
<일본어로 2-4문장: 전반적인 인상, 가장 큰 우려 사항, 차단 요소(blocker) 여부>
# Findings
## 1. [Critical|Major|Minor|Nit] <짧은 일본어 헤드라인>
- file: `<path>`
- line: `<line 또는 line-range, 예: 42 또는 88-95>`
- category: adversarial | security | refactor | best-practice
- severity: Critical | Major | Minor | Nit
- issue: <일본어로 작성된 구체적인 발견 사항>
- rationale: <이것이 왜 문제인지 일본어로 설명; 해당되는 경우 CVE / RFC / 문서 URL을 인라인으로 인용>
- suggestion: <일본어로 작성된 권장 수정 사항; 간결한 경우 코드 스니펫 포함>
## 2. ...
#```
발견 사항은 1부터 시작하여 순차적으로 번호를 매깁니다. 심각도(Severity) 순서대로 정렬합니다 (Critical → Major → Minor → Nit). 발견 사항이 없는 경우, 다음과 같이 출력합니다:
#```
# Codex Review Summary
<지적할 사항이 없는 이유를 일본어로 솔직하게 2-3문장 설명>
# Findings
(no findings)
#```
# Hard constraints
- 당신은 읽기 전용 샌드박스(read-only sandbox)에 있습니다. 파일을 수정하려고 시도하지 마십시오. 리뷰 텍스트만 생성하십시오.
- 파일 경로 나 줄 번호를 임의로 만들어내지 마십시오. 실제로 보이는 diff hunk에서 인용하십시오.
...

Codex 실행이 실패했을 경우

인증 에러 (401 / unauthenticated 계열) → 「codex login으로 인증한 후 다시 실행해 주세요」라고 전달하고 종료.
네트워크 에러 → 1회에 한해 자동 재시도(retry)를 해도 좋습니다. 그래도 실패한다면 에러 내용을 그대로 제시하고 종료.
.codex/review.md가 비어 있거나 섹션이 누락된 경우 → Codex 출력을 그대로 전문 표시하여 사용자에게 판단을 맡깁니다 (무리하게 파싱하지 않음).

Step 4: 리뷰 결과 파싱 및 개요 제시

.codex/review.md를 Read 도구로 읽고, 다음을 파싱합니다:

# Codex Review Summary 섹션 본문
# Findings 하위의 각 ## <N>. [Severity] <headline> 블록
각 finding의 file / line / category / severity / issue / rationale / suggestion
(no findings)인 경우에는 다음과 같이 출력하고 종료합니다:
#```

Codex 리뷰 결과

<Summary 본문> 미결된 지적 사항은 없습니다. 커밋을 진행해도 문제없습니다. ... ``` 지적이 1건 이상 있는 경우에는 개요 테이블로 제시합니다: #``` ## Codex 리뷰 결과 <Summary 본문> ### 지적 목록 (N건) ... ``` 사용자가 OK 하면 Step 5로 진행합니다. ### Step 5: 지적 사항 1건씩 대화 처리 루프 `N`건의 finding을 **Critical → Major → Minor → Nit 순서**로, **1건씩** 처리합니다. 여러 건을 한꺼번에 처리하지 않습니다.

5-1. 해당 코드와 차분(diff) 읽기

finding의 file과 line을 통해, 현재 파일 내용을 Read 툴로 읽는다. 전후 10~20행의 컨텍스트(Context)를 확보한다. 아울러, 해당 지적 사항이 실제로 git diff HEAD의 어느 덩어리(hunk)에 속하는지도 확인한다 (필요하다면 해당 파일에 대해서만 git diff HEAD -- <file>을 실행).

5-2. 지적 사항과 Claude의 평가를 사용자에게 제시

#```

지적 i/N

<file>:<startLine>-<endLine>
<전후 컨텍스트를 포함한 코드>
#```
### Codex의 제안
<suggestion. 짧으면 인라인 diff, 길면 요점 열거>
### Claude의 평가
...

평가는 판단을 강요하지 않는다. Codex의 지적이라 하더라도, 코드베이스 전체의 문맥이나 기존 관습을 고려했을 때 불필요한 경우가 있다. Claude는 "자신은 이렇게 보인다"를 근거와 함께 제시하는 데 그치며, 최종 판단은 반드시 사용자에게 맡긴다.

5-3. 사용자 판단에 따른 처리

"적용"이라고 답변한 경우:
Edit 툴로 대상 파일을 수정한다. Codex의 suggestion을 그대로 채택하는 것이 원칙이지만, Claude가 읽은 현재 코드와 맞지 않는 부분(행 번호 어긋남, 변수명 차이 등)은 최소한의 조정을 가해도 좋다. 여러 파일에 걸친 수정이 필요한 경우, 먼저 "이 수정은 <다른 파일>에도 변경이 필요합니다. 함께 반영할까요?"라고 확인한다.

수정 후 보고:
#```
✅ 적용했습니다

<file>을 수정
<변경 개요(1행)>
...


**"스킵"이라고 답변한 경우:**
#```
⏭ 스킵했습니다.
이유를 메모해 두고 싶다면 그 내용을 알려주세요 (최종 요약에 포함합니다).
다음 지적 (i+1/N)으로 진행합니다.
#```

**"추가 논의"라고 답변한 경우:**
자유 형식의 대화에 들어간다. 관련 부분의 추가 조사, 별도 안 제시, Codex 지적의 타당성 재평가 등을 수행한다. 논의가 수렴되면 "적용 / 스킵" 중 하나를 재확인하고, 확정된 후 다음 지적으로 진행한다.

#### 5-4. 중단 시의 동작
사용자가 도중에 "여기서 멈춰줘"라고 말한 경우, 그 시점까지의 결과를 Step 6의 요약 형식으로 출력하고, 미처리 사항은 "미처리: <i>건"으로 남긴다. 작업 트리는 "적용"한 것들만 반영된 상태 그대로 유지하며, 아무것도 되돌리지 않는다.

### Step 6: 전건 처리 후의 요약
모든 지적을 처리(또는 중단)한 후, 아래를 출력:
#```
## Codex 리뷰 대응 완료 요약
브랜치: `<branch>`
처리 결과: 적용 P건 / 스킵 Q건 / 논의 후 적용 R건 / 논의 후 스킵 S건 / 미처리 T건
...

git status --short를 실행하여 결과를 포함한다.

에지 케이스 (Edge Case)

Codex 출력이 스키마를 벗어난 경우: 파싱(Parsing)에 실패하면 억지로 구조화하지 않고, .codex/review.md의 전문을 그대로 표시하며 사용자에게 "이대로 수동으로 처리할까요? / 다시 Codex를 호출할까요?"라고 확인한다. 재호출은 토큰을 낭비하므로 안이하게 자동 재실행하지 않는다.
지적이 대량인 경우 (20건 초과): 전체 조망 제시 시 "전건 처리 / Critical & Major만 / Critical만"을 선택할 수 있도록 한다. 사용자가 필터링을 선택한 경우, 대상 외의 지적은 최종 요약에서 "미처리 (중요도 필터)"로 명시한다.
동일한 부분에 대한 중복 지적: 1건씩 처리한다는 원칙은 바꾸지 않는다. 다만 2건째 이후를 제시할 때 "지적 i에서는 <행 X>를 <변경 내용>으로 수정 완료했습니다. 본 지적은 동일한 부분에 대한 다른 관점입니다"라고 서두를 넣는다.
Codex가 차분(diff) 외의 수정을 제안한 경우: 그러한 지적은 제시할 때 "Codex는 차분 외의 <file> 수정도 권장하고 있습니다"라고 명시한다. 스코프(Scope)를 넓힐지 여부는 사용자의 판단에 맡긴다.
Codex가 잘못된 행 번호를 반환한 경우: 파싱(Parsing) 시점에 Read한 실제 파일과 대조하여 차이를 감지하면, 제시할 때 "Codex가 지적한 행 번호 <N>은 현재 파일에서는 <M> 부근에 해당합니다"라고 주석을 달고 진행한다.
커밋되지 않은 변경 사항이 staged와 unstaged로 나뉘어 있는 경우: git diff HEAD는 양쪽을 모두 포함하므로 보통은 신경 쓰지 않는다. 다만 요약(Summary)에 "그 중 staged: X 파일 / unstaged: Y 파일"을 보충해도 좋다.
생성된 파일(lockfile, 빌드 결과물 등)이 차분에 포함된 경우: Step 2 확인 시점에 사용자에게 git diff HEAD -- ':(exclude)package-lock.json' ':(exclude)yarn.lock' ':(exclude)pnpm-lock.yaml'와 같은 제외 방식을 제안해도 좋다. lockfile의 차분까지 Codex에게 읽게 하면 S/N(Signal-to-Noise) 비율이 악화된다.
비밀 정보가 차분에 포함되어 있을 가능성: 내부적으로 git diff HEAD | grep -E '(AKIA|api[_-]?key|secret|password|BEGIN .* PRIVATE KEY)'를 확인하여 히트(Hit)가 있으면 Codex 호출 전에 사용자에게 경고한다. Codex로 전송하기 전에 해당 부분을 제거할지, 아니면 사용자의 판단하에 계속 진행할지 확인한다.
Codex 인증이 gpt-5.5를 해제하지 않은 경우: --config model="gpt-5.5"로 400/403 에러가 반환될 경우, gpt-5로 폴백(Fallback)해도 좋다는 내용을 사용자에게 확인한다. 임의로 다운그레이드하지 않는다.

동작 원칙

승인 없이 작업 트리(Working Tree)를 변경하지 않는다: Edit를 통한 수정은 반드시 사용자가 "적용"을 선택한 후에만 수행한다. Claude/Codex의 평가가 "타당"하더라도 임의로 반영하지 않는다.
커밋(Commit) 및 푸시(Push)는 하지 않는다: 본 스킬은 작업 트리에 반영하는 단계까지만 담당한다. 커밋은 /auto-commit, 푸시는 사용자의 수동 조작에 맡긴다. 이는 Codex 대응, 구현, 리팩토링이 일괄 커밋되어 이력이 섞이는 것을 방지하기 위함이다.
판단을 빼앗지 않는다: Claude의 평가는 어디까지나 판단 재료일 뿐이다. "채택해야 함" 또는 "불필요함"이라고 단정적으로 유도하지 않고, 근거를 기술한 뒤 "Claude는 이렇게 보고 있습니다"라는 톤을 유지한다. 최종 판단은 사용자에게 있다.
Codex의 지적이라도 맹종하지 않는다: 다른 모델의 관점은 귀중하지만, 코드베이스의 문맥을 고려하지 않은 지적이나 기존 관습과 모순되는 지적도 섞여 있을 수 있다. 제시할 때 Claude의 독립적인 평가를 반드시 덧붙인다.
일회성 명령 원칙을 준수한다: ~/.codex/config.toml이나 --profile에 의존하지 않는다. 본 스킬만으로 완결되며, Codex CLI만 설치되어 있다면 누구의 환경에서든 동일하게 동작한다.
비용 의식: Codex 호출은 1회 리뷰당 1회만 수행한다. 재실행은 명시적으로 "다시 리뷰해줘"라고 지시받은 경우에만 한다. reasoning_effort=high + web_search=live 조합은 상당한 리소스를 소모한다는 점을 염두에 둔다.
생(Raw) 리뷰 전문을 남긴다: .codex/review.md는 최종 요약 후에도 삭제하지 않는다. 나중에 사용자가 다시 검토하거나 PR(Pull Request) 설명문에 활용할 수 있도록 하기 위함이다.

참고: 왜 Codex를 별도로 사용하는가

Claude Code가 직접 작성한 코드를 Claude Code 스스로 재리뷰하게 하면, 동일한 모델이기 때문에 같은 사각지대를 놓치기 쉽다. OpenAI Codex(gpt-5.5)는 별개의 계통을 가진 모델이며, 특히 다음과 같은 부분에서 독립적인 관점을 얻기 쉽다:

보안 (OpenAI 측의 학습 데이터 및 가이드라인의 차이)
라이브러리의 최신 동동향 (web_search=live를 통해 CVE / 어드바이저리를 매번 취득)
스타일/관습의 편향 (Claude가 선호하는 작성 방식에 대한 과적합을 상대화)

"Claude Code 구현 → Codex 리뷰 → 사용자 판단하에 반영 → 커밋"이라는 파이프라인이 본 스킬이 상정하는 표준 흐름이다.


・Claude Code로 구현한 커밋되지 않은 변경 사항에 대한 코드 리뷰 의뢰 전용 Skill입니다.

...

git diff HEAD | codex exec \
--skip-git-repo-check \
--ephemeral \
-o .codex/review.md \
--config model="gpt-5.5" \
--config model_reasoning_effort="high" \
--config sandbox_mode="read-only" \
--config approval_policy="never" \
--config web_search="live" \
"$(cat <<'PROMPT'

model="gpt-5.5"

: 사용 모델 (가장 뛰어난 모델을 지정)

model_reasoning_effort = "high"

: 추론 강도 (응답이 느리다면 "medium"도 검토)

sandbox_mode="read-only"

: AI에게 허용할 작업 내용과 폴더 범위 설정 (쓰기 권한을 부여하지 않음으로써, 안심하고 approval_policy="never"를 설정할 수 있음)

approval_policy="never"

: 승인 정책 ("never"로 설정하면 사용자에 의한 확인을 스킵함. rm -rf 등 폭주할 가능성도 있으므로 주의가 필요함)

web_search="live"

: 임의의 타이밍에 최신 정보 취득을 허용함

(그 외의 설정은 기본값을 사용)

먼저 Claude Code에 요청하여 구현을 시킨 후, 방금 작성한 Skill을 호출합니다.

리뷰 준비가 완료되었습니다.

Codex의 진행 상황을 실시간으로 확인할 수 있습니다.

(이번 구현에서 변경이 가해진 server.allowedHosts 주변의 보안 베스트 프랙티스 (Security Best Practices)를 web search로 조사하고 있는 것 같습니다)

Codex에 의한 리뷰가 완료되었습니다.

이번 구현 차분 (diff) 중에서 지적될 가능성이 있는 곳이 있다면 바로 여기다! 싶은 부분을 멋지게 지적해 주었습니다.

조금이라도 참고가 된다면 좋겠습니다.

이번 내용은 여기까지입니다.