코드를 작성한 후, 스스로 다시 읽어본 다음 리뷰를 요청합니다. 그럼에도 불구하고 조건 분기의 누락이나 기존 처리에 미치는 영향을 놓치는 경우가 있습니다.
그래서 리뷰 과정의 한 단계로 Codex를 이용한 코드 리뷰를 도입하고 싶습니다.
이 글에서는 GitHub의 Pull Request에 Codex 리뷰를 추가하는 절차와 팀에서 운영할 때의 포인트를 소개합니다.
여기서 다루는 것은 Git으로 관리되는 코드 변경 사항을 GitHub 상에서 리뷰하는 방법입니다.
본 기사는 2026년 11월 5일에 확인한 공식 문서를 기반으로 합니다. 사용 가능한 기능이나 설정 화면은 계약, 권한, 업데이트에 따라 다를 수 있습니다.
Codex는 Pull Request의 차이점(diff)이나 관련 코드, 리포지토리 내 지침을 참조하여 GitHub 상에 리뷰를 게시합니다.
공식 문서에서는 심각한 문제에 초점을 맞춘 리뷰로 설명하고 있습니다. OpenAI 공식 문서: GitHub 코드 리뷰
예를 들어, 리뷰에서 확인하고 싶은 관점에는 다음과 같은 것들이 있습니다.
- 조건 분기로 인해 일부 케이스만 오작동하지 않는지
- 빈 값이나 예상치 못한 입력으로 문제가 발생하지 않는지
- 권한 확인이 빠지지 않았는지
- 기존 호출원(calling code)에 영향을 주는 변경 사항은 없는지
다만, 모든 결함을 탐지할 수 있는 것은 아닙니다. 테스트나 사람의 리뷰와 조합하여 사용해야 합니다.
다음 준비물이 필요합니다.
- 리뷰 대상 GitHub 리포지토리
- Codex를 이용할 수 있는 계정
- Codex 코드 리뷰 설정에 접근할 수 있는 환경
- GitHub 연동에 필요한 권한
자동 리뷰 설정을 위해서는 공식 문서상, 대상 리포지토리에 대한 push 권한 또는 관리자 권한이 필요합니다.
회사 코드를 다룰 경우에는 소스 코드를 외부 서비스로 처리해도 되는지 조직의 규칙을 확인해야 합니다. 연결 시에는 허용할 리포지토리와 접근 범위도 확인해 주세요.
Codex의 GitHub 연동 화면에서 대상 리포지토리를 연결합니다.
조직의 리포지토리를 사용하는 경우, GitHub 측에서 관리자의 승인이 필요할 수도 있습니다.
연결 후에는 Codex 코드 리뷰 설정을 열고, 대상 리포지토리에서 코드 리뷰를 활성화합니다.
처음에는 팀원들이 내용을 파악하기 쉬운 작은 변경 사항을 사용하여 수동으로 리뷰를 요청하는 것이 확인하기 쉽습니다.
GitHub에서 Pull Request를 생성하고, 댓글란에 다음 내용을 게시합니다.
Codex가 반응하며, 리뷰 처리 후에 결과를 게시합니다. 이 댓글이 공식적으로 안내되는 리뷰 요청 방법입니다. 리뷰 요청의 공식 절차
Pull Request 본문에는 변경 배경도 기재해 둡니다.
## 변경 목적
주문 목록에서 검색 결과가 0건일 경우 에러가 발생하는 문제를 수정합니다.
## 기대 동작
...
이는 팀 내부의 리뷰에도 도움이 됩니다. 코드의 차이점만으로는 알기 어려운 '왜 변경했는지'를 공유할 수 있기 때문입니다.
프로젝트 고유의 규칙을 전달하고 싶다면, 리포지토리에 AGENTS.md 파일을 배치합니다.
공식 문서에서는 ## Code Review Rules 섹션에 리뷰 규칙을 작성하는 방법을 안내하고 있습니다. 리뷰 관점 설정 방법
예를 들어, 조직별 데이터를 다루는 웹 시스템이라면 다음과 같이 기재할 수 있습니다.
## Code Review Rules
### 데이터 접근 권한
- 조직에 연결된 데이터의 획득 및 업데이트 시에는,
...
리포지토리 전체에 공통되는 규칙은 루트에, 특정 기능에만 적용하는 규칙은 그 하위의 AGENTS.md에 작성할 수 있습니다.
이미 파일이 있는 경우에는 내용을 확인하고 추가합니다.
처음부터 대량으로 작성하기보다는 반복적으로 지적하는 중요한 관점 2~3가지를 선택하면, 결과를 평가하기 쉽습니다.
참고로, 정형화나 Lint처럼 기계적으로 판별할 수 있는 항목은 CI(Continuous Integration)에서 확인하는 것이 더 적절합니다.
매번 댓글을 다는 운영이 자리 잡으면, 자동 리뷰도 검토합니다.
공식 문서에서는 코드 리뷰 설정의 대상 리포지토리와 개인 설정의 Automatic review를 확인하고, Review trigger에서 실행 시점을 선택하는 절차가 안내되어 있습니다. 자동 리뷰의 공식 절차
설정 후에는 대상 Pull Request에서 리뷰가 실행되는지 확인합니다.
작동하지 않는 경우에는 다음 사항을 확인해 주세요.
- 대상 리포지토리가 Codex에 연결되어 있는지
- 리포지토리에서 코드 리뷰가 활성화되었는지
- 개인 설정에서 자동 리뷰가 활성화되었는지
- 풀 리퀘스트(Pull Request) 작업이 설정된 실행 조건에 맞는지
- 사용량 제한이나 조직의 제약 사항에 문제가 없는지
Codex의 지적을 먼저 확인하면, 사람의 리뷰가 들어가기 전에 문제를 수정할 수 있는 가능성이 있습니다.
사람의 리뷰에서는 사양(Specification)의 타당성이나 설계 의도 등 팀에서 논의하고 싶은 내용에 시간을 할애하기가 수월해집니다.
혼자 작성할 경우, "이 값은 반드시 들어온다", "이 처리는 한 번만 호출된다"와 같은 전제(Assumption)를 놓치기 쉽습니다.
AI의 지적을 계기로, 그 전제가 코드나 테스트에서 보장되고 있는지 재검토할 수 있습니다.
AGENTS.md에 업무상의 제약 사항을 작성함으로써, 담당자의 머릿속에 있던 확인 사항들을 공유할 수 있습니다.
새로 참여한 멤버도 프로젝트에서 무엇을 중요하게 생각하는지 이해하기 쉬워집니다.
지적된 코드에 대해 "어떤 입력에서 문제가 발생하는지", "기존 테스트로 감지할 수 있는지"를 조사하면 구현에 대한 이해가 깊어집니다.
수정하는 경우에도, 제안을 그대로 채택하기보다는 재현 조건과 기대하는 동작을 확인하는 것이 중요합니다.
Codex의 리뷰 결과는 머지(Merge)를 판단하는 자료 중 하나입니다.
지적이 없더라도, 사양(Specification)에의 적합성이나 안전성이 보장된 것은 아닙니다. 반대로, 지적이 기존 사양과 맞지 않는 경우도 있습니다.
운영 시에는 다음 흐름이 권장됩니다:
- Codex의 지적과 근거를 읽는다.
- 관련 코드나 사양을 확인한다.
- 필요에 따라 테스트로 재현한다.
- 수정 후 테스트와 리뷰를 진행한다.
- 팀의 승인 규칙에 따라 머지(Merge)한다.
효과를 확인할 때는 댓글 수뿐만 아니라, 채택된 유효 지적 사항이나 리뷰의 왕복 횟수, 확인에 걸린 시간 등도 살펴봅니다.
Codex의 코드 리뷰는 기존 GitHub 개발 흐름에 변경 내용을 확인할 기회를 추가할 수 있습니다.
먼저 하나의 리포지토리에서 @codex review를 시도하고, 지적 사항을 평가하면서 AGENTS.md에 확인 관점을 정리합니다. 그 후 필요에 따라 자동 리뷰로 확장하면 팀에 맞는 운영 방식을 만들기 수월해집니다.
