Git & GitHub 협업 마스터 4편: Pull Request와 코드 리뷰

Pull Request and Code Review - The Heart of Team Collaboration

2026-01-22 IT/기술

들어가며: PR과 코드 리뷰가 중요한 이유

이전 글에서 브랜치 전략에 대해 알아보았습니다. 브랜치를 잘 나누고 관리하는 것도 중요하지만, 결국 그 브랜치들이 합쳐지는 과정에서 팀의 협업 품질이 결정됩니다. 바로 여기서 Pull Request(PR)와 코드 리뷰가 핵심 역할을 합니다.

솔직히 말하면, 처음 개발을 시작할 때는 PR이나 코드 리뷰가 번거롭게 느껴질 수 있습니다. "내가 작성한 코드를 왜 다른 사람한테 보여줘야 하지?", "그냥 바로 머지하면 안 되나?" 같은 생각이 들 수도 있죠. 하지만 경험이 쌓일수록 PR과 코드 리뷰가 얼마나 귀중한 프로세스인지 깨닫게 됩니다.

잘 운영되는 코드 리뷰 문화는 버그를 조기에 발견하고, 지식을 공유하며, 코드 품질을 일관되게 유지하는 데 결정적인 역할을 합니다. 이번 글에서는 PR의 기본부터 효과적인 코드 리뷰 방법, 그리고 GitHub의 다양한 기능들까지 실무에서 바로 활용할 수 있는 내용들을 다루겠습니다.

1. Pull Request란 무엇인가

1.1 PR의 개념

Pull Request(PR)는 "내 브랜치의 변경사항을 다른 브랜치에 병합해 달라"고 요청하는 것입니다. 단순히 코드를 합치는 것을 넘어서, 팀원들에게 "이런 변경을 했으니 확인해 주세요"라고 알리는 의사소통 도구이기도 합니다.

GitLab에서는 Merge Request(MR)라고 부르고, Bitbucket에서도 Pull Request라고 합니다. 이름은 다르지만 본질적으로 같은 개념입니다.

1.2 PR의 역할

코드 리뷰의 장: 팀원들이 코드를 검토하고 피드백을 주고받는 공간입니다.
변경 이력 문서화: 왜 이런 변경이 필요했는지, 어떤 방식으로 구현했는지 기록됩니다.
품질 게이트: 자동화된 테스트와 검사를 통과해야만 병합할 수 있도록 설정할 수 있습니다.
지식 공유: 다른 팀원의 코드를 보면서 새로운 기술이나 패턴을 배울 수 있습니다.

1.3 PR 생성하기

GitHub에서 PR을 생성하는 방법은 여러 가지가 있습니다.

# 1. 브랜치를 원격에 푸시
git push origin feature/user-profile

# 2-1. GitHub 웹에서 PR 생성
# 브랜치를 푸시하면 GitHub에서 "Compare & pull request" 버튼이 나타남

# 2-2. GitHub CLI로 PR 생성
gh pr create --title "Add user profile feature" --body "사용자 프로필 기능을 추가합니다."

# 2-3. 대화형으로 PR 생성
gh pr create

2. 좋은 PR 작성법

2.1 좋은 PR 제목 작성하기

PR 제목은 변경사항을 한눈에 파악할 수 있도록 명확하게 작성해야 합니다.

좋은 예시:

feat: 사용자 프로필 페이지 추가
fix: 로그인 시 세션 만료 오류 수정
refactor: 결제 모듈 코드 구조 개선
docs: API 문서에 인증 섹션 추가

피해야 할 예시:

수정 - 무엇을 수정했는지 알 수 없음
WIP - 작업 중이라는 것 외에 정보가 없음
asdf - 의미 없는 제목

2.2 효과적인 PR 설명 작성하기

PR 설명(body)은 리뷰어가 변경사항을 이해하는 데 필수적인 정보를 담아야 합니다.

## 변경 사항
- 사용자 프로필 조회 API 엔드포인트 추가 (`GET /api/users/:id/profile`)
- 프로필 수정 API 엔드포인트 추가 (`PUT /api/users/:id/profile`)
- 프로필 이미지 업로드 기능 구현

## 변경 이유
사용자들이 자신의 프로필 정보를 관리할 수 있는 기능이 필요했습니다.
기존에는 관리자만 사용자 정보를 수정할 수 있었는데,
이제 사용자가 직접 프로필을 관리할 수 있습니다.

## 테스트 방법
1. 로그인 후 `/profile` 페이지 접속
2. 프로필 정보 수정 후 저장 버튼 클릭
3. 새로고침 후 변경사항이 유지되는지 확인

## 스크린샷
(해당되는 경우 UI 변경 스크린샷 첨부)

## 체크리스트
- [x] 단위 테스트 작성
- [x] E2E 테스트 통과
- [x] 문서 업데이트
- [ ] 성능 테스트 (대용량 이미지 업로드)

2.3 PR 크기 관리

작은 PR이 좋은 PR입니다. 연구에 따르면 200-400줄 정도의 변경사항이 가장 효과적인 리뷰를 받을 수 있다고 합니다.

작은 PR의 장점: 리뷰가 빠르고, 버그 발견 확률이 높으며, 롤백이 쉽습니다.
큰 PR의 문제: 리뷰어가 지치고, 중요한 이슈를 놓치기 쉬우며, 충돌 가능성이 높습니다.

큰 기능은 여러 개의 작은 PR로 나누세요. 예를 들어 "사용자 프로필 기능"을:

데이터베이스 스키마 변경
백엔드 API 구현
프론트엔드 UI 구현
테스트 및 문서화

이렇게 4개의 PR로 나눌 수 있습니다.

3. PR 템플릿 만들기

3.1 PR 템플릿의 필요성

팀에서 일관된 형식의 PR을 작성하도록 템플릿을 만들어 두면 여러 이점이 있습니다:

필수 정보 누락 방지
리뷰어의 이해 시간 단축
팀 전체의 문서화 품질 향상

3.2 PR 템플릿 생성 방법

프로젝트 루트에 .github/pull_request_template.md 파일을 생성합니다.

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

## 개요
<!-- 이 PR이 무엇을 해결하는지 간단히 설명해 주세요 -->

## 변경 사항
<!-- 주요 변경 사항을 목록으로 작성해 주세요 -->
-
-
-

## 관련 이슈
<!-- 관련된 이슈 번호를 링크해 주세요 (예: Closes #123) -->

## 테스트
<!-- 테스트 방법을 설명해 주세요 -->

## 스크린샷
<!-- UI 변경이 있다면 스크린샷을 첨부해 주세요 -->

## 체크리스트
- [ ] 테스트 코드 작성 완료
- [ ] 문서 업데이트 완료
- [ ] 코드 스타일 가이드 준수
- [ ] Self-review 완료

3.3 여러 개의 템플릿 사용하기

기능, 버그 수정, 문서 등 PR 종류에 따라 다른 템플릿을 사용할 수 있습니다.

.github/
  PULL_REQUEST_TEMPLATE/
    feature.md
    bugfix.md
    documentation.md

PR 생성 시 URL에 ?template=feature.md를 추가하면 특정 템플릿을 선택할 수 있습니다.

4. 코드 리뷰의 중요성

4.1 코드 리뷰의 목적

코드 리뷰는 단순히 버그를 찾는 것 이상의 가치를 제공합니다:

버그 조기 발견: 프로덕션에 배포되기 전에 문제를 발견합니다.
지식 공유: 팀원들이 서로의 코드를 이해하고 배웁니다.
코드 품질 유지: 일관된 코딩 스타일과 패턴을 유지합니다.
설계 검증: 구현 방식이 적절한지 확인합니다.
팀 문화 형성: 건설적인 피드백 문화를 만듭니다.

4.2 코드 리뷰의 통계적 효과

여러 연구에서 코드 리뷰의 효과가 입증되었습니다:

코드 리뷰를 통해 버그의 60-90%를 사전에 발견할 수 있습니다.
리뷰된 코드는 그렇지 않은 코드보다 결함 밀도가 30% 낮습니다.
코드 리뷰에 투자한 시간 대비 버그 수정에 드는 시간이 4-8배 절감됩니다.

5. 효과적인 코드 리뷰 방법

5.1 리뷰 전 준비

효과적인 리뷰를 위해 먼저 맥락을 파악하세요:

PR 설명과 관련 이슈를 읽습니다.
변경된 파일 목록을 훑어봅니다.
전체 변경 규모를 파악합니다.
어떤 부분에 집중할지 계획합니다.

5.2 리뷰 시 확인할 사항

기능적 측면:

요구사항을 충족하는가?
엣지 케이스가 처리되었는가?
에러 처리가 적절한가?

코드 품질:

읽기 쉽고 이해하기 쉬운가?
중복 코드는 없는가?
네이밍이 명확한가?
함수/클래스가 단일 책임 원칙을 따르는가?

성능 및 보안:

성능 문제가 될 수 있는 부분은 없는가?
보안 취약점이 있는가?
민감한 정보가 노출되지 않는가?

테스트:

테스트가 충분한가?
테스트가 의미 있는 케이스를 커버하는가?

5.3 리뷰 시간 관리

효과적인 리뷰를 위한 시간 관리 팁:

한 번에 200-400줄: 너무 긴 리뷰는 집중력이 떨어집니다.
60분 이내: 한 세션은 60분을 넘기지 않습니다.
24시간 내 첫 리뷰: PR이 오래 방치되면 맥락을 잃습니다.
고정 시간 할당: 매일 일정 시간을 코드 리뷰에 할당합니다.

6. 좋은 피드백 주기

6.1 건설적인 피드백의 원칙

코드 리뷰에서 가장 중요한 것은 건설적인 태도입니다. 몇 가지 원칙을 기억하세요:

코드를 비판하지, 사람을 비판하지 마세요: "이 코드는..."이 아니라 "여기서..."라고 표현합니다.
질문 형태로 제안하세요: "이 방식은 어떨까요?" 형태가 "이렇게 해"보다 낫습니다.
이유를 설명하세요: 단순히 "바꿔 주세요"가 아니라 왜 그런지 설명합니다.
좋은 점도 언급하세요: 잘한 부분에 대한 칭찬도 피드백입니다.

6.2 피드백 예시

좋지 않은 피드백:

이거 왜 이렇게 짰어요? 너무 복잡해요.

좋은 피드백:

이 로직이 조금 복잡해 보이는데, 가독성을 위해 별도 함수로
분리하면 어떨까요? 예를 들어:

function calculateDiscount(price, userType) {
  // 할인 로직
}

이렇게 하면 나중에 할인 정책이 바뀌어도
이 함수만 수정하면 될 것 같습니다.

6.3 피드백 분류하기

피드백의 중요도를 표시하면 작성자가 우선순위를 파악하기 쉽습니다:

[필수] 또는 [Blocker]: 반드시 수정해야 병합 가능
[제안] 또는 [Optional]: 고려해 보면 좋을 것 같은 사항
[질문]: 이해를 위한 질문
[칭찬] 또는 [Nice!]: 잘한 부분
[Nit]: 사소한 지적 (오타, 스타일 등)

7. GitHub의 리뷰 기능 활용

7.1 세 가지 리뷰 상태

GitHub에서 PR 리뷰를 제출할 때 세 가지 상태 중 하나를 선택합니다:

상태	의미	사용 시점
Comment	일반 코멘트	질문이나 논의가 필요할 때
Approve	승인	병합해도 좋다고 판단될 때
Request changes	변경 요청	수정이 필요할 때

7.2 라인별 코멘트

GitHub에서는 특정 코드 라인에 직접 코멘트를 달 수 있습니다. 이 기능을 활용하면:

정확히 어떤 부분에 대한 피드백인지 명확합니다.
코드 변경 시 해당 코멘트가 자동으로 "outdated"로 표시됩니다.
여러 라인을 선택하여 코멘트를 달 수 있습니다.

7.3 Suggestion 기능

GitHub의 Suggestion 기능을 사용하면 수정 제안을 코드로 직접 보여줄 수 있습니다:

```suggestion
const userAge = calculateAge(birthDate);
```

작성자는 이 제안을 클릭 한 번으로 바로 적용할 수 있어 매우 편리합니다.

7.4 리뷰 일괄 제출

"Start a review" 버튼을 눌러 여러 코멘트를 모아서 한 번에 제출하세요. 코멘트를 하나씩 제출하면 작성자에게 알림이 여러 번 가서 방해가 될 수 있습니다.

8. Draft PR 활용하기

8.1 Draft PR이란

Draft PR은 "아직 작업 중이며 리뷰 준비가 되지 않은" PR입니다. 2019년에 GitHub에 도입된 기능으로, 여러 상황에서 유용하게 사용됩니다.

8.2 Draft PR 사용 사례

초기 피드백: 큰 방향이 맞는지 미리 확인받고 싶을 때
작업 공유: 팀원들에게 "이런 작업 중이야"라고 알릴 때
CI 테스트: 머지 전에 CI 파이프라인 테스트를 돌려보고 싶을 때
점진적 작업: 여러 날에 걸쳐 조금씩 작업을 진행할 때

8.3 Draft PR 생성 방법

# GitHub CLI로 Draft PR 생성
gh pr create --draft --title "WIP: 결제 시스템 리팩토링" --body "작업 중입니다."

# 또는 웹에서 PR 생성 시 "Create draft pull request" 선택

8.4 Draft에서 Ready로 변경

작업이 완료되면 Draft PR을 리뷰 가능 상태로 변경합니다:

# GitHub CLI로 상태 변경
gh pr ready

# 또는 웹에서 "Ready for review" 버튼 클릭

9. 자동화된 리뷰 설정

9.1 CODEOWNERS 설정

CODEOWNERS 파일을 사용하면 특정 파일이나 디렉토리에 대한 "소유자"를 지정할 수 있습니다. 해당 영역이 변경되면 지정된 사람이 자동으로 리뷰어로 할당됩니다.

# .github/CODEOWNERS

# 전체 코드베이스 기본 소유자
* @tech-lead

# 프론트엔드 코드
/frontend/ @frontend-team
*.jsx @frontend-team
*.tsx @frontend-team

# 백엔드 코드
/backend/ @backend-team
*.py @backend-team

# 인프라 설정
/infra/ @devops-team
Dockerfile @devops-team
docker-compose.yml @devops-team

# 문서
/docs/ @tech-writer
*.md @tech-writer

# 데이터베이스 마이그레이션 (특별 주의 필요)
/migrations/ @dba @tech-lead

9.2 Branch Protection Rules

GitHub의 Branch Protection 기능을 사용하면 PR 병합 전 필수 조건을 설정할 수 있습니다:

Require pull request reviews: 최소 1-2명의 승인 필요
Require status checks: CI 테스트 통과 필수
Require CODEOWNERS review: 코드 소유자의 승인 필수
Require conversation resolution: 모든 코멘트가 해결되어야 병합 가능
Require linear history: 깔끔한 히스토리 유지

9.3 자동 리뷰어 할당

GitHub Actions를 사용하면 더 복잡한 리뷰어 자동 할당 로직을 구현할 수 있습니다:

# .github/workflows/auto-assign.yml
name: Auto Assign Reviewers

on:
  pull_request:
    types: [opened, ready_for_review]

jobs:
  assign-reviewers:
    runs-on: ubuntu-latest
    steps:
      - uses: kentaro-m/auto-assign-action@v1.2.5
        with:
          configuration-path: '.github/auto_assign.yml'

# .github/auto_assign.yml
addReviewers: true
addAssignees: author

reviewers:
  - reviewer1
  - reviewer2
  - reviewer3

numberOfReviewers: 2
reviewGroups:
  frontendReviewers:
    - frontend-dev1
    - frontend-dev2
  backendReviewers:
    - backend-dev1
    - backend-dev2

10. PR 리뷰 문화 만들기

10.1 건강한 리뷰 문화의 특징

좋은 코드 리뷰 문화를 가진 팀의 특징:

빠른 피드백: PR이 24시간 이상 방치되지 않습니다.
존중하는 태도: 피드백이 공격적이지 않고 건설적입니다.
학습 지향: 리뷰를 통해 서로 배운다는 마음가짐이 있습니다.
명확한 기준: 어떤 것이 통과 가능한 코드인지 기준이 있습니다.
균형 잡힌 참여: 특정 사람에게 리뷰가 몰리지 않습니다.

10.2 리뷰 요청자의 책임

PR을 작성하는 사람도 리뷰어를 배려해야 합니다:

PR 크기를 작게 유지합니다.
충분한 설명을 작성합니다.
Self-review를 먼저 합니다.
테스트가 통과된 상태로 PR을 올립니다.
피드백에 열린 마음으로 대응합니다.

10.3 리뷰어의 책임

리뷰어도 책임감 있게 리뷰에 임해야 합니다:

신속하게 리뷰를 시작합니다.
집중해서 꼼꼼하게 확인합니다.
건설적인 피드백을 제공합니다.
사소한 것에 너무 집착하지 않습니다.
잘한 부분도 인정합니다.

마무리: PR과 코드 리뷰는 팀의 성장 엔진

지금까지 Pull Request 작성법부터 효과적인 코드 리뷰 방법, GitHub의 다양한 자동화 기능까지 살펴보았습니다. PR과 코드 리뷰는 단순히 코드를 합치기 위한 절차가 아닙니다. 이는 팀이 함께 성장하고, 더 나은 소프트웨어를 만들기 위한 핵심 프로세스입니다.

처음에는 번거롭게 느껴질 수 있지만, 잘 정착된 리뷰 문화는 장기적으로 엄청난 가치를 제공합니다. 버그가 줄어들고, 코드 품질이 향상되며, 팀원 모두가 코드베이스 전체를 이해하게 됩니다. 무엇보다 "함께 만든다"는 느낌이 팀의 결속력을 높여줍니다.

오늘 배운 내용을 바로 적용해 보세요. PR 템플릿을 만들고, CODEOWNERS를 설정하고, 다음 리뷰 때는 Suggestion 기능을 사용해 보세요. 작은 변화들이 모여 팀 전체의 협업 문화를 바꿀 수 있습니다.

다음 편에서는 GitHub의 이슈 관리와 프로젝트 보드 활용법에 대해 알아보겠습니다. Git & GitHub 시리즈를 계속 따라오시면 실무에서 바로 활용할 수 있는 협업 역량을 갖추실 수 있을 것입니다.

목록으로 돌아가기