PR에서 Code Review 결과 읽고 리뷰 요청하기 (Read and request reviews on a pull request)

기준일: 2026-10-23
공식 기준: Read and request reviews on a pull request

개요

Code Review는 Claude 조직의 Owner가 GitHub 저장소 묶음에 켜는 관리형 서비스입니다. 켜지면 Claude가 해당 저장소의 PR을 리뷰하고, findings를 inline 코멘트, 리뷰 본문의 요약, Claude Code Review라는 check run으로 게시합니다. 리뷰는 PR을 approve하거나 block하지 않으며, check run이 failure로 끝나는 일도 없습니다.

• 리뷰가 언제 실행되는지와 얼마나 철저한지는 저장소별로 Owner가 정합니다.
• 플랜에 Code Review가 없어도 Claude Code 세션에서 /code-review로 로컬 리뷰를 할 수 있습니다.

핵심 개념

항목	내용
심각도	🔴 Important / 🟡 Nit / 🟣 Pre-existing
finding 지우기	thread를 resolve하거나 수정을 push
check run 결론	neutral 또는 skipped. failure는 없음
결과 재사용	같은 줄만 추가·삭제된 push에서는 이전 결과를 유지할 수 있음
리뷰 요청	@claude review(1회), @claude review always(구독), @claude review stop(구독 해제)
스크립트 판정	Details 텍스트 마지막 줄의 bughunter-severity JSON

상세

심각도 수준

Claude는 각 finding을 해당 줄에 inline 코멘트로 달고 세 가지 심각도 중 하나로 표시합니다.

표시	심각도	의미
🔴	Important	merge 전에 고쳐야 할 버그
🟡	Nit	사소한 문제. 고칠 가치는 있지만 blocking은 아님
🟣	Pre-existing	코드베이스에 이미 있던 버그로, 이 PR이 만든 것이 아님

리뷰가 추론을 기록한 경우 finding에 접힌 Why this was flagged 섹션이 붙습니다. 펼치면 Claude가 왜 이 문제를 지적했고 어떻게 검증했는지 볼 수 있습니다. 무엇을 지적할지, 심각도를 어떻게 매길지 바꾸려면 Customize Code Review를 보세요.

findings에 대응하기

저장소 자체 규칙이 요구하지 않는 한 finding에 대응하지 않고 merge해도 됩니다. branch protection이 conversation resolution을 요구하면 merge 전에 각 finding thread를 resolve해야 합니다.

finding은 thread를 resolve하거나 수정을 push하면 지워집니다.

• 코드 변경 없이 무시: GitHub에서 직접 thread를 resolve합니다. 답글만 달아서는 무시되지 않습니다.
• 문제 수정: 코드를 고쳐 push합니다. 다음 리뷰가 문제가 고쳐졌다고 판단하면 이전 thread를 resolve합니다. push로 자동 실행된 리뷰든 직접 요청한 리뷰든 같습니다.
• 설명·반론: 코멘트에 답글을 답니다. Claude는 바로 답하지 않고, 답글이 리뷰를 시작하지도 않습니다. 다음 리뷰가 이전 findings의 답글을 읽고 thread를 resolve하거나 후속 답글을 하나 남길 수 있습니다. 같은 종류의 finding이 반복되면 maintainer에게 REVIEW.md에 규칙을 추가해 달라고 요청하세요.

push 없이 다음 리뷰를 받으려면 PR의 top-level 코멘트로 @claude review를 남깁니다.

check run 출력

Claude Code Review check run의 Details 링크를 열면 findings가 심각도순 표 하나로 정리되어 있습니다. GitHub가 inline 코멘트를 받아들이지 않은 finding도 포함됩니다.

Severity	File:Line	Issue
🔴 Important	src/auth/session.ts:142	Token refresh races with logout, leaving stale sessions active
🟡 Nit	src/auth/session.ts:88	parseExpiry silently returns 0 on malformed input

줄 정보가 있지만 inline 코멘트로 게시되지 않은 finding은 Files changed 탭의 해당 줄에 annotation으로 표시됩니다. Important는 빨강, nit는 노랑, pre-existing은 회색입니다.

check run은 neutral로 끝나거나, 파일을 바꾸지 않아 이전 결과를 유지한 일부 push 뒤에는 skipped로 끝납니다. failure로 끝나지 않으므로 리뷰가 끝나도 required check가 실패하지 않습니다. findings가 보이지 않거나 리뷰가 실행되지 않았다면 Troubleshoot Code Review를 보세요.

push 후 이전 결과를 유지하는 경우

push 후 check run 제목이 다음 중 하나면 Code Review가 새 리뷰를 시작하지 않고 이전 리뷰 결과를 유지한 것입니다.

• Code review skipped — no new changes: 이전 리뷰의 Important finding 중 열려 있는 것이 없으므로 새 리뷰가 필요 없음
• Code review not repeated — earlier findings still open: 새 리뷰를 시작하려면 열린 Important finding의 수정을 push하거나, 그 thread를 resolve하고 다시 push

github.com에서는 다음 두 조건이 모두 맞을 때 결과를 유지할 수 있습니다.

• PR이 여전히 같은 줄을 추가·삭제함(빈 커밋, base 브랜치의 깨끗한 merge, 깨끗한 rebase 뒤처럼)
• 그 리뷰 이후 아무도 Important finding의 thread를 resolve하지 않음

코드 변경 없이 리뷰를 받으려면 @claude review를 코멘트하거나 check run에서 Re-run을 클릭합니다.

스크립트로 결과 읽기

자체 CI에서 merge를 gate하거나 요약을 게시하려면 gh와 jq로 Details 텍스트의 마지막 줄을 파싱합니다. 이 줄은 심각도별 개수를 JSON으로 담은 HTML 코멘트입니다.

<!-- bughunter-severity: {"nit":1,"normal":2,"pre_existing":0} -->

위쪽 줄에는 PR의 파일 이름이 들어갈 수 있습니다. 직접 파싱하더라도 아래 명령처럼 마지막 줄에서만 개수를 읽으세요.

1. check run ID 찾기

커밋의 check run 목록에서 Claude Code Review 실행의 id를 가져옵니다. OWNER·REPO는 저장소 소유자·이름으로, <commit-sha>는 PR의 head 커밋으로 바꿉니다.

gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs --jq '.check_runs[] | {id, name}'

Re-run 등으로 한 커밋에 Claude Code Review 실행이 여러 번 있었다면 GitHub는 최신 것만 보여 줍니다.

2. 심각도 개수 읽기

Details 텍스트가 담긴 check run의 output.text 필드에서 개수를 읽습니다. CHECK_RUN_ID를 ID로 바꿉니다.

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID --jq '
  (.output.text | split("\n") | last
    | scan("^<!-- bughunter-severity: (.*) -->$")[0] | fromjson)?
  // error("no severity line")'

출력은 심각도별 개수를 키 알파벳순으로 담은 JSON 객체입니다(예: {"nit": 1, "normal": 2, "pre_existing": 0}). 이전 결과를 유지한 check run이 아니라면, 이 개수에는 thread가 아직 열려 있는 이전 리뷰의 findings도 포함됩니다.

제목이 Code review skipped — no new changes일 때는 아직 열려 있는 이전 리뷰의 nit·pre-existing findings가 개수에서 빠집니다. 이때는 열린 Important finding이 없습니다.

3. 결과에 따라 처리

스크립트는 다음 순서로 경우를 처리합니다.

• 제목이 Code review not repeated로 시작: Important findings가 열린 채 이전 결과를 유지한 것이며 severity 줄이 없습니다. 개수보다 먼저 gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID --jq .output.title로 제목을 읽습니다. merge를 gate하려면 job을 실패시킵니다.
• 제목이 no new changes로 끝남: 개수를 읽지 않고 job을 통과시킵니다.
• normal이 0보다 큼: merge를 gate하려면 job을 실패시킵니다. normal 키가 Important findings 개수이므로 merge 전에 고칠 버그가 하나 이상 있다는 뜻입니다. 이 개수만 출력하려면 닫는 작은따옴표 앞에 | .normal을 붙입니다.
• 줄이 없음: 명령이 개수 대신 no severity line이 포함된 에러를 출력하고 0이 아닌 상태로 종료합니다. findings 0개가 아니라 "판정 없음"으로 처리하세요. 실패·타임아웃·취소되었거나 더 새 리뷰로 대체된 리뷰의 check run에는 이 줄이 없고, 완료된 리뷰 중 일부에도 없습니다.

리뷰 요청하기

PR이 draft이거나 fork에서 왔다면 자동 리뷰가 건너뛰므로 코멘트 명령으로 요청합니다. 리뷰를 받는 방법은 다음과 같습니다.

• PR 열기 또는 ready 표시: Once after PR creation 또는 After every push로 설정된 저장소에서는 PR을 열거나 다시 열 때, draft를 ready for review로 바꿀 때 리뷰가 시작됩니다.
• 명령 코멘트: PR에 @claude review를 남깁니다.
• 커밋 push: After every push 저장소이거나 @claude review always로 구독한 PR이면 push가 리뷰를 시작합니다. push 후에도 같은 줄만 추가·삭제한다면 이전 결과를 유지할 수 있습니다.
• Re-run 클릭: fork가 아닌 PR에서 리뷰가 실패하거나 타임아웃되면 check run에서 다시 실행합니다. fork가 아닌 PR에서는 이전 결과를 유지한 push 뒤에도 Re-run을 쓸 수 있습니다.
• 자동 재시도 대기: 세션이 중단된 리뷰는 한 번 자동으로 재시도됩니다. 이때는 check run 요약에 그렇게 표시됩니다.

코멘트 명령

명령	동작	언제 쓰나
@claude review	이후 push 구독 없이 리뷰 1회 시작	Manual 저장소의 PR처럼 지금 한 번 리뷰가 필요할 때, 또는 다른 모드에서 바로 한 번 더 리뷰할 때
@claude review always	리뷰를 시작하고 이후 push마다 리뷰하도록 PR을 구독	Manual 저장소의 우선순위 높은 PR처럼 이후 push마다 리뷰가 필요할 때
@claude review once	@claude review와 같음. 구독 없이 1회	@claude review와 같은 경우
@claude review stop	push 리뷰 구독을 끝냄. 리뷰를 시작하거나 실행 중인 리뷰를 취소하지 않음. check run 대신 코멘트로 답함	Manual 또는 Once after PR creation 저장소에서 @claude review always로 구독했다가 push마다 리뷰가 더는 필요 없을 때
@claude review off 또는 @claude review pause	@claude review stop과 같음	@claude review stop과 같은 경우

After every push 저장소에서는 구독과 관계없이 push가 리뷰를 시작하므로 코멘트로 멈출 수 없습니다. 그곳에서 한 PR의 push 리뷰를 멈추려면 draft로 전환합니다. 다시 ready for review로 바꾸면 리뷰가 시작됩니다.

코멘트 명령이 적용되려면 다음 조건을 모두 만족해야 합니다.

• diff 줄의 inline 코멘트나 리뷰 본문이 아니라 새 top-level PR 코멘트로 게시합니다. 이전 코멘트 수정은 인정되지 않습니다.
• 명령 전체를 코멘트 맨 앞 한 줄에 씁니다. 뒤에 다른 텍스트가 와도 됩니다. always나 stop의 철자가 틀렸거나 다음 줄에 있으면 Claude는 일반 @claude review로 읽고 리뷰 1회를 시작합니다. 대소문자는 상관없습니다.
• 저장소에 write, maintain, admin 권한이 있어야 합니다. Claude가 코멘트한 사람마다 GitHub에 권한을 확인하며, 봇 코멘트는 리뷰를 시작하지 않습니다.
• PR이 열려 있어야 합니다.

리뷰를 시작하는 명령이 받아들여지면 PR에 Code review queued... 제목의 Claude Code Review check run이 나타나고, 리뷰가 시작되면 **Code review in progress...**로 바뀝니다. Claude가 코멘트에 👀 반응을 달 수도 있지만 리뷰가 시작되지 않을 때도 붙을 수 있으니 check run을 기준으로 확인하세요.

PR의 최신 커밋에서 이미 리뷰가 실행 중이면 새 요청이 두 번째 리뷰를 시작하지 않습니다.

2026년 7월 업데이트 전에는 @claude review가 PR을 push 리뷰에 구독시켰습니다. 그 동작에 의존했다면 @claude review always를 쓰세요.

이후 리뷰가 다루는 범위

push 뒤처럼 자동으로 시작된 이후 리뷰는 마지막 리뷰 이후 바뀐 부분에 집중하고 nit·pre-existing findings를 덜 게시합니다. 요약에는 빠뜨린 개수가 "found and not posted" 또는 "outside the scope of this re-review and not posted"로 끝나는 줄로 표시됩니다.

빠지는 것 없이 리뷰를 받으려면 @claude review를 코멘트합니다. PR 전체를 다시 다룹니다.

draft와 fork PR 리뷰

자동 리뷰는 두 경우 모두 건너뛰므로 코멘트 명령으로 요청합니다.

• Draft PR: 코멘트 명령은 draft에서도 실행되므로 ready 표시 전에 리뷰를 받을 수 있습니다. @claude review always 뒤에도 draft에 대한 push는 리뷰를 시작하지 않으며, 구독은 PR을 ready로 바꾸면 적용됩니다.
• fork PR: 저장소의 Review runs 설정과 관계없이 fork PR은 자동 리뷰되지 않습니다. PR에 @claude review를 코멘트해 시작합니다. 코멘트 명령 조건은 그대로 적용되며, 필요한 write 권한은 fork가 아니라 base 저장소 기준입니다.

fork PR에서도 @claude review always는 동작하지만 이후 push 리뷰에 구독되지는 않습니다. check run의 Re-run도 리뷰를 시작하지 않습니다.

Claude Code GitHub Action과 함께 쓰기

저장소가 Claude Code GitHub Action을 기본 @claude trigger phrase로 interactive 모드에서 함께 돌리고 있다면 @claude review 코멘트가 Action도 시작합니다. 둘을 분리하려면 Action의 trigger_phrase 입력을 다른 문구로 설정하세요.

체크리스트

• 🔴 Important findings를 merge 전에 수정하거나, 의도적으로 thread를 resolve했다.
• branch protection이 conversation resolution을 요구하는지 확인했다.
• 반론은 답글로 남기고, 반복되는 finding은 REVIEW.md 규칙 추가를 요청했다.
• CI 스크립트가 Code review not repeated·no new changes 제목과 severity 줄 누락을 별도로 처리한다.
• 코멘트 명령을 새 top-level 코멘트의 첫 줄에, write 이상 권한으로 게시했다.
• draft·fork PR은 @claude review로 직접 요청했다.
• GitHub Action과 함께 쓰면 trigger_phrase를 분리했다.

다음 단계

• Troubleshoot Code Review: 시작되지 않았거나 실패했거나 예산 때문에 건너뛴 리뷰
• Code Review: 서비스 개요와 리뷰 실행 방식
• Set up Code Review: Owner용 활성화, 실행 시점·수준 설정
• Customize Code Review: REVIEW.md·CLAUDE.md로 지적 대상 조정
• Code Review costs and usage: 과금과 spend limit
• Review locally with /code-review: Claude Code 세션에서 브랜치 리뷰

기준일

이 문서는 2026-10-23 기준 공식 문서 Read and request reviews on a pull request를 바탕으로 작성했습니다.