Codex 코드 리뷰: GitHub PR을 AI에게 리뷰받기

동료가 올린 풀 리퀘스트(pull request, 이하 PR)를 꼼꼼히 리뷰하고 싶어도 하루에 몇 개씩 쌓이면 대충 훑고 승인하게 되는데요. 그러다 놓친 실수가 배포 후에 터지면 “그때 좀 더 볼걸” 하는 후회가 남습니다. 😅

OpenAI의 Codex에는 GitHub PR을 대신 리뷰해 주는 기능이 있습니다. PR에 @codex review라고 댓글을 달면 Codex가 변경 사항을 읽고 일반 GitHub 리뷰처럼 줄 단위로 의견을 남겨 주죠. 저도 이번에 운영하는 오픈소스 저장소 몇 곳에 이 기능을 연결했는데요. 이 글에서는 실제 PR에 남은 리뷰를 보면서 설정 방법부터 리뷰 규칙 작성, 리뷰 결과 읽는 법까지 정리해 보겠습니다.

Codex 코드 리뷰란?

Codex 코드 리뷰는 Codex가 GitHub PR의 변경 사항(diff)을 검토하고 결과를 GitHub 리뷰로 남겨 주는 기능입니다. 터미널에서 쓰는 Codex CLI에도 /review 명령이 있지만, 이 기능은 내 컴퓨터가 아니라 OpenAI 클라우드에서 돌아갑니다. 그래서 PR을 올린 사람이 Codex를 설치하지 않았어도 저장소에 연결만 되어 있으면 리뷰가 달립니다.

리뷰를 받는 방법은 두 가지인데요. 하나는 PR에 @codex review 댓글을 달아 직접 요청하는 방법입니다. 다른 하나는 자동 리뷰인데, 켜 두면 PR이 열릴 때마다 Codex가 알아서 리뷰합니다.

클로드 코드 GitHub Actions와 비교하면 차이가 분명합니다. 클로드 코드는 저장소에 워크플로 파일을 두고 GitHub Actions 러너에서 실행되지만, Codex 코드 리뷰는 워크플로 파일이 필요 없습니다. GitHub 앱으로 연결해 두고 설정 화면에서 스위치만 켜면 되죠. 대신 리뷰가 OpenAI 쪽에서 실행되니 프롬프트나 실행 환경을 세세하게 바꾸기는 어렵습니다.

저장소 연결과 리뷰 설정

Codex 코드 리뷰를 쓰려면 먼저 GitHub 저장소가 Codex에 연결되어 있어야 합니다. 연결을 마치고 ChatGPT 설정에서 Coding 아래의 Code Review 메뉴로 들어가면 다음과 같은 화면이 나옵니다.

위쪽 Repositories에는 Codex가 접근할 수 있는 저장소 목록이 보이고, 아래쪽 Personal preferences에는 개인 설정이 있습니다. Automatic review는 내가 연 PR을 자동으로 리뷰할지 정하고, Review trigger는 그 자동 리뷰가 언제 돌지 정하는데 기본값은 PR이 열릴 때(On PR open)입니다. Exhaustive code review를 켜면 새 문제가 더 나오지 않을 때까지 계속 찾기 때문에 꼼꼼해지는 대신 시간이 더 걸립니다. 마지막으로 Use credits for reviews는 사용 한도를 넘었을 때 크레딧을 써서라도 리뷰를 계속할지 정합니다.

목록에서 저장소를 하나 누르면 그 저장소의 설정 화면이 열립니다.

여기 있는 설정은 Shared repository settings라는 안내처럼 그 저장소를 쓰는 팀 전체에 적용됩니다. Review code의 Automatic review를 켜면 누가 PR을 열든 Codex가 리뷰하고, 끈 상태에서도 @codex review 댓글로는 언제든 요청할 수 있습니다. 개인 설정과 저장소 설정이 다르면 저장소 설정이 이깁니다. 저장소 설정을 바꾸려면 GitHub에서 그 저장소에 push 이상의 권한이 있어야 합니다.

저는 처음에는 자동 리뷰를 꺼 둔 채로 시작하기를 권합니다. 리뷰 규칙을 다듬기 전에 모든 PR에 리뷰가 달리면 엉뚱한 지적에 팀원들이 금방 지치거든요. 몇 번 직접 요청해 보고 결과가 마음에 들 때 켜도 늦지 않습니다.

@codex review로 리뷰 요청하기

설정을 마쳤으면 PR에 댓글을 하나 남겨 봅시다.

@codex review

Codex는 댓글에 👀 반응을 달아 요청을 받았다고 알린 뒤 리뷰를 시작합니다. 잠시 기다리면 chatgpt-codex-connector 봇이 리뷰 현황을 담은 요약 댓글을 남깁니다.

Codex Review Summary 표에는 리뷰 종류와 상태, 리뷰한 커밋, 리뷰가 시작된 계기(Manual request)가 적힙니다. 새 커밋을 올리고 다시 요청하면 이 댓글이 새로 달리지 않고 갱신되기 때문에, PR 대화가 봇 댓글로 도배되지 않습니다.

이번에 특히 신경 써서 봐 줬으면 하는 부분이 있다면 댓글 뒤에 이어서 적으면 됩니다.

@codex review for issues in the database migration

리뷰 결과 읽기

Codex가 문제를 찾으면 일반 GitHub 리뷰처럼 해당 줄에 인라인 코멘트(inline comment)를 답니다. 아래는 디자인 시스템 저장소에 리뷰 규칙을 추가하는 PR에 달린 리뷰입니다.

“export된 컴포넌트의 prop 이름이나 타입, 기본값을 바꾸면 하위 호환성을 깨는 변경(breaking change)“이라는 규칙에, 필수 prop을 새로 추가하는 경우가 빠졌다는 지적인데요. 필수 prop이 생기면 그 prop을 넘기지 않던 기존 코드가 타입 검사에서 깨지니 정확한 지적입니다. 사람이 리뷰했다면 쉽게 지나쳤을 빈틈이죠. 시맨틱 버저닝으로 치면 메이저 버전을 올려야 하는 변경입니다.

코멘트 앞의 배지는 심각도입니다. P0이 가장 심각하고 P1, P2로 갈수록 가벼워집니다. 공식 문서에는 GitHub에서는 P0과 P1만 지적한다고 되어 있지만, 제 PR에서는 보시다시피 P2 지적도 달렸습니다. 문서와 실제 동작이 다를 수 있으니 배지를 보고 우선순위를 판단하면 됩니다.

코멘트 끝의 “Useful? React with 👍 / 👎.”도 그냥 넘기지 마세요. 반응을 남겨 두면 어떤 지적이 쓸모 있었는지 Codex에 알려 줄 수 있습니다.

반대로 문제를 찾지 못하면 리뷰 대신 짧은 댓글만 남깁니다.

PR 본문에는 👍 반응이 달리고요. 사소한 스타일 지적을 억지로 만들어 내지 않으니, “리뷰가 아무 말이 없으면 통과”라고 받아들이기 편합니다.

AGENTS.md에 리뷰 규칙 적기

Codex 리뷰가 진짜 쓸모 있어지는 건 저장소만의 규칙을 알려 줄 때입니다. Codex는 리뷰할 때 저장소의 AGENTS.md를 찾아 읽고, 그중 ## Code Review Rules 섹션의 규칙을 리뷰 기준으로 씁니다. AGENTS.md는 원래 코딩 에이전트에게 프로젝트 맥락을 알려 주는 파일인데, 같은 파일에 리뷰 기준까지 함께 두는 셈이죠.

## Code Review Rules

- 페이지를 추가하거나 옮기면 한국어(`/...`)와 영어(`/en/...`) 라우트가 모두 있어야 한다.
- 카피를 바꾸면 `src/i18n/ko.ts`와 `en.ts`가 함께 바뀌어야 한다.
- `src/anchors.ts`의 `ANCHORS`에서 이미 공개된 값을 바꾸거나 지우면 지적한다. 외부 링크가 깨진다.
- 마케팅 페이지 콘텐츠가 클라이언트에서만 렌더링되어 prerender된 HTML에 빠지면 지적한다 (SEO).

제가 실제로 쓰고 있는 규칙인데요. 보시다시피 린터나 타입 검사가 잡지 못하는 것만 적었습니다. 한국어 페이지만 추가하고 영어 페이지를 빠뜨리거나, 이미 공개된 앵커 값을 바꿔 외부 링크를 깨뜨리는 실수는 CI가 통과해도 그대로 배포되거든요.

규칙을 쓸 때 기억해 둘 점이 몇 가지 있습니다. 우선 처음부터 많이 쓰지 말고 두세 개로 시작합니다. 규칙이 많아질수록 각 규칙에 쏟는 주의가 흐려집니다. 또 포맷팅이나 린트 규칙은 넣지 않습니다. 그건 CI가 더 빠르고 정확하게 잡습니다. 그리고 “~하면 지적한다”로 끝내지 말고 “외부 링크가 깨진다”처럼 이유를 붙여 둡니다. 이유가 있으면 Codex가 규칙에 딱 맞지 않는 비슷한 상황에서도 판단할 수 있습니다.

규칙이 늘어나면 ### 헤딩으로 묶어 분류합니다. 하위 디렉터리에 AGENTS.md를 따로 두면 그 범위에만 적용되는 규칙이 되니, 저장소 전체 규칙은 루트에 두고 특정 서비스 규칙은 그 서비스 디렉터리에 둡니다.

리뷰 규칙도 리뷰받기

재미있는 건 리뷰 규칙을 추가하는 PR 자체도 Codex가 리뷰한다는 점입니다. 디스코드 봇을 Cloudflare Workers로 운영하는 저장소에서 “Node.js 내장 모듈에 의존하는 코드는 지적한다”는 규칙을 추가했더니 이런 리뷰가 달렸습니다.

규칙이 저장소 전체에 걸려 있으면 Node.js에서 실행되는 scripts/preview-daleui.ts 같은 스크립트까지 오탐(false positive)으로 지적받게 된다는 내용입니다. 저장소에 실제로 있는 파일을 근거로 들었다는 점이 인상적이었는데요. 지적대로 규칙의 범위를 Worker 코드인 src/로 좁히고 나머지는 대상이 아니라고 명시해서 커밋을 올렸습니다.

- `src/`의 Worker 코드에서 `nodejs_compat`이 지원하지 않는 Node.js API(`fs`, `child_process` 등)를 쓰면 지적한다. `scripts/`와 테스트는 Node에서 실행되므로 대상이 아니다.

이렇게 리뷰 규칙을 담은 PR에 @codex review를 한 번 돌려 보면, 규칙이 실제 코드베이스와 어긋나는 곳을 미리 찾을 수 있습니다. 규칙이 잘못되면 이후 모든 PR에 엉뚱한 지적이 쌓이니 꼭 거쳐 볼 만한 단계입니다.

수정까지 맡기기

Codex는 지적만 하고 끝나지 않습니다. PR 댓글로 수정을 요청하면 Codex가 작업을 시작하고, 브랜치에 push할 권한이 있으면 고친 커밋을 직접 올립니다.

@codex fix the P1 issue

CI가 실패했을 때도 같은 식으로 맡기면 됩니다.

@codex fix the CI failures

리뷰 댓글의 안내 문구에 나오는 @codex address that feedback처럼 자연어로 요청해도 됩니다. 다만 Codex가 올린 커밋도 결국 사람이 확인하고 병합해야 하니, 작고 명확한 수정 위주로 맡기는 편이 안전합니다.

보안 쪽을 더 깊이 보고 싶다면 @codex security review로 보안 리뷰를 따로 요청해 보세요. 변경 사항과 저장소 맥락을 바탕으로 보안 취약점만 집중해서 살펴보는 기능인데, 아직 리서치 프리뷰(research preview) 단계입니다. 저장소 설정 화면의 Auto security review를 켜면 이것도 자동으로 돌릴 수 있습니다.

마치며

지금까지 Codex 코드 리뷰를 GitHub 저장소에 연결하고, @codex review로 리뷰를 요청하고, AGENTS.md에 리뷰 규칙을 적어 리뷰를 길들이는 방법을 살펴봤습니다. 직접 써 보니 사소한 지적은 줄이고 놓치기 쉬운 문제에 집중하도록 만든 점이 가장 마음에 들었습니다.

다만 Codex 리뷰가 사람의 리뷰나 테스트를 대신하지는 않습니다. 브랜치 보호 규칙과 필수 승인은 그대로 두고, 사람이 놓치기 쉬운 부분을 한 번 더 걸러 주는 동료 정도로 생각하면 딱 좋은 것 같습니다. 여러분의 저장소에도 CI가 잡지 못하는 실수 두세 개를 규칙으로 적어 두고 한번 시작해 보세요. 🙂

더 자세한 내용은 Codex code review in GitHub 공식 문서를 참고하세요.