PR을 올릴 때마다 확인해야 할 코드 리뷰 체크리스트 38개를 6단계로 정리했다. 셀프 체크, 로직 정확성, 보안 취약점, 성능 최적화, 가독성·유지보수성, 테스트 커버리지 순서로 구성했으며, 클로드 코드·커서·깃허브 코파일럿 같은 AI 코딩 도구로 생성한 코드에서 특히 놓치기 쉬운 항목도 별도로 다룬다. 즉시 사용 가능한 GitHub PR 템플릿 마크다운과 팀 도입 가이드도 포함했다.
PR을 올리면 리뷰가 늦고, 리뷰를 받으면 리뷰어마다 보는 기준이 다르다. 팀에 코드 리뷰 문화는 있지만 무엇을 봐야 하는지 공유된 기준이 없는 경우가 대부분이다.
저는 12개 사이트를 혼자 운영하며 클로드 코드(Claude Code)로 매일 코드를 생성한다. 그 경험으로 알게 된 건, AI 생성 코드일수록 리뷰 체크리스트가 더 중요하다는 점이다. 논리는 그럴듯해 보이지만 엣지 케이스가 빠졌거나, 보안 검증이 누락되거나, SQL 쿼리가 인덱스를 타지 않는 코드가 PR에 들어오는 경우가 잦다.
이 글은 PR 작성자와 리뷰어 모두가 쓸 수 있는 38개 체크리스트를 6단계로 정리한다. 팀 문서에 그대로 붙여 써도 되고, 깃허브 PR 템플릿에 추가해도 된다.
코드 리뷰, 왜 체크리스트가 필요한가
코드 리뷰의 목적은 버그를 잡는 것만이 아니다. 지식 공유, 일관성 유지, 아키텍처 품질 관리까지 포함된다. 그런데 이 모든 것을 리뷰어가 매번 머릿속으로 떠올려야 한다면 리뷰 품질이 들쭉날쭉해진다.
체크리스트가 해결하는 문제는 세 가지다.
일관성: 리뷰어마다 보는 포인트가 달라지는 문제를 없앤다.
빠진 항목 방지: 피로도가 높을 때도 중요한 점검이 빠지지 않는다.
작성자의 셀프 점검: PR 제출 전 작성자가 스스로 걸러내면 리뷰 라운드 수가 줄어든다.
특히 클로드 코드, 커서(Cursor), 깃허브 코파일럿 같은 AI 코딩 도구를 팀에서 쓰기 시작한 이후, 코드 생성 속도는 빨라졌지만 품질 게이트를 체계화하지 않으면 기술 부채가 쌓이는 속도도 같이 빨라진다. AI가 생성한 코드는 구문이 맞아도 비즈니스 로직을 완전히 이해하지 못한 채 작성된다.
아래 38개 항목은 다음 6단계로 나뉜다: 셀프 체크 → 로직 정확성 → 보안 → 성능 → 가독성 → 테스트. 모든 항목을 매 PR마다 적용할 필요는 없다. 프로젝트 성격에 따라 필수/선택을 구분해두는 것이 현실적이다.
코드 리뷰는 6단계 점검 흐름으로 구조화하면 리뷰어 간 편차를 줄일 수 있다.
1단계 — PR 제출 전 작성자 셀프 체크리스트 (10개)
리뷰어에게 PR을 넘기기 전에 작성자 스스로 통과해야 하는 10개 항목이다. 이 단계를 건너뛰면 리뷰 라운드가 늘어나고 팀 전체의 시간이 낭비된다.
팀 도입 팁: 깃허브 PR 템플릿(.github/pull_request_template.md)에 위 항목을 체크박스(- [ ] 항목) 형태로 넣어두면 작성자가 PR을 열 때 자동으로 표시된다. 팀 전체가 자연스럽게 셀프 체크를 수행하게 된다.
2단계 — 코드 정확성·로직 점검 (8개)
가장 핵심적인 리뷰 단계다. 코드가 의도한 대로 동작하는지를 검증한다. 자동화 도구로 대체할 수 없는 영역이 여기에 집중되어 있다.
깃허브 코드 리뷰 화면. 라인 단위 댓글과 변경 제안 기능을 활용하면 리뷰 효율이 높아진다.
3단계 — 보안 취약점 점검 (7개)
보안 점검은 자동화 스캐너(Snyk, CodeQL, Semgrep 등)와 수동 리뷰를 함께 써야 한다. 자동화 도구가 잡아내지 못하는 비즈니스 로직 수준의 취약점은 사람의 눈으로 확인해야 한다.
주의 — AI 생성 코드의 보안 리뷰: AI 생성 코드는 보안 패턴이 표면적으로 맞아 보이는 경우가 많다. 하지만 인가(Authorization) 로직은 비즈니스 규칙을 알아야 올바르게 작성되므로 클로드 코드·커서가 생성한 권한 확인 코드는 반드시 리뷰어가 직접 검토해야 한다.
4단계 — 성능 & 효율성 점검 (7개)
성능 문제는 출시 후에 발견되면 수정 비용이 크다. 특히 데이터베이스 쿼리와 루프 로직은 리뷰 단계에서 잡는 것이 낫다.
5단계 — 가독성 & 유지보수성 점검 (6개)
코드는 한 번 쓰고 여러 번 읽힌다. 오늘의 나는 이해하지만 3개월 후의 동료는 이해하지 못할 코드를 만들지 않는 것이 이 단계의 목표다.
코드 리뷰는 버그를 잡는 것만큼 지식을 공유하고 코드베이스 일관성을 유지하는 역할을 한다.
6단계 — 테스트 커버리지 점검 (6개)
테스트는 "있으면 좋은 것"이 아니라 리뷰 통과 조건이어야 한다. 특히 핵심 비즈니스 로직, 결제 처리, 인증 흐름은 테스트 없이 머지되어서는 안 된다.
리뷰어 피드백 작성법 — 좋은 코멘트의 기준
체크리스트를 통과해도 문제를 어떻게 전달하느냐가 팀 문화에 영향을 준다. 리뷰 코멘트는 지적이 아니라 대화여야 한다.
좋은 리뷰 코멘트의 조건 다섯 가지:
문제와 이유를 함께: "이 코드 고치세요"보다 "이 경우 null이 반환될 수 있어서 다음 줄에서 에러가 납니다"가 낫다.
제안이 있는 코멘트: 깃허브의 "Suggest changes" 기능을 활용해 수정안을 직접 제시한다.
우선순위 명시: nit(사소함), suggestion(제안), blocker(차단) 세 단계로 코멘트를 분류하면 작성자가 무엇을 먼저 처리해야 하는지 알 수 있다.
질문 형태 활용: "이게 왜 이렇게 되어 있는 건가요?"처럼 질문 형태로 작성하면 리뷰어 자신이 이해를 못 한 경우도 열어두게 된다.
긍정적 피드백 포함: 좋은 코드에도 코멘트를 달아라. 팀원이 좋은 패턴을 썼을 때 칭찬하면 팀 전체가 그 패턴을 학습한다.
AI 코딩 도구 도입 후 달라진 리뷰 포인트
클로드 코드, 커서, 깃허브 코파일럿이 팀에 도입되면 코드 생성 속도는 빨라지지만 리뷰어가 더 신경 써야 하는 새로운 포인트가 생긴다.
AI 코드에서 자주 발견되는 패턴 다섯 가지:
컨텍스트 부족: AI는 프로젝트 전체 흐름을 모른다. 다른 모듈과 중복되는 함수가 새로 생성되거나, 기존 유틸리티를 모르고 처음부터 다시 구현하는 경우가 잦다.
에러 처리 패턴 불일치: 프로젝트에서 커스텀 에러 클래스를 쓰는데 AI가 생성한 코드는 일반 Error를 throw하는 경우가 많다.
하드코딩 설정값: 타임아웃, 재시도 횟수, 페이지 크기를 상수 대신 리터럴로 박는 경향이 있다.
테스트 없이 기능 완성: AI는 요청하지 않으면 테스트를 함께 작성하지 않는다. AI 생성 코드 PR에서는 테스트 존재 여부를 반드시 확인해야 한다.
과도한 주석: AI가 생성한 주석은 코드가 하는 일을 반복 설명하는 경우가 많다. "배열을 필터링한다"류 주석은 삭제해도 된다.
AI 코드 리뷰에서 가장 중요한 포인트는 비즈니스 로직이 실제 요구사항을 반영하는가이다. 구문은 AI가 잘 처리하지만 "이 기능이 이 제품의 맥락에서 올바른가"는 사람만이 판단할 수 있다.
GitHub PR 템플릿 — 즉시 사용 가능한 마크다운
아래 내용을 .github/pull_request_template.md에 넣으면 PR을 열 때 자동으로 표시된다. 팀 상황에 맞게 항목을 추가하거나 제거해서 쓴다.
.github/pull_request_template.md
## 변경 요약
<!-- 무엇을, 왜 변경했는지 한 문단으로 설명하세요 -->
## 관련 이슈
<!-- 예: Closes #123 -->
## 변경 유형
- [ ] 버그 수정
- [ ] 새 기능
- [ ] 리팩토링
- [ ] 성능 개선
- [ ] 문서 수정
- [ ] 기타
## 작성자 셀프 체크
- [ ] 로컬에서 정상 동작 확인
- [ ] 불필요한 console.log / 임시 코드 제거
- [ ] 환경변수·시크릿 하드코딩 없음
- [ ] 테스트 추가 (새 기능 / 버그 픽스)
- [ ] UI 변경 시 스크린샷 첨부
## 리뷰어 중점 확인 요청
<!-- 특별히 리뷰어가 집중해서 봐줬으면 하는 부분을 명시하세요 -->
기능 단위가 아니라 변경 이유 단위로 나누는 것이 효과적이다. 예를 들어 새 결제 기능을 구현할 때 ① 데이터베이스 스키마 추가 → ② 서비스 레이어 구현 → ③ API 엔드포인트 노출 → ④ 프론트엔드 UI 구현 순서로 4개의 PR로 쪼갤 수 있다. 각 PR이 단독으로 배포 가능한 상태여야 한다. 피처 플래그를 활용하면 작은 PR로 나눠 머지하면서도 실제 기능은 플래그 뒤에 숨길 수 있다.
리뷰어가 38개 항목을 매 PR마다 전부 확인해야 하나요?
전체 항목을 매번 적용하는 것은 비현실적이다. 대신 PR 유형별 필수 항목을 미리 정해두는 것이 효과적이다. "버그 픽스 PR"은 회귀 테스트 여부와 로직 정확성 항목이 필수, "리팩토링 PR"은 가독성과 테스트 커버리지가 필수, "보안 관련 변경"은 보안 점검 7개 전체 필수처럼 PR 유형별 필수 항목을 팀 문서로 정리해두는 것이 좋다.
클로드 코드나 커서 같은 AI 도구가 코드 리뷰를 자동화할 수 있나요?
정적 분석, 스타일 일관성, 명백한 버그 패턴 감지는 AI 도구가 잘 한다. 깃허브 코파일럿 리뷰, CodeRabbit, 클로드 코드의 /code-review 명령 등이 이 영역에 쓸 만하다. 하지만 비즈니스 로직 정확성, 인가 로직 검토, 아키텍처 결정의 적절성은 여전히 사람 리뷰어가 해야 한다. AI 도구는 리뷰 보조 수단으로 쓰고, 최종 승인은 사람이 하는 구조를 유지하는 것이 좋다.
코드 리뷰가 병목이 되어 배포가 느려지는데 어떻게 개선하나요?
병목이 발생하는 가장 흔한 원인은 PR이 너무 크거나 리뷰어가 너무 적은 경우다. 개선 방법은 ① PR 크기를 400줄 이하로 제한 ② 팀 내 리뷰 SLA(예: 영업일 기준 24시간 내 첫 리뷰) 설정 ③ 우선순위가 낮은 PR에 대해서는 비동기 리뷰 허용 ④ 자동화 도구로 스타일·포매팅 리뷰를 제거해서 사람 리뷰어가 로직에 집중하게 하는 것이다. 충분히 빠른 리뷰 프로세스를 갖추면 속도와 품질 모두를 잡을 수 있다.
주니어 개발자가 시니어 코드를 리뷰해도 괜찮을까요?
괜찮다. 코드 리뷰는 계층 구조가 없어야 한다. 주니어도 코드를 읽고 이해하지 못하는 부분이 있다면 질문 형태의 코멘트를 달 수 있고, 그 자체로 유의미한 피드백이다. "이 부분이 이해가 안 가는데 설명해 주시면 좋겠습니다"라는 코멘트는 코드가 설명 없이는 이해하기 어렵다는 신호다. 실제로 시니어가 자신의 코드에 주니어 리뷰어가 질문을 달았을 때 코드를 더 명확하게 고치는 경우가 많다.
AI가 생성한 코드는 리뷰를 생략해도 되지 않나요?
오히려 반대다. AI 생성 코드는 리뷰를 더 꼼꼼하게 해야 한다. AI는 프로젝트 컨텍스트를 완전히 이해하지 못하기 때문에 비즈니스 로직을 잘못 구현하거나, 기존 유틸리티와 중복되거나, 인가 로직을 빠뜨리는 경우가 있다. "AI가 썼으니 맞겠지"라는 가정이 프로덕션 장애로 이어진 사례가 실제로 존재한다. AI는 코드 생성 도구이고, 최종 책임은 PR 작성자와 리뷰어에게 있다.
코드 리뷰PR체크리스트GitHubAI 코딩 도구보안테스트클로드 코드커서깃허브 코파일럿개발자협업
