Codex Code Review rules 작성법: AGENTS.md로 반복 리뷰를 자동화하는 기준

코드 리뷰에서 반복되는 코멘트가 있다. 오래된 API 계약을 깨지 말라, 고객 데이터를 로그에 남기지 말라, 특정 이벤트 이름은 실험적이어도 외부 소비자가 있으니 바꾸지 말라, 결제 로직에서는 silent fallback을 쓰지 말라 같은 내용이다. 이런 지식은 보통 오래 일한 리뷰어 머릿속에 있다. 문제는 PR이 많아질수록 같은 설명을 반복해야 하고, 새 기여자나 코딩 에이전트는 그 맥락을 모른다는 점이다.

OpenAI의 Codex Code Review가 custom repository rules를 AGENTS.md에서 읽어 리뷰에 적용할 수 있게 된 것은 이 병목을 줄이는 방향이다. 여기서 중요한 키워드는 Codex Code Review rules, AGENTS.md, repository rules, AI code review automation이다. 이 글은 팀이 바로 적용할 수 있는 rule 작성 기준과 검증 방법을 정리한다.

왜 리뷰 규칙이 필요한가

AI 코딩 도구가 들어오면 PR 양이 늘어난다. OpenAI 블로그는 내부에서 Q4 이후 주간 PR volume이 2배 이상 늘었다고 설명한다. 코드가 더 많이 나온다는 것은 좋은 일이다. 하지만 리뷰어가 각 diff의 목적, 주변 맥락, 과거 사고를 모두 기억해야 한다면 병목은 리뷰로 이동한다.

테스트와 린터로 잡을 수 있는 것은 자동화하면 된다. 그러나 모든 중요한 판단이 테스트로 표현되지는 않는다. wire protocol 이름을 바꾸면 컴파일은 통과하지만 외부 client가 깨질 수 있다. 내부 로그에 account email을 남겨도 unit test는 통과할 수 있다. 특정 migration 순서가 필요한 이유는 코드만 보면 드러나지 않는다.

repository rules는 이런 '비결정적이지만 반복되는 판단'을 짧고 scoped된 지침으로 옮기는 장치다. Codex 리뷰는 diff를 보면서 관련 규칙을 찾아 finding에 인용할 수 있다.

좋은 규칙의 조건

첫째, consequential해야 한다. 놓쳐도 별일 없는 스타일 취향을 rule로 넣으면 noise가 늘어난다. 반대로 놓치면 고객 API가 깨지거나 데이터가 노출되거나 운영 장애가 나는 invariant는 rule 후보가 된다.

둘째, non-obvious해야 한다. 누구나 diff만 보고 알 수 있는 내용은 테스트나 린터로 처리하는 편이 낫다. 규칙은 '이 repo를 오래 본 사람만 아는 사정'을 문서화할 때 가치가 있다.

셋째, safe path를 같이 써야 한다. '이 이벤트 이름을 바꾸지 말 것'에서 끝나면 작성자가 막힌다. '기존 이름을 유지하거나 backward-compatible event를 추가할 것'처럼 대안을 줘야 actionability가 생긴다.

넷째, scope가 좁아야 한다. repo root의 AGENTS.md에는 repository-wide rule만 두고, 특정 서비스나 디렉터리 규칙은 하위 AGENTS.md에 둔다. 모든 rule이 모든 PR에 적용되면 에이전트가 중요도를 구분하지 못한다.

AGENTS.md 규칙 예시

다음은 실무에서 바로 쓸 수 있는 형태다.

## Code Review Rules

### API compatibility
Search for breaking changes in public response fields under `apps/api`.
If a field is already consumed by mobile clients, keep the existing field or add a backward-compatible alias before removing it.

### Logging boundary
Do not log raw access tokens, refresh tokens, email addresses, phone numbers, or customer message bodies.
If debugging needs correlation, log a request ID or hashed account ID instead.

### Billing writes
Changes under `billing/` must not silently retry non-idempotent writes.
Use idempotency keys and surface ambiguous payment state for manual review.

이 예시는 금지와 대안을 함께 적는다. 또한 rule 이름만 봐도 어떤 종류의 위험인지 알 수 있다. Codex가 finding을 만들 때 'AGENTS.md의 Logging boundary rule에 따라...'처럼 근거를 붙이기 쉽다.

나쁜 규칙의 예

나쁜 규칙은 너무 넓거나, 취향만 담거나, 현재 함수명에 과하게 의존한다.

- Always write clean code.
- Be careful with security.
- Prefer simple solutions.
- Never change `buildUserResponseV2` because it is important.

앞의 세 문장은 거의 모든 PR에 적용될 수 있어 signal이 없다. 마지막 문장은 함수명이 바뀌면 바로 낡는다. 더 나은 표현은 'mobile v3 clients consume the response field user_status; keep it until v2 sunset date or add an alias'처럼 outcome 중심으로 쓰는 것이다.

검증은 작은 eval로 시작한다

OpenAI 블로그는 rule-guided variant가 required custom finding의 98%를 회복했고 baseline은 58.3%였다고 소개한다. 숫자보다 중요한 것은 검증 방식이다. 규칙을 추가했으면 실제로 원하는 finding이 나오는지, 안전한 counterexample에서 noise가 생기지 않는지 확인해야 한다.

간단한 방식은 세 가지 PR 샘플을 만드는 것이다. 첫째, rule을 명확히 위반하는 diff. 둘째, 비슷하지만 안전한 diff. 셋째, 관련 없는 diff. Codex review를 돌려 첫 번째에서만 유용한 finding이 나오는지 본다. finding에는 위치, 위반 이유, 안전한 수정 경로가 있어야 한다.

이 과정을 하지 않으면 AGENTS.md가 또 하나의 장식 문서가 된다. 리뷰 rule은 작성보다 유지가 중요하다. 반복적으로 noise를 만드는 rule은 좁히거나 제거해야 한다.

운영 프로세스

처음에는 두세 개만 넣는 것이 좋다. 보안, API 호환성, 결제, 데이터 migration처럼 사고 비용이 큰 영역을 고른다. 각 rule에 owner를 붙이고, 월 1회 또는 사고 후에 업데이트한다.

PR template에도 '이 변경이 AGENTS.md rule과 충돌하는가' 같은 체크를 넣을 수 있다. 다만 사람에게 모든 것을 떠넘기지 말고 Codex review가 먼저 지적하게 하는 것이 목적이다. 사람은 false positive를 줄이고 rule을 개선하는 쪽에 시간을 써야 한다.

실행 체크리스트

• 반복해서 설명하는 리뷰 코멘트 5개를 모은다.
• 그중 놓치면 장애, 보안, 호환성 문제가 되는 2개만 고른다.
• root와 하위 디렉터리 중 어디에 둘지 scope를 정한다.
• 규칙에는 invariant, 위험, safe path를 함께 쓴다.
• 취향, 포맷, 단순 스타일은 lint나 formatter로 보낸다.
• 위반 PR, 안전한 PR, 무관한 PR로 작은 eval을 만든다.
• noise가 생기면 rule을 좁히고, 놓치면 예시를 구체화한다.
• rule owner와 업데이트 주기를 정한다.