LLM Wiki

AI 코딩 시대의 코드 리뷰 실무 가이드 — diff에서 의도·증거 검증으로

Properties3
description볼트의 코드 리뷰 관련 노트를 종합해 AI 시대 코드 리뷰의 원칙, 단계별 실무 절차, 역할별 체크리스트와 도입 로드맵으로 정리한 가이드다.
tagsai-coding, ai-agents, dev-tools, harness, automation
aliasesAI 시대 코드 리뷰 가이드, 코드 리뷰 실무 가이드, Review intent not diffs 실전편

13 min read

이 노트는 2026-08-22-code-review-intent-verification(Ankit Jain 강연)을 출발점으로, 볼트 안에서 코드 리뷰를 다룬 노트들을 종합해 “그래서 내일 아침부터 뭘 어떻게 해야 하는가” 에 답하는 실무 가이드다. 강연자는 검증 제품 판매자이고(발표자 이해관계 참조), 리뷰 제거를 시도했다가 되돌린 사례(2026-07-27-agentos-why-software-factories-fail)도 있으므로, 어디까지가 검증된 원칙이고 어디까지가 제안인지 구분하며 쓴다.

질문

  • AI가 코드 대부분을 쓰는 팀에서 코드 리뷰는 무엇을 보고 누가 담당해야 하는가?
  • diff 리뷰가 깨진 상태에서 사람 리뷰어의 시간은 어디에 쓰는 것이 맞는가?
  • 자동화와 인간 판단의 경계는 어떻게 그리고 언제 옮기는가?

한 문장 결론

리뷰는 사라지지 않고 재분배된다 — 반복 가능한 검사는 시스템으로 밀어내고, 사람은 의도·아키텍처·검증 증거의 판정자로 이동한다. 단, 검증 루프가 증거로 안정화됐다고 입증되기 전에는 인간 리뷰를 지우지 않는다.

설계 원칙 5가지

  1. 리뷰를 두 반쪽으로 쪼갠다. 버그·보안·컨벤션·불변식 같은 반복 가능한 의미 정확성과, 아키텍처·멘토링·지식 공유 같은 *정렬(alignment)*은 성격이 다르므로 담당 주체(시스템/사람)도 달라야 한다 (2026-08-22-code-review-intent-verification).
  2. 작성자와 검증자를 분리한다. 구현 에이전트가 자기 출력을 판정하게 하지 않는다. 구현 에이전트 ≠ 테스트 계획 에이전트 ≠ 최종 리뷰어라는 분리가 최소 조건이다 (loop-engineering, 2026-08-22-code-review-intent-verification).
  3. 리뷰 표면을 diff에서 ‘의도 + 증거’로 바꾼다. 세션에서 캡처한 결정(인수 조건)과 실행 결과(pass/fail, 스크린샷, 로그)가 새 리뷰 대상이다 (2026-08-22-code-review-intent-verification).
  4. 병렬성보다 리뷰 대역폭을 먼저 본다. 에이전트를 늘리는 건 싸졌지만 승인할 양은 늘지 않았다. 96%가 AI 코드를 불신하는데 항상 검증하는 사람은 48%라는 통계가 이 격차를 찍는다 (loop-engineering, 2026-08-03-agentos-own-the-outer-loop).
  5. 결정론 우선, LLM 보조, 사람 최종. “Deterministic where you can. LLM where you must.” 재현 가능한 검사는 결정론적으로 하고, 모호한 행동 판단만 LLM judge에 맡기되 최종 판정 기록(judge of record)은 만들지 않는다.

단계별 실무 절차

0단계 (주 1회, 월 1회) — 기반 축적: 리뷰 코멘트를 규칙으로 바꾸기

  • 지난 100~1,000개 리뷰 코멘트를 모아 반복 지점(예: 금액 필드에 float 사용, print 로깅, 하드코딩된 secret, user_* 테이블 직접 쿼리)과 매번 새 판단이 필요한 논점(아키텍처 선택, 트레이드오프)을 분리한다.
  • 반복 지점을 불변식·가드레일 목록(AI Slop Register)으로 등록한다. linter 규칙, CI assertion, 커스텀 스캐너 중 가장 결정론적인 형태로 구현한다 (2026-08-22-code-review-intent-verification).
  • 과거 리뷰 코멘트를 AGENTS.md·스킬로 증류해 리뷰 전에 에이전트가 지키게 만든다 — 리뷰에서 걸러내는 것보다 생성 단계에서 막는 게 싸다 (2026-07-19-human-in-the-loop-fatigue, 2026-07-08-claude-code-getting-started-with-loops).
  • 참고 구현: 정적 규칙 + LLM 에이전트 하이브리드 구조는 2026-07-26-alibaba-open-code-review가 오픈소스로 존재한다.

1단계 (작업 시작 전) — 정렬 리뷰가 곧 최고의 리뷰다

  • PR이 열리기 전에 방향을 맞추는 것이 리뷰 비용을 가장 크게 줄인다. 계획·정렬에 투자하면 코드 리뷰·코딩이 동시에 짧아진다는 것이 리뷰 제거 실험의 결론이었다 (2026-07-27-agentos-why-software-factories-fail).
  • 실무 형태: 구현 전에 에이전트에게 계획서(접근 방식, 영향 파일, 거절한 대안)를 제출받고 사람이 이것만 승인한다. diff 리뷰에서 “방향이 잘못됐다”를 발견하는 것은 가장 비싼 발견 위치다.

2단계 (세션 중) — 결정을 버리지 않고 캡처한다

  • 프롬프트와 세션 안의 왕복(“기존 RateLimiter 유틸을 쓴다”, “/api/v2 인증은 미들웨어가 처리하므로 생략”, “금액은 Money 타입”)이 진짜 의도가 살아 있는 곳이다. PR 생성 시 세션이 버려지면 리뷰어는 코드에서 의도를 역추론해야 한다.
  • 실무 형태: 세션 로그를 PR에 연결하거나, 세션의 결정을 인수 조건 목록으로 변환해 PR 본문에 붙인다. 도구 없이도 PR 템플릿에 “세션에서 내린 결정” 섹션을 넣는 것부터 시작할 수 있다.

3단계 (PR 전) — 자동 검증 루프를 먼저 돌린다

  • 인수 조건 + 불변식 목록 → 테스트 계획(LLM이 초안 생성, 사람이 검토) → preview 환경 실행 → pass/fail과 증거(스크린샷, 로그, 상태 코드) 남기기.
  • 결정론적 검사(스캔, assertion, 재현 스크립트)가 가능한 항목은 전부 결정론으로. UI 동작처럼 모호한 것만 런타임+LLM 판정.
  • loop-engineering의 원칙 적용: 정지 조건(통과/실패/비용 한도)을 먼저 쓰고, 루프가 못 푼 것은 조용히 재시도하지 말고 증거를 갖춘 decision-ready 상태로 사람에게 넘긴다.

4단계 (인간 리뷰) — diff 대신 네 가지를 본다

리뷰어 체크리스트:

  1. 의도: 이 PR이 만들려 한 것이 계획·인수 조건과 일치하는가? (세션 캡처와 대조)
  2. 구조: 아키텍처 수준의 선택(경계, 의존성, 추상화)이 팀의 방향과 맞는가?
  3. 증거: 테스트 계획이 실제로 요구한 행동을 검사하는가? 실패한 항목의 처리가 타당한가?
  4. 독립성: 검증 경로가 작성 에이전트와 독립적이었는가? (같은 에이전트가 만들고 판정했으면 결함 상관이 높다)

diff를 읽지 말라는 것이 아니라, 읽는 순위가 바뀐다: 증거·계획 먼저, diff는 의심 표시가 있는 부분(테스트 계획이 못 덮는 영역, 실패 항목 주변)을 표본적으로 확인하는 용도.

5단계 (머지 후) — 회귀를 다시 규칙으로

  • 운영 incident, 머지 후 발견된 결함은 0단계의 레지스터로 되돌려 등록한다. 리뷰 경험이 검사 규칙으로 복리로 쌓이는 것이 이 체계의 핵심 수익 구조다.

역할별 요약

역할하는 일하지 않는 일
작성자(사람+에이전트)계획 승인 받기, 세션 결정 캡처, 인수 조건 명시, 자동 검증 통과리뷰어 시간 낭비할 저품질 diff 올리기
자동 검증불변식·회귀·보안 검사, preview 실행, 증거 생성모호한 행동의 최종 판정
인간 리뷰어의도·구조·증거·독립성 판정, 멘토링, 아키텍처 논의모든 줄 읽기, 반복 지점 다시 쓰기
팀 (주기적)레지스터 갱신, AGENTS.md 증류, 검증 루프 신뢰도 평가—

도입 로드맵 (규모별)

  • 개인: 오늘 할 수 있는 것 — PR 템플릿에 “세션 결정” 섹션 추가, 최근 받은 리뷰 코멘트 20개를 규칙 후보로 분류, 구현 전 계획 승인 습관화.
  • 소규모 팀(2~10명): 0단계 레지스터를 저장소 문서로 운영, CI에 결정론 검사 연결, 인간 리뷰 범위를 “증거 + 구조”로 명문화. 리뷰 없는 merge 비율을 지표로 추적.
  • 조직: 세션→인수 조건 파이프라인 도구화(MCP 등), preview 환경 표준화, 팀별 레지스터 공유. 이 단계부터 비로소 “사람이 읽는 양 줄이기”를 검증된 데이터 위에서 논의한다.

안티패턴 (하면 안 되는 것)

  • 1일 차에 리뷰 삭제 — “Build the register. Don’t kill review on day one.” 리뷰 제거를 먼저 한 팀은 결국 PR에서 전부 다시 읽게 됐다 (2026-07-27-agentos-why-software-factories-fail).
  • AI가 리뷰했으니 괜찮다는 믿음으로 대충 merge — “AI가 리뷰하고 아무도 안 읽는다면 잘못 설정한 것이다.”
  • 불신하면서도 검증보다 빠르게 배포 — 위험은 불신이 아니라 불신과 배포 사이의 간극이다 (2026-08-03-agentos-own-the-outer-loop).
  • 구현 에이전트의 자기 승인 — 작성자=판정자 구조는 낙관 편향을 시스템화한다 (loop-engineering).
  • LLM judge를 최종 판정 기록으로 사용 — 재현 불가능한 판정은 감사·디버깅이 안 된다.
  • 세션 폐기 — 의도가 담긴 프롬프트·결정을 PR 후 버리면 리뷰어는 영원히 역추론을 반복한다.

근거 노트

백링크