AI 코딩 에이전트 PR 리뷰 체크리스트: 사람이 봐야 할 diff와 자동화가 봐야 할 diff를 분리하는 법
AI 코딩 에이전트가 만든 PR은 사람 개발자가 만든 PR과 다르게 리뷰해야 합니다. 이유는 간단합니다. 에이전트는 빠르게 넓은 범위를 건드릴 수 있고, 겉으로는 그럴듯한 수정이 많습니다. 타입 오류를 없애기 위해 예외를 삼키거나, 테스트를 통과시키려고 검증을 약하게 만들거나, 기존 정책을 모른 채 “깔끔한” 리팩터링을 할 수 있습니다.
그래서 AI 코딩 에이전트 PR 리뷰의 목표는 “코드 스타일 확인”이 아닙니다. 목표는 변경 의도, 영향 범위, 안전장치, 테스트 신뢰도를 짧은 시간 안에 판별하는 것입니다. 모든 줄을 사람이 다 읽는 방식은 오래 못 갑니다. 사람이 봐야 할 diff와 자동화가 봐야 할 diff를 분리해야 합니다.
이 글은 Codex·Claude Code·Cursor류 도구를 모두 포함해, AI가 만든 변경을 팀 프로세스에 넣을 때 쓸 수 있는 실무 체크리스트입니다.
리뷰 시작 전에 PR 설명부터 표준화한다
AI PR에서 가장 먼저 볼 것은 diff가 아니라 PR 설명입니다. 설명이 부실하면 리뷰 비용이 급증합니다. PR 본문에는 최소 다섯 가지가 있어야 합니다. 요청 원문, 변경한 파일 그룹, 실행한 테스트, 의도적으로 건드리지 않은 범위, 리뷰어가 집중해서 봐야 할 지점입니다.
예를 들어 “로그인 버그 수정”은 부족합니다. “소셜 로그인 콜백에서 state 검증 실패 시 500이 나는 문제를 400 응답으로 바꾸고, 기존 이메일 로그인 플로우는 수정하지 않았다”처럼 써야 합니다. AI가 만든 PR이라면 이 설명은 더 중요합니다. 모델은 실제 의도와 다른 방향으로 코드를 수정할 수 있기 때문입니다.
팀에서는 PR 템플릿에 AI 작업 여부를 넣는 것이 좋습니다. “AI generated/assisted: yes”, “human verified files”, “commands run” 같은 항목을 두면 나중에 회귀가 생겼을 때 추적하기 쉽습니다.
자동화가 먼저 봐야 할 diff: 포맷·타입·테스트·보안 스캔
사람 리뷰어가 포맷팅이나 단순 타입 오류를 보면 안 됩니다. 이 영역은 자동화가 먼저 걸러야 합니다. lint, format, typecheck, unit test, dependency audit, secret scan은 PR 생성 직후 실행되어야 합니다. AI 에이전트가 만든 PR은 특히 secret scan이 중요합니다. 모델이 예시 코드를 만들면서 가짜 키처럼 보이는 문자열을 넣거나, 환경변수 사용 방식을 잘못 제안할 수 있습니다.
자동화 결과는 단순 pass/fail보다 원인을 남겨야 합니다. 어떤 명령을 실행했는지, 실패 로그가 무엇인지, 재시도했는지 PR에 기록합니다. AI가 테스트를 “고쳤다”고 주장해도 실제 CI 로그가 없으면 믿으면 안 됩니다.
또 하나 중요한 자동화는 diff 크기 제한입니다. 파일 수가 너무 많거나 삭제 라인이 과도하면 리뷰 전에 분할을 요구해야 합니다. AI PR은 한 번에 많은 파일을 건드리는 경향이 있습니다. 큰 PR은 버그를 숨깁니다.
사람이 집중해서 봐야 할 diff: 정책·경계·삭제·fallback
사람 리뷰어는 자동화가 볼 수 없는 영역에 집중해야 합니다. 첫째, 정책 변경입니다. 인증, 결제, 개인정보, 권한, 요금제 조건은 코드가 맞아도 제품 정책이 틀릴 수 있습니다. 둘째, 경계 조건입니다. null, 빈 배열, 중복 요청, 네트워크 실패, 부분 성공 같은 케이스를 봐야 합니다. 셋째, 삭제입니다. AI가 “사용하지 않는 코드”라고 판단해도 실제로는 런타임에서 호출될 수 있습니다.
넷째, fallback입니다. 외부 API 실패 시 기존 동작이 유지되는지 확인해야 합니다. 에이전트는 성공 경로를 잘 만들지만 실패 경로를 단순화하는 경우가 많습니다. 예를 들어 결제 provider timeout에서 재시도 정책이 사라지거나, 캐시 미스 때 빈 응답을 돌려주는 식입니다.
리뷰어는 “이 코드가 정상 입력에서 동작하나?”보다 “이 코드가 이상 입력에서 안전하게 실패하나?”를 봐야 합니다. 프로덕션 장애는 대부분 이상 입력과 외부 의존성 실패에서 납니다.
테스트 리뷰: 추가된 테스트보다 삭제된 테스트를 먼저 본다
AI PR에서 테스트가 추가되었다고 안심하면 안 됩니다. 모델은 통과하기 쉬운 테스트를 만들 수 있습니다. 더 위험한 것은 기존 테스트를 약하게 바꾸는 경우입니다. assertion을 줄이거나, mock을 과도하게 쓰거나, 실패해야 할 케이스를 성공으로 바꿀 수 있습니다.
리뷰 순서는 삭제·수정된 테스트를 먼저 보는 것이 좋습니다. 기존 테스트가 왜 바뀌었는지 설명이 없으면 경고 신호입니다. 다음으로 새 테스트가 실제 버그를 재현하는지 봅니다. 단순히 함수가 호출되는지만 확인하는 테스트는 가치가 낮습니다. 입력, 상태 변화, 오류 응답, 권한 경계를 확인해야 합니다.
AI가 만든 테스트에는 “회귀 테스트 이름”을 붙이는 것도 좋습니다. 예를 들어 test_social_login_invalid_state_returns_400처럼 버그 조건이 이름에 드러나야 합니다. 그래야 다음 리뷰어가 테스트 의도를 이해합니다.
리뷰 시간을 줄이는 운영 규칙
AI PR 리뷰를 오래 지속하려면 규칙이 필요합니다. 첫째, 작은 PR만 허용합니다. 둘째, 자동화 실패 PR은 사람 리뷰 전에 되돌립니다. 셋째, 위험 파일은 CODEOWNERS로 강제 리뷰어를 붙입니다. 넷째, AI가 생성한 migration, auth, billing 변경은 별도 승인 없이 병합하지 않습니다.
또한 리뷰어는 AI에게 바로 수정 요청을 할 수 있어야 합니다. “이 부분 고쳐줘”가 아니라 “테스트 A를 유지하면서 파일 B의 fallback만 수정해”처럼 좁게 요청해야 합니다. 요청이 넓으면 에이전트가 다시 큰 diff를 만들 수 있습니다.
마지막으로 병합 후 추적이 필요합니다. AI PR의 rollback 비율, 리뷰 코멘트 수, CI 실패율, 장애 연결 여부를 월 단위로 봅니다. 이 지표가 좋아질 때만 에이전트 권한을 넓히는 것이 안전합니다.
실행 체크리스트
- PR 템플릿에 요청 원문, 변경 범위, 실행 테스트, 미확인 리스크를 강제한다.
- lint/format/typecheck/test/secret scan/dependency audit을 사람 리뷰 전에 돌린다.
- 큰 diff, 대량 삭제, 위험 디렉터리 변경은 자동으로 분할 요청한다.
- 사람은 인증·결제·개인정보·권한·fallback·삭제 diff에 집중한다.
- 추가된 테스트보다 삭제·수정된 기존 테스트를 먼저 확인한다.
- AI PR의 CI 실패율, 리뷰 수정 횟수, rollback 여부를 월 단위로 추적한다.