GitHub Actions Claude Code PR 자동 리뷰 5단계 — 비용 통제형 셋업

GitHub Actions에 Claude Code Action을 붙이면 PR이 열릴 때마다 봇이 변경 사항을 읽고 인라인 코멘트를 달아줘요. 이슈 라벨링이나 테스트 실행까지 같은 워크플로에 얹을 수도 있고요.

문제는 비용이에요. "이거 켜뒀다가 요금 폭탄 맞는 거 아닌가" 싶어서 도입을 미루는 경우가 많은데, 실제로 비용이 튀는 상황은 대체로 turn 제한을 안 걸었거나, 캐싱을 안 켰거나, 콘솔에 상한을 안 걸어둔 것 셋 중 하나예요. 반대로 말하면 이 세 가지만 챙기면 예산이 통제 범위 안에 들어와요.

이 글은 5단계 셋업 + 안전장치 + 비용 절감 노하우를 순서대로 정리한 내용이에요. 요금은 수시로 바뀌니 구체적인 금액은 Anthropic 공식 요금 페이지를 기준으로 잡으세요.

비용 구조 — 무엇이 요금을 좌우하나

금액을 외우는 것보다 어떤 항목이 비용을 밀어 올리는지 아는 게 훨씬 쓸모 있어요. 트리거 종류별 부담은 대략 이렇게 갈려요.

정리하면 비용의 대부분은 대형 PR과 깊은 분석 트리거에서 나와요. 평범한 리뷰는 캐싱만 켜두면 부담이 크지 않은 편이고요. 그래서 예산 관리의 핵심은 요금제 고르기가 아니라 "깊게 볼 PR을 어떻게 골라낼 것인가"예요.

구독 vs API — 어느 쪽을 고를까

판단 기준은 단순해요. 트리거 횟수가 적고 들쭉날쭉하면 쓴 만큼만 내는 API가 맞고, 매일 꾸준히 도는 팀이라면 금액이 고정되는 구독이 예산 짜기 편해요. 구독제는 rate limit이 걸리는 대신 추가 청구 걱정이 없다는 점이 장점이고요.

순서를 추천하자면 첫 달은 API로 시작해서 실제 사용 패턴을 재보고, 그 데이터를 근거로 구독 전환을 판단하는 방식이 안전해요. 감으로 요금제부터 고르면 과하게 결제하거나 반대로 한도에 계속 걸리기 쉬워요. 각 요금제의 실제 금액과 한도는 도입 시점에 공식 페이지에서 직접 확인하세요.

5단계 셋업 — Claude Code Action 도입

단계 1. ANTHROPIC_API_KEY 발급 + GitHub Secrets 등록

claude.ai 콘솔 → API Keys → "Create Key" 누르고 'github-actions-pr-review-bot' 같은 명확한 이름. 권한은 최소한으로 — Read/Write 만, Admin 안 줌.

발급 즉시:

1. claude.ai 콘솔 → Settings → Spending limits → $100/월 설정
2. GitHub 레포 → Settings → Secrets and variables → Actions
3. New repository secret → 이름 ANTHROPIC_API_KEY, 값 붙여넣기
4. 환경(environment) 분리하고 싶으면 'production' environment 만들고 거기에만 secret 등록

단계 2. .github/workflows/claude-pr-review.yml 작성

name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
    branches: [main, develop]

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false
    permissions:
      contents: read
      pull-requests: write
      issues: write
    environment: production
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: secrets.ANTHROPIC_API_KEY
          # 모델 ID는 Anthropic 공식 문서에서 최신 값을 확인해 채우세요
          model: MODEL_ID
          max-turns: 8
          system-prompt: |
            너는 코드 리뷰 전문가야.
            PR 변경 사항을 7가지 관점에서 분석하고 인라인 코멘트 작성:
            1. 잠재적 버그
            2. 타입 안전성
            3. 테스트 커버리지
            4. 성능 회귀
            5. 보안 위험
            6. 코드 스타일
            7. 비즈니스 로직 모순
          prompt: |
            이 PR을 리뷰하고 인라인 코멘트 작성해줘.
            심각도 상 5개 이상이면 'changes-requested' 리뷰,
            그 외는 'commented' 리뷰로 마무리.

주의: 위 YAML 의 secrets.ANTHROPIC_API_KEY 부분은 GitHub 표준 표현식 문법 (대괄호 둘러싸인 문법) 인데, 이 글에서 마크다운 렌더링 문제로 단순 표기. 실제 작성 시엔 표준 시크릿 참조 문법 사용하세요.

단계 3. CODEOWNERS 와 결합 — 자동 리뷰어 지정

.github/CODEOWNERS 파일:

# 모든 PR 에 Claude 봇이 코드 리뷰 어사인
*  @claude-bot

# 보안 민감 영역은 사람도 추가
src/auth/  @claude-bot @senior-dev
src/payment/  @claude-bot @senior-dev @cto

이렇게 두면 PR 오픈 시 자동으로 Claude 봇 어사인 + 사람 리뷰어도 자동.

단계 4. 라벨 기반 트리거 분기

특정 라벨일 때만 깊은 분석. .github/workflows/deep-review.yml:

name: Claude Deep Security Review

on:
  pull_request:
    types: [labeled]

jobs:
  security:
    if: github.event.label.name == 'security-review'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: secrets.ANTHROPIC_API_KEY
          # 모델 ID는 Anthropic 공식 문서에서 최신 값을 확인해 채우세요
          model: MODEL_ID
          max-turns: 15
          system-prompt: |
            너는 보안 감사 전문가.
            OWASP Top 10 기준 + 최신 CVE 검토.
          prompt: 이 PR 의 보안 취약점 5가지 깊이 분석.

라벨 'security-review' 붙은 PR 만 깊은 분석. 평소엔 단순 리뷰만, 큰 변경에만 보안 감사.

단계 5. 결과 저장 + 메트릭 수집

PR 자동 리뷰 결과를 별도 레포 claude-review-logs 에 저장:

- name: Save Review Log
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: review-${{ github.event.pull_request.number }}
    path: review-output.json
    retention-days: 90

매주 1번 메트릭 집계: 처리 PR 수·평균 코멘트 수·발견 이슈 심각도 분포·자동 머지 비율·비용 합계. 이걸로 운영 효율 추적.

비용 절감 5가지 노하우

1. Prompt Caching 필수 활성화

리뷰마다 같은 코드베이스를 통째로 다시 보내면, 실제로 바뀐 건 몇십 라인인데 입력 토큰은 매번 최대치로 잡혀요. 비용이 튀는 지점이 대체로 여기예요. prompt caching을 켜두면 첫 호출에서 캐시를 만들고 이후 호출은 캐시를 읽는 방식이라 반복되는 부분의 입력 부담이 줄어들어요. 캐시 쓰기·읽기 단가 배수와 캐시 유지 시간은 Anthropic 공식 문서 기준으로 확인하세요.

Claude Code Action 은 자동으로 cache 적용하지만, 직접 API 호출 시 명시 필요:

system=[{
    "type": "text",
    "text": codebase_content,
    "cache_control": {"type": "ephemeral"}
}]

같은 ai-blog의 Claude AI 키워드 분석 블로그 글 최적화 에서도 캐싱 활용 사례 다뤘는데, 코드 리뷰 자동화에서도 동일 원리예요.

2. max-turns 8~10 으로 제한

값을 비워두면 액션 기본 동작을 그대로 따라가서, 무한 루프나 과도한 분석으로 이어질 여지가 있어요. PR 리뷰는 5~10턴이면 충분하니 명시적으로 걸어두세요.

3. 작은 PR 분리 권고

2000라인 넘는 PR은 비용 + 분석 품질 둘 다 떨어져요. 의뢰인(개발자)에게 "PR 500 라인 이하로 쪼개주세요" 가이드 PR 템플릿에 명시.

4. 라벨 기반 분기 — 모든 PR 깊게 안 봄

평범한 리팩터링 PR까지 보안 감사를 돌리면, turn 수도 늘고 읽는 파일 범위도 넓어져서 같은 PR인데 비용 부담이 훨씬 커져요. 라벨 'security-review' / 'deep-review' 붙은 PR만 깊게 보도록 분기하세요.

5. 야간 batch mode 활용

긴급하지 않은 PR(의존성 업데이트·문서 수정)은 batch mode로 돌려도 충분해요. Anthropic의 Message Batches API는 즉시 응답 대신 비동기로 처리하는 대신 단가가 낮게 책정돼 있어요. 할인 폭과 결과 보장 시간은 공식 문서 기준으로 확인하시고, "리뷰가 몇 시간 늦어도 되는 PR"을 골라내는 게 핵심이에요.

batch = client.messages.batches.create(
    requests=[{...}, {...}, ...]
)

ANTHROPIC_API_KEY 노출 사고 방지 — 5가지 안전장치

1. GitHub Secrets에만 저장

코드·로그·디스코드·이메일 절대 X. .env 파일에 적었다가 commit 사고 흔함. .gitignore 에 .env* 추가 + git pre-commit hook 으로 secret 패턴 검출.

2. API 키 분리 — 봇 전용

본인 개인 ANTHROPIC_API_KEY 와 봇용 분리. 봇용은 claude.ai 콘솔에서 별도 발급. 사고 시 봇 키만 회수, 본인 작업 영향 0.

3. environment 한정

jobs:
  review:
    environment: production

environment: production 명시하면 GitHub UI에서 "production environment 의 secrets" 만 접근. 다른 환경(staging)에서 이 secret 못 쓰게 격리.

4. Workflow 로그 verbose 끄기

set -x 또는 echo $ANTHROPIC_API_KEY 같은 디버그 코드 사고 방지. 의심스러우면 ::add-mask:: 으로 마스킹.

5. Spending limits + Alert

claude.ai 콘솔 → Settings → Spending limits:

• 월 한도 $100 설정
• 50% 도달 시 이메일 알림
• 100% 도달 시 자동 차단

설정을 잘못 걸어 호출이 폭주하더라도, 상한선이 있으면 피해가 그 금액에서 끊겨요. 안전장치 중에 품이 가장 적게 드는 항목이니 도입 첫날 바로 걸어두세요.

흔한 실수 5가지

실수 1. max-turns 안 정함

턴 수를 안 걸면 한 번의 리뷰가 어디까지 늘어날지 예측이 안 돼요. 8~10 으로 명시 필수.

실수 2. Spending limits 안 걸어둠

상한이 없으면 잘못된 트리거 하나가 그대로 청구로 이어져요. 콘솔에서 한도 설정만 해둬도 사고 대부분이 막혀요.

실수 3. 모든 PR 깊은 분석

평범한 리팩터링까지 보안 감사를 돌리면 turn 수와 읽는 파일 범위가 함께 늘어 비용이 불필요하게 커져요. 라벨로 분기하세요.

실수 4. ANTHROPIC_API_KEY 셸 environment 에 저장

.bashrc 에 export ANTHROPIC_API_KEY=... 두면 자식 프로세스 모두 상속. claude -p 같은 CLI 실수로 폭주 가능. GitHub Secrets만.

실수 5. PR 컨텍스트에 .env·secrets 파일 포함

.dockerignore·.gitignore 에 secrets 파일 패턴 명시. PR diff 에 포함되면 Claude가 그대로 분석에 쓰면서 로그·결과에 노출 위험.

도입 효과는 어떻게 재나 — 직접 측정할 지표

남의 숫자를 가져다 쓰면 우리 레포에서 그대로 재현되지 않아요. 코드베이스 크기·PR 문화·팀 규모가 전부 다르기 때문이에요. 그래서 도입 첫 달에는 아래 항목을 직접 기록해서 본인 기준선을 만드는 게 맞아요.

• 처리 PR 수: 봇이 실제로 트리거된 횟수. 예상보다 적으면 트리거 조건이 좁은 거예요
• PR당 코멘트 수: 너무 적으면 프롬프트가 두루뭉술한 것, 너무 많으면 노이즈예요
• 코멘트 채택률: 개발자가 실제로 반영한 코멘트 비율. 이게 품질의 핵심 지표예요
• 사람 리뷰까지 걸린 시간: 봇이 1차로 걸러준 덕에 줄었는지 확인
• 월 사용량: 콘솔 대시보드 기준. 요금제 전환 판단의 근거가 돼요

이 중에서 하나만 본다면 코멘트 채택률을 보세요. 코멘트 수가 아무리 많아도 개발자가 전부 무시하면 비용만 나가는 거예요. 채택률이 낮으면 모델을 바꾸기 전에 system-prompt의 관점 목록부터 손보는 게 순서예요. 팀이 실제로 자주 놓치는 항목만 남기고 나머지는 빼는 식으로요.

측정 주기는 주 1회면 충분해요. 5단계에서 만든 아티팩트 로그를 그대로 집계하면 별도 작업 없이 숫자가 쌓여요. 같은 ai-blog의 n8n + Claude API 자동화 5단계 에서 다룬 지표 수집 방식도 같은 원리로 응용할 수 있어요.

이 셋업이 잘 맞는 팀·안 맞는 팀

모든 레포에 필요한 건 아니에요. 도입 전에 한 번 걸러보세요.

잘 맞는 경우

• 리뷰어가 한두 명뿐이라 PR이 대기열에 쌓이는 팀
• 외부 기여자 PR이 자주 들어오는 오픈소스 레포
• 주니어 비중이 높아 기본적인 지적이 반복되는 조직
• 테스트 누락·타입 미비처럼 기계적으로 잡히는 문제가 잦은 코드베이스

안 맞는 경우

• PR이 한 달에 몇 건뿐인 소규모 개인 프로젝트. 굳이 자동화할 이유가 없어요
• 도메인 지식이 있어야만 판단되는 코드. 봇이 맥락을 몰라 엉뚱한 지적을 해요
• 대형 PR을 통째로 올리는 문화. 이건 봇을 붙이기 전에 PR 쪼개기부터 해야 해요
• 리뷰 코멘트를 강제 차단 조건으로 쓰려는 경우. 봇 리뷰는 참고용이지 게이트가 아니에요

특히 마지막 항목을 조심하세요. 봇이 'changes-requested'를 남발하면 개발자들이 리뷰 자체를 무시하기 시작하고, 그러면 자동화가 오히려 방해물이 돼요. 처음에는 'commented' 수준으로만 두고, 팀이 코멘트 품질을 신뢰하게 된 뒤에 강도를 올리는 걸 권해요.

마무리 — 다음 단계

5단계 셋업 익숙해지면 다음 확장:

1. Slack 알림 통합 — critical 이슈 발견 시 즉시 알림
2. JIRA 자동 이슈 생성 — 중간 심각도 이슈를 백로그로
3. 테스트 자동 작성 — PR이 새 함수 추가 시 테스트 자동
4. 문서 자동 갱신 — public API 변경 시 README 자동 갱신
5. 릴리스 노트 생성 — 마일스톤 PR 모아서 changelog

확장할수록 트리거가 늘어나는 만큼 비용도 같이 올라가니, 하나 켤 때마다 콘솔 사용량을 확인하고 다음 단계로 넘어가세요. 같은 ai-blog의 Claude Code 자동화 5가지 실전 사용기 와 함께 보면 전체 자동화 흐름 잡기 쉬워요.

처음엔 단순 PR 리뷰 1단계만 켜고 한 달 데이터 쌓아보세요. 비용 패턴 + 정확도 둘 다 검증되면 단계별 확장. 처음부터 다 켜면 디버깅 어려워서 결국 다 끄는 사례 많아요.