Codex 코드리뷰 사용법: PR 검토와 버그 찾기 자동화하기

Codex 코드리뷰는 커밋 전 로컬 변경이나 GitHub Pull Request의 diff를 읽고, 실제 동작을 깨뜨릴 가능성이 큰 회귀와 버그를 우선순위별로 찾는 보조 검토 방식입니다. 로컬에서는 /review, GitHub PR에서는 @codex review를 사용하며 저장소별 기준은 AGENTS.md에 둘 수 있습니다. 설정부터 오탐을 줄이는 규칙, 발견된 문제를 안전하게 수정하는 순서까지 설명합니다.

Codex 코드리뷰가 하는 일

Codex는 선택한 diff와 저장소 문맥을 바탕으로 조치 가능한 문제를 찾고 근거가 되는 파일과 줄을 제시합니다. OpenAI 공식 문서에 따르면 로컬 /review는 작업 트리를 수정하지 않은 채 우선순위에 따라 결과를 보고합니다. GitHub 코드 검토는 PR에 일반 코드 리뷰로 게시되며 높은 위험에 집중하도록 P0와 P1 이슈를 표시합니다.

방식	검토 대상	알맞은 시점
앱·CLI·IDE의 /review	브랜치 diff, 미커밋 변경, 특정 커밋	커밋·푸시 전
GitHub @codex review	열린 Pull Request	팀 리뷰와 병합 전
GitHub 자동 검토	설정 조건을 만족하는 새 PR	모든 PR에 일관된 1차 검토
@codex security review	PR의 보안 위험	인증·비밀·권한 등 고위험 변경

코드리뷰가 잘 찾는 문제와 놓칠 수 있는 문제

• 회귀: 기존 입력이나 호출 순서에서 달라진 동작
• 경계 조건: 빈 값, 최대값, 동시 요청과 재시도에서 발생하는 오류
• 호환성: API 응답, 데이터베이스 스키마와 공개 타입의 깨지는 변경
• 보안: 인증·인가 누락, 민감 정보 노출과 불안전한 입력 처리
• 검증 누락: 변경된 동작을 보호할 테스트나 문서가 없는 경우

반면 제품 요구사항이 문서화되지 않았거나 diff 밖의 운영 데이터, 외부 시스템 상태가 핵심이면 올바른 동작을 단정하기 어렵습니다. 리뷰가 아무 문제도 보고하지 않았다는 사실은 버그가 없다는 증명이 아닙니다.

로컬에서 /review 사용하는 방법

프로젝트가 Git 저장소 안에 있어야 /review를 사용할 수 있습니다. Codex 앱, CLI 또는 IDE 확장의 입력창에서 명령을 실행하고 검토 범위를 선택합니다.

/review

1. 기준 브랜치와 비교: 현재 브랜치가 main이나 지정 브랜치에서 달라진 전체 내용을 봅니다.
2. 커밋되지 않은 변경: 스테이징·미스테이징·추적되지 않은 파일을 검토합니다.
3. 특정 커밋: 한 커밋에 포함된 변경만 확인합니다.
4. 사용자 지정 지침: 특정 위험이나 테스트 범위를 중심으로 검토합니다.

처음에는 전체 diff를 검토하고, 지적 사항을 수정한 뒤 같은 범위를 다시 검토하면 회귀가 남았는지 확인하기 쉽습니다. 검토 과정은 읽기 전용이지만 이후 수정을 요청하면 기존 샌드박스와 승인 설정이 적용됩니다.

버그를 더 잘 찾는 로컬 요청문

/review Focus on behavior regressions, null and empty inputs,
authorization boundaries, race conditions, and missing tests.
Report only actionable findings with file and line evidence.
Do not suggest style-only changes.

검토 범위를 넓게 늘어놓기보다 이번 변경에서 실제 위험한 축을 선택하세요. 데이터 마이그레이션이라면 롤백과 구버전 호환성, 결제라면 중복 처리와 멱등성, React 화면이라면 로딩·빈 상태·모바일 오버플로를 지정하는 식입니다.

GitHub PR에서 @codex review 설정하기

OpenAI 공식 문서 기준으로 GitHub 자동 검토를 구성하려면 Codex Cloud가 설정된 저장소, 연결된 GitHub 저장소와 해당 설정에 대한 push 또는 admin 권한이 필요합니다.

1. 검토할 저장소에 Codex Cloud를 설정합니다.
2. Codex 설정의 Code review로 이동합니다.
3. 대상 저장소에서 코드 검토를 켭니다.
4. Pull Request 댓글에 정확히 @codex review를 남깁니다.
5. Codex가 반응을 남긴 뒤 게시한 리뷰의 파일·줄·우선순위를 확인합니다.

모든 새 PR을 검토하려면 설정에서 자동 검토를 활성화할 수 있습니다. 이 경우 새 PR이 검토 대상으로 열릴 때 댓글을 직접 남기지 않아도 Codex가 검토를 게시합니다.

한 번만 검토 초점을 지정하기

PR마다 위험이 다르면 댓글에 이번 검토의 초점을 함께 적을 수 있습니다.

@codex review for backward compatibility, transaction rollback,
and data loss risks in the database migration

다음과 같이 한국어로 구체적인 실패 시나리오를 덧붙이는 것도 가능합니다.

@codex review
이번 변경에서 권한이 없는 사용자가 다른 사용자의 데이터를 읽을 수 있는 경로,
재시도 시 중복 결제가 발생하는 경로, 누락된 회귀 테스트를 중점적으로 검토해줘.

AGENTS.md로 저장소별 리뷰 규칙 만들기

Codex는 변경된 파일에 적용되는 AGENTS.md를 찾아 ## Code Review Rules 섹션의 지침을 따릅니다. 저장소 전체 규칙은 루트에 두고 결제·인증처럼 특정 서비스에만 필요한 규칙은 해당 코드와 가까운 하위 파일에 둡니다. 자세한 파일 우선순위는 Codex AGENTS.md 작성법에서 확인할 수 있습니다.

## Code Review Rules

### Authentication
- Flag routes that access user data without the existing authorization check.
  Safe path: verify resource ownership before reading or modifying data.

### Payments
- Flag retries that can create duplicate charges.
  Safe path: require an idempotency key and test repeated requests.

### API compatibility
- Flag removal or renaming of public response fields.
  Exception: an approved versioned endpoint with a migration note.

좋은 리뷰 규칙과 나쁜 리뷰 규칙

피할 규칙	개선한 규칙
코드를 꼼꼼히 검토한다	사용자 소유권 확인 없이 데이터를 읽는 경로를 표시한다
보안을 확인한다	관리자 전용 작업에서 서버 측 권한 검사가 빠지면 표시한다
테스트가 충분해야 한다	버그 수정에는 실패를 재현하고 수정 후 통과하는 회귀 테스트가 있어야 한다
스타일 오류를 찾는다	포맷·lint는 CI에 맡기고 동작 변경에 집중한다
함수 X를 항상 사용한다	인증된 사용자와 리소스 소유권을 확인하는 결과를 요구한다

공식 문서는 검토자가 반복해서 설명하는 영향도 높은 기준 두세 개로 시작하고, 포맷팅이나 lint처럼 기계적으로 판정 가능한 검사는 CI에 맡길 것을 권합니다. 안전한 처리법과 예외를 함께 쓰면 정상 동작을 버그로 오인하는 경우를 줄일 수 있습니다.

우선순위별로 결과 판단하기

등급	판단 질문	권장 대응
P0	배포 즉시 광범위한 장애·손실·침해를 일으키는가	병합 중단, 즉시 재현과 수정
P1	일반적인 사용 경로에서 심각한 오동작이 발생하는가	병합 전 수정과 회귀 테스트
P2	특정 조건에서 제한적으로 잘못 동작하는가	영향 범위와 일정에 따라 처리
P3	낮은 위험의 개선이나 유지보수 문제인가	별도 이슈 또는 후속 작업

등급 이름만 믿지 말고 실제 입력, 도달 가능성, 사용자 영향과 복구 가능성을 확인하세요. GitHub의 Codex 리뷰가 P0·P1에 집중한다는 것은 낮은 우선순위 문제가 존재하지 않는다는 의미가 아닙니다.

리뷰 결과가 진짜 버그인지 확인하는 5단계

1. 문제 줄을 봅니다. 지적된 줄만 아니라 호출자와 변경 전 동작도 확인합니다.
2. 도달 가능성을 확인합니다. 실제 입력과 권한으로 해당 경로가 실행되는지 봅니다.
3. 최소 재현을 만듭니다. 실패하는 테스트나 명령으로 관찰 가능한 증상을 남깁니다.
4. 수정 범위를 제한합니다. 지적 사항과 무관한 리팩터링을 섞지 않습니다.
5. 다시 검토합니다. 회귀 테스트, 기존 테스트, lint·typecheck를 실행하고 동일 범위를 재검토합니다.

오탐을 줄이는 방법

• PR 설명에 변경 목적, 비변경 영역과 호환성 결정을 작성합니다.
• 생성 파일·벤더 코드처럼 사람이 수정하지 않는 영역을 명시합니다.
• 저장소 고유의 안전한 패턴과 허용된 예외를 AGENTS.md에 적습니다.
• 한 PR의 변경 범위를 작게 유지해 관련 없는 문맥을 줄입니다.
• 대표 PR에서 규칙을 시험하고 불필요한 경고를 만드는 문장을 좁힙니다.
• 스타일·포맷·정적 규칙은 CI와 전용 분석기에 맡깁니다.

보안 검토는 언제 사용할까

인증·인가, 비밀정보, 암호화, 결제, 파일 업로드와 외부 명령 실행이 바뀌는 PR이라면 일반 코드 검토와 별도로 보안 검토를 고려할 수 있습니다. 공식 문서에 따르면 보안 검토는 연구 프리뷰이며 PR diff, 저장소 문맥과 구성된 보안 지침을 더 깊게 분석합니다.

@codex security review

일반 코드 검토도 보안 문제를 찾을 수 있어 결과가 겹칠 수 있습니다. 보안 검토 역시 위협 모델링, 전문 보안 도구, 침투 테스트와 사람의 승인을 대신하지 않습니다.

발견된 문제를 Codex에 수정 요청하기

GitHub 리뷰가 게시된 뒤 같은 PR에서 특정 항목을 지정해 수정을 요청할 수 있습니다.

@codex fix the P1 issue

필요한 권한이 있으면 Codex가 PR을 문맥으로 클라우드 작업을 시작하고 변경을 브랜치에 푸시할 수 있습니다. 자동 수정 전에는 지적 사항의 재현 가능성을 확인하고, 수정 후 diff와 테스트 결과를 사람이 다시 검토하세요. “모든 지적을 수정해줘”보다 항목 하나씩 처리하면 예상치 못한 변경을 줄일 수 있습니다.

PR 컨텍스트가 보이지 않을 때

데스크톱 앱에서 PR 댓글과 변경 파일을 불러오려면 공식 문서가 안내하는 GitHub CLI 인증을 사용할 수 있습니다.

gh auth login

gh가 설치되지 않았거나 인증되지 않으면 PR 세부 정보가 사이드바와 검토 창에 표시되지 않을 수 있습니다. 현재 프로젝트가 해당 PR 브랜치인지, Codex가 저장소에 접근할 권한이 있는지도 함께 확인합니다.

@codex review가 반응하지 않을 때

증상	확인할 항목	해결
반응 자체가 없음	정확한 트리거	PR 댓글에 @codex review 사용
리뷰가 게시되지 않음	저장소 코드 검토 설정	Codex 설정에서 대상 저장소 활성화
특정 저장소만 실패	Codex Cloud 연결	해당 저장소 연결과 권한 재확인
자동 리뷰가 누락됨	자동 검토와 PR 이벤트 조건	설정된 트리거 조건 확인
로컬 /review가 안 보임	Git 저장소 여부	올바른 프로젝트 루트에서 실행
PR 문맥이 없음	GitHub CLI 인증·현재 브랜치	gh auth login 후 PR 브랜치 확인

팀에 적용하는 현실적인 자동화 순서

1. 한 저장소에서 수동 @codex review로 2~4주 시험합니다.
2. 실제 버그, 오탐, 놓친 버그와 수정 시간을 기록합니다.
3. 반복되는 도메인 기준 2~3개를 AGENTS.md에 추가합니다.
4. 규칙을 대표 PR과 의도적으로 만든 실패 사례에 시험합니다.
5. 신호 품질이 안정되면 자동 검토를 활성화합니다.
6. 브랜치 보호, 필수 CI와 사람 승인 규칙은 그대로 유지합니다.
7. 매월 규칙의 유효성과 오탐을 검토해 오래된 항목을 삭제합니다.

리뷰 절차 자체를 반복 가능한 워크플로로 묶고 싶다면 Codex Skills 사용법도 참고할 수 있습니다. 다만 자동화가 늘어날수록 승인 경계와 실패 시 중단 조건을 더 명확히 해야 합니다.

병합 전 최종 체크리스트

• PR 목적과 실제 diff가 일치하는가
• Codex 지적 사항을 재현하거나 근거를 확인했는가
• 정상·오류·권한·경계 조건 테스트가 있는가
• 공개 API와 데이터 마이그레이션의 호환성을 확인했는가
• lint, typecheck, 단위·통합 테스트가 통과했는가
• 보안과 개인정보 영향이 있는 변경을 별도로 검토했는가
• 필수 사람 승인과 브랜치 보호를 통과했는가
• 실행하지 못한 검사를 PR에 명시했는가

편집부 결론

Codex 코드리뷰의 장점은 사람을 대체하는 데 있지 않고, 반복적으로 놓치기 쉬운 회귀와 위험 경로를 병합 전에 한 번 더 찾는 데 있습니다. 로컬 /review로 작은 변경부터 검증하고, GitHub @codex review와 저장소별 AGENTS.md 규칙으로 팀의 고위험 기준을 일관되게 적용하세요. 결과는 재현 테스트와 사람의 도메인 판단으로 확정해야 합니다.

이 글은 2026년 9월 4일 OpenAI 공식 문서를 분석해 작성했으며 특정 저장소에서 장기간 버그 탐지율을 측정한 사용 후기는 아닙니다. 계정·조직별 기능 제공 범위와 화면은 바뀔 수 있으므로 도입 전 최신 공식 문서와 실제 설정을 확인하세요.

공식 문서와 함께 읽을 글

Codex로 GitHub Pull Request 검토하기

Codex 로컬 코드 검토 공식 문서 보기

AI 코드리뷰 자동화와 PR 보안 운영 기준 확인하기

여러 에이전트로 PR을 병렬 검토하기

AGENTS.md에 코드 검토 규칙 작성하기

Codex Skills로 반복 검토 절차 자동화하기

Codex에 외부 개발 도구 연결하기

자주 묻는 질문

Codex에서 로컬 코드를 검토하려면 어떻게 하나요?

Git 저장소에서 앱, CLI 또는 IDE 확장에 /review를 입력하고 기준 브랜치, 커밋되지 않은 변경이나 특정 커밋을 선택합니다.

GitHub PR 검토 명령은 무엇인가요?

Codex Cloud와 코드 검토가 설정된 저장소의 Pull Request 댓글에 @codex review를 정확히 입력합니다.

모든 PR을 자동으로 검토할 수 있나요?

Codex 설정에서 대상 저장소의 자동 검토를 켜면 설정 조건에 맞는 새 PR에 리뷰를 게시할 수 있습니다.

Codex 코드리뷰가 버그를 모두 찾나요?

아닙니다. diff와 제공된 문맥을 기반으로 잠재 문제를 찾는 보조 수단입니다. 테스트, 브랜치 보호, 전문 도구와 사람의 승인이 필요합니다.

리뷰 기준을 프로젝트에 맞게 설정할 수 있나요?

가장 가까운 AGENTS.md의 ## Code Review Rules에 저장소나 서비스별 고위험 동작, 안전한 처리법과 예외를 작성할 수 있습니다.

코드리뷰 오탐을 줄이려면 어떻게 하나요?

PR 목적과 예외를 명확히 쓰고, AGENTS.md 규칙을 좁게 만들며, 포맷·lint 같은 기계적 검사는 CI에 맡기세요.

보안 검토는 일반 코드리뷰와 다른가요?

보안 검토는 PR의 보안 위험을 더 깊게 보는 추가 검토이며 @codex security review로 요청할 수 있습니다. 공식 문서상 연구 프리뷰입니다.

Codex가 찾은 문제를 자동으로 고칠 수 있나요?

PR 댓글에서 특정 항목의 수정을 요청할 수 있고 권한이 있으면 브랜치에 변경을 푸시할 수 있습니다. 수정 전후의 diff와 테스트는 사람이 확인해야 합니다.