Code Review 문제 해결 (Troubleshoot Code Review)

기준일: 2026-11-03
공식 기준: Troubleshoot Code Review

개요

Code Review가 PR에서 기대대로 동작하지 않으면 Claude Code Review check run부터 확인합니다. check run 제목이 리뷰가 어디까지 진행됐는지 알려 줍니다. 이 페이지는 리뷰가 시작되지 않은 경우, 실패·타임아웃, 예산 부족으로 건너뛴 경우, findings가 안 보이는 경우, REVIEW.md 관련 메시지, Owner의 설정 문제를 다룹니다.

핵심 개념

증상	먼저 볼 곳
check run이 없음	`@claude review` 코멘트 후 check run이 생기는지
"⚠️ Code review skipped" 코멘트	코멘트 문구로 어떤 한도에 걸렸는지
Code review failed / timed out	자동 재시도 여부 → `@claude review` 또는 Re-run
findings가 있다는데 inline 코멘트 없음	check run Details, Files changed annotation, 리뷰 본문
`REVIEW.md` 메시지	기본 브랜치 보호 여부, 링크 수·형식

상세

리뷰 진행 상황 확인

PR의 Claude Code Review check run 제목을 다음 표와 맞춰 봅니다.

check run 제목	의미	할 일
Code review queued... 또는 Code review in progress...	리뷰가 끝나지 않음	제목이 바뀔 때까지 대기
Code review found no issues	리뷰가 끝났고 게시한 findings가 없음	이 PR의 첫 리뷰가 아니라면 리뷰 본문에서 리뷰가 제외한 findings 개수를 확인. 첫 리뷰라면 없음
이슈를 찾았다는 제목	findings와 함께 끝남	diff에 보이지 않으면 아래 "inline 코멘트로 안 보이는 findings 찾기"
Code review skipped — no new changes	최신 push에서 자동 리뷰가 실행되지 않음	그래도 리뷰를 받으려면 `@claude review` 코멘트
Code review not repeated — earlier findings still open	최신 push에서 자동 리뷰가 실행되지 않았고 이전 리뷰의 Important findings가 열려 있음	수정을 push하거나 `@claude review` 코멘트. When a push keeps the earlier result 참고
Code review failed 또는 Code review timed out	리뷰가 끝나지 않음	아래 "실패·타임아웃 리뷰 다시 실행"
Code review declined	리뷰가 실행되지 않음	check run 요약을 읽음. 예산이나 spend limit이 언급되면 아래 "예산 메시지"
check run 없음	리뷰가 시작되지 않음	`@claude review` 코멘트. 그래도 check run이 없으면 아래 "코멘트 명령이 리뷰를 시작하지 않음"

리뷰가 시작되지 않음

Claude Code Review check run이 보이지 않거나 Claude가 리뷰를 건너뛰었다는 코멘트를 남겼을 때 확인합니다.

코멘트 명령이 리뷰를 시작하지 않음

@claude review 코멘트 후 PR에 Code review queued... 또는 Code review in progress... 제목의 check run이 생기는지 봅니다. 코멘트의 👀 반응은 리뷰가 시작된다는 확인이 아닙니다. check run이 없으면 다음 원인을 확인합니다.

저장소에 Code Review가 꺼져 있음: Claude가 코멘트도 check run도 남기지 않습니다. Owner에게 저장소 추가를 요청합니다.
코멘트가 조건을 만족하지 않음: 새 top-level 코멘트가 아니라 inline 코멘트나 리뷰 본문이었거나, 명령이 코멘트 맨 앞에 있지 않았습니다. 이전 코멘트 수정도 인정되지 않고, PR이 열려 있어야 합니다. 코멘트 명령 조건을 보고 새 코멘트를 남깁니다.
write 권한 없음: 저장소에 write, maintain, admin 권한이 필요합니다. fork PR에서는 base 저장소 권한이 기준입니다. 본인 PR이 아니면 Claude가 tip 코멘트로 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답할 수 있습니다. write 권한이 있는 사람에게 대신 코멘트를 요청합니다.
예산 소진: Claude가 "⚠️ Code review skipped"로 시작하는 코멘트를 남깁니다. 아래 예산 메시지 항목을 봅니다.

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

조직 예산으로 리뷰를 감당할 수 없으면 Code Review는 리뷰를 건너뛰고 "⚠️ Code review skipped"로 시작하는 코멘트를 남깁니다. 일부 경우에는 Code review declined check run도 생깁니다.

코멘트에는 admin이 예산을 복구하는 claude.ai/admin-settings/usage 링크가 있고, 문구로 어떤 한도에 걸렸는지 알 수 있습니다.

문구	원인	조치
"has reached its monthly code review spending cap"	Code Review 월간 spend limit 도달	다음 결제 기간 시작 시 재개. 더 빨리 필요하면 admin에게 한도 상향 요청
"has no extra usage available to pay for this review"	조직의 usage credits 잔액이 비었거나 전체 월간 spend limit 도달	admin에게 usage credits 추가 또는 한도 상향 요청
"is too low to start another review"	남은 예산·잔액이 리뷰 1회 예상 비용보다 적음	admin에게 한도 상향 또는 usage credits 추가 요청

예산이 복구되면 PR에 @claude review를 코멘트해 건너뛴 리뷰를 받습니다. 코멘트 명령 조건이 적용되므로 코멘트한 사람에게 write 권한이 있어야 합니다.

실패·타임아웃 리뷰 다시 실행

check run 요약에 "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이면 코멘트나 re-run으로 다시 실행합니다.

@claude review 코멘트: PR의 top-level 코멘트로 남깁니다. 이후 push 구독 없이 새 리뷰를 시작합니다.
Re-run 클릭: PR이 fork에서 온 것이 아니면 GitHub Checks 탭의 Claude Code Review check에서 Re-run을 클릭합니다. PR의 현재 head 커밋을 리뷰하며 역시 구독하지 않습니다.

inline 코멘트로 안 보이는 findings 찾기

check run 제목은 이슈를 찾았다는데 diff에 inline 리뷰 코멘트가 없다면 다음 위치를 봅니다.

check run Details: Checks 탭의 Claude Code Review 옆 Details를 클릭합니다. inline 코멘트가 받아들여졌는지와 관계없이 심각도 표에 파일·줄·요약이 나옵니다.
Files changed annotation: PR의 Files changed 탭을 엽니다. 줄 정보가 있지만 inline 코멘트로 게시되지 않은 finding이 해당 줄에 annotation으로 표시됩니다.
리뷰 본문: inline 위치가 없거나 현재 diff 밖에 있는 findings는 리뷰 본문의 Additional findings 제목 아래에 나옵니다.

check run에 REVIEW.md가 언급될 때

check run이 REVIEW.md에 대해 남길 수 있는 메시지 중 네 가지입니다.

"This review applied the repository's review instructions (REVIEW.md) from its default branch, which is not protected against direct pushes.": 리뷰가 루트 파일만 읽었습니다. 브랜치를 보호하면 무엇이 달라지는지는 Which branch REVIEW.md is read from을 보세요.
"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 링크가 있습니다. 고치거나 지웁니다.
- 변경된 파일로의 링크: 이 PR이 바꾸는 파일·폴더를 링크하고 있고, 리뷰가 그 링크가 있는 줄만 빼낼 수 없었습니다. 규칙을 REVIEW.md 안에 직접 씁니다.
"include line(s) in the root REVIEW.md were skipped on this review": 루트 REVIEW.md는 적용됐지만 그 include 줄이 가리키는 파일은 적용되지 않았습니다. Include other files in REVIEW.md의 목록과, skill이라면 Include a skill file의 목록을 확인하세요.

설정 문제

Owner가 Code Review를 설정하는 중에 겪는 경우입니다.

Add a repository에 저장소가 없음

대화상자는 긴 목록을 모두 불러오지 않으므로 먼저 이름으로 검색합니다. 대화상자에는 Claude GitHub App이 접근할 수 있는 저장소만 나옵니다. Install GitHub App을 클릭해 앱에 저장소 접근 권한을 줍니다. 저장소가 하나도 없을 때 Install GitHub App은 대화상자 안의 버튼이고, 그렇지 않으면 대화상자의 GitHub organization 필터 메뉴 맨 아래에 있습니다.

테스트 PR에 check run이 생기지 않음

Allow code review가 켜져 있는지, Code review 섹션의 Repositories에 저장소가 있는지, Claude GitHub App이 저장소에 접근할 수 있는지 확인합니다. 자동 리뷰는 draft PR을 건너뛰고, **Manual (@claude review)**로 설정된 저장소는 첫 리뷰를 시작하려면 @claude review 코멘트가 필요합니다.

체크리스트

check run 제목으로 리뷰 진행 단계를 먼저 확인했다.
👀 반응이 아니라 Code review queued... check run으로 리뷰 시작을 확인했다.
코멘트 명령이 새 top-level 코멘트 첫 줄이고, 작성자에게 write 이상 권한이 있다(fork면 base 저장소 기준).
예산 메시지 문구로 어떤 한도인지 구분하고 admin에게 알렸다.
inline 코멘트가 없으면 Details, Files changed, Additional findings를 확인했다.
REVIEW.md의 Markdown 링크가 64개 이하이고 형식이 올바르며, 기본 브랜치가 보호되어 있다.
(Owner) Allow code review, Repositories 목록, GitHub App 접근 권한을 확인했다.

다음 단계

Read and request reviews on a pull request: findings와 check run의 의미, 코멘트 명령
Set up Code Review: Owner용 활성화와 저장소 관리
Code Review costs and usage: 예산 메시지 뒤의 spend limit
Customize Code Review: 리뷰가 어떤 REVIEW.md를 읽는지

기준일

이 문서는 2026-11-03에 공식 Troubleshoot Code Review 페이지를 기준으로 작성했습니다.

Code Review 문제 해결 (Troubleshoot Code Review)

기준일: 2026-11-03
공식 기준: Troubleshoot Code Review

개요

핵심 개념

증상	먼저 볼 곳
check run이 없음	`@claude review` 코멘트 후 check run이 생기는지
"⚠️ Code review skipped" 코멘트	코멘트 문구로 어떤 한도에 걸렸는지
Code review failed / timed out	자동 재시도 여부 → `@claude review` 또는 Re-run
findings가 있다는데 inline 코멘트 없음	check run Details, Files changed annotation, 리뷰 본문
`REVIEW.md` 메시지	기본 브랜치 보호 여부, 링크 수·형식

상세

리뷰 진행 상황 확인

PR의 Claude Code Review check run 제목을 다음 표와 맞춰 봅니다.

check run 제목	의미	할 일
Code review queued... 또는 Code review in progress...	리뷰가 끝나지 않음	제목이 바뀔 때까지 대기
Code review found no issues	리뷰가 끝났고 게시한 findings가 없음	이 PR의 첫 리뷰가 아니라면 리뷰 본문에서 리뷰가 제외한 findings 개수를 확인. 첫 리뷰라면 없음
이슈를 찾았다는 제목	findings와 함께 끝남	diff에 보이지 않으면 아래 "inline 코멘트로 안 보이는 findings 찾기"
Code review skipped — no new changes	최신 push에서 자동 리뷰가 실행되지 않음	그래도 리뷰를 받으려면 `@claude review` 코멘트
Code review not repeated — earlier findings still open	최신 push에서 자동 리뷰가 실행되지 않았고 이전 리뷰의 Important findings가 열려 있음	수정을 push하거나 `@claude review` 코멘트. When a push keeps the earlier result 참고
Code review failed 또는 Code review timed out	리뷰가 끝나지 않음	아래 "실패·타임아웃 리뷰 다시 실행"
Code review declined	리뷰가 실행되지 않음	check run 요약을 읽음. 예산이나 spend limit이 언급되면 아래 "예산 메시지"
check run 없음	리뷰가 시작되지 않음	`@claude review` 코멘트. 그래도 check run이 없으면 아래 "코멘트 명령이 리뷰를 시작하지 않음"

리뷰가 시작되지 않음

Claude Code Review check run이 보이지 않거나 Claude가 리뷰를 건너뛰었다는 코멘트를 남겼을 때 확인합니다.

코멘트 명령이 리뷰를 시작하지 않음

저장소에 Code Review가 꺼져 있음: Claude가 코멘트도 check run도 남기지 않습니다. Owner에게 저장소 추가를 요청합니다.
코멘트가 조건을 만족하지 않음: 새 top-level 코멘트가 아니라 inline 코멘트나 리뷰 본문이었거나, 명령이 코멘트 맨 앞에 있지 않았습니다. 이전 코멘트 수정도 인정되지 않고, PR이 열려 있어야 합니다. 코멘트 명령 조건을 보고 새 코멘트를 남깁니다.
write 권한 없음: 저장소에 write, maintain, admin 권한이 필요합니다. fork PR에서는 base 저장소 권한이 기준입니다. 본인 PR이 아니면 Claude가 tip 코멘트로 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답할 수 있습니다. write 권한이 있는 사람에게 대신 코멘트를 요청합니다.
예산 소진: Claude가 "⚠️ Code review skipped"로 시작하는 코멘트를 남깁니다. 아래 예산 메시지 항목을 봅니다.

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

코멘트에는 admin이 예산을 복구하는 claude.ai/admin-settings/usage 링크가 있고, 문구로 어떤 한도에 걸렸는지 알 수 있습니다.

문구	원인	조치
"has reached its monthly code review spending cap"	Code Review 월간 spend limit 도달	다음 결제 기간 시작 시 재개. 더 빨리 필요하면 admin에게 한도 상향 요청
"has no extra usage available to pay for this review"	조직의 usage credits 잔액이 비었거나 전체 월간 spend limit 도달	admin에게 usage credits 추가 또는 한도 상향 요청
"is too low to start another review"	남은 예산·잔액이 리뷰 1회 예상 비용보다 적음	admin에게 한도 상향 또는 usage credits 추가 요청

실패·타임아웃 리뷰 다시 실행

그 외에 제목이 Code review failed 또는 Code review timed out이면 코멘트나 re-run으로 다시 실행합니다.

@claude review 코멘트: PR의 top-level 코멘트로 남깁니다. 이후 push 구독 없이 새 리뷰를 시작합니다.
Re-run 클릭: PR이 fork에서 온 것이 아니면 GitHub Checks 탭의 Claude Code Review check에서 Re-run을 클릭합니다. PR의 현재 head 커밋을 리뷰하며 역시 구독하지 않습니다.

inline 코멘트로 안 보이는 findings 찾기

check run 제목은 이슈를 찾았다는데 diff에 inline 리뷰 코멘트가 없다면 다음 위치를 봅니다.

check run Details: Checks 탭의 Claude Code Review 옆 Details를 클릭합니다. inline 코멘트가 받아들여졌는지와 관계없이 심각도 표에 파일·줄·요약이 나옵니다.
Files changed annotation: PR의 Files changed 탭을 엽니다. 줄 정보가 있지만 inline 코멘트로 게시되지 않은 finding이 해당 줄에 annotation으로 표시됩니다.
리뷰 본문: inline 위치가 없거나 현재 diff 밖에 있는 findings는 리뷰 본문의 Additional findings 제목 아래에 나옵니다.

check run에 REVIEW.md가 언급될 때

check run이 REVIEW.md에 대해 남길 수 있는 메시지 중 네 가지입니다.

"This review applied the repository's review instructions (REVIEW.md) from its default branch, which is not protected against direct pushes.": 리뷰가 루트 파일만 읽었습니다. 브랜치를 보호하면 무엇이 달라지는지는 Which branch REVIEW.md is read from을 보세요.
"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 링크가 있습니다. 고치거나 지웁니다.
- 변경된 파일로의 링크: 이 PR이 바꾸는 파일·폴더를 링크하고 있고, 리뷰가 그 링크가 있는 줄만 빼낼 수 없었습니다. 규칙을 REVIEW.md 안에 직접 씁니다.
"include line(s) in the root REVIEW.md were skipped on this review": 루트 REVIEW.md는 적용됐지만 그 include 줄이 가리키는 파일은 적용되지 않았습니다. Include other files in REVIEW.md의 목록과, skill이라면 Include a skill file의 목록을 확인하세요.

설정 문제

Owner가 Code Review를 설정하는 중에 겪는 경우입니다.

Add a repository에 저장소가 없음

테스트 PR에 check run이 생기지 않음

체크리스트

check run 제목으로 리뷰 진행 단계를 먼저 확인했다.
👀 반응이 아니라 Code review queued... check run으로 리뷰 시작을 확인했다.
코멘트 명령이 새 top-level 코멘트 첫 줄이고, 작성자에게 write 이상 권한이 있다(fork면 base 저장소 기준).
예산 메시지 문구로 어떤 한도인지 구분하고 admin에게 알렸다.
inline 코멘트가 없으면 Details, Files changed, Additional findings를 확인했다.
REVIEW.md의 Markdown 링크가 64개 이하이고 형식이 올바르며, 기본 브랜치가 보호되어 있다.
(Owner) Allow code review, Repositories 목록, GitHub App 접근 권한을 확인했다.

다음 단계

Read and request reviews on a pull request: findings와 check run의 의미, 코멘트 명령
Set up Code Review: Owner용 활성화와 저장소 관리
Code Review costs and usage: 예산 메시지 뒤의 spend limit
Customize Code Review: 리뷰가 어떤 REVIEW.md를 읽는지

기준일

이 문서는 2026-11-03에 공식 Troubleshoot Code Review 페이지를 기준으로 작성했습니다.

Code Review 문제 해결 (Troubleshoot Code Review)

개요

핵심 개념

상세

리뷰 진행 상황 확인

리뷰가 시작되지 않음

코멘트 명령이 리뷰를 시작하지 않음

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

실패·타임아웃 리뷰 다시 실행

inline 코멘트로 안 보이는 findings 찾기

check run에 REVIEW.md가 언급될 때

설정 문제

Add a repository에 저장소가 없음

테스트 PR에 check run이 생기지 않음

체크리스트

다음 단계

기준일

관련 가이드

Code Review 문제 해결 (Troubleshoot Code Review)

개요

핵심 개념

상세

리뷰 진행 상황 확인

리뷰가 시작되지 않음

코멘트 명령이 리뷰를 시작하지 않음

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

실패·타임아웃 리뷰 다시 실행

inline 코멘트로 안 보이는 findings 찾기

check run에 REVIEW.md가 언급될 때

설정 문제

Add a repository에 저장소가 없음

테스트 PR에 check run이 생기지 않음

체크리스트

다음 단계

기준일

관련 가이드