Running Claude in CI: A GitHub Actions + Claude Code SDK Auto-PR-Reviewer That Costs $0.03 per Review

개요

이 GitHub Actions 워크플로는 Claude Code SDK를 사용하여 각 풀 리퀘스트(pull request) 시 변경된 코드의 diff만을 분석하여 GitHub API를 통해 인라인 리뷰 코멘트를 자동으로 게시하는 시스템을 구축하는 방법을 설명합니다.

주요 내용

* Claude API를 활용한 코드 리뷰 자동화: GitHub Actions 워크플로우와 Python 스크립트를 결합하여, 풀 리퀘스트 발생 시 Claude Code SDK가 코드 변경사항(diff)만을 분석하고 그 결과를 GitHub API를 통해 인라인 코멘트로 작성합니다.
* 비용 절감을 위한 diff 기반 리뷰: 전체 파일을 Claude에 전달하는 대신, 3줄의 컨텍스트를 포함한 git diff를 사용함으로써 입력 토큰을 5~15배 감소시켜 리뷰당 비용을 약 $0.03으로 절감했습니다. (Claude-haiku-4-5 기준)
* 명확한 프롬프트 설계: Claude에게 버그, 미처리 오류, null 체크 누락, 비밀 키 노출, 디버그 흔적 등 특정 유형의 코드 문제점을 검토하도록 지시하고, 불확실한 경우 침묵하도록 하여 불필요한 코멘트를 줄였습니다.
* GitHub Actions 워크플로우 설정: on: pull_request, permissions: pull-requests: write, actions/checkout@v4 (fetch-depth: 0), astral-sh/setup-uv@v5 설정 등을 포함하는 .github/workflows/claude-review.yml 파일의 구성 요소를 상세히 안내합니다.
* Python 스크립트 구현: anthropic 및 PyGithub 라이브러리를 사용하여 diff 생성, Claude API 호출, 그리고 GitHub API를 통한 인라인 코멘트 작성을 처리하는 .github/scripts/review.py 스크립트의 핵심 로직을 제공합니다. 특히 Claude의 응답을 구조화된 JSON 형식으로 강제하기 위해 tool_choice 기능을 활용합니다.
* 인라인 코멘트 오류 처리: Claude가 제안한 라인 번호가 실제 diff에 포함되지 않아 발생하는 HTTP 422 오류를 처리하기 위해, 오류 발생 시 일반 이슈 코멘트로 대체하는 try-except 구문을 추가하여 코멘트 누락을 방지하고 인라인 코멘트 성공률을 60%에서 94%로 향상시켰습니다.
* 무한 루프 방지: synchronize 트리거와 Claude가 자체적으로 수정사항을 커밋하는 경우 발생할 수 있는 리뷰-수정-리뷰의 무한 루프를 방지하기 위해, 워크플로우 YAML에서 if 조건을 활용하거나 Python 스크립트에서 봇(bot)에 의한 이벤트임을 확인하는 로직을 추가했습니다.
* 리뷰의 실제 성능 및 한계: 60건의 PR 리뷰에서 11건의 실제 버그와 23건의 유효한 지적사항을 발견했으며, 6건의 오탐지를 기록했습니다. 파일 간의 복잡한 의도를 이해해야 하는 버그는 놓치는 한계가 있어 인간 리뷰어를 완전히 대체하기보다는 효율적인 1차 검토 도구로서의 가치를 강조합니다.
* 경제적 이점: 60건의 리뷰에 총 $1.68의 비용이 소요되어, 유료 SaaS 리뷰어 대비 상당한 비용 절감 효과를 제시합니다.

시사점

이 시스템은 Claude Code SDK와 GitHub Actions를 통합하여 개발 비용을 최소화하면서도 코드 품질을 향상시킬 수 있는 자동화된 코드 리뷰 프로세스를 구축할 수 있음을 보여줍니다. 이를 통해 개발팀은 반복적이고 사소한 코드 검토에 소요되는 시간을 줄이고, 더 중요하고 복잡한 아키텍처 설계에 집중할 수 있습니다.