# [[Pull Request Best Practices (PR 베스트 프랙티스)|Pull Request Best Practices (PR 베스트 프랙티스]]

## 📌 Brief Summary
Pull Request(PR) 베스트 프랙티스는 코드 변경 사항을 메인 브랜치에 통합하기 전, 리뷰와 검증 과정을 효율화하고 품질을 높이기 위한 핵심 활동 지침입니다 [1]. PR을 작고 응집력 있는 단위(200~400 LOC 이하)로 유지하고, 템플릿을 활용해 변경 맥락을 명확히 전달하며, 자동화된 도구와 결합하여 리뷰어의 인지 부하를 최소화하는 것을 목표로 합니다 [2, 5]. 이는 결함 발견율을 높이고 배포 주기를 단축하며 팀의 협업 생산성을 극대화하는 기반이 됩니다.

## 📖 Core Content
*   **작은 PR 유지 (Small Pull Requests):**
    *   **규모와 품질의 상관관계:** 변경 사항이 400줄(LOC)을 초과하면 리뷰어의 집중력이 급격히 하락하여 결함 발견율이 낮아집니다 [1, 6]. 200~400줄 사이일 때 가장 높은 결함 발견율(66~75%)을 보입니다 [3].
    *   **단일 목적 원칙:** 하나의 PR은 기능 추가, 버그 수정, 리팩토링 중 단 하나의 명확한 목적만을 다루어야 합니다 [10, 11]. 관련 없는 여러 변경을 묶는 '주방 싱크대(Kitchen sink)' 방식의 PR은 리뷰를 어렵게 만듭니다.
    *   **분할 전략:** 거대한 기능 구현 시 '기능 토글(Feature Flags)'이나 '스택 PR(Stacked PRs)' 기법을 활용해 논리적으로 쪼개어 점진적으로 병합합니다 [14, 15].
*   **PR 템플릿(PR Templates) 활용:**
    *   **정보 구조화:** 변경 이유(Why), 해결 방법(How), 영향 범위, 테스트 결과, 체크리스트 등을 표준화된 형식으로 제공합니다.
    *   **리뷰어 가이드:** 스크린샷, 관련 이슈 링크, 재현 방법 등을 포함하여 리뷰어가 변경 맥락을 즉각 파악할 수 있게 돕습니다.
*   **초안 PR (Draft PR) 활용:**
    *   구현이 완료되지 않았더라도 초기 설계 단계에서 미리 PR을 Draft 상태로 공유하여, 방향성에 대한 조기 피드백을 받고 중복 작업을 방지합니다.
*   **원자적 커밋 (Atomic Commits):**
    *   논리적으로 나눌 수 없는 최소 단위의 변경을 커밋으로 유지하여, 리뷰어가 커밋 단위로 변경 이력을 추적하기 쉽게 만듭니다.

## ⚖️ Trade-offs & Caveats
*   **전체 맥락 파악의 어려움:** PR을 작게 쪼개면 개별 리뷰는 쉬워지나, 대규모 아키텍처 변경 시 '큰 그림'을 한 번에 파악하기 힘들 수 있습니다 [17]. 이를 위해 전체 설계를 다루는 RFC(Request for Comments)나 설계 문서를 선행 공유해야 합니다.
*   **관리 오버헤드:** 작업을 세밀하게 나누기 위한 사전 계획과 규율이 필요하며, 관리해야 할 PR 수가 늘어나는 비용이 발생합니다 [18].
*   **유연한 기준 적용:** 기능 변경이 없는 단순 리팩토링(포맷팅 일괄 변경 등)은 400줄 제한을 예외적으로 허용하는 등 상황에 맞는 유연함이 필요합니다 [6].

## 🔗 Knowledge Connections

### Related Concepts
*   **[[Feature-Flags|Feature Flags]]**: 미완성 기능을 사용자에게 노출하지 않고 지속적으로 작은 PR을 병합할 수 있게 돕는 핵심 도구입니다.
*   **Stacked Pull Requests**: 상호 의존적인 여러 변경 사항을 논리적 단계로 나누어 리뷰 흐름을 관리하는 워크플로우입니다.
*   **Defect Density**: PR 크기와 결함 발견율 사이의 상관관계를 보여주는 정량적 품질 지표입니다.
*   **Time to Review (TTR**: 작은 PR을 통해 최소화하고자 하는 코드 리뷰 병목 시간 지표입니다.

### Deeper Research Questions
*   언어별 표현력 차이(장황한 Java vs 간결한 Python)에 따라 '작은 PR'의 기준(LOC)을 어떻게 차등 적용하는 것이 합리적인가?
*   Stacked PR 기법 사용 시 발생하는 브랜치 간 의존성 관리 및 병합 복잡성을 해결하기 위한 최적의 도구 체계는 무엇인가?
*   PR 템플릿에 AI를 결합하여 변경 사항을 자동으로 요약하고 위험도를 평가해주는 기능의 실질적 효용성은 어느 정도인가?
*   리뷰어 할당 시 로직의 복잡도와 변경 범위를 고려하여 가장 적합한 리뷰어를 자동 매칭해주는 알고리즘은 어떻게 설계하는가?
*   작은 PR들이 모여 하나의 큰 기능을 구성할 때, 개별 리뷰에서 놓친 통합 단계의 구조적 결함을 최종 검증하기 위한 '게이트 키핑' 전략은 무엇인가?

### Practical Application Contexts
*   **Implementation:** 작업을 시작하기 전 200~400 LOC 이내의 논리적 단위로 세분화하고 단일 목적의 커밋을 작성합니다 [50].
*   **System Design:** 미완성 코드도 안전하게 병합할 수 있도록 시스템 아키텍처에 기능 토글을 내장합니다 [51].
*   **Operation / Maintenance:** 문제 발생 시 원인이 된 작은 PR 단위로 신속하게 롤백(Revert)하여 서비스 복구 시간을 단축합니다 [52].
*   **Learning Path:** 신규 입사자에게 작은 PR 작성을 훈련시켜 빠르고 구체적인 코드 품질 피드백을 주고받는 온보딩 문화를 구축합니다 [53].
*   **My Project Relevance:** GitHub Actions를 활용해 PR 크기가 기준을 초과할 경우 자동으로 경고를 남기거나 병합을 제한하는 품질 게이트를 적용합니다.

### Adjacent Topics
*   **[[Continuous Integration (CI)|Continuous Integration (CI]]**: 빈번하고 작은 단위의 병합이 어떻게 지속적 통합의 신뢰성을 높이는지 탐구합니다.
*   **Conventional Commits**: 커밋 메시지를 표준화하여 변경 이력의 가독성을 높이는 전략으로 확장됩니다.

---
*Last updated: 2026-05-02*
