Codex의 코드 리뷰에서 반복해서 놓치는 저장소 규칙은 AGENTS.md에 짧고 구체적으로 적어 둘 수 있습니다. OpenAI의 2026년 7월 20일 안내는 규칙을 기계적 검사와 나누고, 중요한 변경 위험에 한정해 리뷰가 근거를 들어 지적하도록 구성하는 방법을 소개했습니다.
간단 요약
- 규칙은 반복 설명하는 비자명한 위험부터 선택
- 저장소 공통 규칙과 폴더별 규칙을 구분
- 위반 예시와 정상 예시를 함께 점검
- 코드 리뷰는 보조 검토자로 사용
1. 규칙이 필요한 순간
코드 차이만 읽어서는 발견하기 어려운 위험이 있습니다. 응답 필드 이름을 정리하는 변경은 겉보기에는 단순하지만, 이미 그 값을 읽는 다른 서비스가 있다면 연동이 끊길 수 있습니다. 팀의 리뷰어 몇 명만 알고 있던 맥락을 저장소에 가까이 두면 처음 보는 기여자와 코딩 에이전트도 확인 기준을 찾기 쉽습니다.
2. 첫 규칙은 반복 지적에서 찾기
리뷰에서 “이 부분은 왜 매번 되돌리는가?”를 물어보세요. 외부 API 계약 유지, 로그에서 고객 데이터 제거, 권한 경계를 넘지 않는 것처럼 놓쳤을 때 영향이 큰데 diff만으로 알아채기 어려운 내용을 우선합니다. 이름 정렬이나 공백처럼 자동 검사할 수 있는 조건은 규칙으로 늘리지 말고 CI 도구에 맡깁니다.
모든 디렉터리에 적용될 원칙은 루트 AGENTS.md에 두고, 한 서비스에만 필요한 사항은 그 서비스 폴더 안에 둡니다. 예를 들어 앱 서버의 이벤트 이름 호환성은 앱 서버 폴더에서 관리할 수 있습니다. 리뷰 대상과 관련 없는 규칙이 지나치게 자주 끼어들면 적용 범위가 넓은 신호입니다.
3. 위험과 대안을 한 문장에 담기
“호환성을 지켜라”만 쓰면 어떤 인터페이스를 어떻게 확인해야 하는지 모호합니다. “외부 소비자가 읽는 이벤트 이름은 유지하고, 변경이 필요하면 기존 이름을 계속 제공하는 호환 이벤트를 추가한다”처럼 보존해야 할 조건과 허용 가능한 경로를 같이 씁니다.
내 경우 판단 순서
- 놓쳤을 때 영향이 큰 불변 조건을 고릅니다.
- 대상 코드 범위와 유지해야 할 조건을 씁니다.
- 위반·정상 예외·무관 변경으로 지적을 비교합니다.
4. 3가지 예시로 노이즈 확인
한 가지 규칙을 추가했다면 이를 어기는 변경, 안전한 예외, 전혀 관계없는 변경을 각각 준비해 검토합니다. 첫 변경에서 실제 위험을 찾아내고 나머지 두 변경에 불필요한 지적을 붙이지 않는지 확인하세요. OpenAI의 안내도 규칙의 포괄성뿐 아니라 과잉 지적을 억제하는지 살펴보도록 권합니다.
코드 리뷰는 발견을 도와주는 추가 검토자입니다. 테스트, 브랜치 보호, 필수 승인 절차를 대신하는 강제 장치는 아닙니다. 데이터 손실이나 호환성 단절처럼 반드시 막아야 하는 조건은 가능한 범위에서 결정론적 검사와 보호 규칙으로 보완해야 합니다.
예를 들어 외부 이벤트 이름을 바꾸는 변경이 위험하다면 규칙에는 영향을 받는 소비자를 확인하라는 행동과 호환 이름을 유지하는 방법을 함께 씁니다. Codex 코드 리뷰가 어떤 파일에 그 규칙을 적용해야 할지도 명확하게 정하세요. 검토 결과에서 근거 위치와 다음 행동이 빠졌다면 규칙을 더 길게 늘이기보다, 놓친 조건 한 가지를 좁혀 보완하는 편이 낫습니다. 이런 방식이면 반복되는 설명을 줄이면서 안전한 예외를 허용할 수 있습니다.
Codex 코드 리뷰 결과가 실제 변경 위치와 규칙의 근거를 가리키는지 확인하는 일도 중요합니다. 지적 문장이 일반론에 머물거나 정상 변경까지 매번 막는다면 그 규칙은 더 구체적이어야 하거나 범위가 넓을 수 있습니다. 리뷰어가 다음으로 해야 할 조치를 바로 알 수 있는지까지 살펴보세요.
규칙에 따라 검토 결과가 달라졌다면, 팀에서 그 차이를 받아들일 수 있는지도 리뷰어와 함께 맞추는 편이 좋습니다.
5. 작게 시작하고 오래된 규칙은 줄이기
한 번에 규칙을 많이 넣기보다 가장 중요한 두세 가지부터 시험합니다. 프로젝트 구조나 인터페이스가 바뀌면 규칙도 같이 검토하고, 실제로 위험을 줄이지 못하거나 무관한 지적을 반복하면 범위를 좁히거나 제거합니다. 결과적으로 좋은 규칙은 리뷰 문장을 길게 만드는 대신 반복 설명을 줄입니다.
✅ 결론
코드 리뷰 규칙은 자동화하기 어려운 저장소의 약속을 기록할 때 가치가 있습니다. 반복되는 중요한 위험 하나를 고르고, 적용 위치와 안전한 대안을 분명히 쓴 다음, 위반·정상·무관 사례로 지적의 품질을 확인해 보세요.
자료 출처 OpenAI Developers, 「Custom Code Review rules for Codex」(2026년 7월 20일) 확인 기준. 기능과 안내는 변경될 수 있습니다.
FAQ — 자주 묻는 질문
Q1. 규칙을 AGENTS.md에 쓰면 Codex가 모든 문제를 잡나요?
아닙니다. 리뷰는 추가 검토 수단입니다. 테스트와 브랜치 보호, 필수 승인은 별도로 유지해야 합니다.
Q2. 몇 개의 규칙으로 시작하면 좋나요?
OpenAI 안내는 적용할 파일에 두세 개의 규칙부터 추가해 대표 변경으로 확인하는 방식을 제안합니다. 규칙 수보다 중요하고 범위가 좁은지가 더 중요합니다.
Q3. 코드 스타일 규칙도 넣을 수 있나요?
쓸 수는 있지만, 포매터나 린터가 안정적으로 검사할 수 있는 스타일은 해당 도구에 맡기는 편이 효율적입니다. 저장소 규칙에는 리뷰어의 맥락 판단이 필요한 호환성·데이터 경계 같은 내용을 남기세요.
※ 이 글은 2026년 9월 29일 기준 OpenAI 공식 안내를 바탕으로 작성한 정보성 해설입니다. 제품 기능과 운영 방식은 바뀔 수 있으며, 실제 저장소 적용과 코드 변경 결과는 프로젝트 환경에서 별도로 검토해야 합니다.
