PR의 효능(feat.AI 코드리뷰)

이현성·2026년 7월 3일
post-thumbnail

최근 부트캠프 프로젝트에서 거의 처음 제대로 된 코드 리뷰를 진행했다!

처음 경험은 회사에서 약 한달간 진행한 PR이었는데, 이땐 팀원과 팀장님도 처음이기도 해서 PR 시간 내기 힘들기도 했고, 간단한 댓글들이 주를 이뤘었다.

그래서 이번 경험이 더욱 의미 있었다.

이번엔 글을 쓰면서 느낀 점들을 써볼까 한다~

[리뷰이] PR 준비

코드 리뷰를 달면서 느낀 것 중 하나는 가독성의 중요성이다.

코드의 가독성

그중 첫번째는 코드 자체의 가독성이다.
그걸 위해 기본적인 함수나 컴포넌트를 최소 단위로, 재사용성 있게 분리하기 위해 노력했다.

주석

두번째는 주석이다.
함수에는 JSDoc으로 주석을 달았다.

/**
 * 스캔된 문자열을 QR 처리 대상 URL로 변환합니다.
 *
 * 일반 문자열이 브라우저 기준 상대 경로로 변환되는 것을 막기 위해
 * 절대 URL 또는 /로 시작하는 앱 내부 경로만 URL로 인정합니다.
 *
 * @param value - QR 코드에서 읽은 원본 문자열
 * @returns QR 처리 대상으로 볼 수 있는 URL이면 URL 객체, 아니면 null
 */
const toQrUrl = (value: string) => {
  try {
    if (value.startsWith("/")) {
      return new URL(value, getCurrentOrigin());
    }

    return new URL(value);
  } catch {
    return null;
  }
};

연계되는 코드가 있다면 1, 2, 3과 같은 단계별 주석을 표시했다.
객체 안에 여러 값이 있을 때, 어떤 값인지 이해할 수 있게 각 항목 옆에 표시하기도 했다.

const AUTO_SCROLL_TEXT_ANIMATION = {
  initialDelayMs: 500, // hover 후 스크롤 애니메이션을 시작하기 전 대기 시간
  endPauseMs: 500, // 텍스트가 끝까지 이동한 뒤 유지되는 시간
  startPauseMs: 500, // 처음 위치로 돌아온 뒤 다음 이동 전 대기 시간
  speedPxPerSecond: 30, // 텍스트가 1초 동안 이동하는 픽셀 거리
} as const;

커밋 단위

셋째로 최대한 커밋을 잘게 쪼개려고 했다.
코드를 보는데, 하나의 PR 안에서 한두 개의 커밋을 보는 것보다 여러 개의 커밋을 보는 게 읽기도 좋고 작성자의 의도도 더 잘 느낄 수 있었다. 이건 사실 맞는 건지 잘 모르겠다. 하나의 PR 아래 여러 개의 커밋이 있어도 되는지.
나는 개인적으로 만들 기능이 있으면 그 기능에서 나온 여러 단계를 커밋으로 쪼개곤 했는데.
이것도 숙달이 잘 안돼서 간혹 한 번에 모든 변경을 해버리는 경우도 있었는데, 이 경우엔 늦게나마 코드를 쪼개서 작동 가능한 수준으로 나누어 커밋했다.

[리뷰이] PR 작성

PR 작성에도 엄청 많은 시간을 들였다. 코드 작성에 최대한 AI를 지양하려고 했으나 어느 정도 쓴 부분도 있었는데, 이전 같으면 작동에 문제 없는지, 에러 처리가 잘 되어 있는지, 코드 전반적으로 스윽 보고 끝냈다.
그런데 PR을 작성하면서 훨씬 더 막중한 책임감을 느끼기도 했다. 본문을 작성할 때도 AI로 딸깍 할 수 있지만 결국 질문이 들어오면 내가 제대로 이해해야 좋은 답변을 낼 수 있다. 또 AI로 작성하면 적어도 개인적으로는 가독성이 안 좋게 느껴지기도 하고.

그리고 PR 본문의 길이에 대해.. 나는 길게 다는 것도 좋아했다. 물론 그냥 무의미하게 분량을 늘리고 사소한 내용들을 다 넣는 그런 본문이 아니라, 내 작업 내용을 본문만으로도 어느 정도 이해되게 요약하면서 시행착오나 내 생각의 흐름 등을 넣으려고 했다.
이렇게 적으면 리뷰어도 표면적인 코드 변경보다 깊숙히 의도를 이해하고, 질문의 퀄리티도 올라갈 수 있지 않나 싶다!

[리뷰어] 코드 리뷰

코드 리뷰는 첨엔 깃헙에서 확인했는데, 봐도 잘 이해가 안돼서 vscode에서 해당 pr의 브랜치로 이동해서 보니 보기 편했다. 나중에 알았는데 원래 이렇게 하는 것 같다..
직접 브랜치를 열어서 실행해서 확인하면 디버깅하기도 좋고 커밋 단위로 코드 보기도 좋았다.

vercel preview url

또 vercel을 초기에 연결해놨는데, 이 vercel 기능 중에 pr 올리면 preview url도 제공해서 배포 환경과 비슷한 환경에서 확인하기도 좋았고.
특히 이 preview url이 되게 좋았던 게, 핸드폰으로 테스트할 일이 많았는데 QR을 핸드폰으로 스캔하면 url은 localhost:3000이라 확인이 안 되는 문제가 있었다.
집이었다면 ip로 접속하면 끝이지만 위워크에서 인터넷 접속하는 거였고, 잘은 모르지만 위워크 와이파이가 뭔가 보안 때문에 ip로 접속하는 게 잘 되지 않았다.
이렇게 테스트 용도로라도 vercel 연결해놓는게 좋았다.

리뷰 방법

두 가지로 나눠서 확인했다. 화면 상에서, 코드 상에서.

  • 화면 상인 건 UI에 문제는 없는지, 이것저것 테스트해봤을 때 버그는 없는지 등을 확인하는 작업이었다.
  • 코드 상인 건 로직이 자연스러운지, 구조에 어색함이 없는지, 필요 없는 코드는 없는지, 컨벤션이 맞는지 등을 확인했다.

화면 상에서 확인하는 건 익숙하고 어렵지 않으니 이 내용으로 가장 많이 댓글을 달았다.
그리고 코드 상에서 리뷰도.. 많이 달고 싶었는데 너무 힘들었다..
기껏 다는 게 필요 없는 코드가 있거나 컨벤션 등 바로 눈에 띄는 내용만을 달 수 있었고 구조적인 문제는 전혀 눈에 안 띄었다 ㅠ
뭔가 문제가 있는 코드가 아니다 보니까 그냥 코드를 읽으면서 그렇구나 그렇구나 하기만 하고..
그래서 다른 사람들이 다는게 너무 멋있었다.

댓글 퀄리티

다른 사람들의 댓글을 보니 순수하게 궁금한 점도 물어보는 질문이 있었다.
개인적으로 그런 가벼운 질문은 내가 한다고 생각했을 때 최대한 찾아보고, AI로도 찾아보다가 정말 이해가 안 될 때 그 흐름을 물어봤다.
그래서 나는 가볍게 물어보는 질문은 지양하려고 했는데, 막상 받아보니 오히려 내가 한번 더 생각하고 찾아보는 경우가 많았다;
생각해보니 그 정도로 가벼운 질문이라면 답변자도 바로 답변을 달면 그만이고, 나처럼 완전히 이해를 못 하고 있는 경우라면 한 번 더 찾아보고 이해하는 과정도 거칠 수 있어서 도움이 될 수 있어 보였다. 사실 바로 답변하는 게 맞지..

칭찬

리뷰를 하다 보니 문제점이 있는지만을 찾곤 했다. 내가 찾을 수 없는 문제점을 도움받아 개선하는 게 코드 리뷰니까.
그런데 작성을 하다 보니 뭐랄까.. 너무 헐뜯기만을 위해 코드 리뷰를 하고 있는 게 아닌가 하는 생각이 들었다. 실제로 헐뜯으면서 댓글을 달진 않았지만;
그래서 그 뒤로 뭔가 칭찬할 것도 찾으려고 노력했다. 기왕이면 어떤 방식으로 해서 좋은건지 구체적으로 칭찬하려고 했다.
이렇게 하니 코드 리뷰 분위기도 왠지 좋아진 것 같고, 그렇게 찾은 좋은 코드로 배울 점도 있었다.
또 문제점을 얘기할 때도 좋은 점을 먼저 얘기하면서 문제점을 얘기하니 좋기도 했다.

[리뷰이] 댓글을 받고

수정 사항이 생기면 PR을 취소하고 다시 올리는 게 아니라, 그 상태에서 push를 하면 pr에 추가로 반영된다.
그리고 완료된 이슈의 댓글은 resolve conversation으로 닫는다. 간혹 접힌 댓글이 있어서 뭐지 싶었는데 이렇게 완료된 댓글을 닫는 거였다ㅎ; 이렇게 하면 이미 완료된 댓글을 접어서 불필요하게 볼 필요가 없다.

아티클

https://news.hada.io/topic?id=31067

코드 리뷰의 주된 목적은 유지보수하기 어려운 코드를 찾는 것

코드 리뷰는 버그를 잡아내거나 무결성을 보장하는 절차보다, 나중에 유지보수하기 어려운 코드를 미리 드러내는 과정에 가까움
리뷰어가 코드를 읽어도 이해하기 어렵다면, 같은 문제를 미래의 유지보수자도 겪을 가능성이 높음
수정은 원 작성자가 맥락을 기억하고 있는 지금 하는 편이 낫고, 코드 검사만으로 버그를 안정적으로 찾겠다는 기대는 현실적이지 않음
“버그를 찾아라”보다 “이해해 보고, 이해 안 되는 부분을 표시하라”가 리뷰어에게 더 실행 가능한 과제임
좋은 리뷰는 모든 것을 완벽히 증명하는 일이 아니라, 이해되지 않는 지점에 메모를 남기고 개선을 요구하는 데서 시작함

코드 리뷰의 초점 바꾸기

코드 리뷰의 핵심 목적은 리뷰어가 버그를 찾는 것이 아니며, 코드에 버그가 없다고 보증하는 것도 아님
코드만 훑어 일반적으로 버그를 찾아낼 수 있다는 기대는 실무적으로 약함
그래서 리뷰의 중심은 “맞는 코드인가”보다 “다른 사람이 나중에 읽고 고칠 수 있는가”에 놓임

이해하기 어려운 코드는 유지보수 위험 신호

리뷰어는 코드가 무엇을 하고, 어떻게 동작하는지 이해하려고 읽음
이해되지 않는 부분은 미래의 유지보수자가 막힐 가능성이 있는 위험 신호가 됨
이런 코드는 원 작성자가 아직 맥락을 기억하고 있을 때 바로 고치는 편이 낫음

버그 찾기보다 실행 가능한 리뷰 과제

“이 코드에서 버그를 찾아보라”는 요청은 성공 여부를 판단하기 어려운 작업임
버그를 몇 개 찾아도 더 숨어 있는 버그를 놓쳤을 수 있어, 리뷰어 입장에서는 실패만 명확해지기 쉬움
반대로 “이 코드를 이해해 보고, 이해할 수 없으면 지적하라”는 요청은 기준이 더 분명함
모든 것을 완벽히 이해할 필요는 없음
이해하지 못한 부분을 기록하면 됨
전체를 이해하려고 시도하고, 막힌 지점에 메모를 남기면 리뷰의 역할을 수행한 것임

실무에서의 리뷰 기준

리뷰어가 이해하지 못한 코드는 그 자체로 수정 대상이 될 수 있음
리뷰 코멘트는 버그 보고뿐 아니라 설명 부족, 구조 문제, 읽기 어려운 흐름을 드러내는 역할을 함
이 기준에서는 코드의 정당성을 증명하는 일보다, 이후 팀원이 읽고 다룰 수 있는 상태로 만드는 일이 중요함

버그 발견은 부수 효과

코드 리뷰가 버그를 전혀 찾지 못한다는 뜻은 아님
버그는 리뷰 중 발견될 수 있지만, 모든 버그나 대부분의 버그를 찾는 방법으로 기대하기는 어려움
더 현실적인 성공 조건은 이해 가능성을 점검하고, 유지보수하기 어려운 부분을 원 작성자와 함께 바로 개선하는 것임

이런 내용이 있어서 한번 생각해볼까 싶어 가져왔다.

특히 이 부분이 인상 깊었다.

“버그를 찾아라”보다 “이해해 보고, 이해 안 되는 부분을 표시하라”가 리뷰어에게 더 실행 가능한 과제임
좋은 리뷰는 모든 것을 완벽히 증명하는 일이 아니라, 이해되지 않는 지점에 메모를 남기고 개선을 요구하는 데서 시작함

이 내용을 보고 생각났는데, 예전에 이 부분이 이해가 안 된다는 질문을 받은 적이 있다. 뭐랄까 신기한 관점이다. 고치는 게 중요하다고 생각했는데 팀원의 이해를 중점으로 생각해야 한다니. 물론 그걸 생각 안 한다는 건 아니지만..

그 밑의 코드 리뷰의 초점 바꾸기도 인상 깊었다. 그래 코드를 완전히 파악하기엔 시간도 많이 걸리고, 버그를 찾는 것도 전문적으로 오랫동안 QA를 하는 게 아니면 그 시점에 찾는 건 한계가 있고.
저 말대로 나중에 읽고 고칠 수 있는가가 중요한 것 같기도 하다. 실제로 누군가가 작성한 코드를 다른 사람이 손대는 일이 있었는데, 같은 프로젝트를 하고 있음에도 불구하고 꽤 오랜 시간이 걸렸다.

나는 내가 이해를 잘 못하는 게 내가 부족해서라고 생각했는데, 실제로 그러기도 하겠지만 그런 이유로 작성자의 코드를 분석하는 데 시간을 많이 썼다.
그런데 이게 좋은 코드가 아닐 수도 있고, 막히면 질문을 해도 되는구나 싶었다.

아 이런 견해가 맞나 싶다. 실제로 코드 리뷰가 있는 회사에서 경험해본 것이 아니어서..

AI 코드 리뷰

우리 팀은 이번 프로젝트에 AI 코드 리뷰 툴을 넣지 않았는데, 다른 팀을 보니 gemini 코드 리뷰 도구나 코드 래빗을 적용한 걸 볼 수 있었다.

지켜보면서 장단점을 느낄 수 있었는데,
장점은 코드의 품질을 끌어올릴 수 있다. 그리고 대체로 댓글에서 볼 수 없던, AI로 알 수 있는 피드백을 받을 수 있다.
그리고 보면서 신기했던 게, 그렇게 AI에게 댓글을 받으면 그 리뷰에 대해 수정 완료한 커밋의 링크를 달면 AI가 그 댓글을 보고 조치 완료를 파악하여 댓글을 닫는다. 사실 닫는지는 정확히 모르겠고ㅎ;

단점은 AI 코드 리뷰에 의존도가 올라가는 것 같다. 그리고 받은 리뷰에 대해 수동적으로 대처하게 된다. 대체로 AI의 지적은 정확한 편이라고 느꼈기 때문이다.
그런데 팀원의 리뷰는 맞을 수도 있고, 아닐 수도 있다. 이 점을 이해하고 질문의 내용을 의심하고 점검하면서 판단력도 올라간다.
그리고 코드 리뷰를 하는 건 결국 내가 작성한 코드를 팀원에게 보여주고 설득을 받는 과정이다(아마..) 그래서 AI와 코드 리뷰를 하더라도 그 수정 사항까지 팀원의 이해를 받아야 한다.

그래서..

생각해본 건 PR 이전에 한 번 AI 코드 리뷰를 받는 게 어떨까 하는 생각이 들었다. 마치 lint나 build를 한 번 돌리는 것처럼.
그러면 팀원들은 굳이 볼 필요 없는 AI 코드 리뷰 사항에 대한 내용도 안 볼 수 있고, 좀 더 퀄리티 있는 코드를 초기에 바로 확인할 수 있다. 역할을 좀 더 분리하자는 거다.

일반적으로 사용하던 codex나 claude code를 사용할 수도 있겠지만, 찾아보니 역시 이미 있더라;
CodeRabbit CLI를 사용하면 스테이지(Staged) 및 언스테이지(Unstaged) 상태의 코드 분석 및 리뷰를 받을 수 있다고 한다. 가격도 무료고, 코드 리뷰 특화된 AI이기도 하고.

그래서 이 다음에 이 CodeRabbit CLI를 적용해보는 글을 쓰려고 한다. 어떤 곳에 넣을지, 어떻게 리뷰하고 완료 처리할지 고민해봐야지.

profile
이현성
이전 포스트

왜 생성형 AI의 대부분은 채팅 형태일까

0개의 댓글