> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Review 문제 해결

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

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

<h2 id="check-how-far-the-review-got">
  리뷰 진행 상황 확인하기
</h2>

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

| 체크 실행 제목 | 의미 | 조치 |
| :- | :- | :- |
| **Code review queued...** 또는 **Code review in progress...** | 리뷰가 아직 완료되지 않았습니다 | 제목이 바뀔 때까지 기다립니다 |
| **Code review found no issues** | 리뷰가 완료되었으며 지적할 사항을 찾지 못했습니다 | 조치가 필요하지 않습니다 |
| 문제가 발견되었다는 제목 | 리뷰가 발견 사항과 함께 완료되었습니다 | diff에서 발견 사항이 보이지 않으면 [인라인 댓글로 표시되지 않는 문제 찾기](#find-issues-that-aren’t-showing-as-inline-comments)를 참조하세요 |
| **Code review skipped — no new changes** | 최근 푸시에 대해 자동 리뷰가 실행되지 않았습니다 | 그래도 리뷰를 받으려면 `@claude review`라고 댓글을 작성합니다 |
| **Code review failed** 또는 **Code review timed out** | 리뷰가 완료되지 않았습니다 | 다시 실행하려면 [실패하거나 시간 초과된 리뷰 다시 트리거하기](#retrigger-a-failed-or-timed-out-review)를 참조하세요 |
| **Code review declined** | 리뷰가 실행되지 않았습니다 | 체크 실행의 요약을 읽습니다. 요약에 예산이나 지출 한도가 언급되어 있으면 [리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요 |
| 체크 실행 없음 | 리뷰가 시작되지 않았습니다 | `@claude review`라고 댓글을 작성합니다. 그 후에도 체크 실행이 나타나지 않으면 [댓글 명령으로 리뷰가 시작되지 않는 경우](#a-comment-command-didn’t-start-a-review)를 참조하세요 |

<h2 id="a-review-didn’t-start">
  리뷰가 시작되지 않는 경우
</h2>

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

<h3 id="a-comment-command-didn’t-start-a-review">
  댓글 명령으로 리뷰가 시작되지 않는 경우
</h3>

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

* **이 저장소에 Code Review가 켜져 있지 않음**: Claude가 명령에 대한 응답으로 댓글이나 체크 실행을 게시하지 않습니다. Owner에게 [저장소 추가](/docs/ko/code-review-setup#add-more-repositories)를 요청합니다.
* **댓글이 조건을 충족하지 않음**: 새 최상위 댓글이 아니라 인라인 댓글이나 리뷰 본문이었거나, 명령이 댓글의 시작 부분에 있지 않았습니다. 새 댓글을 게시하지 않고 이전 댓글을 편집한 경우도 인정되지 않으며, 풀 리퀘스트가 열려 있어야 합니다. [댓글 명령의 조건](/docs/ko/code-review-pull-requests#comment-commands)을 확인하고 이를 충족하는 새 댓글을 게시합니다.
* **쓰기 권한이 없음**: 저장소에 대한 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에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요.

<h3 id="review-didn’t-run-and-the-pr-shows-a-budget-message">
  리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우
</h3>

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

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

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

예산이 복원된 후 풀 리퀘스트에 `@claude review`라고 댓글을 작성하면 건너뛴 리뷰를 받을 수 있습니다. [댓글 명령의 조건](/docs/ko/code-review-pull-requests#comment-commands)이 적용되므로 댓글 작성자에게 쓰기 권한이 있어야 합니다.

<h2 id="retrigger-a-failed-or-timed-out-review">
  실패하거나 시간 초과된 리뷰 다시 트리거하기
</h2>

체크 실행의 요약에 "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 클릭**: 풀 리퀘스트가 [포크에서 생성된](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks) 것이 아니라면, GitHub의 **Checks** 탭에서 **Claude Code Review** 체크의 **Re-run**을 클릭합니다. 재실행은 풀 리퀘스트의 현재 헤드 커밋을 대상으로 하며, 이 방법 역시 풀 리퀘스트를 구독시키지 않습니다.

<h2 id="find-issues-that-aren’t-showing-as-inline-comments">
  인라인 댓글로 표시되지 않는 문제 찾기
</h2>

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

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

<h2 id="the-check-run-mentions-review-md">
  체크 실행에 REVIEW\.md가 언급되는 경우
</h2>

체크 실행에 표시될 수 있는 `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를 읽는 브랜치](/docs/ko/code-review-customize#which-branch-review-md-is-read-from)를 참조하세요.
* **"were not applied to this review: branch protection could not be confirmed"**: 리뷰가 `REVIEW.md`를 전혀 읽지 않았습니다.

<h2 id="setup-problems">
  설정 문제
</h2>

다음 사례는 Owner가 [Code Review를 설정](/docs/ko/code-review-setup)하는 과정에서 발생합니다.

<h3 id="a-repository-isn’t-listed-in-add-a-repository">
  Add a repository에 저장소가 나열되지 않는 경우
</h3>

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

<h3 id="no-check-run-appears-on-the-test-pull-request">
  테스트 풀 리퀘스트에 체크 실행이 나타나지 않는 경우
</h3>

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

<h2 id="related-resources">
  관련 리소스
</h2>

* [풀 리퀘스트에서 리뷰 읽기 및 요청하기](/docs/ko/code-review-pull-requests): 발견 사항과 체크 실행의 의미, 그리고 댓글 명령
* [Code Review 설정하기](/docs/ko/code-review-setup): Owner를 위한 Code Review 켜기 및 저장소 관리
* [Code Review 비용 및 사용량](/docs/ko/code-review-costs): 예산 메시지의 원인이 되는 지출 한도
* [Code Review 사용자 지정하기](/docs/ko/code-review-customize): 리뷰가 읽는 `REVIEW.md`의 사본