onejaejae/pr-reviewer

PR Reviewer

PR을 체계적으로 리뷰하기 위한 워크플로우와 체크리스트. 일관된 관점에서 누락 없이 리뷰하고, 건설적인 피드백을 작성한다.

Workflow

PR 리뷰는 4단계로 진행. 각 단계마다 사용자 승인 후 다음 단계로 진행.

Step 1: PR 정보 수집 → 요약 출력 → [승인 대기]
Step 2: 변경사항 분석 → 분석 결과 출력 → [승인 대기]
Step 3: 관점별 리뷰 → 발견사항 출력 → [승인 대기]
Step 4: 코멘트 정리 → 코멘트 목록 출력 → [승인 대기] → 제출
Step 5: 리뷰 파일 저장 → .dev/pr-reviews/{id}-review.md (file handoff)

---

Step 1: PR 정보 수집

GitHub PR URL인 경우

gh pr view <PR_NUMBER> --json title,body,files,additions,deletions
gh pr diff <PR_NUMBER>

로컬 브랜치인 경우

git diff main...<branch>
git log main..<branch> --oneline

파악할 컨텍스트

• PR 제목과 설명 (의도 파악)
• 연관된 이슈 번호
• 변경 파일 수와 라인 수
• 변경 유형: 새 기능 / 버그 수정 / 리팩토링 / 문서

→ 승인 대기

수집한 정보를 요약하여 출력:

PR #123: [제목]
- 변경: N개 파일, +100/-50줄
- 유형: 새 기능
- 설명: [PR 설명 요약]

이 PR을 리뷰할까요?

사용자 승인 후 Step 2로 진행.

---

Step 2: 변경사항 분석

변경 규모 평가

| 규모 | 기준 | 리뷰 전략 | |------|------|----------| | 소형 | <100줄, <5파일 | 전체 상세 리뷰 | | 중형 | 100-500줄, 5-15파일 | 핵심 로직 집중 | | 대형 | >500줄, >15파일 | 아키텍처 중심, 분할 요청 제안 |

리뷰 우선순위

1. 비즈니스 로직 변경
2. API/인터페이스 변경
3. 보안 관련 코드
4. 테스트 코드
5. 설정/문서 변경

→ 승인 대기

분석 결과를 출력:

규모: 중형 (150줄, 8파일)
전략: 핵심 로직 집중 리뷰

리뷰 순서:
1. src/auth.py - 인증 로직 변경
2. src/api/users.py - API 엔드포인트
3. tests/test_auth.py - 테스트

이 순서로 리뷰를 진행할까요?

사용자 승인 후 Step 3로 진행.

---

Step 3: 관점별 리뷰

각 관점에서 순차적으로 검토. 발견사항은 바로 기록.

3.1 코드 품질

• [ ] 변수/함수/클래스 이름이 의도를 명확히 표현하는가?
• [ ] 함수가 한 가지 일만 하는가? (SRP)
• [ ] 중복 코드가 있는가?
• [ ] 복잡도가 높은 부분이 있는가? (깊은 중첩, 긴 함수)
• [ ] 프로젝트 코딩 컨벤션을 따르는가?
• [ ] 매직 넘버/스트링이 상수로 추출되었는가?

3.2 안정성/보안

• [ ] 입력값 검증이 적절한가?
• [ ] 에러 핸들링이 적절한가?
• [ ] 엣지 케이스가 처리되었는가?
• [ ] 민감 정보(API 키, 비밀번호)가 노출되지 않는가?
• [ ] SQL Injection, XSS 등 보안 취약점이 없는가?
• [ ] 인증/인가 로직이 올바른가?

3.3 성능/효율

• [ ] 불필요한 반복이나 중복 연산이 없는가?
• [ ] 적절한 자료구조를 사용하는가?
• [ ] N+1 쿼리 문제가 없는가?
• [ ] 큰 데이터 처리 시 페이지네이션/스트리밍 고려?
• [ ] 캐싱이 필요한 부분이 있는가?
• [ ] 메모리 누수 가능성이 있는가?

3.4 테스트

• [ ] 새로운 코드에 대한 테스트가 추가되었는가?
• [ ] 엣지 케이스 테스트가 있는가?
• [ ] 테스트가 실제 동작을 검증하는가? (구현 세부사항 X)
• [ ] 테스트 이름이 의도를 명확히 표현하는가?
• [ ] 기존 테스트가 깨지지 않는가?

3.5 문서화

• [ ] 복잡한 로직에 주석이 있는가?
• [ ] API 변경 시 문서가 업데이트되었는가?
• [ ] README나 CHANGELOG 업데이트가 필요한가?
• [ ] 함수/클래스의 공개 인터페이스에 문서가 있는가?

→ 승인 대기

발견사항 요약을 출력:

리뷰 결과:
- 코드 품질: 이슈 2건 발견
- 안정성/보안: 이슈 1건 발견 (중요)
- 성능: 이슈 없음
- 테스트: 이슈 1건 발견
- 문서화: 이슈 없음

총 4건의 코멘트를 작성할 예정입니다.
코멘트 작성을 진행할까요?

사용자 승인 후 Step 4로 진행.

---

Step 4: 코멘트 작성

톤 가이드

건설적이고 친절하게 작성. 비판이 아닌 제안으로.

사용할 표현:

• "~하면 더 좋을 것 같아요"
• "혹시 ~는 어떨까요?"
• "~가 궁금한데, 의도가 있으실까요?"
• "제 생각에는 ~도 고려해볼 수 있을 것 같아요"

피할 표현:

• "이건 틀렸습니다"
• "왜 이렇게 했죠?"
• "이건 말이 안 됩니다"

Pn 우선순위 룰

코멘트에 P1~P5 우선순위를 명시. P1, P2가 있으면 REQUEST_CHANGES 필수.

| Pn | 의미 | 예시 | |----|------|------| | P1 | 반드시 반영 - 버그, 잘못된 구현 | "A가 없으면 에러 발생", "데이터 추출 오류" | | P2 | 반영 필요 - 규칙 미준수, 비효율, 유지보수 어려움 | "여기선 double quote 사용", "변수명 오타", "array 대신 dictionary" | | P3 | 다른 PR에서 반영 가능 - 대규모 리팩토링, 논의 필요 | "테스트 리팩토링 필요", "이전 코드가 더 나음" | | P4 | 반영 안해도 됨 - 사소한 개선 | "함수 축약 가능", "변수명 개선 제안", "오탈자" | | P5 | 요구 아님 - 질문, 칭찬, 의견 | "이렇게도 되는군요!", "수정 이유가 뭔가요?", "깔끔해졌습니다" |

코멘트 템플릿

P1 예시 (반드시 반영):

P1: 이 부분에서 사용자 입력을 직접 SQL 쿼리에 넣고 있어서
SQL Injection 취약점이 있습니다. parameterized query를 사용해주세요.

현재:
query = f"SELECT * FROM users WHERE id = {user_id}"

수정:
query = "SELECT * FROM users WHERE id = ?"
cursor.execute(query, (user_id,))

P2 예시 (반영 필요):

P2: 요소가 많아지면 비효율적이 될 거에요.
array 대신 dictionary를 사용해보아요.

현재: O(n) 검색
users = [user1, user2, ...]

제안: O(1) 검색
users = {user_id: user, ...}

P3 예시 (다른 PR에서):

P3: 이 테스트들이 외부 dependency에 의존하고 있어요.
mock으로 분리하면 좋겠는데, 이건 별도 PR에서 진행해도 될 것 같아요.

P4 예시 (반영 안해도 됨):

P4: 함수명을 `processData`에서 `validateAndTransformUser`로 변경하면
의도가 더 명확해질 것 같아요. 사소한 제안이라 반영 안하셔도 돼요.

P5 예시 (질문/칭찬):

P5: 에러 핸들링 패턴이 깔끔하네요!
특히 사용자 메시지와 로깅 메시지를 분리한 부분이 좋습니다.

P5: 여기서 retry를 3번으로 제한한 이유가 있을까요?

→ 승인 대기 (최종)

코멘트 목록을 출력:

작성할 코멘트 (총 4개):

1. P1 src/auth.py:25
   SQL Injection 취약점 수정 필요

2. P2 src/auth.py:42
   비효율적인 자료구조 사용

3. P4 src/api/users.py:15
   변수명 개선 제안

4. P5 tests/test_auth.py:30
   테스트 커버리지 질문

권장: REQUEST_CHANGES (P1, P2 코멘트 있음)

이대로 GitHub에 제출할까요?

사용자 승인 시 Claude가 실행:

1. /tmp/pr_review_<PR번호>.json 파일 생성 (Write 도구 사용)
2. Bash 도구로 스크립트 실행:

   python3 <이 스킬의 scripts/submit_comments.py 절대경로> /tmp/pr_review_<PR번호>.json
   

3. 실행 결과 확인 후 사용자에게 출력
4. 실패 시: 에러 메시지 + 수동 제출 방법 안내 (아래 문제 해결 섹션 참조)

---

Quick Reference Checklist

빠른 리뷰를 위한 핵심 체크리스트:

품질: 이름 명확? 함수 단일 책임? 중복 없음?
안정: 입력 검증? 에러 핸들링? 보안 취약점?
성능: 불필요 연산? N+1 쿼리? 메모리 누수?
테스트: 테스트 추가? 엣지 케이스? 기존 테스트 통과?
문서: 주석 필요? API 문서? README 업데이트?

---

Examples

좋은 리뷰 코멘트

예시 1 - P2 구체적 제안:

P2: `getUserData` 함수가 40줄인데, 검증 로직을 `validateUserInput`으로
분리하면 테스트하기도 쉽고 가독성도 좋아질 것 같아요.

예시 2 - P5 칭찬 + P4 제안:

P5: 에러 핸들링 패턴 깔끔하네요!

P4: 한 가지 더, retry 로직도 같이 추가하면 네트워크 이슈에 더 강건해질 것 같아요.
(사소한 제안이라 반영 안하셔도 돼요)

예시 3 - P5 맥락을 고려한 질문:

P5: 이 캐싱 TTL을 5분으로 설정한 배경이 궁금해요.
데이터 특성상 더 길게 가져가도 될 것 같은데, 제가 놓친 부분이 있을까요?

피해야 할 코멘트

| 피해야 할 표현 | 개선된 표현 (Pn 적용) | |---------------|----------------------| | "이건 안 됩니다." | "P1: ~하면 에러가 발생할 것 같아요." | | "왜 이렇게 했어요?" | "P5: ~가 궁금한데, 특별한 이유가 있으실까요?" | | "코드가 지저분합니다" | "P4: 이 부분을 ~로 리팩토링하면 가독성이 좋아질 것 같아요" | | "테스트가 없네요" | "P2: 이 로직에 대한 테스트를 추가해주시면 좋을 것 같아요" |

---

Step 5: 리뷰 파일 저장 (File Handoff)

리뷰 결과를 .dev/pr-reviews/에 구조화된 마크다운으로 저장한다. 이 파일은 다른 스킬(/compound, /session-wrap 등)이 소비할 수 있는 handoff 아티팩트다.

저장 경로

.dev/pr-reviews/{identifier}-review.md

• GitHub PR: {identifier} = PR 번호 (예: pr-123-review.md)
• 로컬 브랜치: {identifier} = 브랜치명 (예: feature-DPT-1234-add-auth-review.md)

파일 구조

# PR Review: {PR 제목 또는 브랜치명}

**Date**: {YYYY-MM-DD}
**Reviewer**: Claude (pr-reviewer)
**Decision**: {APPROVE / REQUEST_CHANGES / COMMENT}
**PR**: {PR URL 또는 브랜치명}

## Summary
{1-2줄 요약: 무엇을 변경했고 전체적으로 어떤 수준인가}

## Findings

### P1 (반드시 반영)
- {파일:라인} — {요약}

### P2 (반영 필요)
- {파일:라인} — {요약}

### P3-P5 (참고)
- {파일:라인} — {요약}

## Stats
- Files reviewed: {N}
- Comments: P1={n} P2={n} P3={n} P4={n} P5={n}
- Lines: +{additions}/-{deletions}

저장 실행

mkdir -p .dev/pr-reviews

Write 도구로 리뷰 파일을 저장한 뒤, 사용자에게 저장 경로를 알려준다:

리뷰 파일이 저장되었습니다: .dev/pr-reviews/{identifier}-review.md

이 파일은 git에 커밋하여 리뷰 히스토리로 남기거나, .gitignore에 추가하여 로컬 참고용으로 사용할 수 있다.

---

리뷰 완료 후

1. 전체 요약 코멘트 작성: 리뷰 내용 요약, 잘된 점, 개선 필요 사항
2. 승인/변경 요청 결정 (Pn 기준):
   • P1 또는 P2가 있으면 → REQUEST_CHANGES
   • P3 이하만 있으면 → APPROVE 또는 COMMENT
3. 후속 논의 필요 시: P3 항목에 대해 직접 대화나 미팅 제안
4. 리뷰 파일 확인: .dev/pr-reviews/에 리뷰 파일이 저장되었는지 확인

---

Scripts

submit_comments.py - 코멘트 일괄 제출

GitHub PR에 리뷰 코멘트를 일괄 제출하는 스크립트. Claude가 Bash 도구로 실행.

스크립트 위치: <이 SKILL.md가 있는 디렉토리>/scripts/submit_comments.py

Claude 실행 절차:

# 1. Write 도구로 JSON 파일 생성
# 2. Bash 도구로 스크립트 실행 (절대 경로 사용)
python3 /path/to/pr-reviewer/scripts/submit_comments.py /tmp/pr_review_123.json

# 제출 전 미리보기 (dry-run)
python3 /path/to/pr-reviewer/scripts/submit_comments.py /tmp/pr_review_123.json --dry-run

중요: 스크립트 경로는 이 스킬이 설치된 위치의 절대 경로를 사용해야 함.

JSON 형식:

{
    "pr": 123,
    "event": "REQUEST_CHANGES",
    "body": "전체적으로 잘 작성되었습니다. 몇 가지 수정이 필요합니다.",
    "comments": [
        {"path": "src/main.py", "line": 10, "body": "[제안] 함수명 변경 제안"},
        {"path": "src/utils.py", "line": 25, "body": "[필수] 보안 취약점 수정 필요"}
    ]
}

event 옵션:

• COMMENT: 코멘트만 남김
• APPROVE: 승인
• REQUEST_CHANGES: 변경 요청

필수 조건:

• gh CLI 설치 및 인증 완료

---

문제 해결

gh CLI 미설치

# macOS
brew install gh

# 설치 후 인증
gh auth login

인증 실패

# 인증 상태 확인
gh auth status

# 재인증
gh auth login --scopes repo

스크립트 실행 실패

• Python 3 필요: python3 --version 확인
• 스크립트 경로가 올바른지 확인
• 실패 시 수동 제출: GitHub 웹에서 직접 코멘트 작성