Custom Code Review rules for Codex

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Codex Code Review는 AGENTS.md의 저장소별 규칙을 활용해 팀의 맥락과 관례를 코드 리뷰에 반영하고, 문제 지적에 해당 규칙을 인용할 수 있다.

📌 핵심 요약

• Codex Code Review는 AGENTS.md에 작성한 사용자 지정 저장소 규칙을 적용하고, 발견한 문제의 근거가 되는 지침을 제시할 수 있다.
• 반복되는 리뷰 항목으로는 기존 API 계약 유지, 고객 데이터의 로그 기록 방지, 다른 서비스를 손상할 수 있는 이름 변경 회피가 제시된다.
• OpenAI의 주간 PR 수는 4분기 이후 두 배 이상 증가했으며, 글은 많은 고객에게서도 비슷한 추세가 나타난다고 설명한다.
• PR이 늘어나면 리뷰어가 변경 의도와 관련 맥락을 파악할 시간이 줄고, 작성자가 다른 작업으로 이동한 뒤에는 작은 수정에도 더 오래 걸릴 수 있다.
• AGENTS.md에는 간결하고 적용 범위가 명확한 리뷰 지침을 담을 수 있으며, 이는 저장소의 이력을 잘 모르는 기여자나 코딩 에이전트에게 특히 유용하다.

🧩 주요 포인트

1. 리뷰어에게 집중된 API 계약과 서비스 의존성 지식 → 저장소 규칙으로 명시해 리뷰에서 참조할 수 있는 맥락으로 전환.
2. 주간 PR 수의 두 배 이상 증가 → 코드 작성 속도와 함께 리뷰 처리 능력 및 피드백 시점의 중요성도 확대.
3. AGENTS.md의 범위가 명확한 지침과 규칙 인용 → 변경에 필요한 관례를 적용하고 문제 지적의 근거를 작성자에게 전달.

🧠 상세 정리

1. 반복되는 리뷰 의견과 지식의 편중

글은 Codex로 코드 리뷰를 수행할 때 같은 종류의 의견이 반복되는 상황에서 출발하며, 기존 API 계약을 유지하거나 고객 데이터가 로그에 남지 않도록 하는 점검을 예로 든다. 다른 서비스에 영향을 줄 수 있는 이름 변경을 피하는 것도 반복되는 항목으로, 겉으로 보이는 수정 내용 외에 팀이 알고 있는 의존 관계를 고려해야 하는 사례다. 이러한 점검은 중요하지만 그 배경이 소수 리뷰어의 기억에만 남아 있으면, 변경을 작성하거나 검토하는 과정에서 쉽게 누락될 수 있다고 설명한다. 따라서 글이 제기하는 문제는 개별 코드의 타당성뿐 아니라, 팀이 경험을 통해 축적한 맥락을 리뷰에 필요한 순간에 어떻게 전달할 것인가에 있다.

2. AGENTS.md를 통한 리뷰 규칙 제공

Codex Code Review는 AGENTS.md에 담긴 사용자 지정 저장소 규칙을 사용해 문제를 발견하고, 그 지적의 배경이 되는 지침을 작성자에게 안내할 수 있다. 이미 코딩 작업을 안내하는 용도로 AGENTS.md를 사용하고 있다면, 같은 파일을 코드 리뷰의 방향을 정하는 데에도 활용할 수 있다는 설명이다. 이 방식은 저장소의 익숙하지 않은 영역에서 작업하는 기여자나 코딩 에이전트처럼, 해당 코드의 과거 결정과 사정을 아직 모르는 주체에게 특히 유용하다. 원문은 저장소 규칙을 통해 이런 맥락을 제공할 수 있다고 소개하며, 규칙의 위치와 작성 방법 및 시험 과정에서 얻은 내용을 다루겠다고 예고하지만 제공된 본문에는 그 상세 내용까지 포함되어 있지 않다.

3. 코드 생산 증가와 리뷰 병목

글은 코딩 에이전트가 더 큰 변경을 맡고 더 긴 시간에 걸쳐 작업할 수 있게 되면서, 팀이 더 많은 아이디어를 실제 코드로 옮길 수 있다고 설명한다. 이를 보여 주는 수치로 OpenAI의 주간 PR 수가 4분기 이후 두 배 이상 늘었다고 밝히며, 많은 고객에게서도 비슷한 추세를 관찰하고 있다고 덧붙인다. 코드가 늘어나면 새로운 기능을 출시하고 더 많은 문제를 해결하는 데 도움이 되지만, 무엇을 살펴봐야 하는지 아는 사람의 검토를 기다리는 PR도 함께 늘어난다. 이 때문에 개발 단계의 생산성 향상이 리뷰 단계의 부담으로 이어질 수 있으며, 글은 코드 리뷰가 빠르게 병목이 될 수 있다는 점을 사용자 지정 규칙이 필요한 배경으로 제시한다.

4. 동시 변경과 피드백 시점의 부담

여러 변경이 한꺼번에 들어오면 리뷰는 더 어려워지며, 변경 내역이 충분히 합리적으로 보여도 오래된 클라이언트를 손상하거나 작성자가 몰랐던 경계를 넘을 수 있다. 누군가는 그러한 맥락을 기억하고 있다가 작성자가 아직 대응할 수 있는 시점에 전달해야 하므로, 리뷰에는 코드 자체를 읽는 일 이상의 맥락 파악이 필요하다. PR이 많아질수록 리뷰어가 각 변경의 의도를 이해하고 관련 정보를 모은 뒤 의견을 남길 시간은 줄어들고, 작성자가 다른 작업으로 넘어간 뒤에는 작은 수정에도 더 오래 걸릴 수 있다. 글은 이러한 연결을 근거로 빠른 피드백의 중요성을 강조하며, 더 빨라진 개발의 이점을 살리면서 사람의 검토가 병목이 되는 상황을 줄여야 한다고 설명한다.

5. 변경 내역만으로 드러나지 않는 호환성

글은 변경 내역만으로 발견하기 어려운 문제를 구체화하기 위해 응답 필드의 이름을 바꾸는 사례를 제시한다. 이 변경은 단순한 정리 작업처럼 보일 수 있지만, 기존 계약에 계속 의존하는 클라이언트가 있다면 그 클라이언트의 동작을 깨뜨릴 수 있으므로 판단에 추가 맥락이 필요하다. 경험이 많은 리뷰어는 해당 필드를 유지해야 하는 이유를 기억할 수 있는 반면, 새 기여자나 그 서비스를 처음 다루는 에이전트는 같은 배경을 알지 못할 수 있다. 이 사례는 코드에 드러난 변경의 합리성과 기존 사용자가 기대하는 동작의 보존이 별개의 검토 대상임을 보여 주며, 저장소의 이력을 리뷰 지침으로 전달하려는 문제의식을 뒷받침한다.

6. 범위가 명확한 지침과 근거 인용

제공된 본문의 마지막 부분은 팀이 시간을 들여 익히는 맥락을 코딩 에이전트에게 어떻게 전달할 것인지 묻고, 저장소 규칙 인터페이스를 그 방법으로 제시한다. 핵심은 AGENTS.md에 간결하면서도 적용 범위가 명확한 리뷰 지침을 두는 것으로, Codex Code Review는 검토 중인 변경에 관련된 규칙을 적용하고 발견한 문제에 그 규칙을 인용할 수 있다. 앞서 제시한 기존 API 계약이나 서비스 간 의존성 같은 맥락을 지적의 근거와 연결한다는 점에서, 규칙은 리뷰 방향을 정하는 동시에 작성자가 해당 지적을 이해하는 데 필요한 설명을 제공한다. 다만 본문은 같은 설명을 반복하는 상황을 언급하려는 문장 도중에 끊겨 있으므로, 이후의 구체적인 규칙 예시나 시험 결과는 제공된 자료만으로 정리할 수 없다.

🧾 핵심 주장 / 시사점

• 저장소 규칙은 소수 리뷰어의 기억에 의존하던 API 계약과 서비스 의존성 맥락을 코드 리뷰에 전달하는 수단이다.
• PR 증가에 대응하려면 변경을 검토하는 능력뿐 아니라 작성자가 다른 작업으로 넘어가기 전에 피드백을 전달하는 시점도 중요하다.
• 문제 지적에 규칙을 인용하는 기능은 작성자가 저장소 관례와 해당 지적의 관계를 이해하는 데 도움이 된다.

✅ 액션 아이템

• 반복되는 API 계약 유지, 고객 데이터의 로그 기록 방지, 서비스에 영향을 주는 이름 변경 관련 지침을 AGENTS.md에 명시.
• AGENTS.md의 리뷰 지침을 간결하고 적용 범위가 명확하게 정리해 저장소 이력을 모르는 기여자와 코딩 에이전트에게 제공.
• Codex Code Review에서 변경에 관련된 저장소 규칙의 적용 여부와 문제 지적에 인용된 근거를 확인.

❓ 열린 질문

• 반복되는 리뷰 항목 중 기존 API 계약 유지, 고객 데이터의 로그 기록 방지, 이름 변경 회피 가운데 무엇을 AGENTS.md에 먼저 명시할 것인가?
• 저장소 이력을 잘 모르는 기여자와 코딩 에이전트가 활용할 수 있도록 AGENTS.md 지침의 적용 범위를 어떻게 명확히 할 것인가?
• PR 증가로 리뷰어의 맥락 파악 시간이 줄어드는 상황에서 작성자가 다른 작업으로 이동하기 전에 피드백을 전달하려면 무엇이 필요한가?