AI 에이전트가 한 번에 많은 파일을 바꾼 PR을 열면, 리뷰어는 두 가지 나쁜 선택 사이에 놓이기 쉽습니다. 모든 diff를 읽다가 핵심 변경을 놓치거나, 규모가 너무 크다는 이유로 충분히 확인하지 못한 채 병합하는 선택입니다.
이때 필요한 것은 AI가 모든 코드를 자연어로 설명하는 화면이 아닙니다. 먼저 사람이 판단해야 하는 변경을 분류하고, 왜 그 변경에 사람이 승인해야 하는지 남기는 절차입니다. 기존 코드 리뷰, 정적 분석, LLM 기반 리뷰, 변경 우선순위 분류는 서로 대체재가 아니라 다른 실패를 막는 계층으로 설계해야 합니다.
요구사항은 “무엇을 찾을까”보다 “누가 승인할까”부터 정한다
대규모 PR 검토 체계를 만들 때 흔히 보안 취약점, 버그, 스타일 위반을 탐지하는 목록부터 작성합니다. 그러나 AI 에이전트가 만든 변경에서는 책임 경계가 더 먼저입니다. 어떤 변경이 배포 후 장애, 보안 사고, 비용 증가, 계약상 약속 위반으로 이어질 수 있는지를 정하고, 그 변경을 누가 승인해야 하는지 연결해야 합니다.
초기 요구사항 문서에는 적어도 다음 네 항목을 넣는 편이 좋습니다.
| 구분 | 결정할 내용 | 산출물 |
|---|---|---|
| 변경 위험 | 인증, 권한, 결제, 개인정보, 데이터 삭제, 외부 연동, 인프라 변경 중 무엇을 고위험으로 볼지 | 변경 위험 분류표 |
| 승인 책임 | 코드 소유자, 보안 담당자, 서비스 책임자, 인프라 담당자가 각각 어떤 변경을 승인할지 | 승인 매트릭스 |
| 병합 조건 | 자동 차단할 조건, 추가 검토를 요구할 조건, 기록만 남길 조건 | PR 병합 정책 |
| 증적 범위 | 모델 판단, 정적 분석 결과, 사람의 승인 또는 반려 사유를 어디까지 보관할지 | 리뷰 이력 스키마 |
예를 들어 의존성 버전 변경은 많은 저장소에서 일상적 변경일 수 있습니다. 다만 인증 라이브러리, 데이터베이스 드라이버, 결제 SDK처럼 서비스 동작과 공급망 위험을 함께 바꾸는 의존성이라면 담당자가 확인할 이유가 생깁니다. 반대로 문서 문구, 테스트 데이터, 생성 파일처럼 서비스 동작에 영향을 주지 않는 변경까지 같은 강도로 승인하게 하면 분류 체계는 빠르게 무시됩니다.
여기서 중요한 원칙은 P0, P1, P2 같은 등급이 결함의 확률을 뜻하지 않는다는 점입니다. 등급은 사람의 주의와 승인 순서를 배분하는 장치로 정의해야 합니다. “P0이므로 버그다”가 아니라 “P0이므로 지정된 사람이 병합 전에 판단한다”로 써야 운영 중 오해가 줄어듭니다.
검토 도구는 탐지, 설명, 우선순위, 승인으로 나눈다
AI 에이전트 PR에 하나의 리뷰 도구만 붙이면 그 도구의 맹점을 사람이 떠안게 됩니다. 권장할 만한 조합은 각 계층의 질문을 분리하는 방식입니다.
정적 분석과 테스트는 규칙을 확인합니다. 컴파일 오류, 타입 오류, 알려진 취약한 패턴, 라이선스 정책, 테스트 실패, 코드 포맷처럼 판정 기준이 비교적 명확한 항목은 여기서 처리합니다. 결과는 가능한 한 차단 조건으로 연결합니다. 사람이 LLM의 설명을 읽고도 빌드 실패를 발견해야 하는 운영은 비효율적입니다.
LLM 리뷰는 변경의 의미와 누락 가능성을 살핍니다. 기존 코드와 변경 코드의 관계, 함수 호출 흐름, 예외 처리의 공백, 요구사항과 구현의 불일치처럼 규칙만으로 찾기 어려운 부분을 검토 대상으로 삼습니다. 다만 LLM의 지적은 확정 판정이 아니라 검토 가설입니다. 모델이 문제를 지적하지 않았다고 안전하다고 볼 수 없고, 지적했다고 곧바로 차단해서도 안 됩니다.
우선순위 분류기는 사람의 화면과 시간을 배분합니다. 파일 수나 변경 줄 수가 아니라 변경 행위와 영향 범위를 기준으로 봐야 합니다. 권한 검증을 우회하는 조건문 변경, 삭제 범위가 넓은 데이터 마이그레이션, 외부 API 호출 경로 변경은 작은 diff여도 위로 올라와야 합니다. 반대로 많은 생성 코드나 기계적 이름 변경은 규모가 커도 낮은 우선순위로 접을 수 있습니다.
사람의 코드 리뷰는 책임 있는 판단을 남깁니다. 리뷰어는 모든 코드를 다시 작성하거나 AI 설명을 교정하는 역할이 아닙니다. 고위험 변경이 제품 요구, 운영 제약, 고객 약속과 맞는지 판단하고, 수용 가능한 위험인지 승인하는 역할입니다.
이 분리는 “AI가 설명하고 사람이 읽는다”는 단순한 흐름보다 강합니다. 검토자가 먼저 봐야 할 변경과 승인할 사람을 알 수 있기 때문입니다.
구현은 작은 정책 파일과 PR 증적부터 시작한다
처음부터 조직 전체의 완전한 위험 모델을 만들 필요는 없습니다. 한 서비스 또는 한 저장소에서 병합 사고의 비용이 큰 변경부터 정의하고, 정책을 코드와 함께 버전 관리하는 편이 낫습니다.
첫 번째 단계에서는 .review-policy.yml 같은 정책 파일에 경로, 변경 유형, 필요 승인자를 기록합니다. 예를 들어 auth/, payments/, infra/, 데이터베이스 마이그레이션 경로, CI 배포 설정을 고위험 후보로 지정할 수 있습니다. 경로만으로 부족한 경우에는 공개 API 변경, 권한 조건 변경, 데이터 삭제 쿼리 추가, 네트워크 목적지 변경 같은 행위 규칙을 추가합니다.
두 번째 단계에서는 분석 파이프라인을 구성합니다. PR 생성 또는 업데이트 시 다음 결과를 하나의 리뷰 보고서에 모읍니다.
- 빌드, 테스트, 린트, 보안 스캔의 성공·실패 상태
- 파일과 변경 단위별 위험 등급
- 등급을 부여한 정책 규칙 또는 모델 판단 근거
- LLM이 제기한 검토 질문과 관련 코드 위치
- 필요한 승인자와 아직 충족되지 않은 승인 조건
- 분석한 커밋 SHA와 보고서 생성 시점
이 보고서는 PR의 최신 커밋과 묶여야 합니다. 새 커밋이 올라온 뒤 이전 분석 결과를 계속 보여 주면, 리뷰어는 이미 사라진 코드에 승인할 수 있습니다. 커밋이 바뀌면 분석을 다시 실행하고 이전 결과는 이력으로만 남기는 방식을 권합니다.
세 번째 단계에서는 화면을 설계합니다. 기본 화면에 모든 자연어 설명을 펼치기보다, P0 또는 조직이 정한 고위험 항목, 실패한 자동 검사, 아직 승인되지 않은 항목을 먼저 보여 줍니다. 원본 diff로 언제든 돌아갈 수 있어야 하며, AI가 만든 요약 화면이 Git diff를 대체해서는 안 됩니다.
일부 로컬형 도구는 변경 단위를 제한해 분석하거나, 지정한 최대치까지만 처리할 수 있습니다. 예를 들어 분석 대상이 경로 순서로 잘리면 중요한 변경이 뒤쪽에 있어도 제외될 수 있습니다. 이런 제한이 있는 제품을 검토할 때는 “분석하지 않은 변경을 화면에서 어떻게 표시하는가”, “고위험 경로를 우선 분석할 수 있는가”, “커밋 갱신 시 오래된 보고서를 숨기는가”를 확인해야 합니다.
모델 정확도보다 먼저 검증할 것은 누락과 과잉 경보다
우선순위 분류를 도입할 때 첫 목표를 “P0을 많이 찾아내기”로 잡으면 경보가 과도해질 수 있습니다. 반대로 P0 수를 줄이는 데만 집중하면 위험한 변경을 P2로 내리는 문제가 생깁니다. 따라서 파일 단위 정확도보다 승인 흐름이 제대로 작동하는지 검증해야 합니다.
검증용 PR 묶음에는 과거의 실제 변경을 쓸 수 있다면 좋지만, 민감한 코드나 사건 정보를 그대로 복제할 필요는 없습니다. 조직 정책에 맞는 대표 변경 유형을 골라 다음을 확인합니다.
- 권한, 데이터 삭제, 배포 설정 변경이 높은 우선순위로 올라오는가
- 생성 코드나 기계적 포맷 변경이 사람의 검토 대기열을 과도하게 채우지 않는가
- 정적 분석 실패가 자연어 설명에 묻히지 않고 병합 조건에 반영되는가
- 모델이 잘못 분류했을 때 리뷰어가 등급과 사유를 수정할 수 있는가
- 사람이 승인한 항목과 승인 사유가 커밋 기준으로 남는가
이 검증에서 발견한 오분류는 모델 프롬프트만 고쳐서는 해결되지 않을 수 있습니다. 고위험 경로를 정책에 추가해야 할 수도 있고, 코드 소유자 규칙이 실제 팀 구조와 다를 수도 있습니다. 분류 품질은 모델 선택보다 조직의 변경 책임 정의에 크게 좌우됩니다.
운영 단계에서는 “병합 후 학습”이 아니라 “정책 수정”으로 닫는다
AI 리뷰 도입이 실패하는 초기 신호는 비교적 분명합니다. 리뷰어가 모든 항목을 같은 이유로 승인하거나, P0이 너무 많아 기본 화면의 의미가 없어지거나, 담당자가 없는 변경이 계속 대기열에 남는 경우입니다. 이때 모델을 더 추가하기보다 정책과 승인 구조를 먼저 점검해야 합니다.
운영 회의에서는 모델의 문장 품질보다 다음 질문을 다루는 편이 생산적입니다.
- 어떤 고위험 변경이 낮은 우선순위로 분류됐는가
- 어떤 유형의 경보가 반복적으로 무시됐는가
- 승인자는 실제로 변경의 영향을 판단할 권한과 맥락을 갖고 있는가
- 에이전트가 만든 PR의 범위를 더 작게 나누도록 개발 흐름을 바꿔야 하는가
- 외부 모델에 보낼 수 없는 코드와 문맥은 무엇인가
코드를 외부 AI 제공자에게 보내는 도구라면, 로컬 브라우저 확장이나 로컬 서버를 사용하더라도 분석 명령이 어떤 코드와 주변 문맥을 전송하는지 별도로 확인해야 합니다. 키 보관 방식, 전송 범위, 보존 정책, 민감 저장소 제외 기능도 보안팀과 함께 검토할 항목입니다. 로컬 화면이라는 이유만으로 코드가 외부로 나가지 않는 것은 아닙니다.
대규모 AI PR을 다루는 팀이 먼저 만들 일은 더 설득력 있는 요약이 아닙니다. 다음 스프린트에서 병합될 변경 가운데 사람이 서명해야 할 변경 세 종류를 고르고, 그 변경에 대한 승인자와 증적 형식을 정책 파일로 정해 보십시오. 그 뒤에 정적 분석, LLM 리뷰, 우선순위 분류를 붙여도 늦지 않습니다.
