리뷰는 버릇이다: 코드 리뷰 문화 되살리기

우리 코드 리뷰, 잘 되고 있을까?

코드 리뷰를 하기 싫어서 하지 않는 개발팀이 있을까요? 수많은 개발팀이 채용 공고에서 우리는 코드 리뷰 문화가 있다고 내세웁니다. 그렇지만 하루하루 빠르게 제품이 변화하는 회사에 있다보면 여러 이유로 코드 리뷰의 우선순위가 뒤로 밀려버릴 때가 많습니다. 그렇게 한 번 두 번 리뷰를 하지 않다 보면 어느새 리뷰되지 않는 코드가 더 많아지는 날이 찾아옵니다.

코멘토 프론트엔드팀 역시 비슷한 문제를 겪고 있었습니다. 리뷰가 줄어든다는 문제는 인식하고 있었고 한 번씩 다시 되살리기 위해 논의했지만 쉽게 해결되지는 않았었는데요. 이번에는 반드시 코드 리뷰 문화를 다시 자리 잡게 해보자는 생각으로 프로젝트를 시작했고, 이제는 자연스럽게 코드 리뷰를 하는 팀이 되었다고 생각해서 과정을 공유해보려고 합니다.

욕심 부리지 않기

우선, 다같이 모여서 코드 리뷰 이야기를 했습니다. 모두가 최근에 코드 리뷰가 제대로 되고 있지 않다는 아쉬움을 가지고 있었고 다시 제대로 하면 좋겠다는 의견을 공유하고 있었습니다. 그동안 어떤 이유 때문에 코드 리뷰가 어려웠고 그런 어려움을 어떻게 극복할 수 있을까 같이 고민해봤습니다. 이야기하다보니 개발자답게 새로운 도구와 자동화 이야기도 자연스럽게 나왔는데요. 정말 매력적인 유혹이지만 일단은 접어두고 우리가 이미 쓰고 있는 기술과 도구 안에서 바로 행동할 수 있는 방안만 뽑아보기로 했습니다.

개발자가 코드 리뷰를 요청할 때는 사내 게시판에 Pull Request 링크를 올리기로 했고 리뷰는 GitHub가 PR에서 제공하는 리뷰 기능을 사용해서 코멘트를 남겼습니다. 리뷰를 완료했다는 표시는 글에 좋아요나 댓글을 남겨서 표시했고요. 처음에는 이걸로 충분할까하는 걱정을 많이 했는데 의외로 큰 불편함 없이 리뷰할 수 있었습니다. 리뷰 시스템이 어느 정도 자리 잡은 지금도 이 구조에서 크게 달라짐 없이 운영하고 있습니다.

이 선택이 가장 중요했다고 생각합니다. 새로운 도구와 시스템에 또 시간을 쓰다 보면 코드 리뷰는 뒤로 밀려버렸을 수 있을 것 같아요. 일단 리뷰부터 해보자는 생각으로 시작했기 때문에 자연스럽게 아래에서 설명할 체계도 자리잡을 수 있었습니다.

작은 팀이니까 모두 같이 해보자

리뷰에 몇 명이 참여해야 하는지도 고민이었습니다. 리뷰 논의를 하면서 팀이 걱정한 점은 ‘내가 이 업무를 잘 몰라서 리뷰를 제대로 못해줄 것 같다’와 ‘리뷰 때문에 배포가 밀릴 것 같다’였거든요. 리뷰를 해야 하는 사람이 늘면 이런 문제가 더 커지지 않을까하는 걱정이 있었습니다.

결론부터 이야기하면, 그럼에도 저희는 팀원 모두가 리뷰를 하는 것으로 결정했습니다.

첫 번째 이유는 리뷰 문화를 자리 잡게 하는 단계이기 때문에 모두가 참여하는게 맞다는 것이었습니다. 처음부터 이런저런 이유로 리뷰를 하지 않게 되면 문화로 자리잡기 어렵다고 생각했습니다.

중간에 몇 번 필수 인원을 바꿔보았지만 결국은 다시 전원 리뷰 참여로 바뀌었는데요. 팀 인원이 5명으로 많지 않기 때문에 전원이 참여해도 무리없었고 팀이 다같이 참여하면서 서로의 리뷰를 보면서 지식을 공유하는 장점이 컸기 때문입니다.

리뷰를 위한 마인드셋 장착하기

그렇다면 위에서 이야기한 우려되는 점은 어떻게 해결했을까요?

무조건 모두가 코드 리뷰를 하자! 하고 결정한 이후, 저희는 매주 한 주간의 코드 리뷰를 회고하는 모임을 가졌습니다. 한 주간 아쉬웠던 점이나 제대로 실행되지 않은 점을 논의하고 다음 주에 새롭게 해볼 행동을 결정하는 시간이었습니다.

이 시간에 저희는 코드 리뷰 스터디도 진행했습니다. 어떻게 하면 더 좋은 코드 리뷰를 할 수 있을지 조사해서 공유하는 시간이었습니다. 다른 회사에서 어떻게 코드 리뷰를 하는지 알아보기도 하고, 코드 리뷰를 위한 코멘트 템플릿을 알아보고, 언제 코드 리뷰를 하면 좋은지도 공유했습니다. (스터디 자료 중 ‘코드 리뷰 시간 만들기’를 공유합니다)

처음에는 코드 리뷰를 어떻게 하는지, 어떤 문제를 찾아봐야 하는지, 어떤 절차를 따르는지 등 코드 리뷰 시스템을 좀 더 튼튼하게 할 수 있는 지식을 기대한 스터디였는데요. 스터디를 하면서 여러 사람의 의견과 회사의 사례를 살펴보다보니 코드 리뷰를 잘하는 팀이라고 특별한 도구가 있거나 자동으로 리뷰해주는 시스템이 있는 것은 아니라는 것을 깨달았습니다. 정말 중요한 것은 코드 리뷰를 받아들이는 팀의 마인드셋이었습니다. 이 스터디를 바탕으로 저희는 아래의 규칙과 마인드셋을 기반으로 코드 리뷰를 진행하고 있습니다.

빠르게 리뷰해주기

팀의 코드 리뷰 규칙 중 하나는 무조건 업무일 기준 1일 이내 리뷰하기입니다. 배포가 리뷰 때문에 늦어질 수 있다는 걱정도 논의 중에 나왔고 실제로 리뷰가 늘어지면서 PR이 정체된 경험도 있고 여러 회사에서 빠른 시일 내에 하는 것이 좋다는 규칙이 있어서 이번에 리뷰 규칙을 정할 때도 1일 규칙을 정했었습니다. 하지만 도입 초반에는 규칙대로 되지 않는 경우가 종종 있었는데요. 스터디를 하면서 굉장히 감명 깊은 문구를 발견했습니다.

리뷰를 요청한 개발자는 고객과 만나는 문 앞 한 발자국에서 기다리고 있다.

이런 글을 공유하며 끊임없이 강조한 끝에 지금은 아래에서 설명할 리마인드 규칙을 포함해 잘 지켜지는 규칙이 되었습니다.

리뷰가 장애물이 되지 않게 하기

또 하나는, 리뷰와 배포를 별개로 가져간다는 규칙입니다. 배포 전에 리뷰를 통과해야한다는 규칙이 있으면 리뷰를 해주는 사람도, 리뷰를 받는 사람도 서로 시간에 쫓길 수 있는데요. 이 규칙은 안정성을 조금 희생하는 규칙이지만, 팀원을 믿고 이 규칙을 만들었습니다. 대신, 배포가 이미 된 코드도 리뷰를 진행하고, 리뷰를 받은 사람은 후속 작업으로 리뷰를 반영한 작업을 진행합니다.

코드 리뷰에서 볼 것은 ‘코드’다

서로의 업무를 몰라서 리뷰가 어렵다는 점도 리뷰 접근법을 바꾸면서 해결하고 있습니다. 요구사항에 맞는 동작, UI 구성, 흐름 처리는 작업한 팀원을 믿고, 리뷰어는 말그대로 코드에 집중하는 리뷰를 하기로 했습니다. 명백한 오류 가능성이 있는 코드 찾기, 이해가 어려운 코드 개선 요청하기, 컨벤션에 맞지 않는 코드 작성 찾기, 더 나은 방법 제시하기 등 더 좋은 코드가 우리 팀의 결과물에 쌓일 수 있는 리뷰를 하는 방향으로 나아가기로 했습니다.

이런 마인드셋으로 리뷰를 하다보니 몰라서 리뷰를 하지 못하겠다는 생각은 들지 않았습니다. 다른 사람의 리뷰를 읽는 것으로 더 좋은 코드를 만들 수 있는 공부가 되기도 했고요.

실제 리뷰 진행

그러면 실제로 어떤 식으로 현재 코드 리뷰를 진행하고 있는지 공유해보도록 하겠습니다. 먼저 작업 후 GitHub에 PR을 올립니다. 코드 리뷰를 더 자주 하게 되면서 기존의 PR 템플릿을 조금 다듬게 되었습니다. 빠르게 배포되어야 하는 기능을 빠르게 파악하기 위해 가장 아래에 있던 배포 예정일을 맨 위로 올렸고 좀더 자세한 내용을 쓸 수 있게 주석을 보강했습니다. 이 과정에서 ChatGPT와 Claude의 도움을 받아 템플릿을 다시 다듬는 작업을 거쳤습니다.

## 배포 예정일
<!-- 배포 예정일을 명시해 주세요. -->

## 작업 내용
<!--
  내가 한 작업이 어떤 건지 간략히 설명해주세요.
  (짧은 개요 또는 상세한 내용, 혹은 스스로 고민한 내용과 함께 논의가 필요한 부분이 있다면 명시)
-->
- **변경된 주요 내용**:
  <!-- 코드의 어떤 부분이 어떻게 변경되었는지 구체적으로 기술하세요. -->
  <!-- 리뷰어의 이해를 돕기 위한 추가 정보 (다이어그램, GIF 등) -->
  <!-- 예시: 특정 함수의 로직 변경, 새로운 모듈 추가, 스타일 수정 등 -->
- **변경 이유**:
  <!-- 이 변경이 필요한 이유를 설명해주세요. -->
  <!-- 예: 성능 개선, 버그 수정, 신규 기능 추가, 코드 유지보수성 향상 등 -->

## 테스트 가이드
<!--
  리뷰어가 테스트를 쉽게 할 수 있도록 테스트 조건과 방법을 작성하세요.
  - 예: 어떤 페이지에서 테스트해야 하는지, 특정 사용자 계정이 필요한지, 환경 설정이 필요한지 등
-->

## 관련 문서
<!-- 
  이 PR과 관련된 문서나 참고 링크를 추가하세요.
-->

## 작업 분류
- [ ] 버그 수정
- [ ] 신규 기능
- [ ] 실험
- [ ] 테스트
- [ ] 프로젝트 구조 변경
- [ ] 기타

## 체크리스트
- [ ] 코드에 에러, 경고가 없는지 확인했나요?
- [ ] 테스트 환경에서 모든 기능이 정상 동작하는지 확인했나요?
- [ ] 주석이나 문서가 충분한가요?
<!--
  오류를 줄이기 위한 최종 점검
  - 코드가 에러, 경고 없이 깨끗한지 확인: IDE에서 빨간 줄, 노란 줄이 없는지 확인
  - 테스트 환경에서 테스트를 완료했는지 확인: 로컬 환경에서 모든 기능이 정상 동작하는지 확인
  - 주석이나 문서가 충분한지 확인: 필요한 경우 주석 및 문서 업데이트
-->

PR을 생성하고 나면, Slack의 리뷰 채널에 PR 링크를 공유합니다. 이 채널에는 Github 앱을 적용해둬서 PR의 내용이 바로 보여서 들어가지 않고도 중요 내용을 미리 확인할 수 있습니다. 메시지에 반응 추가하기 기능을 이용해서 메시지를 확인했으면 👀, 들어가서 리뷰까지 완료했으면 ✅ 이모지를 남겨둡니다. 위에서 설명한 1일 규칙을 지키기 위해 요청 다음 날에 이모지를 남기지 않은 사람에게는 리마인드를 합니다.

코드 리뷰는 GitHub PR 리뷰 기능을 이용해 리뷰합니다. 처음에는 단순히 코멘트만 달다가, 다른 기업의 리뷰 방식을 참고해 지금은 Pn 방식으로 리뷰하고 있습니다. P1~P5까지 단계를 나눠, 반드시 변경되어야 하는 제안부터 사소한 제안까지 단계를 나눠 리뷰에서 제안합니다.

리뷰 요청자는 리뷰를 보고 리뷰를 받아들여 수정하는 커밋을 추가할 수도 있고, 이견이 있다면 코멘트에서 추가 논의를 거쳐 결론을 낼 수도 있습니다. 이 과정 역시 최대한 1일 안에 끝내도록 합니다. 만약에 배포가 더 빨리 되어야하는 경우라면 배포 후, 리뷰를 반영한 작업을 새로운 PR에 올려서 공유합니다.

한 주간 쌓인 리뷰에서 모두에게 공유하고 싶은 리뷰는 주간 팀미팅 때 팀에게 모두 공유합니다. 좋은 내용의 리뷰를 팀 모두가 공유하고, 더 좋은 리뷰를 쓰도록 독려하기 위해 가지는 시간입니다.

리뷰는 버릇 들이기다

이렇게 저희는 지금 코드 리뷰를 하는 개발팀이라고 확실하게 이야기할 수 있게 되었습니다. 아직 사람의 손으로 돌아가는 부분이 많지만, 어느 정도 체계가 잡혔기 때문에 앞으로 시간을 들여 반복되는 과정을 자동화하려는 계획도 조금씩 세워보고 있습니다.

짧지 않은 과정을 통해서 정착시킨 코드 리뷰는 팀에게 큰 도움이 되고 있습니다. 리뷰가 있다는 걸 인식하기만 해도 코드 작성 시점부터 이미 더 좋은 코드를 쓰려는 생각이 들고 리뷰 과정에서 새로운 방법을 배우는 점도 좋습니다. 다른 팀원도 코드 리뷰에서 느끼는 장점을 공유해주셨습니다.

제일 큰건 코드 퀄리티가 높아진 느낌이에요. 생각 못했던 부분을 한번 더 볼 수 있는 계기가 되어서 좋았고, 배포할때도 더 자신감이 붙는 느낌이어서 좋았습니다.

배포와 리뷰를 나눠서 저항감이 많이 줄어든 거 같아요. Pn룰을 도입하면서 메시지의 의도를 확실하게 전달할 수 있었어요. 더 좋은 문화를 위해서 계속 자료를 찾아보고 우리 방식대로 다듬어서 적용하는 과정이 좋았어요.

코드 리뷰 또는 새로운 문화를 도입해보려는 팀, 예전에는 했었는데 어느새 사라져서 아쉬운 팀이 있다면 이번 글이 코드 리뷰를 하는 개발팀이 되도록 도움이 되는 글이면 좋겠습니다.