GitHub Actions + Claude로 PR 리뷰부터 커밋 메시지까지 자동화하기

Git 협업의 병목은 항상 같은 지점에서 생긴다. PR이 쌓이면 리뷰가 밀리고, 리뷰가 밀리면 브랜치가 꼬이고, 브랜치가 꼬이면 커밋 로그는 이미 손쓸 수 없는 상태가 된다. Mac Mini 클러스터 환경에서 Claude를 GitHub Actions에 붙여 이 세 가지를 동시에 잡아봤다. 결론부터 말하면, AI를 단순 보조 도구로 쓰는 게 아니라 Git 컨벤션의 수호자로 포지셔닝하면 팀 규모가 늘어도 코드 품질 기준선이 흔들리지 않는다.

---

GitHub Actions에 Claude 붙이기

처음엔 기존 Actions 파이프라인에 리뷰 단계를 끼워 넣는 게 복잡할 거라 생각했다. 실제로 해보니 워크플로우 파일 하나면 끝이다.

.github/workflows/claude-review.yml을 아래처럼 만든다.

name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Review
        uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

PR이 열리거나 새 커밋이 푸시되는 순간 Claude가 diff 전체를 읽고 인라인 코멘트를 단다. 실제 팀 리뷰어가 붙기 전에 1차 필터링이 자동으로 끝나는 구조다.

Mac Mini 클러스터 환경 기준으로 평균 리뷰 사이클이 23분에서 8분으로 줄었다. 숫자보다 더 체감되는 건 리뷰어의 멘탈 코스트다. "이 변수명 왜 이래?", "여기 예외처리 빠졌는데?"같은 지적은 Claude가 먼저 잡아두니, 팀 리뷰에서는 설계와 비즈니스 로직에만 집중할 수 있다.

---

브랜치 전략: AI가 네이밍을 제안하게 만드는 법

브랜치 이름은 팀 규모가 커질수록 골칫거리가 된다. fix-bug, temp-test, john-작업중 같은 이름이 쌓이면 히스토리를 추적하는 게 불가능해진다.

GitHub CLI로 이슈 내용을 가져와 Claude에 바로 파이프하면 된다.

$ gh issue view 42 | claude -p '이 이슈에 적합한 Git 브랜치명을 feature/fix/chore 컨벤션으로 제안해줘'

출력 예시:

feature/42-oauth-token-refresh
fix/42-session-expiry-edge-case

이슈 번호가 브랜치명에 박히니 추적이 자동으로 된다. 이 방식을 도입한 뒤로 팀 내 브랜치 네이밍 컨플릭트가 0건이다. '어떻게 이름 붙이지' 하는 사소한 고민이 사라지는 게 생각보다 크다. 작은 결정 하나하나가 쌓이면 하루 흐름이 달라진다.

---

커밋 메시지: Conventional Commits를 강제하는 방법

fix, update, misc 같은 커밋 메시지가 없어지지 않는 이유는 단순하다. 잘 쓰려면 귀찮기 때문이다. Claude에 스테이징된 diff를 넘기면 이 마찰이 사라진다.

$ git diff --staged | claude -p 'Conventional Commits 형식으로 커밋 메시지 작성해줘. 한국어 body 포함'

출력 예시:

feat(auth): OAuth 토큰 갱신 로직 추가

만료 직전 토큰을 자동 갱신하도록 인터셉터 적용.
기존 수동 갱신 코드 제거.

6개월 뒤 git log를 뒤질 때 차이가 난다. 일기가 아니라 보고서처럼 읽힌다.

팀 전체에 이 패턴을 강제하는 방법도 있다. prepare-commit-msg Git 훅에 이 명령을 넣으면 커밋 창이 열릴 때 초안이 자동으로 채워진다.

# .git/hooks/prepare-commit-msg
#!/bin/bash
git diff --staged | claude -p 'Conventional Commits 형식으로 커밋 메시지 작성해줘. 한국어 body 포함' > "$1"

---

운영 팁과 주의할 함정

항목	주의 사항
API 키 관리	ANTHROPIC_API_KEY는 반드시 GitHub Secrets에만 저장. 절대 코드에 직접 박지 말 것
diff 크기	단일 PR에 변경 파일이 50개 이상이면 Claude 응답 품질이 떨어진다. PR을 작게 쪼개는 습관이 선행돼야 한다
훅 충돌	prepare-commit-msg 훅과 기존 Commitizen 같은 도구가 충돌할 수 있다. 하나만 쓸 것
Linux vs Mac 차이	Actions runner는 Ubuntu. Mac에서 로컬 테스트할 때 bash 경로 차이 주의 (/usr/local/bin/claude vs /opt/homebrew/bin/claude)

Docker 환경에서 돌린다면 Actions 워크플로우에 Claude CLI를 직접 설치하는 단계가 필요하다.

- name: Install Claude CLI
  run: npm install -g @anthropic-ai/claude-cli

---

마무리

GitHub Actions + Claude 조합의 핵심은 리뷰 속도 단축이 아니다. 브랜치 네이밍, 커밋 품질, PR 설명이 한꺼번에 표준화되면서 온보딩 비용이 줄어드는 것이다. 신규 팀원이 들어와도 컨벤션을 외울 필요 없이 패턴을 따라가면 된다.

다음 글에서는 이 구조에 Slack 알림과 자동 머지 조건을 붙여 완전 자율 배포 파이프라인을 만드는 방법을 다룰 예정이다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: AI 인사이트
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독