codex 코드 리뷰 — /review와 PR 자동 리뷰
Codex 코드 리뷰는 쓰는 곳이 두 군데입니다. 내 컴퓨터에서는 CLI 세션에 /review를 치면 프리셋이 뜨고, 스크립트에서는 codex review --uncommitted처럼 비대화형으로 부릅니다. 깃허브에서는 PR 코멘트에 @codex review를 남기거나 자동 리뷰를 켜 둡니다. 어느 쪽이든 리뷰는 작업 트리를 건드리지 않습니다 — 실제로 codex review를 돌려 보면 세션 헤더가 sandbox: read-only로 뜹니다. 아래는 codex-cli 0.153.4를 윈도우 11에서 직접 돌려 확인한 내용이고, 공식 문서와 실제 CLI가 어긋나는 지점도 같이 적었습니다(2026년 9월 8일 기준).
1. CLI에서 /review 치면 프리셋이 뜬다
대화형 세션에서 /review를 입력하면 Select a review preset이라는 목록이 열립니다. 설치된 0.153.4 바이너리에 들어 있는 프리셋은 정확히 세 개입니다.
| 프리셋 | 무엇을 보나 |
|---|---|
| Review against a base branch | 기준 브랜치와의 갈래점(merge base)을 찾아 내 브랜치 diff를 본다 |
| Review uncommitted changes | staged · unstaged · 추적 안 되는(untracked) 파일까지 본다 |
| Custom review instructions | "이 함수 예외 처리 빠진 데 있나"처럼 기준을 직접 적어 좁힌다 |
codex review --commit <SHA>를 쓰세요.
리뷰 결과를 보고 나서 diff를 직접 확인하고 싶으면 이어서 /diff를 치면 됩니다. 참고로 클로드 쪽 도구도 비슷한 명령을 갖고 있어서, 클로드 코드 리뷰 방식과 비교해 보면 어떤 쪽을 어디에 붙일지 정하기 쉽습니다.
2. 비대화형 codex review 옵션 정리
codex --help의 하위 명령 목록에 review가 "Run a code review non-interactively"로 들어 있습니다. 즉 세션을 띄우지 않고 한 방에 돌릴 수 있습니다.
codex review --help| 옵션 | 설명 (--help 원문 기준) |
|---|---|
--uncommitted |
Review staged, unstaged, and untracked changes |
--base <BRANCH> |
Review changes against the given base branch |
--commit <SHA> |
Review the changes introduced by a commit |
--title <TITLE> |
리뷰 요약에 표시할 커밋 제목(선택) |
[PROMPT] |
리뷰 지시문. -를 주면 표준입력에서 읽는다 |
그래서 실제로는 이렇게 씁니다.
# 커밋 전 변경분만 리뷰
codex review --uncommitted
# main 과 갈라진 내 브랜치 전체를 리뷰
codex review --base main
# 특정 커밋 하나만
codex review --commit 9f2c1ab
# 기준을 좁혀서 (지시문을 그대로 인자로)
codex review --uncommitted "SQL 인젝션과 트랜잭션 경계만 봐 줘"
# 지시문이 길면 표준입력으로
cat review-rules.md | codex review --uncommitted -3. 리뷰만 다른 모델로 돌리기 — review_model
기본값은 지금 세션이 쓰는 모델입니다. 리뷰만 더 센 모델로 돌리고 싶으면 ~/.codex/config.toml에 review_model을 넣습니다. 공식 설정 레퍼런스의 설명은 "Optional model override used by /review (defaults to the current session model)"입니다.
# ~/.codex/config.toml
review_model = "gpt-5.5"이 키가 정말 먹는지는 --strict-config로 확인할 수 있습니다. 이 옵션은 이 버전이 모르는 설정 필드가 있으면 그냥 죽습니다.
$ codex review --uncommitted --strict-config -c review_model=gpt-5.5
# 설정 오류 없이 통과 → 0.153.4 가 아는 키
$ codex review --uncommitted --strict-config -c review_modelx=abc
Error loading config.toml: unknown configuration field `review_modelx` in -c/--config override--strict-config를 붙여 한 번 돌려 보면 오타를 바로 잡아 줍니다. 조용히 무시되는 것과 인정된 것을 구분하는 가장 빠른 방법입니다. 설정 파일의 다른 항목은 agents.md 작성법 글과 함께 보면 정리됩니다.
4. 깃허브 PR에서 자동 리뷰 받기
PR에 리뷰를 붙이는 건 CLI가 아니라 Codex 클라우드 쪽 기능입니다. 공식 문서 기준 준비물은 세 가지입니다: 리뷰할 저장소에 Codex cloud 설정, Codex 코드 리뷰 설정 접근 권한, 그리고 저장소 규칙을 따르게 하려면 AGENTS.md입니다.
- 한 건씩 요청 — PR 코멘트에
@codex review를 남깁니다. Codex가 👀로 반응한 뒤 리뷰를 올립니다. - 매번 자동으로 — Codex 설정에서 Automatic reviews를 켜면, 새 PR이 열릴 때마다 코멘트 없이 리뷰가 붙습니다.
- 한 번만 좁히기 —
@codex review for issues in the database migration처럼 코멘트에 관심사를 덧붙입니다.
깃허브에 올라오는 리뷰는 P0·P1 등급 문제만 올립니다. 문서 표현 그대로 "Codex flags only P0 and P1 issues so review comments stay focused on high-priority risks"입니다. 사소한 스타일 지적으로 PR이 뒤덮이지 않게 하려는 설계입니다.
5. 리뷰 기준을 AGENTS.md에 심어 두기
Codex는 저장소에서 AGENTS.md를 찾아 ## Code Review Rules 절의 규칙을 따릅니다. 규칙은 그 규칙이 다스리는 코드에 가장 가까운 파일에 둡니다 — 저장소 전역 규칙은 루트, 서비스별 규칙은 그 폴더의 AGENTS.md입니다.
## Code Review Rules
### 결제
- 금액 계산에 double 을 쓰지 않는다. 안전한 길: BigDecimal 로 계산하고 저장은 정수 최소단위.
- 외부 결제 API 호출을 트랜잭션 안에 두지 않는다. 안전한 길: 커밋 후 이벤트로 분리.공식 문서가 권하는 작성 요령은 네 가지입니다.
- 저장소에 고유한, 결과가 큰 것만 적는다 — 호환성 제약, 데이터 경계, 위험한 부수효과와 그게 왜 문제인지.
- 안전한 길이나 예외를 함께 적는다 — 그래야 정상 동작을 문제로 오해하지 않는다.
- 범위를 좁게, 오래 가게 — 바뀔 함수 이름보다 결과로 쓰고, 규칙은 해당 코드 옆에 둔다.
- 기계적인 검사는 CI에 남긴다 — 포맷·린트를 리뷰 규칙으로 옮기지 않는다.
규칙을 넣은 뒤에는 대표적인 PR 하나로 @codex review를 돌려 보고, 잡음이 많은 규칙은 좁히거나 지우라고 안내합니다. 문서가 못박아 둔 한 줄도 기억할 만합니다 — 리뷰 규칙은 Codex를 안내할 뿐, 테스트·브랜치 보호·필수 승인을 대신하지 않습니다. AGENTS.md 자체의 위치 우선순위는 agents.md 작성법에 정리해 두었습니다.
6. 안 될 때 — 실제로 나오는 두 에러
직접 돌려서 받은 메시지 그대로입니다.
$ codex review --uncommitted # 깃 저장소가 아닌 폴더에서
Not inside a trusted directory and --skip-git-repo-check was not specified.리뷰는 깃 diff를 읽는 기능이라 저장소 안에서만 의미가 있습니다. 저장소가 아니면 위 메시지로 끝납니다(문서도 앱·IDE 기준으로 "/review는 프로젝트가 깃 저장소 안일 때만 나타난다"고 적고 있습니다).
$ codex review --uncommitted # 로그인 안 된 상태
ERROR: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header
Review was interrupted. Please re-run /review and wait for it to complete.세션 헤더까지는 정상으로 뜨기 때문에 "설정이 잘못됐나" 싶지만, 원인은 인증입니다. codex login status가 Not logged in이면 먼저 로그인하세요. 설치 자체가 아직이면 codex cli 윈도우 설치 순서를 따르면 됩니다.
자주 묻는 질문 (FAQ)
Q. 리뷰가 코드를 직접 고치나요?
아니요. 리뷰는 우선순위를 붙인 지적만 내놓고 작업 트리를 바꾸지 않습니다. codex review를 돌리면 세션 헤더가 sandbox: read-only로 뜹니다. 다만 리뷰가 찾은 걸 "고쳐 줘"라고 이어서 시키면 그때는 평소 샌드박스·승인 설정이 그대로 적용됩니다.
Q. CLI 리뷰와 깃허브 PR 리뷰가 같은 건가요?
쓰는 곳이 다릅니다. CLI는 내 컴퓨터의 diff를 보고 터미널에 결과를 냅니다. 깃허브 쪽은 Codex 클라우드가 PR diff를 보고 깃허브 리뷰 코멘트로 올리며, 여기서는 P0·P1만 올립니다.
Q. 커밋 하나만 리뷰하려면요?
codex review --commit <SHA>를 쓰세요. 0.153.4의 /review 프리셋 목록에는 커밋 항목이 없습니다.
Q. 리뷰를 자주 돌리면 사용량이 많이 나가나요?
리뷰도 모델을 호출하므로 사용량에 잡힙니다. 남은 한도를 보는 방법은 codex 사용량 확인에 정리해 두었습니다.
마무리
정리하면 이렇습니다. 로컬에서는 /review(프리셋 3개) 또는 codex review --uncommitted | --base | --commit, 리뷰 모델만 바꾸려면 review_model, 깃허브에서는 @codex review와 Automatic reviews, 기준은 AGENTS.md의 ## Code Review Rules. 버전에 따라 프리셋 구성이 문서와 어긋날 수 있으니, codex --version과 codex review --help를 한 번 찍어 보고 시작하는 게 가장 빠릅니다.
📚 참고 출처 (2026년 9월 8일 확인 · codex-cli 0.153.4 직접 실행)
· Code review — Codex 공식 문서
· Review GitHub pull requests with Codex
· Slash commands in Codex CLI
· Codex Configuration Reference
COMMENTS