코드 검토

언제 쓰나

코드 변경 사항을 커밋하기 전 검토가 필요할 때 또는 GitHub PR의 코드 품질을 확인하고 싶을 때

---
description: 코드 리뷰 — 로컬에서 커밋되지 않은 변경 사항 또는 GitHub PR (PR 번호/URL을 전달하여 PR 모드 사용)
argument-hint: [pr-number | pr-url | 로컬 리뷰 시 공백]
---

# 코드 리뷰

> PR 리뷰 모드는 Wirasm의 PRPs-agentic-eng에서 차용함. PRP 워크플로 시리즈의 일부.

**입력**: $ARGUMENTS

---

## 모드 선택

만약 `$ARGUMENTS`에 PR 번호, PR URL 또는 `--pr`이 포함되어 있다면:
→ 아래 **PR 리뷰 모드**로 이동.

그렇지 않다면:
→ **로컬 리뷰 모드** 사용.

---

## 로컬 리뷰 모드

커밋되지 않은 변경 사항에 대한 종합적인 보안 및 품질 리뷰.

### 1단계 — 정보 수집(GATHER)

```bash
git diff --name-only HEAD
```

변경된 파일이 없으면 중단: "리뷰할 내용 없음."

### 2단계 — 리뷰(REVIEW)

각 변경된 파일을 전체적으로 읽고 다음 항목을 점검:

**보안 이슈 (CRITICAL):**
- 하드코딩된 자격 증명, API 키, 토큰
- SQL 인젝션 취약점
- XSS 취약점
- 입력 검증 누락
- 안전하지 않은 의존성
- 경로 탐색(Path traversal) 위험

**코드 품질 (HIGH):**
- 함수 길이 50줄 초과
- 파일 길이 800줄 초과
- 중첩 깊이 4단계 초과
- 오류 처리 누락
- console.log 문
- TODO/FIXME 주석
- 공용 API에 대한 JSDoc 누락

**모범 사례 (MEDIUM):**
- 불변 대신 가변성 패턴 사용
- 코드/주석 내 이모지 사용
- 새 코드에 대한 테스트 누락
- 접근성 이슈 (a11y)

### 3단계 — 보고(REPORT)

다음 항목을 포함한 보고서 생성:
- 심각도: CRITICAL, HIGH, MEDIUM, LOW
- 파일 위치 및 줄 번호
- 이슈 설명
- 제안된 수정 방법

CRITICAL 또는 HIGH 이슈 발견 시 커밋 차단.
보안 취약점이 있는 코드는 절대 승인하지 않음.

---

## PR 리뷰 모드

GitHub PR에 대한 종합 리뷰 — diff 가져오기, 전체 파일 읽기, 유효성 검사 실행, 리뷰 게시.

### 1단계 — 가져오기(FETCH)

입력을 파싱하여 PR 결정:

| 입력 | 동작 |
|---|---|
| 번호 (예: `42`) | PR 번호로 사용 |
| URL (`github.com/.../pull/42`) | PR 번호 추출 |
| 브랜치 이름 | `gh pr list --head <branch>`를 통해 PR 찾기 |

```bash
gh pr view <NUMBER> --json number,title,body,author,baseRefName,headRefName,changedFiles,additions,deletions
gh pr diff <NUMBER>
```

PR을 찾을 수 없으면 오류와 함께 중단. 이후 단계를 위해 PR 메타데이터 저장.

### 2단계 — 컨텍스트(CONTEXT)

리뷰 컨텍스트 구성:

1. **프로젝트 규칙** — `CLAUDE.md`, `.claude/docs/`, 그리고 기여 가이드라인 읽기
2. **PRP 아티팩트** — 이 PR과 관련된 구현 컨텍스트를 위해 `.claude/PRPs/reports/` 및 `.claude/PRPs/plans/` 확인
3. **PR 의도** — PR 설명을 파싱하여 목표, 연결된 이슈, 테스트 계획 추출
4. **변경된 파일** — 수정된 모든 파일 나열 및 유형별 분류 (소스, 테스트, 설정, 문서)

### 3단계 — 리뷰(REVIEW)

변경된 각 파일을 **전체적으로** 읽기 (diff 조각만이 아니라 주변 컨텍스트 필요).

PR 리뷰의 경우, PR 헤드 리비전에서 전체 파일 콘텐츠를 가져옴:
```bash
gh pr diff <NUMBER> --name-only | while IFS= read -r file; do
  gh api "repos/{owner}/{repo}/contents/$file?ref=<head-branch>" --jq '.content' | base64 -d
done
```

7가지 범주에 걸쳐 리뷰 체크리스트 적용:

| 범주 | 점검 항목 |
|---|---|
| **정확성(Correctness)** | 논리 오류, 오프바이원, null 처리, 예외 케이스, 경쟁 조건 |
| **타입 안정성(Type Safety)** | 타입 불일치, 위험한 캐스트, `any` 사용, 제네릭 누락 |
| **패턴 준수(Pattern Compliance)** | 프로젝트 규칙 준수 여부 (이름 지정, 파일 구조, 오류 처리, import) |
| **보안(Security)** | 인젝션, 인증 누락, 비밀 노출, SSRF, 경로 탐색, XSS |
| **성능(Performance)** | N+1 쿼리, 인덱스 누락, 무제한 루프, 메모리 누수, 대용량 페이로드 |
| **완전성(Completeness)** | 테스트 누락, 오류 처리 누락, 미완료 마이그레이션, 문서 누락 |
| **유지보수성(Maintainability)** | 사용하지 않는 코드, 매직 넘버, 깊은 중첩, 모호한 이름, 타입 누락 |

각 발견 사항에 심각도 할당:

| 심각도 | 의미 | 동작 |
|---|---|---|
| **CRITICAL** | 보안 취약점 또는 데이터 손실 위험 | 병합 전 반드시 수정 필요 |
| **HIGH** | 버그 또는 논리 오류로 인해 문제 발생 가능 | 병합 전 수정 권장 |
| **MEDIUM** | 코드 품질 문제 또는 모범 사례 누락 | 수정 권장 |
| **LOW** | 스타일 제안 또는 사소한 제안 | 선택 사항 |

### 4단계 — 검증(VALIDATE)

사용 가능한 검증 명령어 실행:

설정 파일(`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml` 등)에서 프로젝트 유형을 감지한 후 해당 명령어 실행:

**Node.js / TypeScript** (`package.json` 존재):
```bash
npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null  # 타입 검사
npm run lint                                                    # 린트
npm test                                                        # 테스트
npm run build                                                   # 빌드
```

**Rust** (`Cargo.toml` 존재):
```bash
cargo clippy -- -D warnings  # 린트
cargo test                   # 테스트
cargo build                  # 빌드
```

**Go** (`go.mod` 존재):
```bash
go vet ./...    # 린트
go test ./...   # 테스트
go build ./...  # 빌드
```

**Python** (`pyproject.toml` / `setup.py` 존재):
```bash
pytest  # 테스트
```

감지된 프로젝트 유형에 해당하는 명령어만 실행. 각각의 성공/실패 기록.

### 5단계 — 결정(DECIDE)

발견 사항 기반으로 결정 도출:

| 조건 | 결정 |
|---|---|
| CRITICAL/HIGH 이슈 없음, 검증 통과 | **승인(APPROVE)** |
| MEDIUM/LOW 이슈만 존재, 검증 통과 | **승인(APPROVE)** 및 코멘트 작성 |
| HIGH 이슈 존재 또는 검증 실패 | **변경 요청(REQUEST CHANGES)** |
| CRITICAL 이슈 존재 | **차단(BLOCK)** — 병합 전 반드시 수정 필요 |

특별한 경우:
- 초안(Draft) PR → 항상 **코멘트(COMMENT)** 사용 (승인/차단 금지)
- 문서/설정 변경만 있는 경우 → 경량 리뷰, 정확성에 집중
- 명시적 `--approve` 또는 `--request-changes` 플래그 → 결정 오버라이드 (단, 모든 발견 사항은 여전히 보고)

### 6단계 — 보고(REPORT)

`.claude/PRPs/reviews/pr-<NUMBER>-review.md`에 리뷰 아티팩트 생성:

```markdown
# PR 리뷰: #<NUMBER> — <TITLE>

**리뷰일**: <date>
**작성자**: <author>
**브랜치**: <head> → <base>
**결정**: APPROVE | REQUEST CHANGES | BLOCK

## 요약
<전체 평가 1-2문장>

## 발견 사항

### CRITICAL
<발견 사항 또는 "없음">

### HIGH
<발견 사항 또는 "없음">

### MEDIUM
<발현 사항 또는 "없음">

### LOW
<발견 사항 또는 "없음">

## 검증 결과

| 검사 | 결과 |
|---|---|
| 타입 검사 | 통과 / 실패 / 건너뜀 |
| 린트 | 통과 / 실패 / 건너뜀 |
| 테스트 | 통과 / 실패 / 건너뜀 |
| 빌드 | 통과 / 실패 / 건너뜀 |

## 리뷰된 파일
<파일 목록 및 변경 유형: 추가됨/수정됨/삭제됨>
```

### 7단계 — 게시(PUBLISH)

리뷰를 GitHub에 게시:

```bash
# 승인(APPROVE)인 경우
gh pr review <NUMBER> --approve --body "<리뷰 요약>"

# 변경 요청(REQUEST CHANGES)인 경우
gh pr review <NUMBER> --request-changes --body "<필수 수정 사항 포함 요약>"

# 코멘트(COMMENT) 전용인 경우 (초안 PR 또는 정보 제공용)
gh pr review <NUMBER> --comment --body "<요약>"
```

특정 줄에 인라인 코멘트를 달려면 GitHub 리뷰 코멘트 API 사용:
```bash
gh api "repos/{owner}/{repo}/pulls/<NUMBER>/comments" \
  -f body="<comment>" \
  -f path="<file>" \
  -F line=<line-number> \
  -f side="RIGHT" \
  -f commit_id="$(gh pr view <NUMBER> --json headRefOid --jq .headRefOid)"
```

또는 여러 인라인 코멘트를 한 번에 달기 위해 단일 리뷰 게시:
```bash
gh api "repos/{owner}/{repo}/pulls/<NUMBER>/reviews" \
  -f event="COMMENT" \
  -f body="<전체 요약>" \
  --input comments.json  # [{"path": "file", "line": N, "body": "comment"}, ...]
```

### 8단계 — 출력(OUTPUT)

사용자에게 보고:

```
PR #<NUMBER>: <TITLE>
결정: <APPROVE|REQUEST_CHANGES|BLOCK>

이슈: <critical_count> 심각, <high_count> 높음, <medium_count> 중간, <low_count> 낮음
검증: <pass_count>/<total_count> 검사 통과

아티팩트:
  리뷰: .claude/PRPs/reviews/pr-<NUMBER>-review.md
  GitHub: <PR URL>

다음 단계:
  - <결정에 따른 맥락 기반 제안>
```

---

## 예외 케이스

- **`gh` CLI 없음**: 로컬 전용 리뷰로 전환 (diff 읽기, GitHub 게시 생략). 사용자에게 경고.
- **분기된 브랜치**: 리뷰 전 `git fetch origin && git rebase origin/<base>` 제안.
- **대규모 PR (>50 파일)**: 리뷰 범위에 대한 경고. 먼저 소스 변경 사항에 집중한 후 테스트, 설정/문서 순으로 진행.

1. 1

   SKILL.md 저장

   아래 버튼으로 복사 → 다음 경로로 저장.

   SKILL.md 복사

   macOSLinuxWindows

   ~/.claude/skills/everything-claude-code-106/SKILL.md경로 복사
2. 2

   호출

   Claude Code 채팅창에서 자연어로 부르면 자동 발동:

   예) 코드 변경 사항을 커밋하기 전 검토가 필요할 때 또는 GitHub PR의 코드 품질을 확인하고 싶을 때

   트리거가 안 잡히면 SKILL.md의 description 줄에 더 구체적인 한국어 키워드를 추가해보세요.