에이전트 diff를 사람처럼 리뷰하려면
에이전트가 PR·패치를 빠르게 쌓아도, 머지 결정은 사람이 합니다. 에이전트 diff는 사람이 쓴 것과 같은 도구(git diff, PR Files)로 보이지만, 범위 밖 친절한 리팩터·테스트 스킵·시크릿 근접·“통과했다고만” 적힌 본문이 섞이기 쉽습니다. 그래서 사람 리뷰 체크리스트로 읽는 습관이 필요합니다.
이 글은 뭘 먼저 보나 · 테스트 없이 머지해도 되나 · 롤백 기준은 뭔가만 다룹니다. 브랜치 이름·CODEOWNERS·경로 allowlist·에이전트별 PR 쪼개기는 multi-agent-pr-workflow 축입니다. 여기서는 이미 열린 하나의 diff를 사람이 어떻게 훑는지에 초점을 둡니다. 요금·플랜·토큰 숫자는 없습니다.
뭘 먼저 보나?
한 줄 답: 파일 목록·통계부터 보고, 의도(티켓·PR 본문)와 실제 경로가 맞는지를 확인한 뒤, 위험 표면(인증·데이터·배포·시크릿·스키마) 과 테스트/문서 짝을 봅니다. 줄 단위 미학은 그 다음입니다.
에이전트 diff를 사람 PR처럼 열었을 때 권장 순서:
| 순서 | 먼저 볼 것 | 질문 |
|---|---|---|
| 1 | Files changed / git diff --stat | 파일 수·추가·삭제가 티켓 범위와 맞는가? 잠금파일·생성물·i18n 전체가 갑자기 들어왔는가? |
| 2 | PR 본문 vs diff | “한 줄 요약·비범위·재현/테스트 방법”이 실제 변경과 일치하는가? 에이전트 주장만 있고 증거 경로가 없는가? |
| 3 | 위험 경로 | auth, 결제, 권한, 마이그레이션, CI/배포, .env* / 키 파일, 공개 API 시그니처가 바뀌었는가? |
| 4 | 삭제·이동 | 큰 삭제·파일 rename이 “정리”인지 회귀인지. 호출부가 같이 갱신됐는지. |
| 5 | 테스트·픽스처 | 동작 변경에 대응 테스트가 있는가? skip/xit/assertion 완화로 통과를 만들지 않았는가? |
| 6 | 스타일·네이밍 | 위가 통과한 뒤에만. 순수 포맷-only는 별 PR이 낫습니다. |
체크리스트(복붙용):
[ ] stat: 예상 경로만? 잠금파일·생성물 폭주 없음?
[ ] 의도: PR 본문 Done/Out-of-scope와 diff 일치?
[ ] 위험: 시크릿·권한·스키마·배포 스크립트 변경 명시 검토?
[ ] 삭제/rename: 참조·import·설정 동시 갱신?
[ ] 테스트: 새/변경 동작에 짝이 있거나, 왜 없는지 한 줄 사유?
[ ] 에이전트 “셀프 리뷰” 문구만 믿고 Approve하지 않음에이전트-특유 함정 (사람 작성 diff보다 자주 보임):
- 범위 밖 “같이 고침” — 인접 파일 리네이밍, 무관한 lint 일괄 수정, 사용하지 않는 import 정리로 diff가 커짐.
- 설명과 코드 불일치 — 본문은 “버그 수정만”, 실제는 API 시그니처·기본값 변경.
- 테스트 모양만 — 존재하지만 실패 경로를 덮지 않거나, 플래키 타임아웃만 늘림.
- 도구 산출물 혼입 — 포맷터·codegen·스냅샷이 의도 없이 대량 갱신.
multi-agent-pr-workflow와의 한 줄 경계: 그 글은 누가 어느 브랜치에서 어떤 게이트로 머지할지이고, 이 절은 그 게이트 앞에서 사람이 diff를 어떤 순서로 읽는지입니다.
테스트 없이 머지?
한 줄 답: 기본은 아니오. 로컬·CI에서 합의된 최소 검증이 없거나 실패하면 머지하지 않습니다. 예외는 문서·주석·순수 설정 오타처럼 런타임 영향이 명백히 없고, 팀이 예외 라벨·사유를 PR에 남기는 경우뿐입니다. “에이전트가 돌렸다고 함”은 증거가 아닙니다.
결정표:
| 변경 유형 | 최소 검증 | 테스트 없이 머지? |
|---|---|---|
| 동작·API·스키마·권한 | 관련 단위/통합 또는 문서화된 수동 시나리오 + CI green | 아니오 |
| 버그픽스 | 재현 실패 → 패치 후 같은 명령 통과(가능하면 회귀 테스트 추가) | 아니오 (재현 증거 필요) |
| 리팩터(동작 동일 주장) | 기존 스위트 유지 + 핵심 경로 스모크 | 아니오 (스위트 없이 “동일” 주장 금지) |
| 문서·README·주석만 | 링크·오타 확인, 빌드/사이트 프리뷰(해당 시) | 조건부 예 (런타임 코드 미포함일 때) |
| CI·배포 스크립트 | dry-run·파이프라인 검증 잡 | 아니오 |
| 의존성 잠금만 | 설치·빌드·핵심 테스트 | 아니오 (공급망·브레이킹 가능) |
실무 규칙:
- 증거 경로를 PR에 고정 — 실행한 명령, CI 체크 이름, 수동 시나리오 체크리스트. 에이전트 채팅 로그 전문 복붙은 필요 없습니다.
- 빨강 CI를 초록으로 속이지 않기 — skip, 타임아웃만 상향, flaky를
@retry로만 감추기, assertion 삭제. 보이면 머지 보류 + 되돌리기 요청. - “테스트 추가가 어렵다”면 — 왜 어려운지, 대신 어떤 수동 검증을 했는지, 후속 티켓 ID를 적습니다. 빈칸이면 머지하지 않습니다.
- 에이전트 TDD 루프 글과의 경계 — 그 글은 작성 중 red→green 순서이고, 여기는 머지 직전 사람 게이트입니다. green을 에이전트가 주장해도 사람이 명령·CI를 한 번 더 확인합니다.
예외를 열어 둘 때도 라벨(예: risk:docs-only)과 롤백 한 줄(아래 절)을 같이 요구하면, “일단 머지”가 습관이 되지 않습니다.
롤백 기준은?
한 줄 답: 머지 전에 되돌릴 단위(revert 커밋 / PR revert / feature flag) 를 정해 두고, 증상·범위·시간 중 하나라도 임계를 넘으면 수정 패치보다 롤백을 먼저 합니다. 에이전트에게 “핫픽스로 더 고치라”만 반복하면 사고가 커집니다.
머지 전 롤백 설계:
| 항목 | 정해 둘 것 |
|---|---|
| 되돌림 단위 | 단일 PR revert가 안전한가? 여러 PR이 겹치면 통합 revert 담당은 누구인가? |
| 플래그 | 위험한 경로에 feature flag / config switch가 있는가? |
| 관측 | 어떤 메트릭·로그·알람이면 “실패”인가? (에러율, 5xx, 큐 적체, 데이터 불일치) |
| 소통 | 롤백 결정 채널·OWNER |
머지 후 즉시 롤백을 고르는 기준 예:
- 사용자·데이터 손상 — 잘못된 쓰기, 권한 확대, 결제·삭제 경로 이상.
- 서비스 수준 — 합의된 에러율·지연·실패 예산 초과가 이 배포와 시간적으로 맞음.
- 되돌리기보다 전방 수정이 불명 — 원인 후보가 3개 이상이거나, 에이전트 후속 패치가 diff를 더 키우기만 함.
- 마이그레이션 실패 — expand/contract 없이 깨진 스키마. (데이터 마이그레이션은 revert만으로 부족할 수 있어 백업·forward-fix 런북을 별도 확인.)
- 시크릿·자격 증명 유출 의심 — 롤백과 동시에 키 회전·로그 점검. 코드 revert만으로 끝나지 않습니다.
롤백 실행 체크:
[ ] revert/flag로 증상이 줄었는가?
[ ] main/배포 브랜치에 재발 방지 라벨·이슈가 열렸는가?
[ ] 에이전트에게 “같은 브랜치에 이어서 큰 패치”를 시키지 않았는가? (새 브랜치·최소 repro)
[ ] 사람 포스트모템 한 줄: 무엇이 리뷰에서 빠졌는가? (통계? 테스트? 위험 경로?)전방 수정(forward fix)을 택할 때: 원인이 한 줄로 좁고, 테스트가 이미 빨강을 재현하며, 변경 면적이 원래 PR보다 작을 때입니다. 그렇지 않으면 롤백이 기본값입니다.
FAQ
multi-agent-pr-workflow 글과 무엇이 다른가요?
그 글은 에이전트별 브랜치·사람 Approve 게이트·경로 충돌 예방입니다. 이 글은 게이트에 올라온 diff를 사람이 어떤 순서로·어떤 기준으로 읽을지의 체크리스트입니다.
에이전트 셀프 리뷰·리뷰 봇 Approve만으로 충분한가요?
충분하지 않습니다. 요약·누락 지적은 도움이 되지만, 의도·비밀·데이터·롤백은 사람(또는 CODEOWNERS) 책임으로 두는 편이 안전합니다.
로컬만 초록이고 CI가 없으면?
머지 전에 팀이 동의한 최소 명령을 PR에 적고 결과(통과/실패)를 남깁니다. CI가 없다면 그 공백 자체가 위험 신호이므로, 동작 변경 PR은 더 보수적으로 봅니다.
큰 포맷터 diff와 논리 변경이 섞이면?
리뷰 비용이 급증합니다. 포맷/생성물과 논리 변경을 PR에서 분리하라고 되돌리거나, 논리 파일만 먼저 리뷰하고 포맷은 후속 PR로 미룹니다.
출처 (Sources)
- 팀 관행: PR Files /
git diff --stat우선, 위험 경로·테스트 증거·revert 가능성 — 본문 체크리스트 - 인접 글 축: multi-agent-pr-workflow(브랜치·게이트), agent-tdd-loop(작성 중 red→green), git-worktree-agent(워킹트리 격리)