AI 코딩 에이전트 PR 리뷰 워크플로우: 작은 diff와 테스트 기준으로 실패 줄이기

AI 코딩 에이전트 PR 리뷰는 “코드 좀 봐줘”라고 던지면 실패하기 쉽다. Claude Code는 코드베이스를 읽고 파일을 수정하고 명령을 실행하며 개발 도구와 연동한다. Codex는 PR Chat, 멀티 저장소 리뷰, 데스크톱 앱 통합을 강화하고 있다. 도구는 좋아졌지만, 리뷰 품질은 여전히 워크플로우가 결정한다.

실무에서 AI 리뷰가 망하는 이유는 모델이 부족해서만이 아니다. diff가 너무 크고, 테스트 명령이 없고, 변경 의도가 불분명하고, 민감 파일 접근이 열려 있고, 사람이 어떤 기준으로 승인할지 정하지 않았기 때문이다. 에이전트는 맥락을 잘 먹을수록 잘하지만, 맥락이 무제한이면 엉뚱한 추론도 늘어난다.

PR을 작게 나누는 것이 첫 번째 품질 관리다

AI 리뷰에 가장 좋은 입력은 작은 diff다. 한 PR에 UI 수정, DB migration, API contract 변경, 테스트 리팩터링, dependency upgrade가 모두 들어 있으면 모델은 우선순위를 놓치기 쉽다. 사람 리뷰어도 마찬가지다. 작은 PR은 에이전트가 “무엇을 검증해야 하는지”를 이해하기 쉽고, 사람이 제안을 받아들일 때도 위험이 낮다.

권장 기준은 변경 파일 10개 이하, 핵심 로직 300라인 이하, 목적 하나다. 꼭 큰 변경이 필요하면 plan PR과 implementation PR을 나눈다. 먼저 “어떤 파일을 왜 바꿀지”만 리뷰받고, 그 다음 실제 수정을 진행한다. AI에게도 계획 리뷰와 코드 리뷰를 분리해서 시키면 결과가 훨씬 낫다.

예를 들어 “로그인 리팩터링”이라고 묶지 말고 “토큰 만료 처리 함수를 분리”, “refresh 실패 시 logout fallback 추가”, “모바일 앱 에러 메시지 변경”처럼 쪼갠다. 에이전트에게는 각 PR마다 확인할 위험을 다르게 준다.

리뷰 프롬프트에는 의도와 금지 범위를 같이 준다

나쁜 요청은 “이 PR 리뷰해줘”다. 좋은 요청은 “결제 실패 fallback을 추가한 PR이다. API 응답 타입과 UI 상태 전이가 맞는지, 기존 성공 결제 흐름을 깨지 않는지 봐줘. 코드는 수정하지 말고 위험도 high/medium/low로 분류해줘”처럼 쓴다.

리뷰 프롬프트에는 최소 다섯 가지가 들어가야 한다. 변경 의도, 사용자 영향, 반드시 지켜야 할 계약, 실행할 테스트 명령, 하지 말아야 할 행동이다. 하지 말아야 할 행동도 중요하다. “새 파일 생성 금지”, “dependency 변경 금지”, “production config 수정 금지”, “제안 패치는 별도 섹션으로만” 같은 제한을 둔다.

AI 리뷰는 권한을 줄이는 것만으로도 좋아진다. 수정 권한이 있는 세션과 읽기 전용 리뷰 세션을 분리한다. 리뷰 단계에서는 diff와 관련 파일만 읽게 하고, 수정은 사람이 승인한 항목만 별도 작업으로 넘긴다.

테스트 명령은 에이전트가 추측하게 두지 않는다

에이전트가 “테스트를 실행했다”고 말했는데 실제로는 엉뚱한 명령을 돌리는 경우가 있다. monorepo에서는 더 흔하다. 따라서 PR 템플릿이나 리뷰 프롬프트에 정확한 테스트 명령을 넣어야 한다. 예를 들어 pnpm test --filter checkout, npm run lint, pytest tests/payments, yarn typecheck처럼 적는다.

테스트는 세 단계로 나눈다. 첫째, 빠른 정적 검사다. lint, typecheck, formatting이 여기에 해당한다. 둘째, 변경 영역 단위 테스트다. 결제, 인증, 검색처럼 영향을 받은 모듈만 돌린다. 셋째, 위험 변경에 대한 통합 테스트다. DB migration, API contract, 권한 로직은 통합 테스트나 staging 확인이 필요하다.

AI 리뷰어에게는 테스트 결과를 해석하게 할 수 있다. 실패 로그를 붙이고 “새 변경 때문인지 기존 flaky인지 분류해줘”라고 묻는다. 단, 실패한 테스트를 모델이 임의로 삭제하거나 snapshot을 무조건 업데이트하지 못하게 해야 한다. 테스트 수정은 별도 승인 대상이다.

멀티 저장소 리뷰는 계약 검증에 쓴다

Codex의 멀티 저장소 리뷰 같은 기능은 여러 repo를 한 번에 훑는 데 유용하다. 하지만 “전체를 다 봐줘”보다 contract 검증에 쓰는 편이 효과적이다. 백엔드 OpenAPI schema가 바뀌었으면 웹과 앱 호출부가 따라왔는지, 이벤트 이름이 바뀌었으면 analytics consumer가 맞는지, DB enum이 늘었으면 admin filter가 깨지지 않는지 확인한다.

멀티 저장소 리뷰 요청 예시는 이렇다. “api, web, app 세 저장소의 diff를 보고 subscription_status 변경이 모든 호출부에 반영됐는지 확인해줘. 새 코드 작성은 하지 말고 누락 가능성이 있는 파일 경로와 이유만 표로 정리해줘.” 이렇게 하면 모델이 주변 코드를 넓게 보되, 출력은 좁게 유지된다.

멀티 repo 접근을 허용할 때는 primary source of truth도 정해야 한다. 타입 정의가 백엔드인지, shared package인지, OpenAPI 문서인지 모호하면 모델이 임의로 기준을 고른다. 리뷰 프롬프트에 “계약 기준은 packages/contracts/schema.ts”처럼 명시한다.

민감 파일과 자동 수정 범위를 보호한다

AI 코딩 에이전트는 .env, credential, migration, billing, auth, infra 파일에서 특히 조심해야 한다. 리뷰 세션에서 이런 파일을 읽을 수는 있어도 쓰기는 막는 것이 좋다. production 설정, Terraform state, DB migration rollback, 결제 provider secret은 사람 승인 없이 수정하면 안 된다.

자동 수정 범위도 정한다. 예를 들어 “타입 오류, import 정렬, 테스트 이름 수정은 자동 제안 가능. 로직 변경, schema 변경, migration 변경은 제안만 가능”처럼 분류한다. 이렇게 해야 에이전트가 작은 lint 수정과 큰 설계 변경을 같은 무게로 처리하지 않는다.

리뷰 결과는 action item으로 남겨야 한다. “괜찮아 보입니다”는 쓸모가 적다. “High: refresh 실패 시 기존 토큰을 유지해 무한 재시도 가능. 파일: auth/session.ts:88. 재현: refresh endpoint 500 응답. 권장: 실패 시 logout 상태로 전이.”처럼 위치, 이유, 재현, 권장을 요구한다.

사람 리뷰어의 역할은 사라지지 않는다

AI가 먼저 보는 리뷰는 좋은 필터다. 반복적인 누락, 타입 불일치, 테스트 빠짐, 문서 불일치를 빠르게 잡는다. 하지만 제품 의도, 사용자 경험, 법적 리스크, 조직의 운영 기준은 사람이 판단해야 한다. AI가 “통과”라고 해도 고위험 변경은 사람이 마지막 책임을 져야 한다.

팀 규칙으로는 AI 리뷰를 필수 게이트가 아니라 보조 게이트로 두는 편이 낫다. AI가 high risk를 찾으면 merge를 멈추고, medium은 사람 리뷰어가 판단하고, low는 작성자가 처리한다. 반대로 AI가 아무 문제를 못 찾았다는 이유로 사람 리뷰를 생략하지 않는다.

실행 체크리스트

• PR은 목적 하나, 변경 파일 10개 이하, 핵심 로직 300라인 이하를 기본 목표로 둔다.
• 리뷰 프롬프트에 변경 의도, 사용자 영향, 계약 기준, 테스트 명령, 금지 행동을 적는다.
• 읽기 전용 리뷰 세션과 수정 세션을 분리하고, 자동 수정 범위를 제한한다.
• 테스트 명령은 에이전트가 추측하지 않게 PR 템플릿에 명시한다.
• 멀티 저장소 리뷰는 API contract, event name, shared type 같은 경계 검증에 집중한다.
• .env, credential, billing, auth, infra, migration 파일은 사람 승인 없이 쓰기 금지로 둔다.
• AI 리뷰 출력은 위치, 이유, 재현 방법, 권장 조치가 있는 action item 형식으로 받는다.

출처: Claude Code 공식 문서, OpenAI Codex changelog 및 PR Chat·multi-repository review 공개 내용.