AgentSkillsCN

pr-review

当需要对 PR 进行评审、请求代码审查、或希望他人查看 PR 时,可在 GitHub PR URL 出现在对话中时使用此技能。系统会自动识别仓库,并针对不同项目应用定制化的评审指南。

SKILL.md
--- frontmatter
name: pr-review
description: PR을 리뷰할 때, 코드 리뷰해달라고 할 때, PR 봐달라고 할 때, GitHub PR URL이 대화에 등장할 때 사용. Repository를 자동 감지하여 프로젝트별 맞춤 리뷰 가이드를 적용합니다.
allowed-tools: Bash, Glob, Grep, Read, Task

통합 PR 코드 리뷰

PR을 분석하고 Repository를 자동 감지하여 프로젝트별 맞춤 코드 리뷰를 수행합니다.

지원 프로젝트

Repository가이드 파일설명
likey-backendguides/backend.mdNode.js Express 백엔드
likey-admin-v2guides/admin-v2.mdVue 3 어드민 프론트엔드
likey-webguides/likey-web.mdNuxt.js 2 프론트엔드
기타guides/common.md공통 체크리스트만 적용

트리거 키워드

  • "리뷰해줘", "코드 리뷰", "PR 봐줘"
  • "이 PR 확인해줘", "리뷰 부탁"
  • GitHub PR URL 감지: github.com/.../pull/...
  • PR 번호와 함께 "확인", "검토" 언급

인자

  • $ARGUMENTS: 다음 중 하나
    • PR URL (예: https://github.com/TPC-Internet/likey-backend/pull/6381)
    • PR 번호 (예: 6381) - 현재 디렉토리의 repo 기준
    • 생략 시 현재 브랜치의 PR

실행 순서

1. 인자 파싱 및 PR 정보 조회

bash
# URL이 주어진 경우 - gh가 URL 직접 처리
command gh pr view {URL} --json number,title,body,files,additions,deletions,author,headRefName,baseRefName,headRefOid,url

# 번호만 주어진 경우
command gh pr view {번호} --json number,title,body,files,additions,deletions,author,headRefName,baseRefName,headRefOid,url

# 인자 없는 경우 - 현재 브랜치 PR
command gh pr view --json number,title,body,files,additions,deletions,author,headRefName,baseRefName,headRefOid,url

2. Repository 자동 감지

PR URL에서 repository 이름을 추출합니다:

code
https://github.com/TPC-Internet/likey-backend/pull/6381
                   └────────────┬────────────┘
                           owner/repo

추출 방법:

  • PR 정보의 url 필드에서 파싱
  • 또는 command gh pr view --json baseRepository 사용
bash
# Repository 정보 확인
command gh pr view {PR} --json url | grep -oP '(?<=github.com/)[^/]+/[^/]+'

Repository → 가이드 매핑:

Repository 이름적용할 가이드
likey-backendguides/backend.md + guides/common.md
likey-admin-v2guides/admin-v2.md + guides/common.md
likey-webguides/likey-web.md + guides/common.md
기타guides/common.md 만 적용

3. 프로젝트별 가이드 로딩

감지된 repository에 따라 해당 가이드 파일을 Read 도구로 로딩합니다:

code
/Users/muzi/.claude/skills/pr-review/guides/backend.md
/Users/muzi/.claude/skills/pr-review/guides/admin-v2.md
/Users/muzi/.claude/skills/pr-review/guides/likey-web.md
/Users/muzi/.claude/skills/pr-review/guides/common.md

중요: 반드시 해당 가이드 파일을 읽고 체크리스트를 적용해야 합니다.

4. 변경 내용 확인

bash
command gh pr diff {PR번호}

diff를 분석하여 다음을 파악:

  • 어떤 기능이 추가/수정되었는지
  • 변경된 파일들의 역할
  • 코드 변경의 의도

5. 리뷰 제외 대상 확인

공통 제외:

  • 자동 생성 파일
  • 번역 파일

Backend 제외:

  • locales/ - 번역 파일
  • po/ - 번역 소스
  • spec/*.yaml - 자동 생성 스펙
  • src/gen/ - 자동 생성 라우트

Admin V2 제외:

  • src/api/ - 자동 생성 API 타입
  • auto-imports.d.ts, components.d.ts

likey-web 제외:

  • models/spec/likey-api.ts - 백엔드 OpenAPI 스펙에서 자동 생성
  • locales/*.json - Lokalise에서 자동 동기화

6. 관련 코드 탐색

변경된 코드를 이해하기 위해 필요시 추가 탐색:

  • 기존 코드 확인: 변경된 파일의 전체 컨텍스트 파악
  • 관련 함수 검색: 사용된 함수나 클래스의 정의 확인
  • 유사 패턴 검색: 코드베이스 내 유사한 구현 참고

7. 코드 리뷰 수행

로딩한 가이드 파일의 체크리스트를 적용하여 리뷰합니다.

  1. guides/common.md의 공통 체크리스트 적용
  2. 프로젝트별 가이드 체크리스트 적용 (backend.md, admin-v2.md, 또는 likey-web.md)
  3. 자동 검사 패턴 실행 (가이드에 정의된 grep 패턴)

8. 인라인 코멘트용 라인 번호 계산

피드백이 필요한 각 코드에 대해 정확한 라인 번호를 계산해야 합니다.

라인 번호 계산 방법

  1. diff에서 해당 파일의 hunk 헤더 확인:

    bash
    command gh pr diff {PR번호} | sed -n '/^+++ b\/{파일경로}/,/^diff --git/p' | grep "^@@"
    

    예: @@ -150,18 +153,24 @@ → 새 파일에서 153번 라인부터 시작

  2. hunk 내에서 해당 코드의 위치 계산:

    • 공백으로 시작하는 줄: 기존 코드 (라인 번호 증가)
    • +로 시작하는 줄: 새로 추가된 코드 (라인 번호 증가)
    • -로 시작하는 줄: 삭제된 코드 (라인 번호 증가 안 함)
  3. 실제 라인 번호 계산:

    • hunk 시작 라인 + (해당 줄까지의 공백/+ 줄 수 - 1)

9. 리뷰 코멘트 작성 (인라인 + 요약)

GitHub API를 사용하여 전체 요약과 인라인 코멘트를 한 번에 작성합니다.

PR URL에서 owner/repo를 추출하여 사용:

bash
command gh api repos/{owner}/{repo}/pulls/{PR번호}/reviews \
  -X POST \
  --input - << 'EOF'
{
  "commit_id": "{headRefOid}",
  "event": "COMMENT",
  "body": "## 코드 리뷰 요약\n\n@{author} 리뷰 확인 부탁드립니다!\n\n### 감지된 프로젝트\n**{repository}** - {가이드 설명}\n\n### 전체 요약\n{전체 요약 내용}\n\n### 리뷰 통계\n| 심각도 | 개수 |\n|--------|------|\n| 🔴 Critical | 0 |\n| 🟠 Major | 1 |\n| 🟡 Minor | 0 |\n| 💬 Comment | 2 |",
  "comments": [
    {
      "path": "src/path/to/file.ts",
      "line": 123,
      "side": "RIGHT",
      "body": "🔴 **Critical**: 문제 설명\n\n```typescript\n// 수정 제안\n```"
    }
  ]
}
EOF

인라인 코멘트 필드 설명

필드설명
path파일 경로 (repo root 기준)
line새 파일 기준 라인 번호
side"RIGHT" (새 코드) 또는 "LEFT" (삭제된 코드)
body코멘트 내용 (마크다운 지원)

심각도 레벨 (공통)

레벨설명예시
🔴 Critical반드시 수정 필요보안 취약점, 버그 유발, 잘못된 API 사용
🟠 Major수정 권장가이드라인 위반, deprecated API 사용
🟡 Minor개선 제안코드 스타일, 성능 최적화
💬 Comment질문 또는 의견로직 확인, 의도 질문

출력 형식

markdown
## PR #{번호} 코드 리뷰 완료

**제목**: {PR 제목}
**작성자**: @{author}
**Repository**: {owner}/{repo}
**적용 가이드**: {프로젝트 가이드 이름}
**변경**: +{additions} -{deletions} ({files}개 파일)

### 작성된 인라인 코멘트
| 파일 | 라인 | 심각도 | 내용 |
|------|------|--------|------|
| `src/path/to/file.ts` | 123 | 🔴 Critical | 문제 설명 |
| `src/another/file.ts` | 456 | 🟠 Major | 문제 설명 |

### 리뷰 요약
| 심각도 | 개수 |
|--------|------|
| 🔴 Critical | 1 |
| 🟠 Major | 1 |
| 🟡 Minor | 0 |
| 💬 Comment | 0 |

### 잘된 점
- {긍정적인 피드백}

### 리뷰 링크
{GitHub 리뷰 URL}

트러블슈팅

Repository 감지 실패

  • PR URL이 없는 경우: 현재 디렉토리의 git remote 확인
  • git remote get-url origin으로 repo 추론

"Line could not be resolved" 에러

  • 라인 번호가 diff 범위 내에 있어야 합니다
  • hunk 헤더의 시작 라인 번호를 기준으로 계산했는지 확인
  • 새로 추가된 파일은 side: "RIGHT"를 사용

인라인 코멘트가 안 보이는 경우

  • commit_id가 정확한지 확인 (PR의 HEAD commit SHA)
  • path가 정확한 파일 경로인지 확인 (앞에 / 없이)

패턴 분석 연동 (Confirm 필수)

리뷰 중 "이 패턴이 프로젝트에서 어떻게 사용되는지" 확인이 필요할 때, 사용자 확인 후 analyze-repo-patterns 스킬을 sub agent로 호출합니다.

호출 시점

  • 코드에서 여러 방식이 혼재되어 있을 때 (예: ConfirmDialog ref vs useConfirmDialog)
  • 프로젝트 표준 패턴이 불확실할 때
  • 리뷰 코멘트에 참고 PR을 첨부하고 싶을 때
  • 새로운 패턴/라이브러리가 도입된 경우

1단계: 사용자 확인 (AskUserQuestion)

패턴 분석이 필요하다고 판단되면, 먼저 사용자에게 확인합니다:

json
{
  "questions": [{
    "question": "'{패턴명}' 패턴의 프로젝트 사용례를 분석할까요?",
    "header": "패턴 분석",
    "options": [
      {"label": "분석 실행", "description": "최근 PR과 코드베이스에서 사용례 확인"},
      {"label": "건너뛰기", "description": "분석 없이 리뷰 계속 진행"}
    ],
    "multiSelect": false
  }]
}

여러 패턴이 의심될 때:

json
{
  "questions": [{
    "question": "다음 패턴들의 프로젝트 사용례를 분석할까요?",
    "header": "패턴 분석",
    "options": [
      {"label": "useDialog", "description": "다이얼로그 composable 패턴"},
      {"label": "notifyError", "description": "에러 처리 패턴"},
      {"label": "전체 분석", "description": "위 패턴 모두 분석"},
      {"label": "건너뛰기", "description": "분석 없이 진행"}
    ],
    "multiSelect": true
  }]
}

2단계: 조건부 실행

  • "분석 실행" 선택 시 → Task 도구로 패턴 분석 실행
  • "건너뛰기" 선택 시 → 분석 없이 리뷰 계속

3단계: 호출 방법 (승인된 경우만)

code
Task 도구 사용:
- subagent_type: "Explore"
- prompt: |
    analyze-repo-patterns 스킬을 실행하여 '{패턴}' 패턴을 분석해줘.
    - 현재 코드베이스에서 사용 현황
    - 최근 머지된 PR에서의 사용례
    - 권장 패턴 및 참고 PR 링크

예시 흐름

code
[pr-review 진행 중...]

Claude: PR에서 `useDialog` 대신 `ref<InstanceType<typeof ConfirmDialog>>`
        방식을 사용하고 있네요.

        ┌─────────────────────────────────────────┐
        │ 'useDialog' 패턴의 프로젝트 사용례를    │
        │ 분석할까요?                              │
        │                                          │
        │  [분석 실행]  [건너뛰기]                │
        └─────────────────────────────────────────┘

User: [분석 실행] 클릭

Claude: [analyze-repo-patterns 실행...]

        분석 결과, 프로젝트에서는 useDialog composable이
        87개 파일에서 사용 중이고, ref 방식은 레거시 3개만
        남아있습니다.

        [리뷰 코멘트 작성 계속...]

결과를 받아 리뷰 코멘트에 반영:

  • "최근 PR #1091, #1088에서는 useConfirmDialog() 사용"
  • "권장: composable 방식으로 변경"

주의사항

  • 기존 코드의 문제점은 지적하되, PR 범위 외 수정은 별도 이슈로 제안
  • 스타일 이슈는 기능 이슈보다 낮은 우선순위로 취급
  • 자동 생성 파일은 리뷰 스킵
  • PR 작성자에게 건설적이고 구체적인 피드백 제공
  • 반드시 해당 프로젝트의 가이드 파일을 읽고 체크리스트를 적용할 것
  • 패턴 확인이 필요하면 analyze-repo-patterns 스킬을 sub agent로 호출할 것