Code Review 문제 해결

시작되지 않았거나, 실패했거나, 예산 때문에 건너뛴 Code Review를 해결하고, 누락된 발견 사항을 찾고, 설정 및 REVIEW.md 문제를 해결합니다.

Code Review가 풀 리퀘스트에서 예상대로 동작하지 않으면 먼저 Claude Code Review 체크 실행을 확인합니다. 체크 실행의 제목을 보면 리뷰가 어디까지 진행되었는지 알 수 있습니다.

리뷰 진행 상황 확인하기

풀 리퀘스트에서 Claude Code Review 체크 실행을 찾은 다음, 그 제목을 아래의 일반적인 제목과 비교합니다.

리뷰가 시작되지 않는 경우

Claude Code Review 체크 실행이 나타나지 않거나, Claude가 리뷰를 건너뛰었다는 댓글을 게시한 경우 다음 사례를 확인합니다.

댓글 명령으로 리뷰가 시작되지 않는 경우

@claude review라고 댓글을 작성한 후, 풀 리퀘스트에서 Code review queued... 또는 **Code review in progress...**라는 제목의 Claude Code Review 체크 실행이 있는지 확인합니다. 댓글에 👀 반응이 달렸다고 해서 리뷰가 진행된다는 의미는 아닙니다. 체크 실행이 나타나지 않으면 다음 각 원인을 확인합니다.

• 이 저장소에 Code Review가 켜져 있지 않음: Claude가 명령에 대한 응답으로 댓글이나 체크 실행을 게시하지 않습니다. Owner에게 저장소 추가를 요청합니다.
• 댓글이 조건을 충족하지 않음: 새 최상위 댓글이 아니라 인라인 댓글이나 리뷰 본문이었거나, 명령이 댓글의 시작 부분에 있지 않았습니다. 새 댓글을 게시하지 않고 이전 댓글을 편집한 경우도 인정되지 않으며, 풀 리퀘스트가 열려 있어야 합니다. 댓글 명령의 조건을 확인하고 이를 충족하는 새 댓글을 게시합니다.
• 쓰기 권한이 없음: 저장소에 대한 write, maintain 또는 admin 권한이 필요하며, 포크에서 생성된 풀 리퀘스트의 경우 기본 저장소에 대한 권한이 기준이 됩니다. 본인이 작성한 풀 리퀘스트가 아니면 Claude가 팁으로 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답장할 수 있습니다. 쓰기 권한이 있는 사람에게 대신 댓글을 작성해 달라고 요청합니다.
• 예산 소진: Claude가 "⚠️ Code review skipped"로 시작하는 댓글을 게시합니다. 리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우를 참조하세요.

리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우

조직의 예산으로 리뷰 비용을 감당할 수 없으면 Code Review는 리뷰를 건너뛰고, Claude가 풀 리퀘스트에 "⚠️ Code review skipped"로 시작하는 댓글을 게시합니다. 이 중 일부 경우에는 Code review declined라는 제목의 체크 실행도 함께 나타납니다.

이 댓글에는 관리자가 예산을 복원할 수 있는 claude.ai/admin-settings/usage 링크가 포함되어 있습니다. 댓글의 문구를 보면 어떤 한도에 도달했는지 알 수 있습니다.

• "has reached its monthly code review spending cap": Code Review의 월간 지출 한도에 도달했습니다. 리뷰는 다음 청구 기간이 시작될 때 재개됩니다. 더 일찍 리뷰를 받으려면 관리자에게 한도를 높여 달라고 요청합니다.
• "has no extra usage available to pay for this review": 조직의 사용량 크레딧 잔액이 비어 있거나, 전체 월간 지출 한도에 도달했습니다. 관리자에게 사용량 크레딧을 추가하거나 해당 한도를 높여 달라고 요청합니다.
• "is too low to start another review": 남은 예산이나 잔액이 리뷰 1회의 예상 비용보다 적습니다. 관리자에게 한도를 높이거나 사용량 크레딧을 추가해 달라고 요청합니다.

예산이 복원된 후 풀 리퀘스트에 @claude review라고 댓글을 작성하면 건너뛴 리뷰를 받을 수 있습니다. 댓글 명령의 조건이 적용되므로 댓글 작성자에게 쓰기 권한이 있어야 합니다.

실패하거나 시간 초과된 리뷰 다시 트리거하기

체크 실행의 요약에 "The review session was interrupted before it could finish. A new review of this commit has been queued automatically."라고 표시되어 있다면 별도로 조치할 필요가 없습니다. 해당 리뷰는 자동으로 한 번 재시도됩니다.

그 외에 체크 실행의 제목이 Code review failed 또는 Code review timed out인 경우, 댓글이나 재실행으로 리뷰를 다시 실행합니다.

• @claude review 댓글 작성: 풀 리퀘스트에 최상위 댓글로 게시합니다. 이렇게 하면 풀 리퀘스트를 이후 푸시에 구독시키지 않고 새 리뷰를 시작합니다.
• Re-run 클릭: 풀 리퀘스트가 포크에서 생성된 것이 아니라면, GitHub의 Checks 탭에서 Claude Code Review 체크의 Re-run을 클릭합니다. 재실행은 풀 리퀘스트의 현재 헤드 커밋을 대상으로 하며, 이 방법 역시 풀 리퀘스트를 구독시키지 않습니다.

인라인 댓글로 표시되지 않는 문제 찾기

체크 실행 제목에는 문제가 발견되었다고 나와 있지만 diff에 인라인 리뷰 댓글이 보이지 않는 경우, 발견 사항이 표시되는 다음의 다른 위치를 확인합니다.

• 체크 실행 Details: Checks 탭에서 Claude Code Review 체크 옆의 Details를 클릭합니다. 심각도 표에는 인라인 댓글의 게시 여부와 관계없이 발견 사항이 파일, 줄, 요약과 함께 나열됩니다.
• Files changed 주석: PR의 Files changed 탭을 엽니다. 줄 정보가 있지만 인라인 댓글로 게시되지 않은 발견 사항은 해당 줄에 주석으로 표시됩니다.
• 리뷰 본문: 인라인 위치가 없거나 현재 diff 범위를 벗어나는 발견 사항은 리뷰 본문의 Additional findings 제목 아래에 표시됩니다.

체크 실행에 REVIEW.md가 언급되는 경우

다음은 체크 실행에 표시될 수 있는 REVIEW.md 관련 메시지 중 세 가지입니다.

• "This review applied the repository's review instructions (REVIEW.md) from its default branch, which is not protected against direct pushes.": 리뷰가 루트 파일만 읽었습니다. 브랜치를 보호하면 무엇이 달라지는지는 REVIEW.md를 읽는 브랜치를 참조하세요.
• "were not applied to this review: branch protection could not be confirmed": 리뷰가 REVIEW.md를 전혀 읽지 않았습니다.
• "they link to a file this pull request modifies, or carry more links than the review checks": 리뷰가 루트 REVIEW.md 또는 메시지에 표시된 개수만큼의 하위 디렉터리 REVIEW.md 파일을 건너뛰었습니다. 건너뛴 파일에서 각 원인을 확인하세요. 루트 REVIEW.md의 경우 포함된 파일도 확인하세요.
  • 링크가 너무 많은 경우: Markdown 링크가 64개를 초과합니다. 링크를 64개 이하로 줄이세요.
  • 리뷰가 파싱할 수 없는 링크가 있는 경우: 형식이 잘못된 Markdown 링크가 있습니다. 해당 링크를 수정하거나 제거하세요.
  • 변경된 파일에 대한 링크가 있는 경우: 이 풀 리퀘스트가 변경하는 파일이나 폴더에 링크되어 있으며, 리뷰가 해당 링크가 있는 줄만 제외할 수 없었습니다. 규칙을 REVIEW.md 자체에 직접 작성하세요.

설정 문제

다음 사례는 Owner가 Code Review를 설정하는 과정에서 발생합니다.

Add a repository에 저장소가 나열되지 않는 경우

대화 상자는 긴 목록을 전부 불러오지 않으므로 먼저 이름으로 저장소를 검색합니다. 대화 상자에는 Claude GitHub App이 접근할 수 있는 저장소만 나열됩니다. Install GitHub App을 클릭하고 앱에 해당 저장소에 대한 접근 권한을 부여합니다. 나열된 저장소가 없으면 Install GitHub App은 대화 상자의 버튼으로 표시됩니다. 그렇지 않으면 대화 상자의 GitHub 조직 필터 메뉴 하단에 있습니다.

테스트 풀 리퀘스트에 체크 실행이 나타나지 않는 경우

Allow code review가 켜져 있는지, Code review 섹션의 Repositories 아래에 저장소가 나열되어 있는지, Claude GitHub App이 해당 저장소에 접근할 수 있는지 확인합니다. 자동 리뷰는 초안 풀 리퀘스트를 건너뛰며, **Manual (@claude review)**로 설정된 저장소는 첫 번째 리뷰를 시작하려면 @claude review 댓글이 필요합니다.

관련 리소스

• 풀 리퀘스트에서 리뷰 읽기 및 요청하기: 발견 사항과 체크 실행의 의미, 그리고 댓글 명령
• Code Review 설정하기: Owner를 위한 Code Review 켜기 및 저장소 관리
• Code Review 비용 및 사용량: 예산 메시지의 원인이 되는 지출 한도
• Code Review 사용자 지정하기: 리뷰가 읽는 REVIEW.md의 사본