Codex 코드 리뷰 실전: AI가 PR을 보되 코드를 함부로 고치지 않게 하는 법

800줄짜리 PR이 올라왔는데 제목은 fix, 설명은 “몇 가지 문제를 고쳤습니다” 한 줄뿐입니다. diff를 보고 있어도 어디가 핵심 변경인지 확신이 없고, 변경 파일 전체를 한 줄씩 읽고 싶지도 않습니다. 누군가 PR comment에 @codex review for auth bypass and PII logging이라고 남기면, 몇 분 뒤 logger.info(user.email)을 가리키는 inline comment가 나타납니다.

이제 결정해야 합니다. Codex가 자동으로 fix하게 할지, 직접 고칠지, 아니면 먼저 비즈니스 담당자에게 이 로그가 정책상 허용되는지 확인할지 말입니다. 이 글에서는 트리거 조건, Review guidelines 작성법, P0/P1의 의미, 처리 흐름, 사람이 확인해야 하는 경계를 정리합니다.

@codex review는 만능 주문이 아닙니다

@codex review는 AI가 코드를 자동으로 바꾸게 하는 스위치가 아닙니다. Codex가 PR diff를 읽고, 정해 둔 규칙에 따라 review comments를 게시하게 하는 요청입니다. 트리거되는지, 트리거 후 무엇을 보는지, review 결과를 어떻게 처리할지는 모두 사전 조건과 사람의 판단에 달려 있습니다.

GitHub Cloud 트리거와 설정

Codex로 code review를 하려면 repository에 Codex Cloud가 설정되어 있어야 하고, code review settings에 접근할 권한이 있어야 합니다. 트리거 방식은 두 가지입니다. PR comment에 @codex review라고 쓰거나, settings에서 Automatic reviews를 켜서 새 PR이 opened for review 상태가 될 때 Codex가 자동으로 review를 게시하게 할 수 있습니다.

트리거된 뒤 Codex는 PR diff를 읽고, repository guidance, 즉 AGENTS.md의 Review guidelines를 따르며, 표준 GitHub code review 형식으로 inline comments를 게시합니다. @codex review는 approval이 아닙니다. Automatic reviews도 자동 승인이라는 뜻이 아닙니다. auth, payment, data migration 같은 민감한 변경은 여전히 사람이 확인해야 합니다.

PR trigger와 CI workflow에 branch protection rules를 조합하면 AI review를 여러 점검 중 하나로 둘 수 있습니다. PR trigger 설정은 이전 글 GitHub Actions PR 트리거 기본을 참고하세요.

P0/P1에 집중하고, 장황한 기록으로 만들지 않기

Codex는 기본적으로 P0/P1 우선순위 문제만 표시합니다. P0는 security regressions, auth bypass, data loss 같은 차단급 문제입니다. P1은 performance, concurrency, logging sensitive data처럼 고쳐야 하는 문제입니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

이렇게 좁히는 이유는 review comments가 폭발하는 것을 막고, 신호를 높게 유지하며, 낮은 가치의 노이즈를 줄이기 위해서입니다. AGENTS.md의 Review guidelines 섹션에서 기본 규칙을 덮어쓸 수 있습니다. 예를 들어 auth bypass, PII logging, concurrency만 보게 하고, code style은 Prettier에 맡기며, minor performance는 hot path가 아니면 보지 않게 할 수 있습니다. 다음 절에서 Review guidelines의 구체적인 작성법을 다룹니다.

Review guidelines는 AGENTS.md에 쓰고, PR comment에 매번 반복하지 않습니다

Review guidelines는 Codex review의 focus와 우선순위를 결정합니다. 이 규칙은 repository의 AGENTS.md 파일에 있어야 하며, 매번 PR comment에 반복해서 쓸 필요가 없습니다.

AGENTS.md 계층 읽기와 Review guidelines 작성법

Codex는 작업을 시작하기 전에 AGENTS.md를 읽습니다. 읽는 순서는 Git root에서 현재 작업 디렉터리까지 계층적으로 내려가며, 더 가까운 디렉터리의 지침이 더 구체적입니다. 예를 들어 auth/ 디렉터리 아래의 AGENTS.md는 프로젝트 전체 규칙을 덮어쓰고 auth 관련 리스크만 보게 할 수 있습니다.

전형적인 Review guidelines 섹션은 다음과 같습니다.

## Review guidelines

다음 리스크에만 집중:
1. Security regressions(auth bypass、path traversal)
2. PII logging(user.email、phone number)
3. Concurrency issues(race condition、deadlock)

보지 않을 것:
- Code style(Prettier로 자동화)
- Minor performance(핫패스가 아닌 경우)

이 방식의 장점은 모든 PR이 같은 기준을 공유하고, 매번 comment로 반복하지 않아도 되며, changed file과 가까운 AGENTS.md가 더 구체적인 규칙을 제공할 수 있다는 점입니다.

주의할 점도 있습니다. 지침 파일 길이는 project_doc_max_bytes 제한을 받으며, 기본값은 32 KiB입니다. 너무 긴 파일은 잘릴 수 있습니다. Project rules, Review guidelines, Coding style을 포함한 AGENTS.md 전체 작성법은 Codex 실전 가이드의 다른 글에서 다룰 예정입니다. 이 글은 Review guidelines의 구조와 우선순위 제어에만 집중합니다.

Codex app review pane에서 diff를 보고 결정합니다

Codex app의 review pane은 AI의 변경 제안만 보여 주는 화면이 아닙니다. Git repository의 전체 상태를 반영합니다. 기본적으로 uncommitted changes에 집중하지만, all branch changes나 last turn changes로 전환할 수도 있습니다.

Inline comments와 PR context

Review pane의 inline comments는 diff 줄에 직접 붙습니다. 이 정확한 피드백을 기준으로 다음 행동을 결정할 수 있습니다. Codex가 fix하게 할지, 직접 고칠지, false positive로 표시할지 말입니다. /review를 실행하면 결과가 review pane의 inline comments로 표시됩니다.

Codex가 GitHub access를 가지고 있고 현재 프로젝트가 PR branch 위에 있다면, app에서 PR context를 보여 줄 수 있습니다. reviewer feedback, changed files, PR description 같은 정보입니다. 전제 조건은 GitHub CLI가 설치되어 있고 gh auth login으로 인증되어 있어야 한다는 점입니다. 이 조건이 없으면 PR details가 보이지 않고 로컬 diff만 보일 수 있습니다.

file 또는 hunk 단위로 stage/revert하고, commit 전체를 되돌리지 않습니다

Review pane은 entire diff, file, hunk 단위로 stage, unstage, revert를 지원합니다. finding을 보자마자 commit 전체를 revert하는 것은 좋지 않습니다. 특히 여러 file을 바꾼 경우 더 위험합니다. hunk 단위로 처리하면 안전한 변경은 남기고, 위험한 부분만 되돌릴 수 있습니다.

review findings 처리: @codex fix 뒤에도 diff, CI, 테스트를 봅니다

P0/P1이 발견되면 바로 @codex fix에 맡기고 끝내면 안 됩니다. 이 finding이 실제인지, 수정 방식이 합리적인지, 민감한 변경이라 팀 확인이 필요한지 판단해야 합니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

Review findings triage 판단표

findings 처리 실행 흐름

finding이 실제인지 확인합니다: inline comment가 가리키는 diff 줄을 보고 실제 문제가 있는지 확인합니다.

수정 경계를 판단합니다: auth, payment, data migration은 민감한 변경이므로 사람이 반드시 확인해야 합니다. style이나 minor perf는 무시하거나 toolchain에 맡길 수 있습니다.

처리 방식을 고릅니다:

• Codex가 fix하게 하기: PR comment에 @codex fix the P1 issue라고 쓰면, Codex가 PR context를 기반으로 cloud task를 시작합니다
• 직접 고치기: 수동으로 코드를 수정하고, 로컬 테스트 후 push합니다
• 테스트 보강 요청하기: follow-up issue를 열거나 comment에서 설명합니다
• false positive로 표시하기: comment에 이유를 설명해 이후 같은 오탐을 줄입니다

diff와 CI를 확인합니다: @codex fix가 PR branch에 push할 권한을 가지고 있어도 diff, CI 결과, 테스트 커버리지는 확인해야 합니다. Codex의 fix는 자동 merge도, CI 통과도, 사람 reviewer의 approve도 아닙니다.

민감한 변경은 사람이 확인합니다: auth bypass, payment flow, data migration은 보안 경계와 관련됩니다. 팀 reviewer가 확인해야 합니다. 사람의 점검을 건너뛰면 안 됩니다.

하지 말아야 할 일

• 자동 push/merge하지 않습니다: @codex fix는 AI에게 코드 변경을 요청하는 것일 뿐 merge 허가가 아닙니다
• CI 점검을 건너뛰지 않습니다: Codex가 문제를 고쳐도 CI를 실행해 다른 테스트가 깨지지 않았는지 확인해야 합니다
• 사람 reviewer의 의견을 무시하지 않습니다: AI review는 두 번째 점검이지 팀 reviewer의 대체가 아닙니다
• Codex에 과도한 권한을 주지 않습니다: main branch push, force push, 민감 디렉터리 write access는 제한해야 합니다

민감한 변경의 보안 경계와 권한 제어는 Codex 실전 가이드의 후속 글, 즉 보안 권한과 Secrets 관리에서 더 자세히 다룹니다. CI workflow의 모범 사례는 이전 글 GitHub Actions CI pipeline을 참고하세요.

commit message와 PR description: AI가 문안을 쓰게 하되 규칙을 지어내지 않습니다

@codex generate commit message 또는 @codex generate PR description을 쓰면 Codex가 diff와 PR context를 기반으로 문안을 만들 수 있습니다. 생성 후에는 사람이 검토해야 하며, 그대로 commit하면 안 됩니다. commit message는 Conventional Commits 규격을 따라야 하고, 임의 형식을 만들면 안 됩니다.

Conventional Commits 규격과 commit message 템플릿

Conventional Commits 형식은 <type>[optional scope]: <description>입니다. 흔한 type으로는 PATCH 버전에 대응하는 fix, MINOR 버전에 대응하는 feat, breaking change를 나타내는 BREAKING CHANGE footer 또는 !가 있습니다.

예시:

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

fix(auth): prevent bypass in login flow

- Add session validation before auth redirect
- Reject expired tokens within 5 minutes

Refs: #123

Conventional Commits를 쓰는 이유는 널리 쓰이는 표준이기 때문입니다. semantic-release, auto-changelog, commitlint 같은 toolchain은 이 형식을 기반으로 changelog를 자동 생성하고 버전 번호를 판단합니다. 임의 규칙을 만들면 toolchain이 깨지고 팀 협업 비용이 늘어납니다.

PR description 템플릿

PR description에는 최소 다섯 가지가 들어가야 합니다.

1. 배경: 왜 이 변경을 하는지(사용자 피드백, 성능 문제, 보안 리스크)
2. 변경 범위: 어떤 모듈이 영향을 받는지(auth, payment, logging)
3. 테스트: 확인한 시나리오(로컬 테스트, CI 커버리지, 수동 검증)
4. 리스크: 알려진 경계 조건(동시성 시나리오, 고트래픽 상황의 동작)
5. 롤백: 빠르게 되돌리는 방법(revert commit, feature flag, config toggle)

Codex가 생성한 뒤에는 이 다섯 부분이 모두 있는지, 설명이 정확한지, 리스크와 롤백이 빠지지 않았는지 확인합니다. 특히 민감한 변경에서는 생성된 문안을 그대로 commit하지 마세요.

commit message와 PR description 생성 전략은 PR comment에 구체적인 지시로 쓸 수 있습니다. 예를 들어 @codex generate commit message following Conventional Commits라고 쓰면 AI가 표준 형식을 따르게 할 수 있습니다.

요약

Codex review는 두 번째 고신호 점검이지 merge 허가가 아닙니다. @codex review는 AI에게 diff를 읽고 inline comments를 게시하게 하는 요청입니다. Automatic reviews는 트리거 단계를 자동화할 뿐, approval이나 merge가 아닙니다.

핵심 흐름:

1. AGENTS.md의 Review guidelines에서는 auth bypass, PII logging, concurrency 같은 리스크 1~2개에 집중합니다. 너무 넓게 잡지 않습니다
2. P0/P1은 기본 focus이며, review comments가 폭발하는 것을 막습니다. P0는 반드시 고쳐야 하고, P1은 처리 방식을 판단해야 합니다
3. finding이 나오면 inline comment가 가리키는 diff 줄을 보고 실제 문제인지 확인합니다. auth, payment, data migration 같은 민감한 변경은 사람이 확인해야 합니다
4. @codex fix 뒤에도 diff, CI 결과, 테스트 커버리지, 사람의 판단을 확인합니다. 자동 push/merge, CI 건너뛰기, 사람 reviewer 무시는 하지 않습니다
5. commit message는 Conventional Commits 규격을 사용합니다. 임의 형식을 만들지 마세요. toolchain은 표준 형식에 의존해 changelog를 생성하고 버전을 판단합니다

실행 제안:

• repository에 AGENTS.md를 추가하고, 1~2개 리스크만 다루는 Review guidelines를 작성합니다
• 다음 PR에서 @codex review를 시도하고, inline comments가 규칙에 맞는지 봅니다
• 민감한 변경에서는 보안 권한과 Secrets 관리, AI 변경 실패 복기 같은 Codex 실전 가이드 후속 글을 먼저 읽고 @codex fix를 쓸지 결정합니다

관련 글

• GitHub Actions PR 트리거 기본: PR trigger와 branch protection rules 설정
• GitHub Actions CI pipeline 모범 사례: CI 흐름의 점검과 사람 reviewer의 역할
• AI coding assistant 비교: Claude Code vs Cursor vs Copilot: AI coding tool 선택 기준