AI 코드리뷰 운영법: Codex·Claude·Gemini CLI를 PR 전에 붙이는 현실적인 절차

요약: AI 코드리뷰는 “PR에 댓글을 많이 달아주는 기능”이 아니다. 잘 쓰려면 사람 리뷰 전에 반복 검사를 끝내고, 사람은 설계·위험·제품 판단에 집중하게 만들어야 한다. Codex, Claude Code, Gemini CLI 같은 도구를 붙일 때도 목표는 자동 합격이 아니라 리뷰 대기열을 줄이는 것이다.

AI 코드리뷰를 어디에 넣어야 하나

가장 흔한 실수는 AI 리뷰를 PR이 열린 뒤에만 붙이는 것이다. 이 방식은 이미 사람 리뷰어가 알림을 받은 뒤라 노이즈가 된다. AI가 사소한 스타일 문제를 뒤늦게 지적하면 작성자는 커밋을 추가하고, 리뷰어는 다시 봐야 한다. 자동화가 오히려 리뷰 시간을 늘릴 수 있다.

더 나은 위치는 PR 전이다. 개발자가 브랜치에서 작업을 끝낸 뒤 pre-review 단계를 실행한다. 이 단계에서 AI 에이전트는 변경 파일을 읽고, 테스트 실패 가능성, 누락된 케이스, 위험 경로, PR 설명 초안을 점검한다. 사람 리뷰어에게 올라가는 PR은 이미 기본 정리가 끝난 상태여야 한다.

CI 안에 넣을 수도 있지만, 처음부터 필수 게이트로 두면 실패 원인 파악이 어렵다. 추천 순서는 로컬 또는 임시 브랜치에서 선택 실행, 팀 템플릿 적용, 이후 안정화된 검사만 CI 필수로 승격하는 것이다.

에이전트가 봐야 할 것과 보지 말아야 할 것

AI 코드리뷰의 범위는 좁을수록 좋다. “이 코드 괜찮아?”라고 물으면 모델은 넓고 추상적인 답을 한다. 대신 변경된 파일, 관련 테스트, 요구사항, 금지된 변경 범위를 함께 줘야 한다. 예를 들어 “인증 로직은 의도적으로 변경하지 않았다. diff에서 인증 경로 변경이 있으면 표시하라”처럼 말한다.

에이전트가 잘 보는 항목은 반복적이고 구조적인 것들이다. 널 처리 누락, 에러 메시지 불일치, API 응답 타입 변경, 테스트 케이스 부재, 로깅 누락, 문서와 코드 불일치, 마이그레이션 영향 같은 부분이다. 반대로 제품 의도, 사용자 경험의 미묘한 판단, 조직 우선순위, 법무·보안 해석은 사람이 봐야 한다.

리뷰 프롬프트에는 “중요도” 기준도 필요하다. 모든 의견을 같은 톤으로 쓰면 작성자는 무엇을 먼저 고쳐야 할지 모른다. blocker, should-fix, nit 세 단계면 충분하다. blocker는 머지 전 반드시 해결, should-fix는 이번 PR에서 권장, nit는 선택이다. AI가 nit을 많이 내면 리뷰 피로가 커진다.

추천 워크플로우

첫 단계는 변경 요약이다. 에이전트에게 전체 diff를 보고 사용자 관점의 변경 요약, 기술적 변경 요약, 테스트 영향 범위를 나누어 쓰게 한다. 이 요약은 PR 설명 초안으로도 쓸 수 있다. 사람이 처음 보는 PR에서 가장 많은 시간이 드는 부분은 “무엇이 바뀌었는지 파악”이다.

두 번째 단계는 위험 경로 확인이다. 저장소마다 위험 경로를 정해 둔다. 예를 들어 auth, billing, migration, permissions, infra, payments, security 같은 경로다. 변경이 있으면 AI가 이유를 설명하고 추가 리뷰어를 추천하게 한다. 단, 추천은 참고 정보여야지 자동 배정까지 바로 이어지면 안 된다.

세 번째 단계는 테스트 매핑이다. 변경 파일마다 어떤 테스트가 실행되었고 어떤 테스트가 빠졌는지 묻는다. 여기서 AI의 역할은 테스트를 “상상”하는 것이 아니라, 실제 파일과 명령을 기준으로 빈틈을 찾는 것이다. 테스트가 없다면 “없음”이라고 쓰게 해야 한다. 없는 테스트를 있는 것처럼 말하는 순간 신뢰가 무너진다.

네 번째 단계는 코멘트 생성이다. 이 단계에서는 최대 개수를 제한한다. 예를 들어 blocker 최대 5개, should-fix 최대 7개, nit 최대 5개다. 개수 제한을 두면 모델이 중요도를 더 신중히 고른다. 댓글이 30개 달린 AI 리뷰는 대부분 읽히지 않는다.

실제 프롬프트 구조

프롬프트는 다음 구조가 좋다. 먼저 역할을 정한다. “너는 이 저장소의 PR 전 검토자다. 목표는 사람 리뷰어에게 올라가기 전 blocker를 찾는 것이다.” 다음으로 입력을 제한한다. “제공된 diff와 파일 내용만 근거로 판단하고, 모르는 것은 모른다고 말하라.” 그리고 출력 형식을 고정한다.

출력 예시는 다음과 같다. 변경 요약 5줄, 위험 경로 여부, 테스트 실행 결과, blocker 목록, should-fix 목록, nit 목록, PR 설명 초안. 각 코멘트에는 파일 경로, 근거, 제안 수정 방향을 포함한다. “성능을 개선하세요” 같은 말은 금지하고, “N+1 쿼리가 발생할 수 있으므로 이 호출을 batch loader로 묶으세요”처럼 써야 한다.

이 구조를 Codex, Claude Code, Gemini CLI 어디에나 적용할 수 있다. 도구별 장점은 다르지만, 리뷰 품질의 절반 이상은 프롬프트와 입력 범위에서 결정된다. 모델을 바꾸기 전에 리뷰 기준을 먼저 고정하는 편이 낫다.

AI 리뷰를 CI에 넣을 때 주의할 점

CI에서 AI 리뷰를 필수로 만들면 비용과 안정성 문제가 생긴다. 외부 모델 호출이 느리거나 실패하면 머지가 막힌다. 따라서 처음에는 필수 게이트가 아니라 참고 체크로 둔다. 결과는 PR 코멘트가 아니라 아티팩트나 요약 댓글 하나로 남기는 것이 좋다.

필수 게이트로 올릴 수 있는 것은 결정적 검사다. 예를 들어 비밀값 탐지, 금지 경로 변경, 테스트 실패, 타입 오류는 좋다. 반면 “AI가 보기엔 코드 품질이 낮음” 같은 주관적 판단을 필수로 두면 분쟁이 생긴다. AI 리뷰의 강점은 판단을 대신하는 것이 아니라 사람이 놓치기 쉬운 반복 패턴을 빠르게 보여주는 데 있다.

비용도 작업 단위로 봐야 한다. PR 하나당 AI 리뷰 비용, 평균 리뷰 시간 단축, 재리뷰 횟수 감소, 버그 발견 수를 함께 기록한다. 비용만 보면 비싸 보일 수 있지만, 시니어 리뷰어가 반복 코멘트에 쓰는 시간을 줄인다면 충분히 이득일 수 있다.

팀 규칙으로 정착시키는 방법

처음부터 전사 표준으로 만들 필요는 없다. 한 팀에서 2주간 “PR 전 AI 리뷰를 실행하고, blocker만 반영한다”는 규칙으로 시작한다. nit은 무시해도 된다. 이 기간에는 AI가 맞힌 문제보다 틀린 문제를 더 열심히 모은다. 오탐이 많은 항목은 프롬프트에서 제거하거나 룰 기반 검사로 바꾼다.

정착의 핵심은 사람 리뷰어가 편해지는지다. AI 리뷰가 작성자에게만 일을 더 시키면 오래가지 않는다. 사람 리뷰어가 “요약이 좋아서 맥락 파악이 빨라졌다”, “테스트 누락을 먼저 잡아줘서 설계 리뷰에 집중했다”고 느껴야 한다.

실행 체크리스트

• AI 리뷰는 PR 이후가 아니라 PR 전에 먼저 실행한다.
• 출력 중요도를 blocker, should-fix, nit으로 나눈다.
• 변경 요약, 위험 경로, 테스트 매핑, 코멘트, PR 설명 초안을 고정 형식으로 받는다.
• 제공된 diff와 파일 내용만 근거로 판단하게 하고 추측을 금지한다.
• 코멘트 최대 개수를 제한해 노이즈를 줄인다.
• CI 필수 게이트는 결정적 검사만 사용한다.
• 2주 파일럿 동안 오탐과 누락 사례를 모아 프롬프트를 수정한다.
• 성공 기준은 댓글 수가 아니라 사람 리뷰어의 맥락 파악 시간 감소다.