내가 안 짠 코드를 리뷰할 때 진짜 봐야 하는 것들

• 코드 리뷰는 '내가 안 짠 코드에 참여하는 방법'에 가깝다는 게 글의 핵심임

  • 요즘은 팀원도, AI 에이전트도 코드를 빠르고 싸게 만들 수 있어서 PR이 읽는 속도보다 더 빨리 쌓임
  • 리뷰를 건너뛰면 그 코드에 관여하는 게 아니라 그냥 옆에 서 있는 사람이 된다는 표현이 꽤 정확함

• 좋은 리뷰는 diff만 훑는 게 아니라 변경의 맥락을 다시 조립하는 일임

  • 작은 버그 수정은 브라우저 diff로 충분할 수 있지만, 동작이 바뀌는 PR이면 브랜치를 체크아웃해서 실제 코드 위치, 호출자, 의존성을 같이 봐야 함
  • 티켓이나 설계 문서도 같이 읽어야 함. 코드가 내부적으로는 일관돼도, 애초에 틀린 문제를 풀고 있을 수 있음

• 리뷰의 첫 타깃은 '핵심 경로'여야 함

  • 예를 들어 모든 줄이 깔끔하고 테스트도 통과하지만, 이미 공용 클라이언트가 tenacity로 백오프 재시도를 하고 있는데 새 코드가 재시도를 또 쌓는다면 그게 진짜 문제임
  • 이런 문제는 linter가 못 잡음. diff 안의 줄만 보면 멀쩡해 보이기 때문임

• 접근 방식 다음에는 동작을 층층이 봐야 함

  • 빈 입력, 반복 호출 같은 정확성 케이스를 확인해야 함
  • 의존성이 타임아웃 나거나 큐가 같은 메시지를 두 번 전달할 때 어떻게 되는지도 봐야 함
  • 사용자 입력이 어디로 흘러가는지, 권한 검사가 실제 작업과 맞는지도 추적해야 함
  • 테스트가 내부 호출을 따라 쓴 건지, 진짜 공개 동작을 증명하는지도 따져야 함

• 리뷰 코멘트는 우선순위를 노골적으로 드러내야 함

  • 15개 코멘트를 남기면 블로커와 취향 문제가 화면에서 같은 무게로 보임
  • 병합을 막아야 하면 이유를 쓰고, 취향이나 작은 개선이면 nit:처럼 기다려도 된다는 신호를 줘야 함
  • 확신이 없으면 단정 대신 질문이 낫다. '이게 두 번 호출되면 어떻게 되나요?' 같은 질문은 작성자가 놓친 맥락을 설명할 여지를 줌

• 좋은 코멘트는 속성 이름이 아니라 결과를 설명함

  • '이건 멱등하지 않음'은 문제의 이름만 말하는 것임
  • '큐가 이 메시지를 두 번 전달할 수 있어서 고객에게 두 번 과금될 수 있음'은 왜 고쳐야 하는지 바로 보임

• AI가 만든 코드는 더 적은 선의로 봐야 한다는 주장도 나옴

  • 모델은 존재하지 않는 API도 아주 그럴듯하게 호출할 수 있음
  • 프로젝트 버전에서는 무시되는 설정 플래그도 자연스럽게 써낼 수 있음
  • 테스트가 너무 완성도 높아 보여도, 실제 요구사항이 아니라 구현의 잘못된 로직을 그대로 인코딩했을 수 있음

• AI 패치에서 특히 흔한 냄새는 과한 구조임

  • 필요 없는 캐시 계층, 구현체가 하나뿐인 인터페이스가 성숙한 시스템처럼 보이게 들어갈 수 있음
  • 이럴 땐 '어떤 측정된 문제를 캐시가 해결하나', '두 번째 구현체가 지금 필요한가'를 물어보고 답이 없으면 단순화시키는 게 맞음

• 리뷰 실력은 코멘트 개수로 늘지 않음

  • 이미 병합된 PR을 보고, 설명과 diff를 먼저 읽은 뒤 리뷰 대화와 최종 패치를 비교하면 어떤 코멘트가 실제로 중요했는지 보임
  • 다른 엔지니어에게 내 리뷰 코멘트를 봐달라고 하는 것도 유용함. 내가 놓친 이슈와 그냥 취향이었던 코멘트를 구분할 수 있기 때문임

---

기술 맥락

• 이 글에서 중요한 선택은 'diff 중심 리뷰'가 아니라 '시스템 중심 리뷰'예요. 변경된 줄만 보면 코드가 예뻐 보일 수 있지만, 이미 저장소 안에 같은 기능이 있거나 기존 설계와 충돌하는지는 전체 맥락을 봐야 알 수 있거든요.

• 특히 AI가 코드를 많이 만드는 환경에서는 리뷰어의 역할이 더 커져요. 생성 모델은 빠르게 구현을 만들지만, 존재하지 않는 API나 불필요한 캐시처럼 그럴듯한 구조도 같이 만들 수 있어서 사람이 요구사항과 실제 실행 경로를 대조해야 해요.

• 테스트도 그냥 통과 여부만 보면 부족해요. 구현 내부 호출을 그대로 따라간 테스트는 리팩터링 때 쉽게 깨지고, 사용자 관점의 동작이 틀려도 통과할 수 있거든요. 그래서 글에서는 changed path를 직접 실행하고 어색한 경로까지 눌러보라고 해요.

• 리뷰 코멘트의 우선순위를 나누는 것도 협업 비용을 줄이기 위한 선택이에요. 모든 지적을 같은 톤으로 쓰면 작성자는 무엇을 반드시 고쳐야 하는지 헷갈리고, 정작 병합을 막아야 할 설계 문제가 취향 코멘트에 묻힐 수 있어요.