본문으로 건너뛰기

코드 리뷰 워크플로우

Claude Code는 코드 리뷰의 두 가지 단계 모두에서 활용할 수 있습니다: PR 작성자의 자가 리뷰와, 리뷰어의 검토 지원. 두 단계 모두를 Claude로 강화하면 리뷰 품질이 크게 향상됩니다.

PR 작성자: 자가 리뷰 워크플로우​

1단계: PR 전 자가 리뷰​

PR을 올리기 전에 Claude와 함께 먼저 검토합니다:

> git diff main...HEAD 를 확인하고, 내가 놓친 것들을 찾아줘:
- 테스트가 빠진 로직
- 하드코딩된 값
- 에러 처리가 없는 곳
- 컨벤션에서 벗어난 부분

2단계: 자동 커밋 메시지 생성​

> /commit

커스텀 Skills로 Conventional Commits 형식의 커밋 메시지를 자동 생성합니다.

3단계: PR 설명 자동 작성​

> 이 PR의 설명을 작성해줘.
다음 내용을 포함해줘:
- 변경 이유 (Why)
- 변경 내용 요약 (What)
- 테스트 방법
- 스크린샷 필요 여부

git diff main...HEAD 와 커밋 메시지를 참고해줘.

완전한 자가 리뷰 Skill​

.claude/commands/pre-pr.md:

PR을 올리기 전 최종 점검을 진행해줘.

## 단계 1: 변경사항 분석
git diff main...HEAD 로 변경사항을 파악해줘.

## 단계 2: 자가 리뷰
다음 항목을 체크해줘:
- [ ] 새 기능에 테스트 포함
- [ ] 에러 처리 완전성
- [ ] 하드코딩된 값 없음
- [ ] 불필요한 console.log 없음
- [ ] 타입 에러 없음 (tsc --noEmit)
- [ ] 린트 통과 (npm run lint)

## 단계 3: PR 설명 초안
체크 결과를 바탕으로 PR 설명 마크다운을 작성해줘.

## 단계 4: 실제 테스트 실행
npm test 실행하고 결과 알려줘.

리뷰어: Claude 보조 리뷰 워크플로우​

리뷰 컨텍스트 파악​

리뷰할 PR의 변경사항을 빠르게 이해:

> PR #42의 변경사항을 요약해줘.
어떤 문제를 해결하고, 어떤 방식으로 구현했는지 설명해줘.
(gh pr diff 42 를 실행해서 확인해줘)

심층 리뷰 요청​

> PR #42를 시니어 개발자 관점에서 리뷰해줘.

특히 다음 관점에서:
1. 아키텍처 적합성 (기존 패턴과 일관성)
2. 성능 영향 (쿼리, 루프, 메모리)
3. 보안 (입력 검증, 인증, 노출)
4. 엣지 케이스 처리
5. 테스트 완전성

발견한 이슈는 GitHub 코멘트 형식으로 작성해줘:
파일명:줄번호 — 이슈 설명 및 개선 제안

리뷰 코멘트 자동 작성​

> 다음 코드에 대한 GitHub 리뷰 코멘트를 작성해줘.
건설적이고 구체적으로, 개선 방법도 함께 제시해줘:

[코드 스니펫]

리뷰 품질 기준 정의​

팀 리뷰 체크리스트 CLAUDE.md에 포함​

## 코드 리뷰 기준

### 필수 통과 조건
- 모든 테스트 통과
- 타입 체크 통과 (tsc --noEmit)
- 린트 통과
- 빌드 성공

### 리뷰 포인트 (우선순위 순)
1. 보안 이슈 (블로커)
2. 기능 버그 (블로커)
3. 성능 문제 (중요)
4. 코드 품질 (일반)
5. 스타일 (선택)

### Claude 리뷰 활용 방침
- PR 작성자: PR 올리기 전 /pre-pr Skill 실행 필수
- 리뷰어: 복잡한 로직은 Claude에게 먼저 분석 요청
- 피드백: Claude 제안은 반드시 사람이 검토 후 전달

실전: 완전한 리뷰 사이클​

PR 작성자 사이드​

# 1. 개발 완료 후 자가 리뷰
/pre-pr

# 2. Claude 제안 사항 반영
claude "방금 리뷰에서 지적된 [문제]를 수정해줘"

# 3. 최종 커밋 및 PR 오픈
/commit
gh pr create --title "..." --body "..."

리뷰어 사이드​

# 1. PR 전반 파악
claude "gh pr diff $PR_NUM 실행해서 변경사항 요약해줘"

# 2. 심층 리뷰
claude "이 PR의 보안 및 성능 이슈를 집중 분석해줘"

# 3. 특정 코드 이해
claude "이 함수가 왜 이렇게 구현됐는지 설명해줘: [코드]"

# 4. 리뷰 코멘트 작성 지원
claude "이 로직의 문제점을 건설적으로 전달하는 코멘트 작성해줘"

로컬 변경사항 리뷰: /code-review​

대화형 세션에서 현재 브랜치 변경을 점검하려면 내장 명령 /code-review를 사용할 수 있습니다. 기본 실행은 upstream 이후 커밋과 미커밋 변경을 검토하고, 결과를 대화에 보고합니다. 특정 PR 번호, 브랜치, 경로 또는 커밋 범위도 지정할 수 있습니다.

/code-review
/code-review 1234
/code-review src/auth
  • 기본 실행은 결과를 보고만 합니다. --fix를 붙이면 발견 사항을 작업 트리에 적용하도록 요청하며, 수정은 현재 권한 모드의 적용을 받습니다. 백그라운드 리뷰의 수정은 세션 체크포인트의 /rewind로 되돌릴 수 없을 수 있으니 실행 전에 변경 상태를 확인하세요.
  • --comment는 GitHub PR에 인라인 결과를 게시합니다. 외부 게시 효과가 있으므로 대상과 결과를 확인하고 사용합니다.
  • 노력 수준을 높이면 더 넓게 검토하지만 결과가 늘 수 있습니다. 기본 명령은 현재 세션에서 작업 중인 변경을 대상으로 하므로, 대상이 맞는지 먼저 확인하세요.
  • v2.1.311부터 /code-review는 effort 수준을 먼저 지정하도록 안내하며, max는 사용자가 요청한 경우에만 사용합니다.
  • 이 명령은 현재 세션 사용량 또는 API 과금에 포함됩니다. 자동 PR 검토가 목적이면 아래의 관리형 서비스를 검토하세요.
  • 로컬 /code-review는 프로젝트의 CLAUDE.md 지침을 따르지만, 관리형 GitHub Code Review용 REVIEW.md는 읽지 않습니다. 두 기능은 별개입니다.

자세한 대상 선택과 옵션은 공식 로컬 리뷰 안내를 확인하세요.

관리형 Code Review 서비스​

Teams/Enterprise

Teams/Enterprise 플랜에서는 관리형 Code Review를 사용할 수 있습니다. GitHub App을 설치하면 PR이 생성되거나 업데이트될 때 자동으로 리뷰가 실행됩니다.

  • 여러 전문 에이전트가 병렬로 diff와 주변 코드를 분석
  • 로직 에러, 보안 취약점, 엣지 케이스, 회귀 버그를 탐지
  • 심각도(Normal/Nit/Pre-existing) 태그와 함께 인라인 코멘트로 결과 게시
  • CLAUDE.md와 REVIEW.md로 리뷰 기준 커스터마이징 가능
  • PR을 승인/차단하지 않으므로 기존 리뷰 워크플로우와 호환
  • 리뷰 수준은 Quick·Standard·Deep 중에서 조직 기본값을 정하고 저장소별로 다르게 지정할 수 있음
  • 실행 시점은 PR 생성 시 1회, 매 푸시, 수동 실행 중에서 저장소별로 선택할 수 있음

설정: claude.ai/admin-settings/claude-code에서 활성화

관리형 서비스는 Team·Enterprise 조직의 GitHub 저장소용이며, Zero Data Retention 또는 HIPAA 구성이 적용된 조직에서는 사용할 수 없습니다. BAA 적용 범위에도 포함되지 않고 고객 관리형 암호화 키(CMEK)도 지원하지 않으므로, 도입 전에 조직의 데이터 요건을 확인하세요. 리뷰는 Anthropic 인프라에서 실행되며, 코드 빌드나 실행 없이 diff와 주변 코드를 읽습니다. 자세한 제한은 공식 서비스 안내에서 확인할 수 있습니다.

비용은 리뷰당 고정 요금이 아니라 변경 크기·복잡도·리뷰 수준·실행 횟수에 따라 달라지고 조직 사용 크레딧으로 별도 청구됩니다. 처음에는 월 지출 한도를 두고 대표 저장소 몇 곳에서 PR 생성 시 1회 또는 수동 실행으로 시험한 뒤 평균 비용을 확인하세요. 매 푸시마다 리뷰하면 PR의 푸시 횟수만큼 비용이 늘 수 있습니다. 공식 비용 안내

PR에서 @claude review는 한 번만 실행하고, @claude review always는 이후 푸시마다 리뷰하도록 구독합니다. 구독을 끝내려면 @claude review stop을 사용합니다. 단, 저장소가 매 푸시 실행으로 설정된 경우에는 이 명령으로 자동 실행을 멈출 수 없습니다. 자세한 조건은 PR 리뷰 요청 안내를 확인하세요.

리뷰 지표 추적​

> 이번 달 머지된 PR들을 분석해줘.
gh pr list --state merged --limit 50 로 목록 가져와서:
- 평균 리뷰 시간
- 자주 발생하는 리뷰 코멘트 유형
- 수정 후 재요청이 많은 패턴

개선할 수 있는 팀 코딩 관행을 제안해줘.

레벨 4 완료!​

이 레벨을 마치면 Claude Code를 고급 수준으로 활용할 수 있습니다. 커스텀 Skills로 팀 워크플로우를 자동화하고, Agent SDK로 복잡한 파이프라인을 구축하고, Docker 환경에서 안전하게 에이전트를 실행하는 역량을 갖췄습니다.

이 챕터를 완료하셨나요?

학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.