TechFeedTechFeed
🔍
Claude Code 가이드

Claude Code 가이드 #15 — Code Review 자동화

claude review 명령어, GitHub Actions PR 자동 리뷰, 커스텀 리뷰 규칙 설정. 코드 품질과 보안 이슈를 CI에서 자동으로 잡는 방법.

Claude Code 가이드 #15 — PR을 올릴 때마다 팀원에게 리뷰를 요청하는 대신, Claude Code가 자동으로 코드를 검토하게 할 수 있습니다. 이 편에서는 claude review 명령어부터 GitHub Actions를 통한 PR 자동 리뷰 파이프라인, 커스텀 리뷰 규칙 설정까지 실전 기준으로 정리합니다.

※ 이 글은 2026년 3월 기준, Claude Code 공식 문서 (GitHub Actions) 기반으로 작성됐습니다.

claude review 명령어란?

claude review는 현재 브랜치의 변경 사항을 Claude Code가 분석하고 코드 품질, 보안 취약점, 스타일 위반 사항을 보고하는 명령어입니다.

로컬에서 직접 실행하면 즉시 리뷰 결과를 확인할 수 있습니다.

리뷰 항목설명
코드 품질중복 로직, 불필요한 복잡도, 네이밍 컨벤션
보안SQL 인젝션, XSS, 하드코딩된 시크릿 감지
성능N+1 쿼리, 불필요한 루프, 메모리 누수 패턴
테스트테스트 커버리지 갭, 엣지 케이스 누락
타입 안전성TypeScript 타입 에러, any 사용 여부
claude review 명령어란? — CLI 실행 화면과 출력 결과
Claude Code 가이드 #15 — Code Review 자동화 — CLI 실행 화면과 출력 결과 (출처: 공식 문서 및 벤치마크 데이터 기반)
로컬에서 claude review 실행
# 현재 브랜치의 변경 사항 리뷰
claude review

# 특정 파일만 리뷰
claude review src/auth/login.ts

# 특정 커밋 범위 리뷰
claude review HEAD~3..HEAD

# main 브랜치 대비 전체 diff 리뷰
claude review main..HEAD
claude review 명령어 실행 화면과 리뷰 결과 출력
Claude Code 가이드 #15 — Code Review 자동화 — claude review 명령어 실행 화면과 리뷰 결과 출력 (출처: 공식 문서 및 벤치마크 데이터 기반)
📌 참고: claude review는 git diff를 기반으로 동작합니다. 스테이징되지 않은 변경 사항(untracked files)은 리뷰 대상에 포함되지 않으므로, 전체 변경 사항을 보려면 먼저 git add로 스테이징하거나 범위를 명시적으로 지정하세요.

GitHub Actions PR 자동 리뷰 설정

GitHub Actions 워크플로우에 Claude Code를 통합하면 PR이 열릴 때마다 자동으로 리뷰 코멘트가 달립니다. 설정은 크게 두 단계입니다.

  1. GitHub Secret 설정: ANTHROPIC_API_KEY를 레포 시크릿에 추가
  2. 워크플로우 파일 작성: .github/workflows/claude-review.yml 생성
.github/workflows/claude-review.yml — 기본 설정
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          claude review \
            --base ${{ github.event.pull_request.base.sha }} \
            --head ${{ github.event.pull_request.head.sha }} \
            --output github-pr-comment

위 워크플로우를 추가하면 PR이 열릴 때마다 Claude Code가 변경된 파일을 분석하고, PR 코멘트로 리뷰 결과를 자동으로 달아줍니다.

권한 설정 주의: pull-requests: write 권한이 없으면 PR에 코멘트를 달 수 없습니다. 포크(fork)에서 열린 PR은 시크릿 접근 제한으로 자동 리뷰가 동작하지 않을 수 있습니다.

리뷰 규칙 커스터마이징

Claude Code의 리뷰 규칙은 프로젝트 루트의 .claude/review.json 또는 CLAUDE.md에 지정할 수 있습니다. 팀의 코딩 컨벤션, 언어별 규칙, 허용/금지 패턴을 설정합니다.

.claude/review.json — 커스텀 리뷰 규칙 예시
{
  "review": {
    "focus": ["security", "performance", "correctness"],
    "ignore": ["style", "formatting"],
    "rules": {
      "no-hardcoded-secrets": "error",
      "no-console-log": "warn",
      "require-error-handling": "error",
      "max-function-lines": 50
    },
    "exclude": [
      "**/*.test.ts",
      "**/*.spec.js",
      "dist/**",
      "node_modules/**"
    ],
    "language-specific": {
      "typescript": {
        "strict-types": true,
        "no-any": "warn"
      },
      "python": {
        "type-hints": "warn"
      }
    }
  }
}

focus 배열에 집중할 리뷰 카테고리를 지정하면 Claude Code가 해당 영역에 집중해서 분석합니다. ignore에 지정한 카테고리는 건너뜁니다.

팀별로 자주 위반되는 패턴을 rules에 추가해두면, 반복적인 리뷰 코멘트를 자동화할 수 있습니다.

GitHub Actions PR 리뷰 결과 — PR 코멘트로 자동 리뷰가 달린 화면
Claude Code 가이드 #15 — Code Review 자동화 — GitHub Actions PR 자동 리뷰 결과 (출처: 공식 문서 및 벤치마크 데이터 기반)
⚠️ 막히는 케이스: 워크플로우가 실행됐는데 PR에 코멘트가 안 달린다 — permissions.pull-requests: write가 설정돼 있는지 먼저 확인하세요. 그다음 Actions 로그에서 403 Forbidden 에러를 확인하세요. 포크 PR은 시크릿 접근 자체가 막혀 있으므로, 포크에서 온 PR은 별도 워크플로우 트리거(pull_request_target)를 사용해야 합니다.

증분 리뷰와 리뷰 캐싱

PR에 커밋이 추가될 때마다 전체 diff를 다시 리뷰하면 비용이 많이 듭니다. 증분 리뷰(incremental review)를 사용하면 마지막 리뷰 이후 변경된 부분만 분석합니다.

증분 리뷰 — synchronize 이벤트에서만 새 커밋 리뷰
name: Claude Code Review (Incremental)

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v44

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run incremental review
        if: steps.changed-files.outputs.any_changed == 'true'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          echo "${{ steps.changed-files.outputs.all_changed_files }}" | \
          xargs claude review --output github-pr-comment
⚠️ 막히는 케이스: PR을 업데이트할 때마다 리뷰 코멘트가 중복으로 달린다 — --output github-pr-comment 옵션은 기본적으로 새 코멘트를 추가합니다. 기존 코멘트를 업데이트하려면 --output github-pr-comment-update 옵션을 사용하세요. 이 옵션은 Claude Code가 이전에 남긴 코멘트를 찾아서 덮어씁니다.

보안 스캔과 CI 게이팅 통합

Claude Code 리뷰를 단순 코멘트가 아니라 CI 게이팅으로 활용할 수 있습니다. 보안 이슈가 발견되면 PR 머지를 막는 방식입니다.

이 패턴은 다음 시나리오에 적합합니다:

  • 하드코딩된 API 키, 패스워드 감지 시 즉시 차단
  • 특정 파일(예: 결제 모듈) 변경 시 강화 리뷰 필수
  • 보안 취약점 등급(HIGH, CRITICAL)에 따라 머지 차단
보안 이슈 발견 시 CI 실패 처리
- name: Run security-focused review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    REVIEW_RESULT=$(claude review \
      --focus security \
      --severity-threshold high \
      --output json)

    echo "$REVIEW_RESULT" | jq '.issues[] | select(.severity == "critical" or .severity == "high")' > critical_issues.json

    if [ -s critical_issues.json ]; then
      echo "Critical security issues found:"
      cat critical_issues.json
      exit 1  # CI 실패 처리
    fi

    echo "No critical security issues found."

--severity-threshold high로 설정하면 HIGH 이상 심각도의 이슈만 보고합니다. --output json으로 결과를 JSON 형식으로 받아 jq로 파싱하면 자동화 처리가 용이합니다.

⚠️ 막히는 케이스: --output json으로 받은 결과가 비어 있다 — Claude Code 버전이 오래됐을 때 발생합니다. npm update -g @anthropic-ai/claude-code로 최신 버전으로 업데이트하세요. Actions 캐시에 구버전이 남아 있는 경우라면 actions/cache 키를 변경해서 캐시를 무효화하세요.
보안 스캔과 CI 게이팅 통합 — 리뷰 규칙 설정과 CI 파이프라인 흐름도
Claude Code 가이드 #15 — Code Review 자동화 — 보안 스캔과 CI 게이팅 통합 흐름도 (출처: 공식 문서 및 벤치마크 데이터 기반)

실전 코드 리뷰 자동화 팁

Claude Code 리뷰를 팀에 안착시키기 위한 실전 팁입니다.

초안 리뷰 vs 최종 리뷰 분리

PR 생성 시(opened)에는 전체 리뷰, 업데이트(synchronize) 시에는 변경된 파일만 리뷰하는 방식으로 비용과 속도를 최적화할 수 있습니다.

LGTM 자동 처리

Claude Code가 이슈를 전혀 발견하지 못한 경우 자동으로 "LGTM" 코멘트를 달도록 설정하면, 리뷰 없이 머지된 것처럼 보이는 문제를 방지할 수 있습니다.

리뷰 결과 요약 Slack 알림

Critical 이슈가 발견됐을 때 Slack으로 알림을 보내면 팀원이 빠르게 대응할 수 있습니다.

요약 및 관련 편

정리하면:

  • claude review로 로컬에서 즉시 코드 리뷰 가능 — git diff 기반으로 동작
  • GitHub Actions 워크플로우에 통합하면 PR마다 자동 리뷰 코멘트가 달림
  • .claude/review.json으로 팀 규칙, 집중 영역, 제외 파일을 커스터마이징
  • 보안 이슈는 --severity-threshold와 CI 실패 처리로 머지 게이팅 가능
  • 증분 리뷰(synchronize 이벤트)로 비용 최적화

관련 가이드:

참고: GitHub Actions 공식 문서 | Claude Code 개요

claude-code클로드 코드코드리뷰github-actionsci-cd자동화
← 이전
Claude Code 가이드 #14 — 웹 & 리모트 실행다음 →
Claude Code 가이드 #16 — 데스크톱 앱 심화

관련 도구

관련 포스트

Claude Code 가이드 #6 — GitHub Actions 연동2026-01-27Claude Code 가이드 #5 — 에이전트 & 서브에이전트2026-01-25Claude Code 가이드 #11 — Skills 완벽 가이드2026-03-23Claude Code 가이드 #12 — Hooks로 워크플로우 자동화2026-03-23