CI에서 Claude Code 돌리기: PR 자동 리뷰 파이프라인 만들기

핵심 요약: Claude Code는 대화형 말고 헤드리스 모드(claude -p "지시")로도 돌아갑니다 — 이걸 GitHub Actions에 얹으면 "PR이 열리면 Claude가 diff를 리뷰하고 코멘트를 다는" 파이프라인이 됩니다. 구성 요소는 셋: ① API 키(구독이 아니라 API 종량 과금 — 저장소 시크릿으로) ② 워크플로 yml(PR 트리거 → diff 추출 → claude -p → 코멘트 게시) ③ 리뷰 기준을 담은 프롬프트(또는 저장소의 AGENTS.md/CLAUDE.md 활용). 주의 두 가지 — 비용 상한(대형 PR에서 폭주 방지)과 권한 최소화(코멘트 쓰기까지만, 코드 수정 권한 금지)가 안전장치입니다.

이 글에서 다루는 내용: 헤드리스 모드의 동작, PR 리뷰 워크플로 구성, 비용·보안 통제, 잘 되는 리뷰 프롬프트.

헤드리스 모드 1분 이해

claude -p "이 diff를 리뷰해줘" < diff.txt — 대화 없이 지시 하나를 처리하고 결과를 출력하고 끝납니다. 출력 형식 지정(JSON 등), 도구 권한 제한 플래그와 조합하면 스크립트의 부품이 되죠. 로컬에서 파이프로 쓰는 것도 유용하지만(git diff | claude -p "..."), 진가는 CI에서 나옵니다 — 사람이 없는 곳에서 도는 반복 작업이니까요.

PR 리뷰 워크플로의 뼈대

# .github/workflows/ai-review.yml (개념 뼈대)
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write   # 코멘트까지만
      contents: read
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - run: |
          git diff origin/${{ github.base_ref }}...HEAD > pr.diff
          claude -p "$(cat .github/review-prompt.md)" < pr.diff > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - run: gh pr comment ${{ github.event.number }} --body-file review.md
        env:
          GH_TOKEN: ${{ github.token }}

실제 구성 시에는 diff 크기 상한(아래), 봇 PR 제외 조건, 재실행 시 기존 코멘트 갱신 로직을 얹게 됩니다. 공식 GitHub 통합·액션이 제공되는지 먼저 확인하세요 — 있다면 직접 조립보다 그쪽이 유지보수가 쌉니다.

비용 통제: 여기가 승부처

CI의 Claude는 구독이 아니라 API 종량제입니다 — PR마다, 커밋 푸시마다 도니까 통제 없이는 청구서가 놀랍게 자랍니다. 장치 세 가지: diff 크기 상한(예: 3,000줄 초과 시 "너무 커서 요약 리뷰만" 모드로 전환), 트리거 조절(모든 push가 아니라 opened + ready_for_review만, draft 제외), 모델 선택(리뷰엔 Sonnet이면 충분 — Opus는 과합니다, 그 기준). 그리고 조직 대시보드에서 월 지출 한도를 반드시 설정하세요.

리뷰 프롬프트: 사람 체크리스트를 이식

"코드 리뷰해줘"는 잡동사니 코멘트를 만듭니다. 기준을 명시하세요 — 요구사항 대조는 못 하니(CI는 요구를 모름) 그 아래 단계인 API 실존·엣지 케이스·조용한 가정·중복·보안에 집중시키고, "심각도 상·중만 보고, 스타일 지적 금지(린터 몫), 각 지적에 파일:줄 명시" 같은 출력 규칙을 붙입니다. 저장소에 AGENTS.md가 있다면 프롬프트에서 참조시키세요 — 프로젝트 관례 기준의 리뷰가 됩니다(AGENTS.md 글).

운용해보니

제 저장소에 2주 돌린 소감 — 가치는 "사람 리뷰 대체"가 아니라 "사람 리뷰 전의 방범대"에 있습니다. 뻔한 결함이 봇 코멘트로 먼저 걸러지니 사람 리뷰가 설계·요구 정합성에 집중하게 됐고, 심야에 올린 PR도 아침엔 1차 리뷰가 달려 있는 리듬이 좋았습니다. 실패담도 하나: 초기엔 draft PR에도 돌게 해놔서 WIP 커밋마다 리뷰가 달리는 소음 + 비용 낭비가 있었습니다 — ready_for_review 트리거로 바꾸고 해결됐습니다.

자주 묻는 질문 (FAQ)

Q. 구독(Pro/Max)으로 CI를 돌릴 수는 없나요?

A. 구독은 개인 대화형 사용 전제라 CI에는 API 키 방식이 맞습니다. 팀 CI라면 조직 API 계정으로 분리해 지출을 관리하세요.

Q. 리뷰 봇이 코드를 직접 고치게 해도 되나요?

A. 권하지 않습니다. CI의 에이전트에게는 코멘트 권한까지만 — 수정은 사람이 지시하는 대화형 세션에서 하는 것이 통제 가능한 구성입니다. permissions의 contents는 read로 유지하세요.

Q. 시크릿이 diff에 있으면 API로 전송되지 않나요?

A. 전송됩니다. 시크릿이 커밋되지 않게 하는 장치(pre-commit 스캐너)가 선행돼야 하고, 이건 AI 리뷰 이전의 기본기입니다.

한눈에 보는 요약

claude -p + Actions + 기준 프롬프트 = PR 방범대. API 종량임을 잊지 말고 diff 상한·트리거 조절·지출 한도부터 걸고 시작하세요. 역할은 사람 리뷰의 대체가 아니라 전처리입니다.

함께 보면 좋은 글

AI가 짠 코드, 뭘 봐야 하나 (리뷰 체크리스트)
Claude Code 훅 레시피 5가지
AGENTS.md란?

참고 자료

Claude Code 공식 문서 (헤드리스·CI)
GitHub Actions 문서