AI 코드리뷰 자동화 실전 — Claude Code + GitHub Actions 완전 세팅

PR을 올릴 때마다 팀원한테 리뷰 요청 메시지 보내고 기다리는 시간, 생각보다 꽤 많이 날아갑니다. 게다가 8시간째 같은 코드를 보다 보면 눈이 익어서 뻔한 버그도 그냥 넘어가는 경우가 생기는데, 이 반복적이고 기계적인 확인 작업만큼은 Claude에게 넘겨버릴 수 있습니다. 이번 글에서는 PR이 열리는 순간 Claude가 자동으로 코드를 읽고 리뷰 코멘트를 달아주는 워크플로우를 처음부터 세팅하는 방법을 정리해 보겠습니다.

핵심요약

Claude Code GitHub Actions는 GitHub의 PR이나 이슈에 @claude를 멘션하거나, 워크플로우 파일에 프롬프트를 지정해두면 Claude가 자동으로 코드를 분석하고 리뷰 코멘트를 남겨주는 공식 액션입니다. 동작 방식은 크게 두 가지로 나뉘는데, 하나는 PR에 @claude를 직접 멘션해서 대화형으로 쓰는 방식이고, 다른 하나는 PR이 열리거나 업데이트될 때 자동으로 실행되는 완전 자동화 방식입니다. 모델은 기본값이 claude-sonnet-4-6으로 설정되어 있고, 인증 코드나 결제 로직 같은 민감한 변경이 포함된 PR에는 Opus 4.7로 바꿔서 더 깊은 리뷰를 받을 수도 있습니다. 비용 면에서는 월 50개 PR 기준 5달러 안쪽으로 운영 가능해서, 엔지니어가 수동 리뷰에 쓰는 시간과 비교하면 가성비가 압도적입니다. CLAUDE.md 파일로 프로젝트 코딩 기준을 미리 정의해두면 팀 컨벤션까지 자동으로 검사해줍니다.

실전 1. GitHub App 설치와 시크릿 등록

가장 먼저 할 일은 GitHub 앱을 리포지토리에 설치하는 것입니다. Claude Code 터미널에서 /install-github-app 명령을 실행하면 설치 과정을 단계별로 안내해줍니다. 이 방법은 Anthropic API를 직접 쓰는 경우에만 동작하고, AWS Bedrock이나 Google Vertex AI를 쓴다면 공식 문서의 cloud-providers 가이드를 별도로 참고해야 합니다.

앱 설치가 끝나면 리포지토리의 Settings → Secrets and variables → Actions로 가서 ANTHROPIC_API_KEY를 등록합니다. 이 키는 Claude API와 Claude Code 사용 권한이 모두 활성화된 키여야 합니다. 키를 등록한 뒤에는 워크플로우 파일에서 secrets.ANTHROPIC_API_KEY로 참조하게 됩니다.

실전 2. 기본 자동 리뷰 워크플로우 만들기

리포지토리의 .github/workflows/ 디렉토리에 claude-review.yml 파일을 만들고 다음 내용을 붙여넣으면 됩니다. PR이 열리거나 커밋이 추가될 때마다 자동으로 리뷰가 실행됩니다.

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude-model: claude-sonnet-4-6
          prompt: |
            이 PR의 변경 사항을 리뷰해주세요.
            버그, 보안 이슈, 성능 문제, 코딩 컨벤션 위반을 중점으로 확인하고
            구체적인 개선 제안을 PR 코멘트로 남겨주세요.

fetch-depth를 1로 설정하는 이유가 있습니다. 이 액션은 GitHub API로 diff를 읽어오는 동시에 워킹 디렉토리의 파일도 직접 열어서 주변 코드 맥락을 확인합니다. checkout 없이 실행하면 파일을 열어보는 과정이 전부 실패해서 Claude가 맥락 없이 추측으로 리뷰를 하거나 타임아웃이 나버립니다.

실전 3. CLAUDE.md로 팀 컨벤션 주입하기

단순히 버그만 찾는 게 아니라 팀의 코딩 기준까지 검사하고 싶다면 리포지토리 루트에 CLAUDE.md 파일을 만들어두면 됩니다. Claude는 리뷰를 시작할 때 이 파일을 자동으로 읽어서 기준으로 삼습니다. 파일을 따로 설정하지 않아도 프롬프트 파라미터에 직접 기준을 적어줄 수도 있지만, 팀 전체가 공유하는 기준이라면 CLAUDE.md에 한 번 정의해두고 유지보수하는 편이 훨씬 관리가 쉽습니다.

아래는 Next.js + TypeScript 프로젝트에 맞춰 작성한 CLAUDE.md 예시입니다.

# 코드 리뷰 기준

## 기술 스택
- Next.js 14, TypeScript strict mode
- Prisma (DB), Zod (입력 검증)

## 리뷰 우선순위
1. 보안: SQL 인젝션, XSS, 인증 우회 가능성
2. 타입 안전성: any 사용, 타입 단언 남용 여부
3. 에러 처리: try-catch 누락, 에러 메시지 노출 여부
4. 성능: N+1 쿼리, 불필요한 리렌더링

## 스타일
- 함수는 단일 책임 원칙을 따른다
- 주석은 '무엇'이 아닌 '왜'를 설명한다

이 파일이 있으면 Claude는 팀이 정한 기준을 그대로 적용해서 리뷰를 작성합니다. 새로운 팀원이 합류했을 때 리뷰 기준을 따로 설명할 필요도 없어지고, 리뷰어마다 기준이 달라서 생기는 혼선도 줄어드는 부가 효과도 있습니다.

실전 4. 민감한 PR만 Opus로 골라서 돌리기

기본 Sonnet으로도 대부분의 리뷰는 충분하지만, 인증·결제·암호화 코드처럼 버그 하나가 크리티컬한 영역은 Opus로 따로 돌리는 게 안전합니다. 경로 필터를 걸어두면 특정 파일이 변경된 PR에만 Opus 리뷰가 자동으로 실행됩니다.

name: Opus Security Review

on:
  pull_request:
    paths:
      - 'src/auth/**'
      - 'src/payment/**'
      - 'src/crypto/**'

jobs:
  opus-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude-model: claude-opus-4-7
          prompt: |
            보안에 집중해서 리뷰해주세요.
            OWASP Top 10 기준으로 취약점을 분석하고,
            인증 우회, broken access control, 민감 데이터 노출 가능성을
            구체적인 코드 라인과 함께 지적해주세요.

이렇게 워크플로우를 두 개로 나눠두면, 평범한 기능 PR은 빠르고 저렴한 Sonnet이, 보안이 중요한 변경은 더 깊이 있는 Opus가 처리하는 구조가 만들어집니다.

결론

Claude Code + GitHub Actions 조합은 사람 리뷰어가 기계적인 검사에 쓰는 시간을 줄이고, 설계와 의도 파악 같이 사람이 잘하는 영역에 집중할 수 있게 만들어줍니다. 월 50개 PR 기준 5달러 안쪽이라는 비용은 엔지니어 한 명이 PR 한 개 리뷰하는 시간보다도 저렴하고, CLAUDE.md로 팀 컨벤션을 한 번 정의해두면 리뷰어마다 다른 기준이 적용되는 문제도 사라집니다. 다만 프롬프트 인젝션에는 아직 완전히 대응되지 않아서, 외부 기여자의 fork PR에는 "Require approval for all external contributors" 설정을 반드시 켜두는 것이 중요합니다.