Claude Code 로 메인 코드 작성, Codex 로 코드리뷰 받고 싶다는 요구사항 전제
OpenAI가 공식 출시한 codex-plugin-cc를 Claude Code에 설치하는 것이 현재 가장 표준에 가까운 답입니다. 2026년 3월 30일에 OpenAI가 공식 플러그인 codex-plugin-cc를 출시하면서 환경이 바뀌었고, 슬래시 커맨드 하나로 Codex 리뷰가 실행되어 DIY 방식보다 진입 장벽이 훨씬 낮아졌습니다.
특히 사용자님의 워크플로우에 정확히 맞는 명령어가 있습니다 — /codex:adversarial-review는 선택한 구현과 설계에 의문을 제기하는 steerable review를 실행하며, 가정·트레이드오프·실패 모드·다른 접근이 더 안전하거나 단순했을지를 압박 테스트하는 데 쓸 수 있습니다. 인증, 데이터 손실, 롤백, 경쟁 조건, 신뢰성 같은 특정 리스크 영역을 압박 테스트할 때 사용합니다.
사용법은 그냥 Claude Code 안에서 작업하다가 PR 만들기 전에 이렇게 치면 됩니다:
/codex:adversarial-review --base main race condition과 auth 로직 중심으로 봐줘
이미 Codex 구독이 있으시니 추가 셋업도 거의 없습니다.
세 단계의 자동화 옵션이 있는데, 손이 가는 정도와 통제력이 트레이드오프됩니다.
Level 1: 수동 슬래시 커맨드 (현재 사용자님 방식의 업그레이드 버전)
codex-plugin-cc 설치 후 /codex:review 또는 /codex:adversarial-review를 PR 만들기 전에 수동 실행. 가장 단순하고, 토큰 비용 통제도 쉽습니다. 단점은 잊어버리면 안 돌아간다는 것.
Level 2: Stop Hook으로 자동화 (놓치는 리뷰 0건 보장)
hamelsmu/claude-review-loop 같은 플러그인이 이 영역입니다. /review-loop 명령으로 두 단계 라이프사이클을 만듭니다 — Task 단계에서 사용자가 작업을 설명하면 Claude가 구현하고, Review 단계에서 Claude가 작업을 끝낼 때 stop hook이 Codex runner 스크립트를 준비하고 종료를 차단합니다. Claude가 직접 Codex를 돌리고 리뷰 피드백을 반영하는 구조로, 모든 작업이 수락 전에 독립적인 second opinion을 받습니다. 프로젝트 타입에 따라 최대 4개의 병렬 Codex sub-agent를 띄우고, 모든 agent가 끝나면 Codex가 발견 사항을 중복 제거해서 reviews/review-<id>.md에 통합 리뷰를 씁니다.
Level 3: GitHub PR 단계에서 자동 실행 (사용자님이 원래 말씀하신 형태에 가장 가까움)
이게 사실 가장 깔끔합니다. PR 생성 시점에 Codex가 자동으로 리뷰 코멘트를 답니다. 공식 기능입니다:
Codex 코드 리뷰는 GitHub pull request에 또 다른 high-signal 리뷰 패스를 제공합니다. PR diff를 리뷰하고, 저장소 가이던스를 따르며, 심각한 이슈에 초점을 맞춘 표준 GitHub 코드 리뷰를 게시합니다. PR 코멘트에 @codex review를 멘션하거나, Codex 설정에서 Automatic reviews를 켜면 모든 PR을 자동으로 리뷰합니다.
리뷰 기준은 AGENTS.md로 커스터마이즈할 수 있습니다 — 최상위 AGENTS.md에 Review guidelines 섹션을 추가하면 (예: "Don't log PII", "Verify that authentication middleware wraps every route"), Codex가 변경된 각 파일에 가장 가까운 AGENTS.md의 가이던스를 적용합니다.
Go/Java 백엔드 작업이면 race condition, 트랜잭션 경계, goroutine leak, 동시성 같은 영역에서 cross-model 리뷰의 가치가 특히 큽니다 (한 모델만 보면 놓치기 쉬운 패턴들). 다음 조합을 권합니다:
- 메인 자동화: Codex의 GitHub Automatic reviews 켜기 → PR 올리면 자동으로 리뷰 코멘트 달림
- PR 전 사전 검증: Claude Code 안에서
/codex:adversarial-review로 PR 만들기 전에 한 번 압박 테스트 AGENTS.md작성: 팀 코드베이스 특유의 리뷰 기준 (예: "context.Context 전파 확인", "ErrGroup 사용 시 cancel 누락 체크" 같은 Go 관용구) 명시
이렇게 하면 PR 만들기 전 1회 + GitHub 단에서 1회, 두 단계 cross-model 게이트가 생기는데 사용자 부담은 사실상 0에 가깝습니다.
리뷰 게이트는 장시간 실행되는 Claude/Codex 루프를 만들 수 있고 사용량 한도를 빠르게 소진시킬 수 있습니다. 적극적으로 모니터링할 계획일 때만 활성화하세요.
Max x20 플랜이라도 Stop hook 기반 자동 루프(Level 2)는 의외로 토큰을 많이 먹습니다. Level 1 + Level 3 조합이 비용 대비 효과가 가장 좋다고 봅니다.
전제: Node.js 18.18+, ChatGPT 구독(또는 OpenAI API 키), Codex CLI 인증 완료 상태.
Step 1 — Claude Code 안에서 마켓플레이스 추가
/plugin marketplace add openai/codex-plugin-cc
Step 2 — 플러그인 설치
/plugin install codex@openai-codex
Step 3 — 플러그인 리로드
/reload-plugins
Step 4 — Codex 준비 상태 확인
/codex:setup
이 명령이 Codex가 설치되어 있는지, 로그인되어 있는지 점검해줍니다. Codex가 없으면 npm으로 설치 제안을 해주고, 로그인이 안 되어 있으면 !codex login을 치라고 안내합니다. 사용자님은 이미 Codex 쓰고 계시니 이 단계는 OK 메시지만 뜰 겁니다.
Step 5 — 첫 실행 테스트 (선택)
/codex:review --background
/codex:status
/codex:result
Go 백엔드 프로젝트를 위한 추천 설정
프로젝트 루트에 .codex/config.toml을 만들고 다음을 넣어두면 race condition 분석 등 동시성 추론에 강한 모델/effort로 고정됩니다:
model = "gpt-5.4-mini"
model_reasoning_effort = "high"리뷰가 약하다 싶으면 xhigh까지 올릴 수 있습니다. 다만 토큰 소비가 늘어납니다.
핵심 명령어 4개만 외워두시면 됩니다
| 명령 | 용도 |
|---|---|
/codex:review --base main |
표준 리뷰 (main 대비 diff) |
/codex:adversarial-review --base main <focus text> |
설계 결정에 의문 던지는 압박 리뷰 |
/codex:rescue <task> |
Codex에게 작업 위임 (디버깅·수정) |
/codex:status, /codex:result, /codex:cancel |
백그라운드 잡 관리 |
한 가지 주의 — /codex:setup --enable-review-gate 옵션은 권하지 않습니다. Stop hook으로 자동 루프를 만드는 기능인데, 토큰 소비가 폭발적이고 Max x20도 빨리 소진됩니다. 수동 호출 + GitHub Codex 자동 리뷰 조합이 비용 대비 효과가 훨씬 좋습니다.
작성 원칙 먼저 짚자면, AGENTS.md는 코딩 에이전트가 매 세션 시작 시 읽는 파일이므로 짧고 핵심만 담아야 합니다 — 도메인 개념, 페르소나, 설계 원칙을 간결하게 설명해야 합니다. 에이전트는 디렉토리 트리에서 가장 가까운 파일을 자동으로 읽기 때문에 가장 가까운 것이 우선순위를 갖고, 각 하위 프로젝트는 맞춤형 지침을 제공할 수 있습니다 — 참고로 OpenAI 메인 레포는 88개의 AGENTS.md 파일이 있습니다.
리뷰 가이드라인 작성의 핵심은 Codex가 가장 가까운 AGENTS.md의 가이던스를 변경된 각 파일에 적용한다는 점입니다. Go 백엔드 프로젝트 루트에 둘 만한 템플릿:
# AGENTS.md
## Project Overview
[프로젝트명]은 Go 1.22+ 로 작성된 [도메인] 백엔드 서비스다.
주요 책임: API 게이트웨이, 비즈니스 로직, 외부 서비스 연동.
## Architecture
- `cmd/`: 엔트리포인트
- `internal/handler/`: HTTP 핸들러 (chi/echo/gin 중 택1 명시)
- `internal/service/`: 비즈니스 로직, context 전파 필수
- `internal/repository/`: DB 접근, sqlc/gorm 사용
- `internal/domain/`: 도메인 모델, 외부 의존성 금지
- `pkg/`: 외부 노출 라이브러리만
## Build & Test
- 빌드: `make build`
- 단위 테스트: `make test` (반드시 `-race` 포함)
- 통합 테스트: `make test-integration` (Docker 필요)
- 린트: `make lint` (golangci-lint v1.60+)
- 커밋 전 필수: `make test lint`
## Code Style
- `gofmt`, `goimports` 적용
- 에러는 `fmt.Errorf("...: %w", err)`로 wrap, sentinel 에러는 `errors.Is`로 비교
- `interface{}` 대신 `any` 사용
- 구조체 태그 순서: `json` → `db` → `validate`
## Review Guidelines
다음 항목을 중요도 순서로 검토할 것:
### P0 (반드시 차단)
- `context.Context`가 첫 번째 인자로 전달되고 모든 I/O 호출에 전파되는지
- goroutine 누수: `go func()` 호출 시 종료 조건과 context cancel 처리 확인
- `sync.Mutex` 잠금 후 모든 경로에서 unlock 보장 (defer 권장)
- DB 트랜잭션: 에러 시 rollback, 성공 시 commit 누락 없는지
- 외부 호출에 타임아웃과 재시도 정책이 있는지
- 패닉 가능 코드: nil map write, nil pointer deref, slice out-of-bounds
- 민감 정보(토큰, PII)를 로그에 출력하지 않는지
### P1 (강력 권고)
- 에러 wrapping에 충분한 컨텍스트 포함 (호출자가 디버깅 가능한 수준)
- `errgroup` 사용 시 `Wait()` 호출과 첫 에러 처리 누락 없는지
- HTTP 핸들러에서 request body 크기 제한
- N+1 쿼리 패턴
- 채널 닫기 책임이 명확한지 (producer가 닫음)
### P2 (개선 제안)
- 매직 넘버 상수화
- 함수 길이 80줄 초과 시 분리 검토
- 테스트 커버리지가 비즈니스 로직에서 80% 미만인지
## Adversarial Review Focus
`/codex:adversarial-review` 실행 시 우선적으로 압박 테스트할 영역:
- 동시성: race condition, deadlock, goroutine leak
- 트랜잭션 경계: 부분 실패 시 데이터 일관성
- 재시도/멱등성: 같은 요청 두 번 와도 안전한가
- 백프레셔: 다운스트림 장애 시 캐스케이딩 실패 차단
## Things to Avoid
- `init()` 함수에서 외부 호출
- 전역 변수 (테스트 어려움)
- 무한 루프 안에 `time.Sleep` (context cancel로 대체)
- `panic`을 흐름 제어로 사용 (라이브러리 진입점에서만 허용)
## Commit & PR
- 커밋 메시지: Conventional Commits (`feat:`, `fix:`, `refactor:`)
- PR 본문에 변경 의도, 테스트 방법, 롤백 절차 필수Java 프로젝트면 review guidelines 섹션을 다음과 같이 바꿔주시면 됩니다:
### P0 (반드시 차단)
- AutoCloseable 리소스가 try-with-resources로 닫히는지
- `@Transactional` 메서드의 전파 속성과 예외 롤백 정책
- ExecutorService 사용 시 shutdown 누락 여부
- `Optional`을 필드/파라미터로 사용하지 않는지 (반환 타입만 허용)
- equals/hashCode 일관성, 특히 mutable 필드 사용 시
- Stream의 무한 시퀀스에 limit 누락
- DB 커넥션 풀 누수: try-with-resources 또는 Spring 관리 보장
### P1
- N+1 (JPA LAZY 로딩 추적)
- Checked exception을 RuntimeException으로 무차별 wrapping
- 동시성 컬렉션 (ConcurrentHashMap vs HashMap) 적절 사용
- Lombok @Data를 entity에 사용하지 않는지 (양방향 관계 무한 루프)루트 외에 서브디렉토리에도 두면 더 정확해집니다:
project/
├── AGENTS.md # 전체 표준
├── internal/repository/AGENTS.md # DB 레이어 특화 (트랜잭션, sqlc 패턴)
├── internal/handler/AGENTS.md # HTTP 레이어 특화 (validation, response 포맷)
└── internal/service/AGENTS.md # 도메인 로직 특화 (테스트 패턴, mock)
- 작업 → Claude Code로 PR 직전까지 작성
/codex:adversarial-review --base main race condition 위주로 봐줘실행- 지적사항 반영
- PR 푸시 → GitHub 단의 Codex Automatic Review가 자동으로 코멘트
- 사람 리뷰어가 들어가기 전 이미 2단계 cross-model 게이트 통과
이 구성이면 사용자님 손은 PR 만들기 전에 /codex:adversarial-review 한 번 치는 게 전부입니다. 토큰 제어도 명시적으로 가능하고, GitHub 단 자동화는 AGENTS.md만 잘 짜두면 별도 코드 없이 동작합니다.