풀 리퀘스트에서 리뷰 읽기 및 요청하기

GitHub 풀 리퀘스트에서 Code Review 결과를 읽고, 응답하거나 해제하며, @claude review로 리뷰를 요청합니다.

Code Review는 Claude 조직의 Owner가 일련의 GitHub 저장소에 대해 켜는 관리형 서비스입니다. 켜지면 Claude가 해당 저장소의 풀 리퀘스트를 리뷰하고, 발견 사항을 인라인 댓글, 리뷰 본문의 요약, 그리고 Claude Code Review라는 이름의 체크 실행으로 게시합니다. 리뷰는 풀 리퀘스트를 승인하거나 차단하지 않으며, 체크 실행은 절대 실패로 종료되지 않습니다.

Owner는 각 저장소에 대해 리뷰가 실행되는 시점과 리뷰의 철저한 정도를 제어합니다.

[!NOTE]

플랜에 Code Review가 포함되어 있지 않더라도 Claude Code 세션에서 Claude가 브랜치를 리뷰하도록 할 수 있습니다. /code-review로 로컬에서 리뷰하기를 참조하세요.

심각도 수준

Claude는 각 발견 사항을 해당 줄에 인라인 댓글로 게시하고 세 가지 심각도 수준 중 하나로 표시합니다.

리뷰가 추론 과정을 기록한 경우, 발견 사항에는 접힌 Why this was flagged 섹션이 있습니다. 이를 펼치면 Claude가 해당 문제를 지적한 이유와 문제를 검증한 방법을 읽을 수 있습니다.

Claude가 저장소에서 지적하는 항목이나 심각도 순위를 매기는 방식을 변경하려면 Code Review 사용자 지정을 참조하세요.

발견 사항에 응답하기

저장소 자체 규칙에서 요구하지 않는 한, 발견 사항에 응답하지 않고도 병합할 수 있습니다. 브랜치 보호가 대화 해결을 요구하는 경우, 병합하기 전에 각 발견 사항의 스레드를 해결해야 합니다.

발견 사항을 정리하려면 해당 스레드를 해결하거나 수정 사항을 푸시합니다.

• 코드 변경 없이 해제하기: GitHub에서 스레드를 직접 해결합니다. 답글만으로는 발견 사항이 해제되지 않습니다.
• 문제 수정하기: 코드를 변경하고 푸시합니다. 풀 리퀘스트의 다음 리뷰가 문제가 수정되었다고 판단하면 이전 스레드를 해결합니다. 해당 리뷰가 푸시 시 자동으로 실행되든 직접 요청하든 마찬가지입니다.
• 설명하거나 이의 제기하기: 댓글에 답글을 답니다. Claude는 즉시 응답하지 않으며, 답글로 리뷰가 시작되지도 않습니다. 풀 리퀘스트의 다음 리뷰가 이전 발견 사항에 달린 답글을 읽고, 스레드를 해결하거나 후속 답글 하나를 게시할 수 있습니다. 같은 종류의 발견 사항이 계속 반복된다면 관리자(maintainer)에게 REVIEW.md에 규칙을 추가해 달라고 요청하세요.

푸시하지 않고 다음 리뷰를 받으려면 @claude review를 최상위 풀 리퀘스트 댓글로 작성합니다.

체크 실행 출력

Claude Code Review 체크 실행의 Details 링크를 열면 발견 사항이 심각도순으로 정렬된 하나의 표로 표시되며, GitHub가 인라인 댓글을 받아들이지 않은 발견 사항도 포함됩니다.

줄 정보가 있지만 인라인 댓글로 게시되지 않은 발견 사항은 Files changed 탭의 해당 줄에 주석(annotation)으로 표시됩니다. Important 발견 사항은 빨간색, Nit은 노란색, 기존 버그는 회색으로 표시됩니다.

체크 실행은 neutral로 종료되거나, 변경된 파일이 없고 이전 결과를 유지하는 일부 푸시 후에는 skipped로 종료됩니다. 절대 실패로 종료되지 않으므로 완료된 리뷰로 인해 필수 체크가 실패하지 않습니다. 발견 사항이 보이지 않거나 리뷰가 실행되지 않았다면 Code Review 문제 해결을 참조하세요.

푸시 후 이전 결과가 유지되는 경우

푸시 후 체크 실행의 제목이 다음 중 하나라면, Code Review가 새 리뷰를 시작하는 대신 이전 리뷰의 결과를 유지한 것입니다.

• Code review skipped — no new changes: 이전 리뷰의 Important 발견 사항 중 아직 열려 있는 것이 없으므로 새 리뷰가 필요하지 않습니다
• Code review not repeated — earlier findings still open: 새 리뷰를 시작하려면 열려 있는 Important 발견 사항에 대한 수정을 푸시하거나, 해당 스레드를 해결한 후 다시 푸시합니다

github.com에서는 다음 두 조건이 모두 충족될 때 Code Review가 결과를 유지할 수 있습니다.

• 빈 커밋, 베이스 브랜치의 깔끔한 병합, 깔끔한 리베이스 이후처럼 풀 리퀘스트가 여전히 동일한 줄을 추가하고 제거하는 경우
• 해당 리뷰 이후 아무도 Important 발견 사항의 스레드를 해결하지 않은 경우

코드 변경 없이 리뷰를 받으려면 @claude review 댓글을 남기거나 체크 실행에서 Re-run을 클릭합니다.

스크립트에서 결과 읽기

자체 CI에서 병합을 제어하거나 요약을 게시하려면 gh와 jq로 Details 텍스트의 마지막 줄을 파싱합니다. 해당 줄은 심각도별 개수를 JSON으로 담고 있는 HTML 주석입니다.

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

그 위의 줄에는 풀 리퀘스트의 파일 이름이 포함될 수 있습니다. 텍스트를 자체 방식으로 파싱하는 경우, 아래 단계의 명령처럼 마지막 줄에서만 개수를 가져옵니다.

1. 체크 실행 ID 찾기

셸에서 커밋의 체크 실행 목록을 조회하고 Claude Code Review 실행의 id를 가져옵니다. OWNER와 REPO를 저장소 소유자와 이름으로, <commit-sha>를 풀 리퀘스트의 head 커밋으로 바꿉니다.

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

Re-run 이후처럼 커밋에 Claude Code Review 실행이 두 번 이상 있었다면 GitHub는 가장 최근 실행만 나열합니다.

2. 심각도별 개수 읽기

Details 텍스트를 담고 있는 체크 실행의 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}입니다. 이전 결과를 유지한 체크 실행을 제외하면, 이 개수에는 스레드가 아직 열려 있는, 풀 리퀘스트의 이전 리뷰에서 나온 발견 사항도 포함됩니다.

제목이 Code review skipped — no new changes인 경우, 개수에는 아직 열려 있는 이전 리뷰의 Nit 및 기존 발견 사항이 포함되지 않습니다. 이때는 이전 리뷰의 Important 발견 사항 중 아직 열려 있는 것이 없습니다.

3. 결과에 따라 조치하기

스크립트가 다음 경우를 순서대로 처리하도록 합니다.

• 제목이 Code review not repeated로 시작하는 경우: Code Review가 Important 발견 사항이 아직 열려 있는 이전 결과를 유지했으며, 체크 실행에 심각도 줄이 없습니다. 개수보다 먼저 gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID --jq .output.title로 제목을 읽습니다. 병합을 제어하려면 작업을 실패시킵니다.
• 제목이 no new changes로 끝나는 경우: 개수를 읽지 않고 작업을 통과시킵니다
• normal이 0보다 큰 경우: 병합을 제어하려면 작업을 실패시킵니다. normal 키는 Important 발견 사항의 개수를 담고 있으므로, Claude가 병합 전에 수정할 가치가 있는 버그를 하나 이상 발견했다는 의미입니다. 이 개수만 출력하려면 닫는 작은따옴표 앞에 | .normal을 추가합니다.
• 해당 줄이 없는 경우: 명령은 개수 대신 no severity line이 포함된 오류를 출력하고 0이 아닌 상태로 종료됩니다. 이를 발견 사항이 0개인 것이 아니라 판정이 없는 것으로 처리합니다. 실패했거나, 시간 초과되었거나, 취소되었거나, 더 새로운 리뷰로 대체된 리뷰의 체크 실행에는 이 줄이 없으며, 일부 완료된 리뷰에도 없습니다.

리뷰 요청하기

풀 리퀘스트가 초안이거나 포크에서 온 경우 자동 리뷰가 건너뛰므로 댓글 명령으로 리뷰를 요청합니다. 풀 리퀘스트에 리뷰를 받으려면 다음 중 하나를 수행합니다.

• 열거나 준비 완료로 표시하기: Once after PR creation 또는 After every push로 설정된 저장소에서는 풀 리퀘스트를 열거나 다시 열거나, 초안을 리뷰 준비 완료로 표시하면 리뷰가 시작됩니다.
• 명령을 댓글로 작성하기: 풀 리퀘스트에 @claude review를 게시합니다.
• 커밋 푸시하기: After every push로 설정된 저장소나 @claude review always로 구독한 풀 리퀘스트에서는 푸시하면 리뷰가 시작됩니다. 푸시 후에도 풀 리퀘스트가 여전히 동일한 줄을 추가하고 제거하는 경우, Code Review는 대신 이전 결과를 유지할 수 있습니다.
• Re-run 클릭하기: 포크에서 오지 않은 풀 리퀘스트에서 리뷰가 실패하거나 시간 초과된 후, 체크 실행에서 다시 실행합니다. 포크에서 오지 않은 풀 리퀘스트에서는 이전 결과를 유지한 푸시 후에도 Re-run을 클릭할 수 있습니다.
• 자동 재시도 기다리기: 세션이 중단된 리뷰는 자동으로 한 번 재시도됩니다. 재시도가 진행 중일 때는 체크 실행의 요약에 표시됩니다.

댓글 명령

다음 명령 중 하나를 풀 리퀘스트의 댓글로 게시합니다.

After every push로 설정된 저장소에서는 구독 여부와 관계없이 푸시하면 리뷰가 시작되므로 댓글로 리뷰를 중지할 수 없습니다. 해당 저장소에서 하나의 풀 리퀘스트에 대해 푸시로 리뷰가 시작되지 않도록 하려면 풀 리퀘스트를 초안으로 전환합니다. 다시 리뷰 준비 완료로 표시하면 리뷰가 시작됩니다.

댓글 명령이 적용되려면 다음 조건을 모두 충족해야 합니다.

• diff 줄의 인라인 댓글이나 리뷰 본문이 아닌, 새로운 최상위 풀 리퀘스트 댓글로 게시해야 합니다. 이전 댓글을 편집하는 것은 인정되지 않습니다.
• 전체 명령을 댓글 맨 앞의 한 줄에 작성합니다. 명령 뒤에는 다른 텍스트가 와도 됩니다. always 또는 stop의 철자가 틀렸거나 이후 줄에 있으면 Claude는 댓글을 일반 @claude review로 읽고 단일 리뷰를 시작합니다. 대소문자는 상관없습니다.
• 저장소에 대한 write, maintain 또는 admin 권한이 필요합니다. Claude는 댓글을 작성한 각 사용자에 대해 GitHub에서 이를 확인하며, 봇의 댓글로는 리뷰가 시작되지 않습니다.
• 풀 리퀘스트가 열려 있어야 합니다.

리뷰를 시작하는 명령이 수락되면 풀 리퀘스트에 Code review queued... 제목의 Claude Code Review 체크 실행이 나타납니다. 리뷰가 시작되면 제목이 **Code review in progress...**로 바뀝니다. Claude가 댓글에 👀로 반응할 수도 있지만, 이 반응은 리뷰가 시작되지 않을 때도 나타날 수 있으므로 대신 체크 실행을 확인하세요.

풀 리퀘스트의 최신 커밋에서 이미 리뷰가 실행 중이면 새 요청으로 두 번째 리뷰가 시작되지 않습니다.

[!NOTE]

2026년 7월 업데이트 이전에는 @claude review가 푸시로 트리거되는 리뷰에 PR을 구독했습니다. 해당 동작에 의존했다면 대신 @claude review always를 댓글로 작성하세요.

이후 리뷰가 다루는 범위

푸시 후처럼 자체적으로 시작되는 이후 리뷰는 마지막 리뷰 이후 변경된 내용에 집중하며, Nit과 기존 발견 사항을 더 적게 게시합니다. 그 결과 제외된 발견 사항이 있는지 확인하려면 리뷰 본문에서 해당 개수를 알려 주는 문장을 찾습니다.

• 마지막 리뷰 이후 변경되지 않은 코드에 대한 발견 사항: 문장이 "outside the scope of this re-review and not posted"로 끝납니다
• Nit과 기존 발견 사항: 문장이 "found and not posted"로 끝납니다

이러한 항목을 하나도 제외하지 않는 리뷰를 받으려면 @claude review를 댓글로 작성합니다. 이 리뷰는 풀 리퀘스트 전체를 다시 다룹니다.

초안 및 포크의 풀 리퀘스트 리뷰하기

자동 리뷰는 다음 두 가지를 모두 건너뛰므로 댓글 명령으로 리뷰를 요청합니다.

• 초안 풀 리퀘스트: 댓글 명령은 초안에서도 실행되므로 풀 리퀘스트를 준비 완료로 표시하기 전에 리뷰를 요청할 수 있습니다. @claude review always 이후에도 초안에 대한 푸시로는 리뷰가 시작되지 않습니다. 구독은 풀 리퀘스트를 준비 완료로 표시하면 적용됩니다.
• 포크의 풀 리퀘스트: 저장소의 Review runs 설정과 관계없이 Claude는 포크에서 온 풀 리퀘스트를 자동으로 리뷰하지 않습니다. 리뷰를 시작하려면 풀 리퀘스트에 @claude review를 댓글로 작성합니다. 댓글 명령의 조건은 그대로 적용되며, 필요한 쓰기 권한은 포크가 아닌 기본 저장소에 대한 것입니다.

포크의 풀 리퀘스트에서 @claude review always도 작동하지만, 이후 푸시에 대한 리뷰에 풀 리퀘스트를 구독하지는 않습니다. 이 경우 체크 실행에서 Re-run을 클릭해도 리뷰가 시작되지 않습니다.

Claude Code GitHub Action과 함께 Code Review 사용하기

저장소에서 기본 @claude 트리거 문구를 사용하는 대화형 모드로 Claude Code GitHub Action도 실행 중이라면, @claude review 댓글이 Action도 시작합니다. 두 가지를 분리하려면 Action의 trigger_phrase 입력을 다른 문구로 설정합니다.

관련 리소스

• Code Review 문제 해결: 시작되지 않았거나, 실패했거나, 예산 때문에 건너뛴 리뷰
• Code Review: 서비스 개요 및 리뷰 실행 방식
• Code Review 설정하기: Owner용, Code Review를 켜고 리뷰 실행 시점과 수준 선택
• Code Review 사용자 지정: REVIEW.md와 CLAUDE.md로 Claude가 지적하는 항목 변경
• Code Review 비용 및 사용량: 리뷰 요금 청구 방식과 지출 한도 설정 위치
• /code-review로 로컬에서 리뷰하기: Claude Code 세션에서 브랜치 리뷰 실행