반복되는 코드 리뷰, 체크리스트로 시간 아끼는 법

풀 리퀘스트를 열 때마다 똑같은 지적이 달립니다. 들여쓰기가 안 맞는다, print가 남아 있다, 함수 이름이 규칙과 다르다. 리뷰어는 매번 같은 말을 적고, 작성자는 매번 같은 수정을 합니다. PR 하나에 이런 왕복이 두 번씩만 생겨도 20~30분이 사라지고, 일주일에 다섯 건이면 두 시간이 넘습니다. 코드리뷰 체크리스트는 이 반복을 줄이는 가장 값싼 도구입니다. 이 글에서는 바로 복사해 쓸 수 있는 체크리스트 항목, 그걸 PR 템플릿으로 붙이는 법, 그리고 사람이 볼 필요조차 없는 항목을 기계에 넘기는 방법까지 다룹니다.

왜 같은 지적이 계속 반복될까

리뷰에서 나오는 코멘트는 성격이 두 가지로 갈립니다. 하나는 “이 로직은 동시 요청이 들어오면 깨진다” 같은 판단이고, 다른 하나는 “여기 공백이 두 칸이다” 같은 확인입니다.

문제는 확인형 코멘트가 리뷰 시간의 상당 부분을 잡아먹는다는 점입니다. 이건 리뷰어의 실력과 무관하게 발생합니다. 사람의 눈은 반복 검사에 약하고, 같은 항목을 스무 번째 확인할 때쯤이면 놓치기 시작합니다. 체크리스트가 필요한 이유가 여기 있습니다. 확인형 항목을 목록으로 고정해두면, 작성자가 PR을 올리기 전에 스스로 걸러낼 수 있고 리뷰어는 판단형 코멘트에 집중할 수 있습니다.

바로 쓸 수 있는 기본 체크리스트

처음부터 항목을 스무 개씩 만들면 아무도 읽지 않습니다. 다섯에서 일곱 개로 시작해서, 실제로 리뷰에서 반복된 지적만 나중에 추가하세요.

동작 확인 — 로컬에서 빌드와 테스트가 통과하는가
잔여물 — 디버그용 출력, 주석 처리한 코드 뭉치, 쓰지 않는 import가 남아 있지 않은가
비밀값 — API 키, 토큰, 비밀번호, 개인 경로가 코드에 박혀 있지 않은가
실패 경로 — 입력이 비어 있거나 네트워크가 끊겼을 때 어떻게 되는가
범위 — 이 PR이 한 가지 일만 하는가 (기능 추가와 리팩터링이 섞이지 않았는가)
문서 — 바뀐 동작이 README나 주석에 반영됐는가

마지막 항목 하나를 덧붙이면 효과가 큽니다. “리뷰어가 특히 봐줬으면 하는 부분”을 작성자가 직접 적게 하는 것입니다. 리뷰어가 300줄을 훑는 대신 핵심 30줄부터 보게 되니, 리뷰 품질과 속도가 동시에 올라갑니다.

체크리스트를 PR 템플릿으로 붙이기

체크리스트는 위키에 적어두면 아무도 안 봅니다. PR을 여는 화면에 자동으로 뜨게 만들어야 합니다. 깃허브라면 저장소 루트에 .github/pull_request_template.md 파일 하나만 두면 됩니다.

<!-- .github/pull_request_template.md -->

## 무엇을 바꿨나


## 왜 바꿨나


## 리뷰 전 셀프 체크

- [ ] 로컬에서 빌드와 테스트가 통과한다
- [ ] 디버그용 print / console.log 를 남기지 않았다
- [ ] 하드코딩한 경로, 토큰, 비밀번호가 없다
- [ ] 실패 케이스(빈 값, 네트워크 오류)를 처리했다
- [ ] 변경한 함수의 주석과 문서가 실제 동작과 맞는다

## 리뷰어가 집중해서 봐줬으면 하는 곳

이 파일을 커밋하면 그 다음부터 열리는 모든 PR의 본문이 이 내용으로 채워집니다. 깃랩은 .gitlab/merge_request_templates/ 폴더에 같은 방식으로 넣으면 됩니다.

체크박스를 강제 조건으로 만들지는 마세요. 긴급 배포 PR에서 체크 여섯 개를 다 채우라고 하면, 사람들은 체크리스트를 지우고 올리기 시작합니다. 목적은 통과 의례가 아니라 기억 보조입니다.

사람이 볼 필요 없는 항목은 기계에 넘긴다

체크리스트 항목 중 상당수는 애초에 사람이 확인할 일이 아닙니다. 공백, 포맷, 남은 디버그 코드, 실수로 커밋된 비밀키 같은 건 도구가 훨씬 정확하게 잡습니다. 파이썬 프로젝트라면 pre-commit으로 커밋 순간에 걸러낼 수 있습니다.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-merge-conflict
      - id: detect-private-key
      - id: check-added-large-files
        args: [--maxkb=1024]

ruff가 코드 문제를 자동으로 찾아 고치는 실제 실행 결과 — 실제 실행입니다. 미사용 import와 정렬은 자동으로 고쳐지고, 사람은 판단이 필요한 것만 봅니다.

설정 파일을 저장소 루트에 두고 아래를 실행하면 준비가 끝납니다.

# 설치는 한 번만
pip install pre-commit
pre-commit install

# 기존 파일 전체에 한 번 돌려보기
pre-commit run --all-files

이제 git commit을 할 때마다 훅이 돌면서 포맷을 고치고, 병합 충돌 표시나 개인키가 섞여 있으면 커밋 자체를 막습니다. 리뷰어가 볼 코드는 이미 한 번 걸러진 상태가 됩니다.

자동화 도구 비교

어떤 도구를 쓸지는 언어와 팀 규모에 따라 갈립니다. 아래는 무료로 쓸 수 있는 오픈소스 조합입니다.

도구	대상	역할	적용 시점
Ruff	파이썬	린트 + 포맷을 한 번에 처리	커밋 / CI
ESLint + Prettier	JS · TS	문법 규칙 검사와 코드 포맷 분리	저장 / 커밋 / CI
pre-commit	언어 무관	여러 검사 도구를 커밋 훅으로 묶어 관리	커밋
gitleaks	언어 무관	커밋에 섞인 토큰·키 탐지	커밋 / CI

한 번에 다 붙이려 하지 말고 pre-commit 하나부터 넣어보세요. 나머지는 그 위에 훅을 한 줄씩 추가하는 형태라 부담이 적습니다.

체크리스트를 실제로 유지하는 방법

리뷰에서 같은 지적이 세 번 반복되면 그때 항목을 추가합니다. 미리 상상해서 넣은 항목은 대부분 죽습니다.
기계가 잡을 수 있게 된 항목은 체크리스트에서 뺍니다. 린터가 포맷을 고쳐준다면 “들여쓰기 확인” 줄은 이제 소음입니다.
분기에 한 번쯤 목록을 읽고, 최근 석 달간 아무도 걸리지 않은 항목은 지웁니다.
항목은 판정 가능하게 씁니다. “코드를 깔끔하게 작성했는가”는 체크할 수 없지만, “함수 하나가 50줄을 넘지 않는가”는 체크할 수 있습니다.

주의할 점

체크리스트가 길어질수록 통과율이 아니라 무시율이 올라갑니다. 열 개를 넘어가면 줄일 때가 된 것입니다.
체크리스트는 설계 리뷰를 대체하지 못합니다. 구조를 바꾸는 PR이라면 코드를 쓰기 전에 짧게라도 논의하는 편이 훨씬 쌉니다.
pre-commit 훅을 처음 도입하면 기존 파일 전체가 포맷 변경으로 잡힙니다. 포맷만 적용한 커밋을 따로 하나 만들어두면, 이후 리뷰에서 진짜 변경사항이 묻히지 않습니다.
혼자 개발하더라도 효과가 있습니다. 이 경우 리뷰어는 3개월 뒤의 자신입니다.

마무리

오늘 할 수 있는 가장 작은 첫걸음은 .github/pull_request_template.md 파일 하나를 만들고, 위 체크리스트에서 항목 다섯 개만 골라 넣는 것입니다. 5분이면 끝나고, 다음 PR부터 바로 효과가 보입니다. 도구 설정은 그 다음에 붙여도 늦지 않습니다.

다음 글에서는 AI 이미지 생성 도구로 블로그 썸네일을 직접 만드는 방법을 다루겠습니다.