AI 코딩에서 가장 자주 생기는 착각은 '코드가 만들어졌으니 이제 테스트만 돌리면 된다'는 생각입니다. 하지만 실무에서 중요한 질문은 조금 다릅니다. 이 변경이 왜 필요한가, 어떤 파일이 위험한가, 어떤 회귀를 막았는가, 배포하다 문제가 나면 어디까지 되돌릴 수 있는가를 설명할 수 있어야 합니다.

이 글은 AI 에이전트가 만든 변경을 사람처럼 꼼꼼하게 읽기 위한 diff 리뷰 루프를 다룹니다. 초보자에게 diff는 낯선 화면일 수 있습니다. 쉽게 말하면 diff는 '이번 작업으로 무엇이 바뀌었는지 보여주는 변경 목록'입니다. 숙련자에게 diff는 배포 위험을 가장 빨리 발견하는 지도입니다. AI가 코드를 빠르게 만들수록, diff를 기준으로 검토하는 습관이 더 중요해집니다.

핵심 결론

AI 코드 리뷰는 완성된 파일 전체를 처음부터 읽는 일이 아니라, diff를 기준으로 변경 의도와 위험을 좁혀 가는 일입니다. 좋은 리뷰 루프는 네 문장으로 시작합니다.

1. 이번 변경의 사용자 문제는 무엇인가.
2. 실제로 바뀐 파일과 함수는 어디인가.
3. 위험 파일과 위험 조건은 무엇인가.
4. 회귀 테스트와 배포 전 검증은 무엇으로 끝낼 것인가.

이 네 문장을 에이전트에게 먼저 쓰게 하면 리뷰가 훨씬 쉬워집니다. '괜찮아 보이는 코드'를 믿는 대신, 변경 요약, 위험 파일, 리뷰 패스, 회귀 테스트, 롤백 기준을 하나씩 확인할 수 있기 때문입니다.

핵심 포인트: AI에게 리뷰를 맡기는 것이 아니라, AI가 만든 diff를 사람이 검토하기 쉬운 증거 묶음으로 바꾸는 것이 목표입니다.

왜 중요한가

AI는 넓게 고치는 경향이 있다

AI 에이전트는 요청을 해결하기 위해 관련 있어 보이는 파일을 여러 개 동시에 고칠 수 있습니다. 작은 문구 수정처럼 보였는데 데이터 로딩, 스타일, 테스트, 라우팅까지 바뀌는 일이 생깁니다. 실제로 필요한 변경이라면 괜찮지만, 설명 없는 넓은 변경은 리뷰 비용과 장애 가능성을 동시에 높입니다.

Diff 리뷰 루프는 이 문제를 빠르게 드러냅니다. 변경 파일 목록을 먼저 보고 '문제 해결에 꼭 필요한 파일인가'를 묻습니다. 그다음 각 파일의 변경 이유를 한 줄로 적게 합니다. 이유를 설명하지 못하는 변경은 되돌리거나 별도 작업으로 분리하는 후보입니다.

테스트 통과만으로는 리뷰가 끝나지 않는다

테스트는 강력한 안전장치지만 모든 위험을 대신 보지는 못합니다. 테스트가 통과해도 접근성 문구가 어색할 수 있고, 공개 페이지에 내부 용어가 남을 수 있고, 배포 환경에서만 필요한 검증이 빠질 수 있습니다. 그래서 AI 코드 리뷰는 테스트 결과와 diff 독해를 함께 봐야 합니다.

실제 작업 순서

1단계: 에이전트에게 변경 요약을 먼저 요구한다

리뷰를 시작하기 전에 에이전트에게 결과 보고를 바로 쓰게 하지 말고, diff 기준 변경 요약을 만들게 합니다. 좋은 요약은 짧지만 구체적이어야 합니다.

• 해결한 사용자 문제: 예를 들어 '모바일 Q&A 카드에서 제목과 답변 요약이 잘리지 않게 한다'.
• 핵심 변경: 예를 들어 '카드 레이아웃의 줄 간격과 최대 높이를 조정한다'.
• 변경하지 않은 것: 예를 들어 '데이터 모델, 관리자 기능, 라우팅은 건드리지 않는다'.
• 검증 방법: 예를 들어 '관련 컴포넌트 테스트, 린트, 빌드, 실제 페이지 스모크'.

이 요약을 먼저 받으면 리뷰어는 전체 파일을 읽기 전에 기대 범위를 갖게 됩니다. 요약과 diff가 맞지 않으면 그 자체가 첫 번째 리뷰 코멘트입니다.

2단계: 위험 파일을 분류한다

모든 파일을 같은 강도로 볼 필요는 없습니다. 위험 파일을 먼저 봐야 합니다. 일반적으로 다음 파일은 더 엄격하게 봅니다.

• 인증, 권한, 관리자 기능을 다루는 파일
• 데이터 쓰기, 삭제, 동기화를 수행하는 파일
• 공개 라우트, SEO, 메타데이터, 공유 이미지 파일
• 배포 설정, 환경 변수 처리, 외부 API 호출 파일
• 공통 유틸, 타입, 전역 스타일처럼 영향 범위가 넓은 파일

초보자는 이 단계를 '중요한 파일 먼저 보기'로 이해하면 됩니다. 실무자는 더 나아가 파일별 실패 모드를 적어야 합니다. 예를 들어 공개 라우트 변경이라면 내부 문구 노출, 404/500, 모바일 레이아웃 깨짐, 메타데이터 누락을 함께 봅니다.

3단계: 리뷰 패스를 나눠서 진행한다

한 번에 모든 것을 보려고 하면 중요한 문제가 섞여 보입니다. diff 리뷰는 세 번의 짧은 패스로 나누면 좋습니다.

#### 패스 A: 의도와 범위

요구사항과 무관한 변경이 있는지 봅니다. 파일 수가 많거나 이름 변경이 섞였거나 자동 포맷 변경이 대량으로 들어갔다면, 기능 변경과 정리 변경을 분리하라고 요구합니다. AI 작업은 작을수록 검증이 쉽습니다.

#### 패스 B: 동작과 예외

조건문, 데이터 변환, 비동기 처리, 빈 값 처리, 에러 처리처럼 실제 동작을 바꾸는 줄을 봅니다. 여기서는 '성공 경로'보다 '없을 때, 실패할 때, 느릴 때, 권한이 없을 때'를 먼저 묻습니다. 에이전트가 만든 코드는 정상 예시에는 강하지만 예외 조건에는 약할 수 있습니다.

#### 패스 C: 공개 품질과 운영 안전

공개 페이지라면 독자가 보는 문구, 접근성, 메타데이터, 링크, 모바일 표시를 확인합니다. 운영 도구라면 권한, 로그, 재시도, 롤백 기준을 확인합니다. 이 패스는 테스트가 잘 잡지 못하는 사용자 신뢰 문제를 잡는 데 유용합니다.

4단계: 회귀 테스트와 수동 스모크를 연결한다

리뷰 코멘트는 '이상해 보인다'에서 끝나면 안 됩니다. 발견한 위험은 검증 방법으로 연결해야 합니다.

• 조건 분기가 바뀌었다면 해당 조건을 재현하는 테스트를 추가합니다.
• 공개 문구가 바뀌었다면 금지어와 내부 경로 스캔을 추가합니다.
• 라우트가 바뀌었다면 200, 404, 리다이렉트, 메타데이터를 확인합니다.
• DB 쓰기나 동기화가 바뀌었다면 dry-run 또는 제한된 대상 검증을 먼저 봅니다.
• 배포 영향이 있다면 라이브 스모크와 롤백 기준을 함께 적습니다.

이렇게 하면 리뷰가 취향 싸움이 아니라 배포 전 검증 목록으로 바뀝니다.

상황별 예시

예시 1: UI 컴포넌트를 AI가 수정한 경우

카드 레이아웃을 고쳤다면 diff에서 먼저 스타일 변경 범위를 봅니다. 컴포넌트의 데이터 구조나 라우팅까지 바뀌었다면 이유를 요구합니다. 그다음 긴 제목, 빈 설명, 모바일 폭, 키보드 포커스, 다크/라이트 대비를 확인합니다.

좋은 리뷰 질문은 '예쁘냐'가 아니라 '긴 한국어 제목에서도 클릭 영역과 정보 우선순위가 유지되는가'입니다. 검증은 스냅샷보다 실제 렌더링 화면과 접근성 텍스트가 더 중요할 수 있습니다.

예시 2: API 호출이나 데이터 저장이 바뀐 경우

데이터 쓰기 코드는 diff 리뷰의 우선순위가 높습니다. 성공 응답만 보지 말고 중복 요청, 네트워크 실패, 부분 성공, 재시도, 권한 없는 요청을 봅니다. 로그가 추가되었다면 민감정보를 출력하지 않는지도 확인합니다.

이 경우 리뷰 코멘트는 '에러 처리 더 해주세요'처럼 모호하면 안 됩니다. '외부 호출 실패 시 사용자에게 재시도 가능 상태를 보여주고, 저장은 한 번만 일어나야 한다'처럼 기대 동작을 테스트 가능한 문장으로 써야 합니다.

예시 3: 배포 설정이나 SEO 메타데이터가 바뀐 경우

배포 설정은 작은 diff라도 크게 봐야 합니다. 빌드 명령, 캐시, 환경 변수 이름, 라우트 메타데이터는 로컬에서는 정상이어도 실제 배포에서 다르게 보일 수 있습니다. SEO 변경은 title만 보지 말고 Open Graph, Twitter 카드, canonical URL, 이미지 응답까지 확인합니다.

이때 배포 전 검증은 '빌드 성공'에서 끝나지 않습니다. 실제 URL을 열어 상태 코드, 메타 태그, 이미지 MIME 타입, 공개 금지어 노출을 확인해야 합니다.

실수와 주의점

diff를 너무 늦게 본다

작업이 끝난 뒤 전체 결과만 보면 이미 변경이 커져 있습니다. 에이전트에게 중간에 변경 요약을 요청하고, 파일 수가 늘어나는 순간 범위를 다시 확인해야 합니다.

테스트 통과를 리뷰 통과로 착각한다

테스트는 자동화된 질문에 대한 답입니다. 하지만 공개 문구, 운영 안전, 배포 위험처럼 자동화하기 어려운 질문도 있습니다. 테스트 결과와 diff 리뷰 결과를 함께 보고 배포 판단을 내려야 합니다.

포맷 변경과 기능 변경을 섞는다

AI가 포맷터를 돌리거나 주변 코드를 정리하면서 diff가 커질 수 있습니다. 기능 변경과 포맷 변경이 섞이면 리뷰어는 실제 위험 줄을 찾기 어렵습니다. 가능하면 포맷 정리는 별도 커밋으로 분리합니다.

롤백 기준을 나중에 생각한다

롤백 기준은 문제가 난 뒤 정하는 것이 아닙니다. 배포 전에 '어떤 증상이 보이면 되돌릴 것인가'를 정해야 합니다. 예를 들어 신규 상세 페이지가 500을 반환하거나 공개 페이지에 내부 문구가 보이면 즉시 롤백 후보입니다.

검증 체크리스트

AI diff 리뷰를 마치기 전에 아래 항목을 확인합니다.

• 변경 요약이 사용자 문제, 핵심 변경, 변경하지 않은 범위, 검증 방법을 포함한다.
• 위험 파일이 먼저 검토되었고 파일별 위험 이유가 설명된다.
• 요구사항과 무관한 변경은 제거되었거나 별도 작업으로 분리되었다.
• 조건 분기, 빈 값, 실패 응답, 권한, 모바일 표시 같은 예외 경로가 확인되었다.
• 회귀 테스트가 필요한 위험은 실제 테스트나 명확한 스모크 절차로 연결되었다.
• 공개 페이지 변경은 내부 문구, 민감정보, 깨진 링크, 메타데이터를 확인했다.
• 배포 전 검증 명령과 라이브 스모크 대상이 기록되었다.
• 문제가 생겼을 때 되돌릴 롤백 기준과 영향 범위를 설명할 수 있다.

다음 단계

처음부터 완벽한 리뷰 루프를 만들 필요는 없습니다. 다음 작업부터 에이전트에게 세 가지 산출물을 요구해 보세요.

1. diff 기준 변경 요약
2. 위험 파일 목록과 이유
3. 테스트와 스모크 검증 계획

이 세 가지가 있으면 AI가 만든 코드를 더 빠르게 읽을 수 있고, 리뷰 코멘트도 훨씬 구체적으로 바뀝니다. 팀에서 운영한다면 Pull Request 템플릿이나 작업 완료 보고에 같은 항목을 넣는 것이 좋습니다. 중요한 것은 AI를 믿지 않는 태도가 아니라, AI가 만든 변경을 배포 가능한 증거로 바꾸는 습관입니다.