Codex의 사용자 지정 코드 리뷰 규칙

Codex로 코드를 리뷰하다 보면 같은 의견이 반복해서 나옵니다. 예전부터 지원해 온 API 계약을 유지해야 한다거나, 로그에 고객 데이터를 남기면 안 된다거나, 이름을 바꾸면 다른 서비스가 동작하지 않는다는 지적입니다. 모두 중요한 확인 사항이지만, 그 배경을 아는 리뷰어가 몇 명뿐이라면 놓치기 쉽습니다.

이제 Codex 코드 리뷰는 AGENTS.md에 정의한 리포지터리별 규칙을 사용해 이런 문제를 찾아내고, 작성자에게 지적의 근거가 된 지침을 알려줄 수 있습니다. 이미 AGENTS.md로 코딩 작업을 안내하고 있다면 같은 파일에 리뷰 지침도 담을 수 있습니다. 기여자나 코딩 에이전트가 리포지터리에서 낯선 부분을 수정할 때는 이전에 어떤 일이 있었는지 모를 수 있어 특히 유용합니다. 이 글에서는 리포지터리 규칙을 어디에 두고 어떻게 작성하면 좋은지, 테스트 과정에서 무엇을 배웠는지 살펴봅니다.

더 많은 코드를 배포하는 팀

코딩 에이전트는 규모가 큰 변경도 맡을 수 있고 더 오랜 시간 작업을 이어갈 수 있어, 팀은 더 많은 아이디어를 코드로 구현할 수 있습니다. OpenAI에서는 4분기 이후 주간 PR 수가 두 배 넘게 늘었고, 여러 고객사에서도 비슷한 추세를 보이고 있습니다. 코드가 늘면 팀은 새 기능을 출시하고 더 많은 문제를 해결할 수 있습니다. 그만큼 무엇을 확인해야 하는지 아는 리뷰어를 기다리는 pull request도 늘어나므로 코드 리뷰가 금세 병목이 될 수 있습니다.

변경 사항이 한꺼번에 여러 건 들어오면 리뷰가 더 어려워집니다. diff만 보면 전혀 문제없어 보이는 변경도 구버전 클라이언트의 동작을 깨뜨리거나 작성자가 몰랐던 경계를 넘을 수 있습니다. 누군가는 그 배경을 기억했다가 작성자가 아직 대응할 수 있을 때 알려줘야 합니다.

리뷰가 병목이 되는 이유

pull request가 늘어나면 리뷰어가 피드백을 남기기 전에 각 변경의 의도를 파악하고 관련 정보를 모을 시간이 줄어듭니다. 작성자가 이미 다른 작업으로 넘어갔다면 작은 수정에도 시간이 더 걸릴 수 있습니다. 피드백을 빠르게 전달하면 리뷰어에게 일이 밀리지 않으면서도 팀이 빨라진 개발 속도를 충분히 활용할 수 있습니다.

diff만으로는 발견하기 어려운 문제도 있습니다. 응답 필드의 이름을 바꾸는 일은 평범한 코드 정리처럼 보여도 기존 계약에 의존하는 클라이언트의 동작을 깨뜨릴 수 있습니다. 경험 많은 리뷰어는 왜 그 필드를 유지해야 하는지 기억할 수 있지만, 새로 합류한 기여자나 해당 서비스를 처음 다루는 에이전트는 그 이유를 모를 가능성이 큽니다.

규칙으로 컨텍스트 전달하기

팀원들이 일하면서 차츰 익히는 컨텍스트를 코딩 에이전트에 어떻게 전달할 수 있을까요? 새로운 리포지터리 규칙 인터페이스를 사용하면 적용 범위가 명확한 리뷰 지침을 AGENTS.md에 간결하게 작성할 수 있습니다. Codex 코드 리뷰는 변경 사항에 해당하는 규칙을 적용하고 문제를 지적할 때 그 규칙을 인용할 수 있습니다. 매번 pull request에서 같은 설명을 반복할 필요 없이 해당 코드 가까이에 설명을 두면 됩니다.

코딩 모델이 지시를 더 잘 따르게 되면서, 적용 범위를 명확히 정한 짧은 지침만으로도 긴 리뷰에서 팀이 실제로 중요하게 여기는 사항에 집중하도록 할 수 있습니다. Codex 리포지터리에서도 AGENTS.md에 코드 리뷰 규칙을 둡니다. 이 규칙은 모델에 노출되는 컨텍스트나 호환성을 깨뜨리는 변경 등을 다룹니다.

실제 사례를 살펴보겠습니다.

Codex App Server는 rawResponseItem/completed라는 내부 알림을 보냅니다. 실험적 기능으로 표시된 알림이지만 Codex Cloud는 이미 이 알림을 사용하고 있습니다. 리포지터리의 호환성을 깨뜨리는 변경에 관한 리뷰 규칙은 rawResponseItem/* 이벤트가 실험 단계에서도 리뷰어가 호환성을 지켜야 하는 연동 인터페이스라고 명시합니다.

통신에 사용하는 기존 이름은 App Server 프로토콜에 정의되어 있습니다. 코드를 정리하면서 한 줄을 다음과 같이 바꿨다고 가정해 보겠습니다.

-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"

코드는 컴파일되지만 기존 알림을 구독하는 클라이언트는 더 이상 알림을 받지 못합니다. 리포지터리 규칙에서 해당 부분을 발췌하면 다음과 같습니다.

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

위 diff에 대해 코드 리뷰는 다음과 같이 지적할 수 있습니다.

기존 rawResponseItem/completed 알림을 유지하세요. Codex Cloud에서 이 알림을 사용하는 클라이언트는 이 이름으로 알림을 수신하므로, 실험 단계의 이벤트라도 이름을 바꾸면 클라이언트가 제대로 동작하지 않습니다. AGENTS.md에 설명된 대로 기존 이름을 유지하거나 하위 호환되는 이벤트를 추가하세요.

Codex 팀은 Codex Cloud에서 이 알림을 사용하는 클라이언트를 보호하기 위해 이 규칙을 추가했습니다. 리포지터리 전체에 적용되는 규칙은 루트에, 특정 서비스에만 적용되는 규칙은 해당 디렉터리에 두세요. 리뷰할 때 Codex는 변경된 파일에 적용되는 지침을 따르고 작성자에게 관련 규칙을 알려줄 수 있습니다. App Server와 무관한 변경에는 해당 서버의 컨텍스트가 필요하지 않습니다.

규칙은 팀에서 이미 사용하는 도구와 함께 활용합니다. 판정 기준을 명확한 로직으로 표현할 수 있는 검사는 테스트와 린터가 잘 처리합니다. 리포지터리 규칙에는 코드로 표현하기 어려운 판단 기준을 담을 수 있습니다. 호환성 요구 사항이나 데이터 경계부터 시작해 보세요. 관련 지침이 이미 갖춰져 있으므로 작성자는 코드를 변경하기 전에 과거의 모든 장애 사례나 해당 코드의 규약을 알 필요가 없습니다.

지속적으로 활용할 수 있는 규칙 작성하기

알려진 규칙 위반 사례와 위반처럼 보이지만 안전한 반례를 포함한 평가 세트로 코드 리뷰가 리포지터리 지침을 얼마나 잘 활용하는지 테스트했습니다. 주 평가 세트에서 규칙을 제공한 베리언트는 사용자 지정 규칙에 따라 찾아야 할 문제의 98%를 발견했고, 기준 대조군은 58.3%를 발견했습니다.

규칙 위반을 찾는 것은 리뷰의 일부일 뿐입니다. 여러 규칙을 함께 고려해야 하거나 pull request에 이미 변경 사항이 많을 때 어떤 결과가 나오는지도 확인하고 싶었습니다. 놓치면 영향이 큰 위반 사례와 지적할 필요가 없는 변경 사항을 모두 테스트한 뒤, 네 가지 질문을 중심으로 결과를 정리했습니다.

짧은 글머리 기호 목록부터 특정 팀이 관리하는 섹션까지, 팀에서 흔히 사용하는 여러 방식으로 지침을 작성해 보기도 했습니다.

내부 리포지터리에 규칙을 적용했을 때도 비슷한 양상이 나타났습니다. Codex는 기본 리뷰에서 놓칠 수 있는 해당 코드의 지침을 찾아 인용할 수 있었지만, 지나치게 포괄적인 지침은 불필요한 지적으로 이어지기 쉬웠습니다. 적용 범위가 좁은 규칙을 소수만 두고 안전하게 변경하는 방법을 명시하면 Codex가 주변의 모든 변경에 규칙을 적용하는 일을 피하고 실질적으로 도움이 되는 사항에 집중할 수 있었습니다.

쉽게 눈에 띄지 않지만 어기면 영향이 큰 불변 조건부터 정하세요. 호환성 요구 사항이나 데이터 경계처럼 리뷰어가 반복해서 설명하는 확인 사항을 규칙으로 작성하세요. 규칙을 빼도 리뷰 결과가 달라지지 않는다면 넣지 않아도 됩니다.

규칙은 해당 코드에만 적용되도록 하세요. 리포지터리 전체에 적용되는 지침은 루트에 두고, 서비스별 지침은 하위 디렉터리의 AGENTS.md에 두세요. 범위를 좁히면 무관한 지침까지 함께 고려할 필요가 없어지고 누가 규칙을 관리하는지도 명확해집니다.

지켜야 할 조건과 안전하게 변경하는 방법을 함께 명시하세요. rawResponseItem/* 규칙은 호환성이 깨질 위험을 짚어줍니다. “기존 이름을 유지하거나 하위 호환되는 이벤트를 추가하세요”라는 지침은 작성자에게 구체적인 대안을 제시합니다.

규칙은 오래 쓸 수 있게 작성하고 최신 상태로 유지하세요. 바뀔 수 있는 함수 이름보다 코드가 계속 보장해야 할 결과를 설명하세요. 규칙을 수정할 때도 리뷰를 거치고, 불필요한 지적을 반복해서 유발하는 지침은 범위를 좁히거나 삭제하세요.

서식 등 기계적으로 확인할 수 있는 항목은 CI에서 검사하세요. 리포지터리 규칙에는 리뷰어가 매번 다시 물어봐야 할 사항을 담으세요.

시작하기

리포지터리에서 이미 Codex 코드 리뷰를 활성화했다면 해당 AGENTS.md 파일에 규칙을 두세 개 추가하고 평소에 자주 하는 변경으로 pull request를 열어 보세요. 코드 리뷰를 처음 사용한다면 코드 리뷰 빠른 시작에서 GitHub 리포지터리에 코드 리뷰를 활성화하는 방법을 확인하세요. @codex review로 직접 리뷰를 요청할 수도 있습니다.

리뷰어가 반복해서 설명하는 내용이나 놓치면 영향이 큰 리포지터리 특유의 실수부터 다뤄 보세요. 규칙 위반으로 지적해야 할 변경, 위반처럼 보이지만 안전한 반례, 규칙과 무관한 변경을 하나씩 테스트하세요. 첫 번째 변경에는 도움이 되는 지적이 나오고 나머지 두 변경에는 불필요한 지적이 없는지 확인한 뒤, 결과를 바탕으로 지침을 다듬으세요.

Codex 코드 리뷰는 추가 리뷰어 역할을 합니다. 필수 요건은 여전히 테스트, 브랜치 보호 규칙, 필수 승인으로 강제합니다.

코드를 작성하는 시간보다 변경 사항을 리뷰하는 시간이 더 길다면, 팀에서 반복해서 확인하는 항목 하나부터 시작하세요. AGENTS.md에 그 항목을 추가하고 다음 pull request에서 Codex 코드 리뷰를 사용해 보세요.