Claude Code의 /review와 claude-code-action으로 PR 리뷰를 자동화한 경험

혼자 프로젝트를 운영하면서 가장 아쉬웠던 건 코드 리뷰가 없다는 점이었습니다. 팀에서 일할 때는 동료가 "이 부분은 N+1 나올 수 있어요"라고 한마디 던져주면 끝나던 일이, 혼자서는 배포 직후에야 발견되곤 했습니다.

처음에는 Claude API를 직접 호출해서 리뷰 파이프라인을 만들어볼까 생각했습니다. 그런데 조사해보니 Anthropic이 이미 공식 도구를 제공하고 있었습니다. Claude Code CLI의 /review 명령과 GitHub Actions용 claude-code-action이었습니다. 직접 만드는 것보다 공식 도구를 써보기로 했습니다.

Claude Code /review — 로컬에서 바로 리뷰받기

Claude Code CLI에서 /review를 실행하면 현재 브랜치의 변경 사항을 분석해서 코드 리뷰를 해줍니다.

# 터미널에 리뷰 결과만 출력
/review
 
# PR에 인라인 코멘트를 직접 남기기
/review --comment
 
# 특정 PR 번호 지정
/review --comment 42

핵심은 --comment 플래그입니다. 이걸 붙이면 gh CLI를 통해 PR의 해당 코드 라인에 직접 인라인 코멘트를 달아줍니다. 하나의 거대한 코멘트가 아니라, 문제가 있는 줄마다 개별적으로 붙습니다.

그리고 /review는 Claude Pro/Max 구독 범위 내에서 동작하기 때문에 별도 API 비용이 들지 않습니다. 추가 과금 없이 PR 리뷰를 자동화하고 싶다면 이 방식이 가장 현실적입니다.

처음 실행했을 때 놀랐던 건, 단순히 diff만 보는 게 아니라 프로젝트 컨텍스트를 함께 읽는다는 점이었습니다. 변경된 파일이 참조하는 다른 파일도 확인하고, 프로젝트 루트의 CLAUDE.md에 적힌 규칙도 참조해서 리뷰합니다.

실제 리뷰 결과

처음 /review를 돌렸을 때 나온 피드백 중 인상적이었던 것들입니다.

[Warning] src/main/java/com/example/order/OrderService.java:45
@ManyToOne의 기본 fetch 전략이 EAGER입니다.
주문 목록 조회 시 N+1 쿼리가 발생할 수 있습니다.
FetchType.LAZY로 변경하고 필요한 곳에서 fetch join을 사용하는 것을 권장합니다.

이전에 JPA N+1 문제로 고생했던 경험이 있어서 반가웠습니다. 사람이 리뷰해도 놓치기 쉬운 부분인데, 일관되게 잡아주는 게 좋았습니다.

CLAUDE.md가 리뷰 기준이 된다

/review의 진짜 강점은 CLAUDE.md 파일이 곧 리뷰 가이드라인 역할을 한다는 점입니다. 프로젝트 루트에 아래처럼 규칙을 적어두면, Claude Code가 이를 참조해서 리뷰합니다.

## 코드 컨벤션
 
- 예외: RuntimeException 직접 사용 금지, 커스텀 예외 사용
- 응답: 모든 API는 ApiResponse<T>로 래핑
- 트랜잭션: 조회 메서드에 @Transactional(readOnly=true) 필수
- JPA: @ManyToOne은 반드시 FetchType.LAZY 설정
 
## 리뷰 시 주의사항
 
- 단순 네이밍 취향 차이는 지적하지 않기
- 테스트 코드의 가독성 스타일에 대한 코멘트 금지
- import 순서나 빈 줄 같은 포매팅 이슈 무시 (Formatter가 처리함)

이 방식의 장점은 리뷰 기준이 코드와 함께 버전 관리된다는 것입니다. 컨벤션이 바뀌면 CLAUDE.md만 수정하면 되고, 리뷰 기준도 자동으로 따라갑니다. 예외 처리 설계를 리팩터링하면서 컨벤션을 바꿨을 때, CLAUDE.md를 같이 업데이트했더니 다음 PR부터 새 기준으로 리뷰가 달렸습니다.

claude-code-action — GitHub Actions에서 자동 리뷰

로컬에서 /review --comment를 쓰는 건 좋았지만, PR을 올릴 때마다 직접 실행해야 한다는 점이 아쉬웠습니다. "PR을 올리면 자동으로 리뷰가 달리는" 구조를 원했습니다. 이건 Anthropic 공식 GitHub Action인 claude-code-action으로 해결했습니다.

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]
 
jobs:
  review:
    if: |
      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: "claude-sonnet-4-20250514"

설정은 이게 전부입니다. 이 Action은 다음을 자동으로 처리합니다.

1. PR이 열리거나 업데이트되면 변경된 코드를 분석
2. 프로젝트의 CLAUDE.md를 읽어서 컨텍스트 파악
3. 문제가 있는 라인에 인라인 코멘트를 직접 남김
4. PR 코멘트에서 @claude를 멘션하면 추가 질문에도 응답

특히 4번이 유용했습니다. 리뷰 코멘트에 "이 부분 왜 이렇게 하면 안 돼?"라고 @claude를 붙여서 물어보면, 해당 맥락을 이해한 상태에서 답변을 달아줍니다.

Draft PR 필터링

처음에는 Draft PR에도 리뷰가 달려서, 작성 중인 코드에 "이 메서드는 미완성입니다" 같은 코멘트가 붙는 상황이 있었습니다. 조건을 추가해서 해결했습니다.

jobs:
  review:
    if: |
      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude'))

비용 구조 — 무료로 쓸 수 있는 방법

자동 리뷰의 비용 구조는 인증 방식에 따라 달라집니다.

Claude Pro/Max 구독자라면 로컬 /review --comment로 추가 비용 없이 리뷰를 달 수 있습니다. claude-code-action은 API Key를 사용하면 종량제가 적용되지만, Max 구독자는 claude setup-token으로 생성한 OAuth 토큰을 쓰면 구독 범위 내에서 처리됩니다.

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

개인 프로젝트에서 비용이 부담된다면 /review --comment를 습관적으로 실행하는 것만으로도 충분했습니다.

도입 전후 비교

자동 리뷰 파이프라인 도입 전후로 체감되는 차이를 정리하면 이렇습니다.

AI 코딩 도구를 비교하면서 느꼈던 것처럼, 도구의 가치는 단순 기능보다 워크플로우에 자연스럽게 녹아드는지에 달려 있었습니다. claude-code-action은 PR을 올리는 기존 흐름을 전혀 바꾸지 않으면서 리뷰를 추가해주니, 도입 저항이 거의 없었습니다.

운영 팁

몇 주 운영하면서 알게 된 것들을 정리합니다.

CLAUDE.md에 "하지 말 것"이 중요하다

리뷰 품질은 "무엇을 봐라"보다 **"무엇을 보지 마라"**로 더 많이 올라갔습니다. 포매팅, 네이밍 취향, 테스트 스타일 등 노이즈를 명시적으로 제외하니 거짓 양성(False Positive)이 크게 줄었습니다.

paths 필터로 비용 관리

설정 파일이나 문서 변경에는 리뷰가 필요 없습니다. paths 필터로 src/**와 빌드 설정 파일만 대상으로 좁히면 불필요한 API 호출을 줄일 수 있습니다.

완벽한 리뷰어는 아니다

비즈니스 로직의 의도를 이해하는 데는 한계가 있습니다. "이 할인율 계산이 기획 의도와 맞는지"는 여전히 사람이 봐야 합니다. 에이전틱 AI 시대의 변화에서도 느꼈지만, AI 도구는 사람을 대체하는 게 아니라 사람이 놓치기 쉬운 것들을 일관되게 잡아주는 역할에 적합합니다.

마무리

처음에는 "AI가 코드 리뷰를 해봤자 얼마나 도움이 되겠어"라는 반신반의로 시작했습니다. 결론부터 말하면, 사람의 리뷰를 대체하진 못하지만 혼자 개발할 때 최소한의 안전망 역할은 확실히 해줍니다.

가장 인상적이었던 건 설정의 간결함이었습니다. claude-code-action YAML 10줄과 CLAUDE.md 하나로 동작하는 자동 리뷰 파이프라인은, 예전에 무중단 배포를 구축하면서 느꼈던 "자동화는 복잡할수록 유지보수가 힘들다"는 교훈과도 맞닿아 있었습니다.

그리고 CLAUDE.md에 리뷰 기준을 정리하는 과정 자체가 가치가 있었습니다. "좋은 리뷰란 무엇인가"를 글로 명문화하면서, 내가 코드를 볼 때 무의식적으로 적용하던 기준들이 처음으로 문서화됐습니다. AI 리뷰어를 설계하는 일은 결국 내가 생각하는 좋은 코드의 기준을 명문화하는 일이었습니다.

다만 CLAUDE.md만으로는 리뷰의 흐름이나 출력 형식까지 제어하기 어려운 경우도 있었습니다. "보안 취약점은 반드시 Critical로 분류하라", "리뷰 결과를 체크리스트 형태로 정리하라" 같은 세밀한 제어가 필요할 때는 Claude Code의 커스텀 스킬을 직접 만들어서 /review를 대체하는 방법도 있습니다. 이 부분은 다음 글에서 다뤄보겠습니다.