Skip to main content
Code Review는 Claude 조직의 Owner가 일련의 GitHub 저장소에 대해 켜는 관리형 서비스입니다. 켜지면 Claude가 해당 저장소의 풀 리퀘스트를 리뷰하고, 발견 사항을 인라인 댓글, 리뷰 본문의 요약, 그리고 Claude Code Review라는 이름의 체크 실행으로 게시합니다. 리뷰는 풀 리퀘스트를 승인하거나 차단하지 않으며, 체크 실행은 절대 실패로 종료되지 않습니다. Owner는 각 저장소에 대해 리뷰가 실행되는 시점과 리뷰의 철저한 정도를 제어합니다.
플랜에 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 문제 해결을 참조하세요.

​
스크립트에서 결과 읽기

자체 CI에서 병합을 제어하거나 요약을 게시하려면 gh와 jq로 Details 텍스트의 마지막 줄을 파싱합니다. 해당 줄은 기계가 읽을 수 있는 주석입니다.
1

체크 실행 ID 찾기

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

심각도별 개수 읽기

CHECK_RUN_ID를 해당 ID로 바꿔 체크 실행에서 개수를 읽습니다.
이 명령은 심각도별 개수를 담은 JSON 객체를 키의 알파벳순으로 출력합니다. 예를 들면 {"nit": 1, "normal": 2, "pre_existing": 0}입니다. 이 개수에는 스레드가 아직 열려 있는, 풀 리퀘스트의 이전 리뷰에서 나온 발견 사항도 포함됩니다.
3

결과에 따라 조치하기

스크립트가 다음 경우를 처리하도록 합니다.
  • normal이 0보다 큰 경우: 병합을 제어하려면 작업을 실패시킵니다. normal 키는 Important 발견 사항의 개수를 담고 있으므로, Claude가 병합 전에 수정할 가치가 있는 버그를 하나 이상 발견했다는 의미입니다.
  • 해당 줄이 없는 경우: 발견 사항이 0개인 것이 아니라 판정이 없는 것으로 처리합니다. 실패했거나, 시간 초과되었거나, 취소되었거나, 더 새로운 리뷰로 대체된 리뷰의 체크 실행에는 이 줄이 없으며, 일부 완료된 리뷰에도 없습니다.

​
리뷰 요청하기

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

​
댓글 명령

다음 명령 중 하나를 풀 리퀘스트의 댓글로 게시합니다. 이러한 명령으로 리뷰를 시작하려면 다음 조건을 모두 충족해야 합니다.
  • diff 줄의 인라인 댓글이나 리뷰 본문이 아닌, 새로운 최상위 풀 리퀘스트 댓글로 게시해야 합니다. 이전 댓글을 편집하는 것은 인정되지 않습니다.
  • 명령을 댓글의 맨 앞에 두고, always는 명령의 나머지 부분과 같은 줄에 있어야 합니다. 대소문자는 상관없습니다.
  • 저장소에 대한 write, maintain 또는 admin 권한이 필요합니다. Claude는 댓글을 작성한 각 사용자에 대해 GitHub에서 이를 확인하며, 봇의 댓글로는 리뷰가 시작되지 않습니다.
  • 풀 리퀘스트가 열려 있어야 합니다.
명령이 수락되면 풀 리퀘스트에 Code review queued… 제목의 Claude Code Review 체크 실행이 나타납니다. 리뷰가 시작되면 제목이 **Code review in progress…**로 바뀝니다. Claude가 댓글에 👀로 반응할 수도 있지만, 이 반응은 리뷰가 시작되지 않을 때도 나타날 수 있으므로 대신 체크 실행을 확인하세요. 풀 리퀘스트의 최신 커밋에서 이미 리뷰가 실행 중이면 새 요청으로 두 번째 리뷰가 시작되지 않습니다.
2026년 7월 업데이트 이전에는 @claude review가 푸시로 트리거되는 리뷰에 PR을 구독했습니다. 해당 동작에 의존했다면 대신 @claude review always를 댓글로 작성하세요.

​
이후 리뷰가 다루는 범위

푸시 후처럼 자체적으로 시작되는 이후 리뷰는 마지막 리뷰 이후 변경된 내용에 집중하며, Nit과 기존 발견 사항을 더 적게 게시합니다. 요약에는 제외한 항목의 개수가 “found and not posted” 또는 “outside the scope of this re-review 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 입력을 다른 문구로 설정합니다.