AI 코드 리뷰 자동화 — Claude Code + GitHub Actions로 PR 리뷰 봇 만들기

핵심 요약

4개월 동안 사내 모노레포에 PR 자동 리뷰 봇을 굴려본 결과. 사람 리뷰 대체가 아닌 보조용으로 자리잡았다. 보안 누락 5건, 누락된 테스트 22건, N+1 후보 11건 사전 발견.

1. 설계 원칙

• 대체 X, 보조 O: 봇이 "approve"는 못 함. 코멘트만.
• 변경 파일만: 전체 코드베이스 X. PR diff + 직접 import한 파일.
• 구체적 한 줄 코멘트: "잘 짜셨네요"는 노이즈. 라인 번호로 박힌 코멘트만.
• 거짓양성 비용 고려: 매번 틀린 지적 → 팀이 무시함. 임계값을 보수적으로.

2. 워크플로

# .github/workflows/ai-review.yml
name: AI Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-7
          prompt_file: .github/review-prompt.md
          mode: pr_review

3. 핵심 프롬프트

# .github/review-prompt.md
당신은 시니어 풀스택 개발자. 아래 PR diff를 검토한다.

## 절대 규칙
1. 변경된 라인에만 코멘트 (주변 코드는 참고만)
2. 라인별로 최대 1개 코멘트
3. 다음 중 하나에 해당할 때만 코멘트:
   - 보안 취약점 (SQL injection, XSS, 인증 우회, secret hardcoded)
   - 명백한 N+1 / 비용 폭증 가능성
   - 누락된 에러 처리로 인한 데이터 손실 위험
   - 누락된 테스트 (퍼블릭 API 추가/시그니처 변경)
4. 스타일·취향 코멘트 금지
5. 추측은 "?"로 마무리 — 확실한 것만 단정

## 출력 형식 (JSON)
{
  "comments": [
    { "path": "...", "line": 42, "severity": "high|medium|low", "body": "..." }
  ]
}

4. 거짓양성 줄이기 — 4단계 필터

1. severity ≥ medium만 게시
2. 봇 자체 self-critique: 동일 모델에 "이 코멘트가 실제 버그인가, 스타일 의견인가?" 재질문
3. 중복 제거: 같은 라인에 비슷한 코멘트가 이전 PR에 있고 거부됐으면 제외
4. 임계 점수: 봇이 "신뢰도 70%+"라고 자평한 것만

5. 토큰 비용 관리

월 300 PR 기준 Sonnet 4.7 단독이 $54/월. 가치 충분.

6. 사람 리뷰어와의 관계

• 봇 코멘트가 먼저 달림 → 사람이 그 위에서 시작
• 사람 리뷰어가 "false positive" 라벨 누르면 학습 데이터로 적재
• 봇이 못 잡은 진짜 이슈는 "missed by bot" 라벨 → 회고에 활용

7. 측정 가능한 효과 — 4개월

8. 흔한 실패

• 모든 PR에 코멘트 100개: 임계값 안 두면 무용지물. 1차 도입시 가장 흔한 실수.
• "리팩토링 제안": 봇은 옳다고 느낄 수 있지만 팀 컨벤션 모름. 명시 금지.
• 비공개 코드 외부 송신 우려: 회사 정책 확인. Anthropic은 API 트래픽 학습 안 함. 그래도 정책 명문화 필요.

9. 다음 단계

• PR 컨텍스트 확장: 관련 Slack/Linear 티켓 본문 자동 포함
• 변경 영향 분석: 호출 그래프로 영향 받을 모듈 자동 표시
• 테스트 생성: 누락 케이스에 대해 testcase 초안 PR

참고

• github.com/anthropics/claude-code-action
• docs.anthropic.com/en/docs/claude-code