Codex 코드 리뷰(/review): 예시로 살펴보는 완벽 가이드

- Codex는 변화가 빠른 기능 영역이에요. 아래 내용은 작성 시점(2026년 8월)의 공식 문서와 대조했지만, 정확한 플래그 이름이나 동작에 의존하기 전에 반드시 최신 문서를 확인하세요.

/review가 실제로 하는 일

/review는 별도의 읽기 전용 서브턴으로 실행돼요. 가리킨 diff를 읽을 뿐, 작업 트리의 파일에는 절대 손대지 않아요. 출력은 diff 내 위치에 연결된 우선순위 지적 목록이지, 일반적인 코멘트 문단이 아니에요. 이것이 diff를 채팅에 붙여넣고 "이거 괜찮아 보여?"라고 묻는 것과의 핵심 차이예요. /review는 진행 중인 코딩 세션과 분리된, 별개의 구조화된 흐름이에요.

공식 문서(learn.chatgpt.com/docs/code-review, 2026년 8월 접속)에 따르면, 이것은 PR을 열기 전이나 병합 전에 실행하도록 만들어졌고, 일반 Codex 작업처럼 "대신 고쳐줘" 모드가 아니에요. Claude Code의 리뷰 흐름에 익숙하다면 머릿속 모델이 그대로 통해요. 별도의 단계이고, 쓰기 전에 읽는다는 거예요.

4가지 리뷰 프리셋

Codex에는 범용 "리뷰" 버튼 하나만 있는 게 아니에요. 리뷰하려는 diff 범위에 따라 프리셋을 골라요.

컴포저에서 /review를 입력하고 메뉴에서 프리셋을 골라요. 앞의 세 가지는 "기존 diff 범위 선택"이고, 네 번째는 기본 범위로 충분하지 않을 때 자체 기준을 적는 곳이에요. 예를 들어 "인증 취약점만 지적해줘"나 "AGENTS.md의 코딩 규칙에 맞춰 리뷰해줘"처럼요.

실행할 수 있는 곳 — CLI, IDE, 앱, 웹

/review는 한 곳에만 묶여 있지 않아요. 현재 네 곳에서 지원해요.

• CLI — 터미널 세션 중에 컴포저에서 /review를 입력하거나, 스크립트/CI에서 비대화형 codex review 명령을 실행해요(아래 플래그 섹션 참고).
• IDE 확장 — VS Code/JetBrains에 임베드된 같은 컴포저로, 열어둔 diff 바로 옆에서 리뷰해요. 창을 전환할 필요가 없어요.
• ChatGPT 데스크톱 앱 — 전용 리뷰 창이 있어, 리뷰 창을 코딩 창과 분리하고 싶을 때 유용해요.
• ChatGPT 웹 — 브라우저에서 바로 리뷰를 실행해요. 개발용 기기가 없을 때 편리해요.

네 곳 모두 같은 기반 리뷰 메커니즘을 공유하지만, 각 환경의 정확한 UI와 명칭이 1:1로 일치한다는 보장은 없어요. 이 글의 버튼 이름이나 메뉴 위치가 어색해 보이면 최신 문서로 확인해볼 만해요.

비대화형 CLI 플래그 (스크립트/CI용)

컴포저의 /review 외에도 Codex는 스크립트나 CI 파이프라인을 위한 비대화형 codex review 명령을 제공해요. learn.chatgpt.com/docs/cli/reference, 2026년 8월 접속 기준이에요.

# Review the diff against a base branch
codex review --base main

# Review one specific commit, with an optional title (--title requires --commit)
codex review --commit <sha> --title "Fix invoice endpoint"

# Review uncommitted changes (staged + unstaged + untracked)
codex review --uncommitted

# Freeform prompt, read directly from stdin
git diff | codex review -

# Strict-match config.toml when you need consistent CI behavior
codex review --base main --strict-config

핵심 규칙: 범위 플래그는 상호 배타적이에요. 실행마다 --base, --commit, --uncommitted, 또는 PROMPT/stdin 중 정확히 하나만 고르고, 절대 섞지 마세요. 이 부분은 Codex 릴리스마다 이름이 조용히 바뀌기 쉬운 곳이라, CI에 하드코딩하기 전에 정확한 플래그 이름을 다시 확인하세요.

실제 diff 리뷰하기 — 실전 예시

이론은 접어두고, 작은 Node.js 라우트에서 /review가 흔히 잡아내는 지적의 예를 볼게요(설명을 위해 다듬었고, 실제 원본 출력 그대로는 아니에요). 이 라우트는 멀티테넌트 시스템에서 ID로 청구서를 가져와요.

// Before
async function getInvoice(req, res) {
 const invoice = await db.invoices.findOne({ id: req.params.id });
 if (!invoice) return res.status(404).end();
 res.json(invoice);
}

지적 1 (심각도: 높음, 정확함): "테넌트 범위 필터가 빠졌어요 — 이 라우트는 id로만 조회하기 때문에, 테넌트 A의 사용자가 ID를 추측하면 테넌트 B의 청구서를 볼 수 있어요. 쿼리 필터에 tenantId: req.user.tenantId를 추가하세요." 이건 교과서적인 IDOR(안전하지 않은 직접 객체 참조) 버그예요. 문법적으로는 문제없고 오류 없이 실행되지만, 테넌트를 넘어 데이터가 유출돼요. 수정은 이래요.

// After
async function getInvoice(req, res) {
 const invoice = await db.invoices.findOne({
 id: req.params.id,
 tenantId: req.user.tenantId,
 });
 if (!invoice) return res.status(404).end();
 res.json(invoice);
}

지적 2 (심각도: 중간, 사람이 한 번 더 봐야 함): /review는 "이 라우트에는 속도 제한이 없어요"라고도 지적했어요. 코드 수준에서는 맞지만, gateway.config.ts를 확인해 보니 이 라우트는 이미 API 게이트웨이의 전역 속도 제한 뒤에 있었어요. 이 지적이 기술적으로 틀린 건 아니고, 단지 /review가 볼 수 없는 맥락(diff 범위 밖의 설정)이 빠졌을 뿐이에요. 자동으로 적용할 게 아니라, 조치하기 전에 사람이 확인해야 하는 경우예요.

한 번의 실행에서 나온 두 지적은 /review 출력을 어떻게 읽어야 하는지 정확히 보여줘요. 지적 1은 진짜 버그이니 지금 고치고, 지적 2는 로컬로는 맞지만 시스템 전체 맥락이 빠졌으니 자동 적용이 아니라 당신의 확인이 필요해요.

GitHub PR 리뷰하기 — gh가 필요한 부분

대충 훑어보면 헷갈리기 쉬운, 서로 다른 두 가지 GitHub 메커니즘이 있어요.

1. PR 맥락을 로컬에서 읽기 (gh 필요). CLI, 앱, IDE에서 PR을 리뷰할 때, Codex는 PR 정보(제목, 설명, 코멘트)를 가져오기 위해 gh가 설치되고 인증돼 있어야 해요. 문서에 따르면 gh가 없거나 인증되지 않으면 PR 세부 정보가 사이드바나 리뷰 창에 나타나지 않을 수 있어요. 설정은 명령 하나예요.

gh auth login

2. 코멘트로 클라우드 리뷰 트리거하기 (로컬 gh 불필요). GitHub PR에 직접 @codex review라고 코멘트하면 클라우드 쪽에서 실행되는 리뷰가 트리거돼요. 위의 로컬 PR 맥락 읽기와는 완전히 별개의 메커니즘이고, 당신의 기기에 gh가 필요하지 않아요. 조건은 저장소에 Codex 클라우드가 이미 구성돼 있어야 한다는 거예요. 이 메커니즘은 더 깊은 Codex Cloud 설정에 속해요. 이런 자동 리뷰 트리거를 구성하고 싶다면 그 내용은 Codex Cloud 가이드에 있어요. 여기서는 두 메커니즘을 헷갈리지 않도록 한 줄만 짚어둘게요.

/review 지적을 얼마나 믿어야 할까요?

솔직히 말하면, /review 지적은 우선순위가 매겨진 제안이지, 자동 병합 게이트가 아니에요. 위의 지적 2가 이를 잘 보여줘요. 문법적으로도 맞고 로컬 로직으로도 맞지만, 시스템 전체 맥락이 빠져서 틀렸어요. 리뷰가 전체 저장소가 아니라 diff만 볼 때, 이런 오탐은 생각보다 자주 일어나요.

그래서 실제 병합 결정을 게이트하는 건 여전히 사람이에요(또는 AgentKit의 Engineer Kit를 설치했다면 그 code-review 스킬/에이전트예요). /review는 기계적인 스캔 부분을 줄여줘서, 사람 리뷰어가 더 어려운 부분에 힘을 쏟게 해줘요. AgentKit는 Claude Code와 Codex 양쪽에서 동작하는, 비슷한 리뷰 흐름의 /ak:review 명령을 제공하는데, 직접 조립하는 대신 미리 만들어진 프로세스가 필요할 때 편리해요. 다만 분명히 해두자면, 이건 그 위에 얹는 유료 키트예요. Codex 자체의 /review는 이미 무료이고 개인 리뷰에는 충분해요. 아직 설정하지 않았다면 먼저 Codex 안에서 AgentKit 사용하기를 보세요.

Codex의 /review vs Claude Code의 리뷰 흐름

발상은 같고 도구가 달라요. Claude Code에도 자체 /review가 있고, "심각한 지적이 남아 있는 동안 병합을 막는" 같은 워크플로를 가져요. 3단계 프로세스와 실제 지적 예시는 Claude Code용 AI 코드 리뷰 가이드에 있어요(그 글은 Codex를 전혀 언급하지 않고, 이 글도 그 내용을 반복하지 않아요). 두 도구를 모두 쓴다면 근본 원칙은 어느 쪽이든 같아요. diff에 대해 리뷰하고, 심각도로 순위를 매기고, 최종 병합 결정은 여전히 사람이 내려요.

자주 묻는 질문

Codex의 /review 프리셋에는 어떤 게 있나요?

베이스 브랜치(병합 기준점에 대한 전체 diff 리뷰), 커밋되지 않음(스테이징됨 + 스테이징 안 됨 + 추적되지 않음), 특정 커밋(그 커밋의 변경 세트), 그리고 커스텀 지시(자유 형식으로 자체 리뷰 기준 설명)가 있어요.

/review가 제 코드를 수정하나요?

아니요. /review는 읽기 전용 서브턴으로 실행되고 작업 트리의 파일에는 절대 손대지 않아요. 우선순위가 매겨진 지적 목록만 돌려주고, 무엇을 고치거나 건너뛸지는 당신이 정해요.

PR 리뷰에 gh가 필요한가요?

네. CLI/앱/IDE에서 PR 맥락(제목, 설명, 코멘트)을 로컬로 읽으려면 gh가 설치되고 인증돼 있어야 하고, 그렇지 않으면 PR 세부 정보가 사이드바에 나타나지 않을 수 있어요. 이건 @codex review라고 코멘트하는 것과는 다른데, 그쪽은 로컬 gh가 필요 없어요.

GitHub의 @codex review는 뭔가요?

PR에 직접 @codex review라고 코멘트해서 클라우드 쪽 리뷰를 트리거하는 방법으로, PR 맥락을 로컬로 읽는 것과는 별개예요. 저장소에 Codex 클라우드가 이미 구성돼 있어야 하고, 더 깊은 세부 사항은 Codex Cloud의 영역이라 이 글의 범위 밖이에요.

스크립트/CI에서 리뷰를 실행할 수 있나요?

네. 비대화형 codex review 명령에 --base, --commit, --uncommitted, 또는 PROMPT/stdin을 써요. 실행마다 범위 플래그는 정확히 하나만, 절대 함께 쓰지 않아요.

/review가 사람의 승인을 대체하나요?

아니요. /review 지적은 우선순위가 매겨진 제안이고, 시스템 전체 맥락이 빠져 틀릴 수 있어요(위의 지적 2 참고). 최종 병합 결정은 여전히 사람이, 또는 AgentKit의 Engineer Kit가 제공하는 것 같은 전용 리뷰 에이전트가 내려요.

결론

정리하면, Codex의 /review는 프리셋 4개를 갖고, CLI/IDE/앱/웹에서 동작하며, 스스로 파일을 수정하지 않고, 로컬 PR 맥락이 필요할 때 gh가 필요해요. 반면 코멘트로서의 @codex review는 별개의 클라우드 메커니즘이에요. 지적은 자동 병합 게이트가 아니라 우선순위가 매겨진 제안으로 읽으세요. Claude Code도 쓴다면 Claude Code용 AI 코드 리뷰 흐름을, Codex가 처음이라면 OpenAI Codex란 무엇인가부터 시작하세요.