Models overview - Anthropic API 공식 문서

PR 하나 올릴 때마다 팀원을 기다리는 시간이 아까웠어요. 혼자 개발하는 프로젝트라면 더 막막하죠. 이 글을 읽고 나면 GitHub Actions로 모든 PR에 Claude API를 붙여서, 사람보다 먼저 버그·보안 이슈를 자동으로 지적받을 수 있게 됩니다. 실제 워크플로우 YAML과 비용 계산까지 직접 설정한 경험을 공유할게요.

준비물

다음 네 가지만 갖춰두세요.

• GitHub 저장소: Actions가 활성화된 public 또는 private 리포지토리
• Claude API 키: Anthropic 콘솔에서 발급 (요금·플랜은 공식 페이지에서 확인하세요)
• git 기본 지식: PR 생성·브랜치 전환 정도
• YAML 편집기: VS Code나 GitHub 웹 에디터면 충분합니다

제가 테스트한 환경은 Node.js 프로젝트였지만, 언어 상관없이 diff만 읽을 수 있으면 작동해요.

워크플로우 파일은 어떻게 만드나요?

리포지토리 루트에 .github/workflows/ai-review.yml 파일을 새로 만듭니다. 저는 아래 구조로 시작했어요.

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get PR diff
        id: diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > changes.diff
      - name: Call Claude API
        env:
          CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}
        run: |
          curl -X POST https://api.anthropic.com/v1/messages \
            -H "x-api-key: $CLAUDE_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "content-type: application/json" \
            -d @payload.json > review.json

이렇게 입력하면 → PR이 열리거나 업데이트될 때마다 워크플로우가 자동 실행됩니다. fetch-depth: 0을 빼먹으면 diff를 제대로 못 가져와서 30분 날렸어요.

YAML 필드 상세 설명 types: [opened, synchronize]는 PR이 처음 생성되거나(opened) 새 커밋이 푸시될 때(synchronize)만 트리거한다는 뜻입니다. reopened나 edited 같은 이벤트는 제외해서 불필요한 실행을 막았어요. fetch-depth: 0은 전체 git 히스토리를 가져오라는 옵션인데, 이게 없으면 shallow clone이 돼서 base 브랜치와 비교할 커밋이 없어 diff 생성이 실패합니다. github.base_ref는 PR의 타겟 브랜치(보통 main), HEAD는 현재 PR 브랜치 최신 커밋이에요. ... 문법은 두 브랜치의 공통 조상부터 HEAD까지 변경점만 추출하는 git의 three-dot diff입니다.

API 키와 시크릿 등록은 어떻게 하죠?

Anthropic 콘솔에서 API 키를 발급받은 뒤, GitHub 리포지토리 Settings → Secrets and variables → Actions로 들어갑니다. New repository secret 버튼을 눌러서 이름은 CLAUDE_API_KEY, 값은 발급받은 키를 붙여넣으세요.

이제 워크플로우에서 ${{ secrets.CLAUDE_API_KEY }}로 안전하게 불러올 수 있습니다. 처음엔 .env 파일에 넣었다가 공개 리포지토리라 키가 그대로 노출됐던 실수가 있었거든요.

코드리뷰 로직 구현하기

diff 파일을 Claude에게 보내서 리뷰를 받는 단계입니다. 저는 payload.json을 동적으로 만들었어요.

cat <<EOF > payload.json
{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "다음 PR diff를 분석해서 버그·보안·성능 이슈를 한국어로 지적해줘:\n\n$(cat changes.diff)"
    }
  ]
}
EOF

이렇게 입력하면 → review.json에 Claude의 리뷰가 JSON 형태로 담깁니다.

payload 필드별 역할 model은 사용할 Claude 모델 버전입니다. Anthropic 모델 문서 기준, 2025년 10월 출시된 Haiku 4.5(claude-haiku-4-5-20251001)는 비용 효율이 좋은 경량 모델이에요. 코드리뷰처럼 명확한 작업엔 충분하고, 품질이 더 필요하면 claude-sonnet-4-5-20250514로 바꿀 수 있습니다. 정확한 최신 모델 ID는 Anthropic 모델 문서에서 확인하세요. max_tokens는 Claude가 생성할 최대 응답 길이인데, 2048로 설정하면 대략 1500~2000단어 정도 나옵니다. 리뷰가 중간에 잘리면 이 값을 4096이나 8192로 늘리면 돼요. messages 배열은 대화 형식인데, role: user는 사용자 질문, content에 실제 diff 텍스트를 $(cat changes.diff) 명령어 치환으로 삽입합니다. API 응답은 {"content": [{"type": "text", "text": "실제 리뷰 내용"}]} 구조라서 jq -r '.content[0].text'로 중첩 배열을 풀어야 텍스트만 추출돼요.

비용 추정과 최적화

Claude API는 입력·출력 토큰 수로 과금됩니다. 제가 50줄 diff를 보냈을 때 대략 입력 600토큰, 출력 400토큰이 나왔어요. 모델과 플랜에 따라 토큰당 요금이 다르니 Anthropic 공식 요금표를 꼭 확인하세요.

실제 비용 계산 예시 제가 가입한 시점 기준으로, 입력 600토큰과 출력 400토큰을 합쳐 총 1000토큰 정도였습니다. 한 달에 PR 30개 정도 올린다면 월 30,000토큰 정도 소비하는 셈이에요. 대규모 리팩토링 PR은 diff가 2000줄 넘어가서 입력만 5000토큰을 넘기기도 했습니다. 이럴 때는 아래처럼 diff 크기를 제한하는 게 좋아요.

- name: Check diff size
  id: check
  run: |
    LINES=$(wc -l < changes.diff)
    if [ $LINES -gt 1000 ]; then
      echo "skip=true" >> $GITHUB_OUTPUT
    fi
- name: Call Claude API
  if: steps.check.outputs.skip != 'true'
  # ... (위와 동일)

이렇게 하면 → 1000줄 이상 diff는 자동 스킵되고, 작은 기능 추가 PR만 리뷰를 받습니다.

리뷰 결과를 PR 코멘트로 달기

Claude가 생성한 리뷰를 사람이 직접 확인하려면 PR 코멘트로 자동 게시하는 게 편합니다. GitHub CLI를 워크플로우에 설치하고 아래 스텝을 추가하세요.

- name: Post review comment
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    REVIEW_TEXT=$(cat review.json | jq -r '.content[0].text')
    gh pr comment ${{ github.event.pull_request.number }} \
      --body "$REVIEW_TEXT"

이렇게 입력하면 → PR 페이지에 Claude의 리뷰가 코멘트로 자동 등록됩니다. GITHUB_TOKEN은 Actions가 기본 제공하는 시크릿이라 별도 등록 불필요해요. 저는 리뷰 텍스트 앞에 ## 🤖 AI 코드리뷰라는 헤더를 붙여서 사람 코멘트와 구분했습니다.

흔한 실수와 해결법

API 키 노출: .env 파일을 커밋하거나, 워크플로우 로그에 키가 찍히는 경우가 많습니다. echo $CLAUDE_API_KEY 같은 디버깅 명령은 절대 남기지 마세요. 저는 한 번 키를 재발급해야 했거든요.

토큰 제한 초과: max_tokens를 너무 작게 설정하면 리뷰가 중간에 잘립니다. 2048로 설정했는데도 긴 diff는 잘려서, 이후 4096으로 늘렸어요. 대신 입력 diff를 핵심 파일만 필터링하는 스크립트를 추가했습니다.

트리거 설정 실수: on: push로 해뒀다가 모든 커밋마다 실행돼서 비용이 10배 뛰었어요. on: pull_request로 바꾸고 types: [opened, synchronize]만 남겨두니 해결됐습니다.

rate limit 함정: Anthropic API는 분당 요청 수 제한이 있습니다. PR이 동시에 5개 열리면 429 에러가 나면서 워크플로우가 실패해요. 저는 워크플로우에 retry 로직을 추가했습니다. curl에 --retry 3 --retry-delay 5 옵션을 붙이면 실패 시 5초 간격으로 3번까지 재시도합니다.

diff 토큰 한계 초과: Anthropic 모델 문서 기준으로 각 모델마다 입력 토큰 한계가 있습니다. 대규모 PR은 diff 자체가 이 한계를 넘어서 API 호출이 실패할 수 있어요. 저는 diff를 파일 단위로 chunk해서 여러 번 나눠 보내는 스크립트를 만들었습니다. 각 chunk별로 리뷰를 받은 뒤 결과를 병합해서 하나의 코멘트로 달았어요.

마무리

이제 코드를 푸시하면 사람보다 먼저 AI가 잠재 버그를 찾아줍니다. 다음 단계로는 리뷰 결과를 Slack이나 Discord로 자동 전송하는 알림 연동을 추천해요. 작은 팀일수록 코드 품질 유지 비용이 확 줄어드는 걸 체감할 거예요.

자주 묻는 질문

Q. GitHub Actions 무료 플랜으로도 쓸 수 있나요? A. 네, public 리포지토리는 무료 사용량 제한 없이 쓸 수 있습니다. GitHub 공식 문서 기준으로 private 리포지토리는 월 2000분 무료 제공량이 있고, 이 워크플로우는 PR당 1~2분 정도 소요되니 충분해요.

Q. Claude 말고 다른 LLM도 가능한가요? A. 가능합니다. OpenAI GPT-4나 Google Gemini API로 교체하려면 curl 엔드포인트와 페이로드 형식만 바꾸면 돼요. 각 API의 인증 헤더 형식이 다르니 공식 문서를 참고하세요.

Q. 리뷰 품질이 떨어지면 어떻게 개선하죠? A. 프롬프트를 구체화하세요. 저는 "다음 항목을 중점 체크: null 체크 누락, SQL 인젝션 취약점, 무한 루프 가능성"처럼 체크리스트를 추가했더니 정확도가 올라갔어요. 모델을 Sonnet이나 Opus 같은 상위 버전으로 바꾸는 것도 방법입니다.

Q. diff가 너무 길면 어떻게 하죠? A. 위에서 설명한 1000줄 제한 외에, .github/workflows/ 같은 특정 경로를 제외하는 필터를 git diff 옵션으로 추가할 수 있어요. git diff -- . ':(exclude).github' 형태로 쓰면 워크플로우 자체 수정은 리뷰에서 빠집니다.