onejaejae/pr-diff-summary

PR Diff Summary

PR의 diff를 분석하여 핵심 변경점을 3줄로 요약하고, 파일별로 구조화된 리뷰 요약을 생성한다.

---

사용법

PR 26번 요약해줘
PR diff 정리해줘 #123
이 PR 변경점 요약해줘

---

Workflow

Step 1: PR 정보 수집 (diff + metadata)
Step 2: 3-Line Executive Summary 생성
Step 3: 파일별 상세 분석 (What / Why / Risk)
Step 4: 최종 리포트 출력

모든 단계는 자동으로 진행되며, 사용자 승인 없이 한 번에 결과를 출력한다.

---

Step 1: PR 정보 수집

PR 번호가 주어진 경우

# PR 메타데이터
gh pr view <PR_NUMBER> --json title,body,files,additions,deletions,author,baseRefName,headRefName,labels

# PR diff (핵심)
gh pr diff <PR_NUMBER>

# 커밋 히스토리
gh pr view <PR_NUMBER> --json commits --jq '.commits[].messageHeadline'

로컬 브랜치인 경우

# base 브랜치 대비 diff
git diff main...HEAD

# 커밋 로그
git log main..HEAD --oneline

# 변경 파일 목록
git diff main...HEAD --stat

수집할 정보

• PR 제목, 설명, 작성자
• 전체 diff 내용
• 변경 파일 목록 및 각 파일의 additions/deletions
• 커밋 메시지들 (의도 파악용)

---

Step 2: 3-Line Executive Summary

diff 전체를 분석하여 정확히 3줄로 핵심을 요약한다.

작성 규칙

1. Line 1 - WHAT: 이 PR이 무엇을 하는가 (기능/수정/리팩토링)
2. Line 2 - HOW: 어떤 접근 방식으로 구현했는가 (핵심 기술적 변경)
3. Line 3 - IMPACT: 이 변경이 시스템에 미치는 영향 (사용자/성능/안정성)

출력 형식

## 3-Line Summary

1. [WHAT] 사용자 인증 플로우에 OAuth2 소셜 로그인 기능을 추가
2. [HOW] Google/GitHub provider를 strategy pattern으로 구현하고, 기존 세션 관리와 통합
3. [IMPACT] 신규 가입 전환율 개선 예상, 기존 이메일 로그인 플로우에는 영향 없음

---

Step 3: 파일별 상세 분석

변경된 각 파일(또는 논리적 파일 그룹)에 대해 3가지 관점으로 분석한다.

분석 관점

| 관점 | 설명 | 분석 방법 | |------|------|----------| | What Changed | 이 파일에서 구체적으로 무엇이 변경되었는가 | diff 내용 기반, 함수/클래스/설정 단위 | | Why It Matters | 이 변경이 왜 중요한가, 어떤 맥락인가 | PR 설명 + 커밋 메시지 + 코드 맥락 | | Risk Level | 이 변경의 위험도는 어느 정도인가 | 아래 Risk 판단 기준 참조 |

Risk Level 판단 기준

| Level | 기준 | 예시 | |-------|------|------| | LOW | 문서, 테스트, 설정값 변경, 리팩토링(동작 불변) | README 수정, 테스트 추가, 변수명 변경 | | MEDIUM | 기존 로직 수정, 새 기능 추가, 의존성 변경 | 새 API 엔드포인트, 비즈니스 로직 변경 | | HIGH | 인증/인가, 데이터 마이그레이션, 핵심 인프라, 삭제 | DB 스키마 변경, 보안 로직, 결제 로직 | | CRITICAL | 프로덕션 데이터 직접 접근, 보안 크리덴셜, 롤백 불가 변경 | 마이그레이션 스크립트, 환경변수 변경 |

Risk 판단 시 체크포인트

다음 항목 중 해당하는 것이 있으면 Risk를 한 단계 올린다:

• [ ] 에러 핸들링 없이 외부 서비스 호출
• [ ] 하위 호환성이 깨지는 API 변경
• [ ] 테스트 없는 비즈니스 로직 변경
• [ ] 동시성/레이스 컨디션 가능성
• [ ] 환경별 동작 차이 가능성 (dev/staging/prod)

파일 그룹핑 규칙

파일이 10개 이상일 때는 논리적으로 그룹핑한다:

• 같은 모듈/패키지의 파일 → 하나의 그룹
• 테스트 파일 → 별도 그룹
• 설정/인프라 파일 → 별도 그룹
• 문서 파일 → 별도 그룹

---

Step 4: 최종 리포트 출력

출력 템플릿

# PR #{number}: {title}
> Author: {author} | Files: {file_count} | +{additions}/-{deletions}

---

## 3-Line Summary

1. **[WHAT]** {한 줄 요약: 이 PR이 무엇을 하는가}
2. **[HOW]** {한 줄 요약: 어떻게 구현했는가}
3. **[IMPACT]** {한 줄 요약: 시스템에 미치는 영향}

---

## File-by-File Analysis

### {파일경로 또는 그룹명} (+{additions}/-{deletions})

| Aspect | Detail |
|--------|--------|
| **What Changed** | {구체적 변경 내용} |
| **Why It Matters** | {변경의 중요성과 맥락} |
| **Risk Level** | {LOW/MEDIUM/HIGH/CRITICAL} - {이유 한 줄} |

### {다음 파일...}
...

---

## Risk Heatmap

| Risk | Files |
|------|-------|
| CRITICAL | {파일 목록 또는 "없음"} |
| HIGH | {파일 목록 또는 "없음"} |
| MEDIUM | {파일 목록} |
| LOW | {파일 목록} |

---

## Reviewer Checklist

위 분석 기반으로, 리뷰어가 특히 주의해서 봐야 할 포인트:

- [ ] {HIGH/CRITICAL 파일에서 확인할 사항 1}
- [ ] {HIGH/CRITICAL 파일에서 확인할 사항 2}
- [ ] {테스트 커버리지 관련 사항}

---

대규모 PR 처리

파일 수 > 20개

파일이 20개를 넘으면:

1. --stat 출력을 먼저 분석하여 변경량 기준 상위 10개 파일에 집중
2. 나머지는 그룹 단위로 요약
3. 리포트 상단에 "대규모 PR - 핵심 파일 중심 분석" 표기

Diff가 너무 클 때

diff가 1000줄을 넘으면:

1. gh pr diff 대신 gh pr view --json files로 파일 목록 먼저 확인
2. HIGH risk 가능성이 있는 파일의 diff만 선택적으로 조회:

   gh pr diff <PR_NUMBER> -- <specific_file_path>
   

3. LOW risk 파일(문서, 테스트)은 stat 정보만으로 요약

---

Examples

예시 1: 소규모 기능 추가 PR

# PR #42: feat: 사용자 프로필 이미지 업로드 기능

> Author: kim | Files: 4 | +120/-15

---

## 3-Line Summary

1. **[WHAT]** 사용자 프로필 페이지에 이미지 업로드 기능을 추가
2. **[HOW]** S3 presigned URL 방식으로 클라이언트 직접 업로드 구현, 서버는 URL 발급만 담당
3. **[IMPACT]** 새 기능 추가로 기존 플로우 영향 없음, S3 버킷 설정 필요

---

## File-by-File Analysis

### src/api/profile.py (+45/-5)

| Aspect | Detail |
|--------|--------|
| **What Changed** | `upload_profile_image` 엔드포인트 추가, presigned URL 생성 로직 |
| **Why It Matters** | 핵심 비즈니스 로직, 파일 크기/타입 검증 포함 |
| **Risk Level** | MEDIUM - 새 API 엔드포인트, S3 연동 |

### src/services/s3.py (+55/-0)

| Aspect | Detail |
|--------|--------|
| **What Changed** | S3 presigned URL 생성 서비스 클래스 신규 |
| **Why It Matters** | 외부 서비스(AWS) 연동, 크리덴셜 관리 |
| **Risk Level** | HIGH - AWS 크리덴셜 사용, 에러 핸들링 확인 필요 |

### src/models/user.py (+5/-5)

| Aspect | Detail |
|--------|--------|
| **What Changed** | User 모델에 `profile_image_url` 필드 추가 |
| **Why It Matters** | DB 스키마 변경 |
| **Risk Level** | MEDIUM - 마이그레이션 필요 |

### tests/test_profile.py (+15/-5)

| Aspect | Detail |
|--------|--------|
| **What Changed** | 업로드 API 테스트 3건 추가 |
| **Why It Matters** | 핵심 로직 테스트 커버리지 |
| **Risk Level** | LOW - 테스트 코드 |

---

## Risk Heatmap

| Risk | Files |
|------|-------|
| CRITICAL | 없음 |
| HIGH | src/services/s3.py |
| MEDIUM | src/api/profile.py, src/models/user.py |
| LOW | tests/test_profile.py |

---

## Reviewer Checklist

- [ ] s3.py: AWS 크리덴셜이 환경변수로 관리되는지 확인
- [ ] s3.py: presigned URL 만료 시간 적절한지 확인
- [ ] profile.py: 파일 크기/타입 검증 로직 우회 가능성 확인
- [ ] user.py: DB 마이그레이션 스크립트 포함 여부 확인

예시 2: 대규모 리팩토링 PR

# PR #89: refactor: 레거시 인증 모듈을 새 아키텍처로 마이그레이션

> Author: park | Files: 23 | +450/-380

---

## 3-Line Summary

1. **[WHAT]** 레거시 세션 기반 인증을 JWT + refresh token 아키텍처로 전면 교체
2. **[HOW]** 기존 AuthManager를 TokenService/SessionService로 분리하고, middleware 체인 재구성
3. **[IMPACT]** 인증 전체 플로우 변경으로 모든 API 엔드포인트에 영향, 하위 호환 레이어 포함

---

## File-by-File Analysis

### Auth Core (src/auth/) (+200/-180) - 5 files

| Aspect | Detail |
|--------|--------|
| **What Changed** | AuthManager 삭제, TokenService/SessionService 신규, JWT 발급/검증 로직 |
| **Why It Matters** | 인증 시스템의 핵심 변경, 모든 API에 영향 |
| **Risk Level** | CRITICAL - 인증/인가 핵심 로직 전면 교체 |

### Middleware (src/middleware/) (+80/-60) - 3 files

| Aspect | Detail |
|--------|--------|
| **What Changed** | auth middleware 체인 재구성, JWT 검증 미들웨어 추가 |
| **Why It Matters** | 모든 요청의 인증 처리 경로 변경 |
| **Risk Level** | HIGH - 미들웨어 순서 오류 시 전체 API 영향 |

### Tests (tests/auth/) (+120/-90) - 8 files

| Aspect | Detail |
|--------|--------|
| **What Changed** | 기존 세션 테스트 삭제, JWT 기반 테스트 전면 재작성 |
| **Why It Matters** | 새 인증 로직의 정합성 검증 |
| **Risk Level** | LOW - 테스트 코드 |

### Config & Migration (+50/-50) - 7 files

| Aspect | Detail |
|--------|--------|
| **What Changed** | JWT 관련 환경변수, DB 마이그레이션(refresh_token 테이블) |
| **Why It Matters** | 배포 시 환경 설정 필요, 롤백 시 DB 고려 |
| **Risk Level** | HIGH - 환경변수 누락 시 장애, 마이그레이션 롤백 복잡 |

---

## Risk Heatmap

| Risk | Files |
|------|-------|
| CRITICAL | src/auth/ (5 files) |
| HIGH | src/middleware/ (3 files), config & migration (7 files) |
| MEDIUM | 없음 |
| LOW | tests/ (8 files) |

---

## Reviewer Checklist

- [ ] auth/: JWT secret rotation 전략 확인
- [ ] auth/: refresh token 만료/갱신 로직 검증
- [ ] middleware/: 미들웨어 체인 순서 정확한지 확인
- [ ] migration/: 롤백 마이그레이션 포함 여부
- [ ] config/: 모든 환경(dev/staging/prod) 환경변수 매핑 확인
- [ ] 하위 호환: 기존 세션 토큰 보유 사용자 처리 방안 확인
- [ ] 전체: 통합 테스트에서 인증 플로우 end-to-end 검증

---

주의사항

1. 요약은 정확히 3줄: 3줄을 넘기지 않는다. 핵심만 압축한다.
2. Risk는 보수적으로: 판단이 애매하면 한 단계 높게 평가한다.
3. Why It Matters는 비즈니스 관점: 기술적 설명보다 "왜 이게 중요한지"에 초점을 둔다.
4. 커밋 메시지 활용: PR 설명이 부실할 때 커밋 메시지에서 의도를 파악한다.
5. 그룹핑은 유연하게: 관련 파일은 묶되, 중요한 파일은 개별 분석한다.