봄봄 코드 리뷰 문화 개선

 

 

 

 

솔직히 말해볼게요. 코드 리뷰, 다들 좋은 거 알잖아요? 하지만 가끔은 슬랙 알림에 뜬 [PR] 글자만 봐도 "아, 조금만 있다가 볼까..." 하고 창을 닫게 되는 순간이 있죠.

 

저에게 코드 리뷰는 단순히 '오타 찾기'나 '버그 검수'가 아니에요. 우리 팀이 어떤 코드를 '좋은 코드'라고 정의하는지, 이 복잡한 문제를 어떤 로직으로 풀어냈는지 서로의 머릿속을 동기화하는 가장 찐한 협업의 시간이라고 생각하거든요. 그래서 우리 팀은 "무조건 리뷰 후 머지"라는 꽤 깐깐한 원칙을 고수해왔고, 실제로 그 덕분에 대형 사고를 막거나 설계가 훨씬 단단해지는 짜릿한 경험도 꽤 했습니다.

 

그런데 팀이 프로젝트가 커져가며 바빠지니 문제가 생기더라고요.

 

리뷰가 '즐거운 대화'가 아니라 '밀린 숙제'가 되어버린 거죠. 쌓여있는 PR은 누군가에겐 압박이 되고, 누군가에겐 긴 기다림이 됩니다. 꼼꼼하게 보자니 진도가 안 나가고, 대충 하자니 찝찝한 그 미묘한 상황. 좋은 의도로 만든 시스템이 어느새 팀의 발목을 잡는 '병목'이 된 거예요.

 

여기서 제가 내린 결론은 하나였습니다. "사람들을 더 채찍질하지 말자." 리뷰가 늦어지는 건 팀원들의 성실함 문제가 아니라, 리뷰를 하기 힘들게 만드는 '운영의 문제'였거든요. 초반에는 "리뷰 좀 빨리해주세요"라고 서로 독촉하면서 다녔는데 이제는 리뷰어가 '딱 5분만 써도 충분히 맥락을 파악할 수 있는 환경'을 만드는 데 집중했습니다.

 

그렇게 바꾸고 나니 변화가 숫자로도 보이더라고요. 평균 리드 타임이 3~6일에서 1~2일 이내로 줄었습니다.

 

어떻게 하면 리뷰어가 길을 잃지 않게 할지, 불필요한 알림 지옥에서 어떻게 탈출했는지—저희 팀의 시행착오 끝에 정착한 '지속 가능한 코드 리뷰 운영법'을 공유합니다.

 

 

1. 문제의 시작

프로젝트를 진행하며 공통적으로 느낀 문제가 있었다.

• 어떤 PR은 사소한 코멘트로 논의가 길어지고
• 중요한 변경이 들어간 PR은 늦게 발견되거나 묻히고
• 리뷰 요청이 제대로 인지되지 않아 며칠씩 대기하는 상황이 발생했다

처음에는 개인의 리뷰 성향 문제라고 생각했다.
“누구는 꼼꼼하고, 누구는 빠르다” 정도로 인식했다.

하지만 PR 수가 늘어날수록 확신이 들었다.

결국 더 열심히 하자는 방식엔 한계가 있었다. 
같은 노력으로도 리뷰가 더 잘 굴러가게 만드는 구조를 손봐야겠다고 느꼈다.

 

2. 문제 정의

팀원들과 리뷰 상황을 정리해보며, 문제를 세 가지로 정리했다.

 

1) 리뷰 코멘트의 중요도 기준이 제각각

• 필수 수정인지, 제안인지 구분되지 않음
• “이건 꼭 반영해야 하나요?” 같은 질문이 반복
• 논의가 길어지고 PR 처리 속도가 들쭉날쭉해짐

2) PR에 맥락이 충분히 남지 않음

• 왜 이 변경을 했는지
• 다른 선택지는 무엇이었는지
• 비즈니스적인 요소와 어떤 연관관계가 있는지
• 단순히 코드 컨벤션이나 코드 구조에 대해서만 리뷰하게 됨 
• 전체적인 그림으로 리뷰하기 위해서는 리뷰할 사람이 따로 찾아봐야 하는게 많았음

3) 리뷰 요청이 묻히는 구조

• GitHub 알림은 많지만 중요 이벤트가 섞여 있음
• Discord 알림은 노이즈가 많아 점점 무시됨
• 결과적으로 리뷰 누락·지연 발생

 

3. “빨리”가 아니라 “덜 소모되게 하자”

여기서 중요한 합의가 필요했다.

목표는 리뷰를 대충 빠르게가 아니라
리뷰 품질을 유지하면서도 예측 가능한 속도를 만드는 것

 

이를 위해 개인의 책임을 늘리는 대신, 팀 전체의 기준과 흐름을 정리하는 방향을 선택했다.

 

4. 해결 방법

1) 리뷰 코멘트의 언어를 통일하다 (Pn 규칙)

우리 팀은 평소 대화할 때는 말뿐 아니라 표정, 톤, 손짓 같은 비언어적 신호로 “이 얘기가 얼마나 진지한지”, “급한 건지”, “그냥 아이디어인지”를 함께 전달한다.

그런데 코드 리뷰는 대부분 텍스트로만 진행되다 보니, 의도와 뉘앙스가 쉽게 빠진다.

가볍게 던진 코멘트가 예상보다 날카롭게 읽히거나, 꼭 반영돼야 하는 지점이 “참고” 정도로 받아들여져서 서로 같은 내용을 반복 설명하게 되기도 한다.

결국 리뷰가 길어지고, 감정 소모가 생기고, 때로는 PR 흐름 자체가 멈추는 상황까지 이어질 수 있다. 

 

그래서 우리는 뱅크샐러드에서 만든 룰을 통해 리뷰 코멘트의 중요도를 명확히 표현하기로 했다.

해당 룰은 우테코 프리코스를 할 때 처음 사용해보았는데 커뮤니케이션 비용이 많이 줄었다.  

 

뱅샐 블로그 글을 보면 아래와 같이 쓰여 있다.

커뮤니케이션 비용을 줄이기 위한 Pn 룰

뱅크샐러드 기술 조직은 코드 리뷰의 코멘트에 Pn 룰을 사용하여 리뷰어가 코멘트를 강조하고 싶은 정도를 표현합니다.

P1: 꼭 반영해주세요 (Request changes)
리뷰어는 PR의 내용이 서비스에 중대한 오류를 발생할 수 있는 가능성을 잠재하고 있는 등 중대한 코드 수정이 반드시 필요하다고 판단되는 경우, P1 태그를 통해 리뷰 요청자에게 수정을 요청합니다. 리뷰 요청자는 p1 태그에 대해 리뷰어의 요청을 반영하거나, 반영할 수 없는 합리적인 의견을 통해 리뷰어를 설득할 수 있어야 합니다.

P2: 적극적으로 고려해주세요 (Request changes)
작성자는 P2에 대해 수용하거나 만약 수용할 수 없는 상황이라면 적합한 의견을 들어 토론할 것을 권장합니다.

P3: 웬만하면 반영해 주세요 (Comment)
작성자는 P3에 대해 수용하거나 만약 수용할 수 없는 상황이라면 반영할 수 없는 이유를 들어 설명하거나 다음에 반영할 계획을 명시적으로(JIRA 티켓 등으로) 표현할 것을 권장합니다. Request changes 가 아닌 Comment 와 함께 사용됩니다.

P4: 반영해도 좋고 넘어가도 좋습니다 (Approve)
작성자는 P4에 대해서는 아무런 의견을 달지 않고 무시해도 괜찮습니다. 해당 의견을 반영하는 게 좋을지 고민해 보는 정도면 충분합니다.

P5: 그냥 사소한 의견입니다 (Approve)
작성자는 P5에 대해 아무런 의견을 달지 않고 무시해도 괜찮습니다.
FYI) Pn 룰은 뱅크샐러드에서 성장하는 회사에서 커뮤니케이션은 가장 큰 비용이라는 문제의식에서 이를 해결하기 위한 문화를 배경으로 탄생했습니다. Pn 룰은 코드 리뷰 외에도 슬랙 등 텍스트로 커뮤니케이션을 하는 곳에서도 활용하고 있습니다

 

위와 같이 p3면 comment이기 때문에  반영할 수 없거나 다음에 반영할 계획을 명시적으로 표현을 하면된다.

 

확실히 이렇게 앞에 pn을 작성하면

불필요한 감정 소모 감소가 감소하고 논의 포인트가 명확해진다. 또한 리뷰어도 “어디까지 개입해야 하는지” 판단이 쉬워진다.

---

2) PR의 시급성을 명확히 드러내다 (D-n 룰)

이 룰을 도입하기 전에는 코드 리뷰를 시간 순서대로 하거나 변경이 적은 PR 부터 했다.  

얼마나 시급한지를 단순히 PR 목록만 봐서는 알 수 없었다. 

엄청 시급하면 해당 크루가 구두로 말하거나  전체를 태그해서 빠르게 코드리뷰를 요청하는 경우가 종종 발생했다.  

 

그래서 어떻게 해결하지 하다가 D-n룰이란걸 알게되었다.

D-n 룰은 리뷰를 요청하는 시점에 PR이 Merge 되어야 하는 일정을 공유하여 리뷰어가 Working day 안에서 스스로 우선순위를 결정한다.

 

이 규칙의 핵심은 “압박”이 아니라 정렬이었다.

 

리뷰어가 맥락을 읽기 전에 이 PR을 언제까지 보면 되는지 바로 알 수 있도록 하는 것이다.

확실히 이를 도입하고 나서 우선순위에 따라 더 빠르게 처리할 수 있었다.  

 

D-n 라벨 자동 조정

그런데 며칠 지나니, 작은 문제가 보이기 시작했다.
라벨은 시간이 지나도 그대로 고정된다는 점이다.

 

예를 들어 D-5를 붙여두면, 5일이 지나도 여전히 D-5다.
리뷰어는 결국 PR 생성일을 다시 보고 “오늘 기준으로 며칠 남았지?”를 계산해야 했다.

 

이 불편함을 그냥 남겨놓으면 D-n룰을 잘 활용하지 않을 것 같았고 또 다른 불편함을 초래할 것 같았다.  
내가 룰을 도입했으니, 끝까지 쓰이게 만드는 것도 내 몫이라고 봤다.
그래서 라벨을 사람이 관리하지 않도록, 자동으로 굴러가게 만들기로 했다.

 

어떻게 하면 할 수 있을까 찾아보다가 GitHub Actions에서 스케줄러를 지원하는 것을 알게되었다.
GitHub Actions는 cron 기반 실행을 지원하니, 매일 아침 10시에 워크플로우를 돌려서

• 열려 있는 PR 목록을 조회하고
• D-n 라벨을 하루마다 -1씩 자동 조정하고
• D-0에 도달하면 디스코드로 알림을 보낸다

그런데 여기에 디테일을 조금 더 넣었다.

 

D-0 알림은 “그냥 PR 링크 던지기”에서 끝내지 않았다.
D-0이 된 PR마다 리뷰 상태를 다시 조회해서, 지금 누구를 깨워야 하는지를 자동으로 판단하게 했다.

• 승인 수(approvedCount)와 수정 요청 여부(hasChangesRequested)를 기준으로 멘션 대상을 고른다.
  • 수정 요청이 있으면 작성자를 먼저 멘션(수정이 필요하니까)
  • 승인 2명 미만이면 아직 승인하지 않은 리뷰어들을 멘션(단, 작성자는 후보에서 제외)
  • 승인 2명 이상이면 작성자를 멘션(이제 merge가 가능하니까)
• 멘션은 중복 호출이 생기지 않도록 Set으로 한번 더 정리한다.

이제 리뷰어는 PR을 열어보기 전에, 라벨만 보고 “오늘 처리할 건지”를 바로 판단한다.
남은 기간을 계산하기 위해 누군가가 기억하고 챙길 필요도 없다.

 

사람의 기억 대신, 시스템에 맡겼다.

 

---

3) 맥락을 남기는 PR

코드 리뷰가 지연될 때 흔히 “PR 템플릿을 만들자”는 해결책이 나온다.

나도 처음엔 그 방법을 떠올렸다.

하지만 여러 번의 협업 경험을 돌아보니, 리뷰가 느려지는 핵심 원인은 템플릿 유무가 아니라

리뷰어가 PR을 이해하기 위해 치르는 ‘맥락 로딩 비용’이었다.

 

변경된 코드는 있는데 “왜 바꿨는지, 어떤 대안을 고민했는지, 어떻게 검증했는지, 비즈니스 요구사항이 뭔지”가 PR에 남아 있지 않으면

리뷰는 코드 컨벤션이나 코드 구조에 대해서만 리뷰하게 된다.  

전체 그림으로 리뷰를 하거나 딥하게 하기 위해서는 직접 코드를 작성한 사람에게 질문을 하거나 PR외 추가적으로 정보를 찾는 비용이 발생된다. 

이런식으로 논의가 길어지고, 정보를 찾는데 시간이 걸리기에 리뷰가 뒤로 밀리며, PR 처리 속도가 느려지기 시작한다.

 

그래서 형식적인 PR 템플릿을 강제하는 대신, PR을 리뷰할 사람이 따로 찾아봐야하는 일이 거의 없도록 상세하게 쓰는 습관을 팀에 정착시키는 방향을 선택했다.

 

얼마전 향로님 블로그를 보다가 이와 관련된 코멘트를 발견했다. 

 

요즘들어 개선되고 있기는 한데 우리팀에 있어서 조금 부족한 부분이었다.  

사실 PR을 자세히 쓰는것은 상당한 비용이 들어가고 귀찮기도 하다.  

 

하지만 나로인해 리뷰어들은 시간을 엄청 세이브 할 수 있고 코드 리뷰의 질도 높일 수 있다.  

그 결과 품질이 높은 코드로 이어질 확률이 높고 이는 결국 유지보수성을 올려주고 버그를 줄여줄 수 있는 효과를 가져올 수 있다. 

 

 

여기에 추가적으로, 실제로 도움이 많이 되었던 것은 PR에 ‘리뷰 포인트’를 한 줄로 미리 열어두는 습관이었다. 예를 들어 “동시성 관점에서 이 변경이 안전한지 확인 부탁드립니다”, “이 선택(설계/쿼리/API 응답)이 팀 컨벤션에 맞는지 의견이 필요합니다”처럼, 리뷰어가 어디를 중점적으로 보면 좋을지 작성자가 먼저 제시하는 방식이다. 이 한 줄이 있으면 리뷰어는 PR을 열자마자 ‘읽는 방향’을 잡고, 코멘트는 스타일 지적에서 벗어나 의사결정·설계 논의로 이동한다. 결과적으로 리뷰 품질은 유지되면서도 속도는 훨씬 안정적으로 나왔다.

 

이 문화를 정착시키는 과정에서 내가 중요하게 본 건 “규칙을 공지하는 것"도 있지만 던 신경쓴 것은 운영으로 습관이 퍼지게 만드는 것이었다. 누군가에게 요구하기 전에 내가 먼저 모든 PR에서 맥락을 남기고, 리뷰 포인트를 적고, 좋은 사례가 나오면 “이 PR은 맥락이 좋아서 리뷰가 쉬웠다”처럼 공개적으로 피드백했다.

 

반대로 부담을 늘리는 방식은 피했다. 완벽한 문서를 쓰게 하는 게 목표가 아니라, “리뷰어가 다시 묻지 않게 만들 정도의 설명”만 남기면 충분하다고 계속 강조했다. 그 결과, 반복 질문이 줄고 리뷰가 미뤄지는 빈도가 감소했으며 평균 리뷰 리드타임이 3~6일에서 1~2일 이내로 단축됐다. 무엇보다 리뷰가 ‘지적받는 자리’가 아니라 ‘생각을 맞추는 과정’으로 인식되기 시작했고, 이는 팀의 협업 피로도를 눈에 띄게 낮췄다.

---

4) “알림”이 아니라 “주의(Attention)”를 운영하기

리뷰 문화가 아무리 좋아져도, PR이 제때 보이지 않으면 결국 병목이 된다.

실제로 우리 팀에서 리뷰 누락·지연이 발생하던 이유 중 하나는 “사람들이 게을러서”가 아니라 알림이 너무 많아 중요한 신호가 묻히는 구조였다.

GitHub 알림은 기본적으로 촘촘하지만, PR이 늘어나면 이벤트가 쏟아지고(코멘트, 업데이트, 라벨, 머지 시도 등) 사람은 결국 노이즈를 무시하게 된다. 이 상태가 되면 가장 중요한 순간인 “리뷰 요청”조차 지나가 버린다.

 

 

기존에 쓰던 PR 알림은 너무 이벤트가 많았다.

그러다 보니 어느순간 나조차도 이 알림을 무시하기 시작했다.

 

왜 이렇게 알림이 많이 오는 걸까? 

깃허브가 제공해주는 웹훅 설정을 보면 그 이유를 알 수 있다.

PR관련 거의 모든 이벤트를 감지해서 알림을 보내게된다.  

물론 Pull request reviews, pull request review comments 같은게 있긴한데 필요한 많은 부분이 pull requests에 선물꾸러미처럼 한꺼번에 다 담겨있다.  

 

결국 우리 입맛에 맞게 커스터마이징을 해야한다.  

 

핵심 질문은 단순했다.

“팀이 지금 당장 주의를 써야 하는 순간은 언제인가?”

 

나는 GitHub의 수많은 이벤트 중에서, 리뷰 흐름을 실제로 움직이는 이벤트만 남겼다.

• PR Open: 새 작업이 시작됐음을 알려야 하는 순간
• Review Request / Re-request: 누군가의 행동(리뷰)이 필요하다는 신호
• Approve: 병목이 풀렸고 다음 단계(머지/배포)로 넘어갈 수 있다는 신호

그리고 이 이벤트들을 기준으로 Discord 알림을 상황별로 다르게 설계했다.

 

1) PR Open

 

 

PR 생성에서는 리뷰어를 멘션을 걸고 제목, 작성자 D-n룰만 보이도록 적용했다. 

그래서 리뷰어가 제목으로 어떤 pr인지 알 수 있고 D-n룰을 보고 시급성을 알 수 있도록 했다.

처음에는 내용도 포함하려고 했으나 길어져서 다른 알림이 묻힐 수 도 있다고 생각해서 과감하게 제거했다.

 

2) PR Request

리뷰 재요청을 재요청을 받을 당사자면 멘션되게 했습니다.

 

3) Request Change

리뷰 이벤트 중에서 가장 우선순위가 높은 알림은 Request changes였다.
이건 단순한 진행 상황 공유가 아니라, 작성자가 다음 액션을 해야 PR이 앞으로 갈 수 있는 상태가 되기 때문이다.

그래서 Request changes 알림은 다음 원칙으로 설계했다.

• 멘션 대상은 PR 작성자(Author)만
  리뷰어 전체를 흔드는 순간 노이즈가 되기 쉽다.
  “이 PR은 작성자가 수정해야 진행된다”라는 메시지이기 때문에, 작성자만 콕 집어 멘션하는 편이 효과가 컸다.
• 알림 본문은 ‘한 번에 파악’ 가능하게
  PR 링크/제목 + 변경 요청자 + 핵심 코멘트 위치(리뷰 링크) 정도만 넣고,
  “지금 뭐 해야 하지?”가 바로 보이도록 만들었다.

 

4) Approve

 

Approve 알림은 반대로, 너무 자주 울리면 가치가 급격히 떨어졌다.
한 PR에 승인 리뷰가 여러 번 달릴 수 있고, 팀 규모가 커질수록 “승인 알림 폭탄”이 되기 쉽다.

그래서 승인 알림은 내부 기준으로 merge 가능한 숫자에 도달하면 알림을 보내도록 설정했다. 

---

 

이 작업은 단순한 자동화가 아니었다.
나는 알림을 “정보를 전달하는 기능”이 아니라, 팀의 주의를 어디에 쓰게 할지 결정하는 운영 설계로 봤다.

이 구조가 자리 잡으면서 리뷰 요청이 묻히거나 지나가는 일이 줄었고, “봤는데 놓쳤다” 같은 상황도 눈에 띄게 감소했다. 리뷰가 더 빨라졌다는 사실보다, 리뷰가 안정적으로 돌아가기 시작했다는 게 더 큰 변화였다.

 

이번 개선의 핵심은 자동화나 규칙 그 자체가 아니라, 팀의 시간을 덜 낭비하게 만드는 방식이었다. 맥락이 남는 PR은 리뷰어의 추측을 줄이고, 이벤트 기반 알림은 팀의 주의를 흩뜨리지 않는다. 결국 협업 문제는 “누가 더 잘하느냐”보다, 덜 흔들리게 만드는 구조가 있느냐에 더 가깝다.

 

나는 앞으로도 개인의 역량으로 버티는 방식보다, 팀이 지속 가능하게 굴러가는 시스템을 설계하는 쪽에 집중하려 한다. 리뷰가 편해지면 속도는 따라오고, 속도가 안정되면 품질을 논의할 여유가 생긴다.

 

그리고 팀 규모가 더 커진다면, 한 리뷰에 모든 사람이 매달리지 않도록 리뷰 참여를 설계하는 방식도 고민해보고 싶다. 메타가 공유한 “코드 리뷰 시간을 개선한 방식”은 그 다음 단계에서 충분히 참고할 만한 사례라고 생각한다.

 

 

Reference

• GitHub Actions로 개선하는 코드 리뷰 문화
• 코드 리뷰 in 뱅크샐러드 개발 문화
• 공통시스템개발팀 코드 리뷰 문화 개선 이야기
• Move faster, wait less: Improving code review time at Meta