원활한 코드 리뷰는 팀 생산성을 좌우합니다. 이 문서는 develop 브랜치를 대상으로 PR을 열 때 따라야 하는 공통 규칙과 템플릿을 제공합니다. 리뷰어가 코드를 열어보기 전에 변경의 맥락과 영향을 이해할 수 있도록 명확함·구체성·재현 가능성을 최우선으로 두세요.
✅ 핵심 원칙
- 작은 단위로 자주 PR을 만듭니다.
- 의도와 영향이 코드만큼 또렷해야 합니다.
- 실행 가능한 증빙(테스트, 스크린샷, 로그)을 남깁니다.
| 항목 | 명령어 / 방법 | 목적 |
|---|---|---|
| 최신 브랜치 반영 | git fetch origin && git rebase origin/develop |
충돌 최소화, 변경 내역 선명하게 유지 |
| 실제 diff 확인 | git diff develop |
PR 본문은 이 diff를 기준으로 작성 |
| 커밋 정리 | git log --oneline develop..HEAD |
히스토리가 너무 많다면 rebase -i로 정리 |
| 기본 테스트 | ./gradlew test 또는 모듈별 테스트 명령 |
최소 신뢰선 확보 |
| 정적 검사 | ./gradlew check/lint 등 |
자동화된 규칙 위반 여부 확인 |
테스트나 빌드가 오래 걸린다면 GitHub Actions 결과 링크를 본문에 포함해 리뷰어가 즉시 확인할 수 있게 합니다.
[타입] 요약 설명
| 타입 | 의미 |
|---|---|
Feat |
신규 기능, API, UI |
Fix |
버그 수정, 핫픽스 |
Refactor |
구조/성능 개선 (동작 변화 없음) |
Docs |
문서만 변경 |
Test |
테스트 코드 추가/수정 |
Chore |
빌드, 의존성, CI 설정 |
Style |
포매팅, 네이밍 등 비기능 변경 |
예) [Feat] 질문 조회 API 추가
- 모든 상위 섹션은
#(h1)으로 시작합니다. - 하위 항목은
##(h2), 세부 단계는###(h3)를 사용합니다. - 볼드체/인라인 텍스트로 제목을 흉내 내지 마세요.
# 📝 어떤 변경인가요?
## 주요 기능
- 항목 1
- 항목 2
## 변경된 파일/모듈
| 파일 혹은 모듈 | 설명 |
| --- | --- |
| ... | ... |
# 🎯 왜 필요한가요?
- 비즈니스/사용자 가치
- 해결하려는 문제, 전후 비교
# ⚙️ 어떻게 구현했나요?
## 접근 방식
- 설계 요약, 대안 비교
## 성능/보안/데이터 영향
- DB 마이그레이션, 캐시, 외부 연동 등
# 🔍 어떻게 테스트했나요?
## 시나리오
1. 스텝
2. 기대 결과
## 명령어 / 증빙
- `./gradlew test`
- Postman 캡처, 로그 링크 등
# ⚠️ 특이 사항
- 배포 전 필요한 사전 작업
- 롤백 전략, 가드 플래그필요 시 섹션을 추가하되, 상위 구조는 유지합니다.
- 기능 단위로 bullet을 작성하고, API/엔드포인트/모듈명을 명시합니다.
- 아래 예시처럼 표를 활용하면 리뷰어가 영향 범위를 빠르게 파악할 수 있습니다.
| 영역 | 변경 내용 |
|---|---|
OnqeustionController |
PDF 내보내기 엔드포인트 추가 |
PdfExportService |
대량 데이터 스트리밍 처리 로직 추가 |
- 해결하려는 문제를 데이터나 현상으로 설명합니다.
예) "자신이 답변한 데이터를 앱 이외에서 볼 수 없다는 문제 발생" - 구독 기능에 Pdf로 자신의 답변을 다운 받을 수 있도록 기능을 추가하여 문제를 해결 합니다.
- 핵심 흐름(시퀀스, 주요 클래스, 정책)을 간결히 요약합니다.
- 구조가 복잡하다면 다이어그램 혹은 의사코드 링크를 첨부하세요.
- 외부 시스템/시크릿/인프라 영향이 있다면 섹션을 분리해 설명합니다.
- 수동 테스트라면 시나리오 + 기대 결과를 목록으로 작성합니다.
- 자동화 테스트는 커맨드와 결과 요약을 표로 보여줍니다.
| 명령어 | 목적 | 결과 |
|---|---|---|
./gradlew :api:test |
단위 테스트 | ✅ Pass |
./gradlew integrationTest |
통합 테스트 |
다음 중 하나라도 해당하면 구체적으로 밝힙니다.
- 데이터베이스 마이그레이션, 백필 작업, 롤백 전략
- 환경 변수/시크릿 추가, 인프라 권한 변경
- 성능 병목이나 임시 제한 사항
- 브레이킹 체인지 여부 및 소비자 영향
- 400라인 이상의 대규모 PR이 예상되면 미리 이슈에서 설계안을 공유하고, PR은 구현 자체에 집중합니다.
- 리뷰어 지정 시, 도메인 담당 + 코드 사용자 두 명 이상을 기본으로 합니다.
- PR 설명이 길다면 요약 bullet(3줄 내외)을 최상단에 두고, 상세 내용은 하위 섹션에 배치하세요.
- 리뷰가 지연되면 코멘트로 친절하게 컨텍스트를 리마인드하거나 Slack/팀 채널에서 상황을 공유합니다.
-
git diff develop를 기준으로 본문을 작성했다. - 제목 형식
[타입] 내용을 지켰다. - 필수 섹션(어떤 변경/왜/어떻게/테스트/특이 사항/이슈)을 모두 채웠다.
- 테스트·빌드 결과를 첨부했다.
- 배포/롤백/권한 변경 사항을 명시했다.
- 불필요한 커밋이나 디버깅 코드가 남아있지 않다.
- PR 설명과 실제 diff가 일치하는지 확인했다.
- 요구사항/이슈와 연결되어 있는지 확인했다.
- 테스트 증빙이 충분한지, 누락된 시나리오가 없는지 확인했다.
- 새로운 위험 요소(성능, 보안, 운영)를 질문했다.
- 이해가 어려운 부분에는 반드시 질문 코멘트를 남겼다.
- 명확성: 비기술자도 읽고 변경 목적을 이해할 수 있다.
- 구체성: 함수명, 엔드포인트, 지표, 로그 등 실체가 있다.
- 재현성: 테스트 방법이 명시되어 리뷰어가 바로 실행할 수 있다.
- 배려: 리뷰어 시간을 고려해 TL;DR와 근거 자료를 제공한다.
- 추적성: 이슈/문서/실험과 링크되어 히스토리를 남긴다.
# 로컬 작업 브랜치 생성
git switch -c feature/123-awesome-change
# 최신 develop 기반으로 정리
git fetch origin
git rebase origin/develop
# 정리된 브랜치 강제 푸시 (실수 방지용 옵션 포함)
git push --force-with-lease
# PR용 diff 다시 확인
git diff develop이 가이드를 팀 컨벤션으로 삼고, 상황에 맞는 템플릿/체크리스트를 지속적으로 개선해주세요. 좋은 PR은 빠른 리뷰와 안정적인 배포를 만듭니다. 🚀