Claude 코드 리뷰 액션

빠른 시작 (Quick Start)

1. 워크플로우 추가 — .github/workflows/claude-review.yml 파일을 생성합니다:

name: Claude Code Review
on:
  pull_request:
...

2. API 키 추가 — 레포지토리 Settings > Secrets > Actions로 이동하여 ANTHROPIC_API_KEY를 추가합니다 (여기에서 받기)

3. Claude GitHub App 설치 — Claude Code에서 /install-github-app을 실행하거나, claude-code-action 설정을 따릅니다.

4. claude-review 레이블 생성 — Issues > Labels > New label로 이동합니다.

5. 테스트하기 — PR(Pull Request)을 열고, claude-review 레이블을 추가한 다음 Actions 탭을 확인하세요.

이것으로 끝입니다. Claude가 몇 분 안에 리뷰를 게시할 것입니다.

개선하기 (Make It Better)

이 액션은 기본적으로 작동하지만, 프로젝트에 대한 정보를 Claude에게 알려주면 리뷰의 질이 극적으로 향상됩니다. 다음 세 가지 레벨 중 적절한 것을 사용하세요:

레벨 1: Claude에게 검토할 내용을 알려주기

- uses: toriihq/claude-review-action@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
...

프로젝트, 기술 스택, 도메인에 대한 한 문장을 추가합니다. 기본값은 `

좋은 리뷰 가이드는 보안 체크리스트, 테스트 기대 사항, 코드 스타일, 아키텍처 규칙, 그리고 도메인별 패턴을 다룹니다. 예시 템플릿를 참고하세요.

보너스: CLAUDE.md — 저장소에 내장된 지식

저장소(repo)의 루트 디렉터리에 CLAUDE.md 파일이 있다면, Claude는 모든 리뷰 과정에서 이 파일을 자동으로 읽습니다. 이는 별도의 설정이 필요 없는, Claude Code의 기본 기능입니다.

이는 이미 Claude Code를 위해 문서화한 컨벤션(아키텍처 결정 사항, 명명 패턴, 데이터베이스 컨벤션, 흔히 발생하는 문제점 등) 또한 코드 리뷰에 반영된다는 의미입니다. CLAUDE.md가 잘 관리되는 팀은 Claude가 단순히 diff 내용 이상의 프로젝트 맥락을 이해하기 때문에 눈에 띄게 더 나은 리뷰를 받습니다.

이 기능을 사용하기 위해 CLAUDE.md가 필요하지는 않습니다. 파일 없이도 아주 잘 작동합니다. 하지만 이미 파일이 있다면, 리뷰 품질이 자동으로 향상됩니다.

CLAUDE.md와 리뷰 가이드의 차이점 — 무엇을 어디에 넣어야 할까?

• CLAUDE.md = 도메인 지식 (프로젝트 구조, 명명 컨벤션, 데이터베이스 패턴, 기술 스택). Claude에게 코드베이스가 어떤 모습인지 알려줍니다.
• 리뷰 가이드 = 리뷰 행동 양식 (심각도 형식, 보안 체크리스트, 테스트 기대 사항, 범위 검증). Claude에게 코드를 어떻게 판단해야 하는지 알려줍니다.

두 가지는 상호 보완적이므로 내용이 중복되지 않도록 주의하세요. 만약 CLAUDE.md에 이미 모든 DB 쿼리가 org_id로 필터링된다고 문서화되어 있다면, 리뷰 가이드에서는

제한 사항 (Limits)

파일 대신 라인 수로 제한하려면, max-files를 늘리고 max-changed-lines를 설정하세요. GitHub는 제외 파일을 포함하여 300개 이상의 파일을 가진 PR에 대한 diff를 반환할 수 없습니다. exclude-paths는 bash 패턴을 사용하며 여기서 *도 /와 일치합니다. 제외된 파일은 diff에서 제거되며 어떤 제한으로도 계산되지 않습니다.

exclude-paths: |
  *package-lock.json
  *.gen.ts
...

모델 및 도구 (Model & Tools)

검토 권한 (Review Authority)

권한 수준:

트리거 (Triggers)

동작 방식 (Behavior)

체크 실행 출력 (Check Run output) (선택 사항)

post-check-run: true를 설정하면 리뷰 판결을 GitHub **체크 실행(Check Run)**으로 게시합니다 (일반 PR 검토 외에). 이 체크는 PR의

필수 권한: 소비자 워크플로우는 checks: write를 부여해야 합니다:

permissions:
  checks: write   # post-check-run: true일 때 필요

범위(scope)가 누락되면 403 오류가 발생하지만, 이는 경고로 기록될 뿐입니다 (작업이 실패하지는 않습니다).

체크를 필수화하기 — 먼저 읽어보세요. 이 체크를 브랜치 보호에서 필수 항목으로 표시하면, 결코 해결되지 않는 pending 상태의 체크에 대해서도 대비해야 합니다. 즉, 액션의 작업은 유한한 시간 제한(timeout)을 가지며, 시간 초과되거나 취소된 작업은 최종 결론(terminal conclusion)을 게시하지 않아 병합 상자를 막아버릴 수 있습니다. 따라서 시작 시점에 in_progress 상태를 추가하고 항상 최종 결론을 게시하는 기능을 먼저 구현하지 않은 상태에서 이 체크를 필수 항목으로 지정하지 마십시오 (기본적으로 구현되어 있지 않으며, 선택적 자문 모드(opt-in advisory mode)가 지원되는 경로입니다).

기능

• 세 가지 트리거 유형(3 trigger types) — 라벨, PR 댓글 내 @claude, 인라인 리뷰 댓글 내 @claude
• 재검토 조정(Re-review reconciliation) — 이전 발견 사항, 작성자 응답, 새 커밋을 추적합니다. HIGH/BLOCKER 등급은 FIXED, ACCEPTED, 또는 STILL OPEN으로 표시됩니다.
• 관련 커밋 필터링(Relevant commit filtering) — 기본 버전 대비 실제 변경 사항에 기여하는 커밋만 플래그를 지정합니다.
• 절단 인식(Truncation awareness) — diff가 제한을 초과할 경우, 누락된 파일 각각의 diff를 저장하여 Claude가 읽도록 하고, Claude의 실행 로그에서 실제로 어떤 파일을 읽었는지 확인한 후 이를 리뷰에 작성합니다. 모든 내용을 읽지 않고 승인하는 첫 번째 리뷰는 그 승인이 철회됩니다.
• PR 크기 가드(PR size guard) — 설정 가능한 파일 또는 라인 제한을 초과하는 PR은 검토를 건너뜁니다.
• 비용 추적(Cost tracking) — 비용, 턴 수, 모델 정보를 리뷰 본문에 추가합니다.
• 리뷰 해제(Review dismissal) — 새로운 리뷰를 게시하기 전에 이전 Claude 리뷰를 해제합니다.
• 유형별 실패 메시지(Typed failure messages) — 최대 턴 제한 초과, API 오류, 누락된 출력 등을 구분합니다.
• 순수 bash(Pure bash) — TypeScript나 node_modules, 빌드 단계가 없습니다.

작동 방식 (How It Works)

resolve-pr.sh        → 트리거 유형 전반에 걸쳐 PR 번호 + SHA 정규화
  ↓
actions/checkout@v4  → PR 브랜치 체크아웃
...

필수 권한 (Required Permissions)

워크플로우 작업은 다음 권한을 반드시 포함해야 합니다:

permissions:
  contents: write        # PR 브랜치 체크아웃, 파일 읽기
  pull-requests: write   # 리뷰 게시, 리뷰 해제, PR 데이터 읽기
...

알려진 제한 사항 (Known Limitations)

1. 사용자 정의 트리거 구문은 👀 반응을 받지 못함 — Claude GitHub App은 @claude 언급에 대해 👀로 반응합니다. 사용자 정의 트리거 구문도 작동하지만 이 시각적 반응을 받지는 못합니다.

2. 리뷰 해제는 최선 노력(best-effort)입니다 — 해제 명령어는 별도의 단계가 아니라 Claude의 프롬프트 안에 있습니다. 만약 Claude가 검토 도중 실패하면 이전 리뷰가 남아 있을 수 있습니다.

3. 실패 유형 감지 — max_turns 실패는 안정적으로 감지합니다. API 오류 하위 유형(401 대 429)은 일반 메시지로 대체됩니다.

라이선스 (License)

MIT