Documentation 2026-10-14 22:58 UTC to 2026-10-15 23:58 UTC

636| 제한 사항 | 설명 |636| 제한 사항 | 설명 |

637| - | - |637| - | - |

638| Write/Edit/NotebookEdit 도구만 | Bash 명령어를 통해 수행된 변경 사항은 추적되지 않습니다 |638| Write/Edit/NotebookEdit 도구만 | Bash 명령어를 통해 수행된 변경 사항은 추적되지 않습니다 |

639| 서브에이전트 편집 | [서브에이전트](/docs/ko/agent-sdk/subagents)가 적용하는 편집 사항은 추적되거나 복원되지 않습니다. 단, `context: fork`를 사용하여 포그라운드에서 실행되는 스킬은 제외됩니다. 추적되지 않은 편집 사항을 되돌리려면 git을 사용하세요 |639| 서브에이전트 편집 | [서브에이전트](/docs/ko/agent-sdk/subagents)가 적용하는 편집 사항은 추적되지 않습니다. 단, `context: fork`를 사용하여 포그라운드에서 실행되는 스킬은 제외됩니다. 되돌리기는 메인 대화에서 이미 편집한 파일에서만 해당 편집 사항을 되돌립니다. 나머지는 git을 사용하여 되돌리세요 |

640| 동일한 세션 | 체크포인트는 이를 생성한 세션에 연결됩니다 |640| 동일한 세션 | 체크포인트는 이를 생성한 세션에 연결됩니다 |

641| 파일 콘텐츠만 | 디렉토리 생성, 이동 또는 삭제는 되돌리기로 실행 취소되지 않습니다 |641| 파일 콘텐츠만 | 디렉토리 생성, 이동 또는 삭제는 되돌리기로 실행 취소되지 않습니다 |

642| 로컬 파일 | 원격 또는 네트워크 파일은 추적되지 않습니다 |642| 로컬 파일 | 원격 또는 네트워크 파일은 추적되지 않습니다 |

17 17 

18이 가이드에서는 SDK가 텔레메트리를 내보내는 방식, 내보내기를 구성하는 방법, 데이터가 백엔드에 도달한 후 태그를 지정하고 필터링하는 방법을 설명합니다. 백엔드로 내보내는 대신 SDK 응답 스트림에서 직접 토큰 사용량 및 비용을 읽으려면 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요.18이 가이드에서는 SDK가 텔레메트리를 내보내는 방식, 내보내기를 구성하는 방법, 데이터가 백엔드에 도달한 후 태그를 지정하고 필터링하는 방법을 설명합니다. 백엔드로 내보내는 대신 SDK 응답 스트림에서 직접 토큰 사용량 및 비용을 읽으려면 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking)을 참조하세요.

19 19 

20<Note>

21 Claude API 또는 Managed Agents의 경우 [Claude API용 OpenTelemetry](https://platform.claude.com/docs/en/manage-claude/opentelemetry)를 참조하세요.

22</Note>

23 

20<h2 id="how-telemetry-flows-from-the-sdk">24<h2 id="how-telemetry-flows-from-the-sdk">

21 SDK에서 텔레메트리가 흐르는 방식25 SDK에서 텔레메트리가 흐르는 방식

22</h2>26</h2>

1926| `costUSD` | `float` | 이 모델의 추정 비용 (USD), 클라이언트 측 계산입니다. 청구 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조하십시오. |1926| `costUSD` | `float` | 이 모델의 추정 비용 (USD), 클라이언트 측 계산입니다. 청구 주의 사항은 [비용 및 사용량 추적](/docs/ko/agent-sdk/cost-tracking) 참조하십시오. |

1927| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기입니다. |1927| `contextWindow` | `int` | 이 모델의 컨텍스트 윈도우 크기입니다. |

1928| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |1928| `maxOutputTokens` | `int` | 이 모델의 최대 출력 토큰 제한입니다. |

1929| `canonicalModel` | `str` | 가격 조회에 사용된 정규 모델 ID입니다. 공급자별 ID 또는 별칭과 같은 원본 모델 문자열과 다를 수 있습니다. 항상 존재하지는 않습니다. |1929| `canonicalModel` | `str` | 가격 조회에 사용된 정규 모델 ID입니다. 항목의 키로 쓰이는 원본 모델 문자열(예: 공급자별 ID 또는 별칭)과 다를 수 있습니다. 항상 존재하지는 않습니다. |

1930| `provider` | `str` | 이 모델을 제공한 API 공급자입니다 (예: `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` 또는 `gateway`). 항상 존재하지는 않습니다. |1930| `provider` | `str` | 이 모델을 제공한 API 공급자입니다 (예: `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` 또는 `gateway`). 항상 존재하지는 않습니다. |

1931| `costBasis` | `str` | 이 모델의 최신 요청 가격을 책정한 가격표입니다: 정가의 경우 `list`, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 테이블의 경우 `managed`, 둘 다 모델 ID와 일치하지 않는 경우 `unknown`입니다. 항상 존재하지는 않으며, TypedDict에 선언되지 않으므로 `.get()`으로 읽으십시오. Claude Code v2.1.246 이상이 필요합니다. |1931| `costBasis` | `str` | 이 모델의 최신 요청 가격을 책정한 가격표입니다: 정가의 경우 `list`, [`modelPricing`](/docs/ko/settings-reference#modelpricing) 테이블의 경우 `managed`, 둘 다 모델 ID와 일치하지 않는 경우 `unknown`입니다. 항상 존재하지는 않으며, TypedDict에 선언되지 않으므로 `.get()`으로 읽으십시오. Claude Code v2.1.246 이상이 필요합니다. |

1932 1932 

201| 서브에이전트가 받는 항목 | 서브에이전트가 받지 않는 항목 |201| 서브에이전트가 받는 항목 | 서브에이전트가 받지 않는 항목 |

202| :- | :- |202| :- | :- |

203| 자체 시스템 프롬프트(`AgentDefinition.prompt`) 및 Agent 도구의 프롬프트 | 부모의 대화 기록 또는 도구 결과 |203| 자체 시스템 프롬프트(`AgentDefinition.prompt`) 및 Agent 도구의 프롬프트 | 부모의 대화 기록 또는 도구 결과 |

204| 프로젝트 CLAUDE.md([`settingSources`](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨). 단, 에이전트가 [`omitClaudeMd`](#agentdefinition-configuration)를 설정한 경우는 제외 | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |204| 프로젝트 CLAUDE.md([`settingSources`](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 통해 로드됨). [`omitClaudeMd`](#agentdefinition-configuration)를 설정한 에이전트는 이 파일 없이 시작합니다 | 미리 로드된 스킬 콘텐츠(`AgentDefinition.skills`에 나열된 경우 제외) |

205| 도구 정의(부모로부터 상속되거나 `tools`에 지정된 하위 집합이며, [백그라운드 실행의 경우 필터링됨](/docs/ko/sub-agents#available-tools)) | 부모의 시스템 프롬프트 |205| 도구 정의(부모로부터 상속되거나 `tools`에 지정된 하위 집합이며, [백그라운드 실행의 경우 필터링됨](/docs/ko/sub-agents#available-tools)) | 부모의 시스템 프롬프트 |

206 206 

207<Note>207<Note>

369| `session_id` | `string` | 이 메시지가 속한 세션 |369| `session_id` | `string` | 이 메시지가 속한 세션 |

370| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |370| `message` | `unknown` | 트랜스크립트의 원본 메시지 페이로드 |

371| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 서브에이전트를 시작한 `Agent` 또는 `Skill` 도구 호출의 `tool_use_id`입니다. 주 세션 메시지 및 이전 세션의 경우 `null` |371| `parent_tool_use_id` | `string \| null` | 서브에이전트 메시지의 경우 서브에이전트를 시작한 `Agent` 또는 `Skill` 도구 호출의 `tool_use_id`입니다. 주 세션 메시지 및 이전 세션의 경우 `null` |

372| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)의 메시지의 경우 이를 생성한 서브에이전트의 `agentId`입니다. 주 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. Claude Code v2.1.202 이상이 필요합니다 |372| `parent_agent_id` | `string \| null` | [중첩된 서브에이전트](/docs/ko/sub-agents#let-subagents-spawn-their-own-subagents)의 메시지의 경우 해당 중첩 서브에이전트를 생성한 서브에이전트의 `agentId`입니다. 주 세션 메시지, 최상위 서브에이전트의 메시지 및 이전 세션의 경우 `null`입니다. Claude Code v2.1.202 이상이 필요합니다 |

373 373 

374<h4 id="example-4">374<h4 id="example-4">

375 예제375 예제

500 백그라운드로 이동할 때 이어지는 것500 백그라운드로 이동할 때 이어지는 것

501</h4>501</h4>

502 502 

503백그라운드로 이동하면 저장된 대화에서 재개하는 새 프로세스가 시작되며, 진행 중인 작업이 그 프로세스로 이동합니다. 실행 중인 백그라운드 셸 명령, 백그라운드로 보낸 서브에이전트, 동적 워크플로, [`/loop`](/docs/ko/scheduled-tasks)로 생성한 예약 작업, 그리고 Claude의 [아티팩트 댓글에 대한 자동 회신](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)이 모두 이어져 그곳에서 계속 실행됩니다. 서브에이전트는 자신이 시작한 모든 것과 함께 이동하므로, 그 작업이 모두 이동할 수 있을 때만 이어집니다. 진행 중인 작업을 이어가는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/docs/ko/env-vars#variables) 환경 변수를 설정합니다. 그러면 Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.503백그라운드로 이동하면 저장된 대화에서 재개하는 새 프로세스가 시작되며, 진행 중인 백그라운드 작업이 그 프로세스로 이동합니다. 실행 중인 백그라운드 셸 명령, 백그라운드로 보낸 서브에이전트, 동적 워크플로, [`/loop`](/docs/ko/scheduled-tasks)로 생성한 예약 작업, 그리고 Claude의 [아티팩트 댓글에 대한 자동 회신](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)이 모두 이어져 그곳에서 계속 실행됩니다. 서브에이전트는 자신이 시작한 모든 것과 함께 이동하므로, 그 작업이 모두 이동할 수 있을 때만 이어집니다. 진행 중인 백그라운드 작업을 이어가는 대신 중지하려면 [`CLAUDE_DISABLE_ADOPT=1`](/docs/ko/env-vars#variables) 환경 변수를 설정합니다. 그러면 Claude Code는 백그라운드로 이동하기 전에 확인을 요청합니다.

504 504 

505[동적 워크플로](/docs/ko/workflows)에 아직 실행 중인 서브에이전트가 있으면, Claude Code는 백그라운드로 이동하기 전에 `Background this session?` 대화 상자로 묻고, 몇 개의 서브에이전트가 재시작되는지 알려줍니다. 먼저 완료되도록 하려면 `Stay`를 선택합니다. 확인하면 Claude Code는 백그라운드 세션에서 실행을 재생합니다. 아직 실행 중이던 서브에이전트는 처음부터 다시 시작되므로, 지금까지 사용한 토큰이 다시 소비됩니다. 완료된 서브에이전트 중 어떤 것이 저장된 결과를 반환하고 어떤 것이 다시 실행되는지는 [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)를 참조하세요.505[동적 워크플로](/docs/ko/workflows)에 아직 실행 중인 서브에이전트가 있으면, Claude Code는 백그라운드로 이동하기 전에 `Background this session?` 대화 상자로 묻고, 몇 개의 서브에이전트가 재시작되는지 알려줍니다. 먼저 완료되도록 하려면 `Stay`를 선택합니다. 확인하면 Claude Code는 백그라운드 세션에서 실행을 재생합니다. 아직 실행 중이던 서브에이전트는 처음부터 다시 시작되므로, 지금까지 사용한 토큰이 다시 소비됩니다. 완료된 서브에이전트 중 어떤 것이 저장된 결과를 반환하고 어떤 것이 다시 실행되는지는 [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)를 참조하세요.

506 506 

507Claude Code는 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)처럼 이어갈 수 없는 작업을 중지하며, 모니터를 소유한 백그라운드 서브에이전트도 함께 중지합니다. 이러한 작업이 실행 중이면 Claude Code는 `Background this session?` 대화 상자를 표시하여 작업을 중지하기 전에 확인할 수 있게 합니다.507Claude Code는 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)처럼 이어갈 수 없는 백그라운드 작업을 중지하며, 모니터를 소유한 백그라운드 서브에이전트도 함께 중지합니다. 이러한 작업이 실행 중이면 Claude Code는 `Background this session?` 대화 상자를 표시하여 작업을 중지하기 전에 확인할 수 있게 합니다.

508 508 

509백그라운드로 이동한 후 세션은 새로운 서브에이전트, 모니터, 백그라운드 명령을 시작할 수 있으며, 이들은 이후 분리 및 재연결 후에도 계속 실행됩니다.509백그라운드로 이동한 후 세션은 새로운 서브에이전트, 모니터, 백그라운드 명령을 시작할 수 있으며, 이들은 이후 분리 및 재연결 후에도 계속 실행됩니다.

510 510 

949 백그라운드로 이동하면 `Background this session?` 대화 상자가 표시됨949 백그라운드로 이동하면 `Background this session?` 대화 상자가 표시됨

950</h3>950</h3>

951 951 

952`←`를 눌러 현재 세션을 백그라운드로 전환할 때 Claude Code가 `Background this session?` 대화 상자를 표시하면, 세션에 백그라운드로 전환 시 중지되거나, 다시 시작되거나, 지켜보는 사람 없이 계속 실행될 진행 중인 작업이 있는 것이며, Claude Code는 이 중 어느 것이든 수행하기 전에 확인을 요청합니다:952`←`를 눌러 현재 세션을 백그라운드로 전환할 때 Claude Code가 `Background this session?` 대화 상자를 표시하면, 세션에 백그라운드로 전환 시 중지되거나, 다시 시작되거나, 지켜보는 사람 없이 계속 실행될 진행 중인 백그라운드 작업이 있는 것이며, Claude Code는 이 중 어느 것이든 수행하기 전에 확인을 요청합니다:

953 953 

954* **이동할 수 없는 작업**: 세션에 백그라운드 세션으로 이동할 수 없는 작업이 있습니다. 예를 들어 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)와 같은 작업입니다. 대화 상자는 Claude Code가 중단할 작업의 이름을 지정하고, 별도로 이동할 작업의 개수를 세어줍니다.954* **이동할 수 없는 작업**: 세션에 백그라운드 세션으로 이동할 수 없는 작업이 있습니다. 예를 들어 실행 중인 [모니터](/docs/ko/tools-reference#monitor-tool)와 같은 작업입니다. 대화 상자는 Claude Code가 중단할 백그라운드 작업의 이름을 표시하고, 별도로 이동할 작업의 개수를 세어줍니다.

955* **실행 중인 서브에이전트가 있는 워크플로**: [동적 워크플로](/docs/ko/workflows)에 여전히 실행 중인 서브에이전트가 있습니다. 워크플로 자체는 이동되지만, 실행 중인 서브에이전트는 처음부터 다시 시작되며, 대화 상자는 개수를 표시합니다.955* **실행 중인 서브에이전트가 있는 워크플로**: [동적 워크플로](/docs/ko/workflows)에 여전히 실행 중인 서브에이전트가 있습니다. 워크플로 자체는 이동되지만, 실행 중인 서브에이전트는 처음부터 다시 시작되며, 대화 상자는 개수를 표시합니다.

956* **자동 아티팩트 답변**: Claude가 [아티팩트의 댓글에 자동으로 답변](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)하고 있습니다. 이러한 답변은 백그라운드 세션에서 계속되며, 대화 상자는 이를 표시합니다.956* **자동 아티팩트 답변**: Claude가 [아티팩트의 댓글에 자동으로 답변](/docs/ko/artifacts#let-claude-reply-to-comments-on-its-own)하고 있습니다. 이러한 답변은 백그라운드 세션에서 계속되며, 대화 상자는 이를 표시합니다.

957 957 

1175| v2.1.199 | 메모리가 부족한 호스트에서 시작을 완료하기 전에 프로세스가 종료되는 백그라운드 세션은 단순히 종료 이유만 표시하는 대신 행 상태에 `possibly low memory — free some up and retry`를 표시합니다. `←` 또는 `/background`로 세션을 백그라운드로 이동하면 `/color`가 새 행으로 이어집니다. |1175| v2.1.199 | 메모리가 부족한 호스트에서 시작을 완료하기 전에 프로세스가 종료되는 백그라운드 세션은 단순히 종료 이유만 표시하는 대신 행 상태에 `possibly low memory — free some up and retry`를 표시합니다. `←` 또는 `/background`로 세션을 백그라운드로 이동하면 `/color`가 새 행으로 이어집니다. |

1176| v2.1.198 | 에이전트 뷰는 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 `preferredNotifChannel`을 통해 알림을 보내고 `agent_needs_input` 또는 `agent_completed` 유형으로 `Notification` 훅을 실행합니다. `claude attach <id>` 내의 `←` 및 `/exit`는 셸로 종료하는 대신 에이전트 뷰로 돌아갑니다. `Ctrl+Z`는 셸로 돌아갑니다. 작업을 워크트리에 격리한 백그라운드 세션은 완료될 때 먼저 묻는 대신 커밋하고, `main`이나 `master`가 아닌 자신의 격리된 브랜치를 푸시하며, 초안 풀 리퀘스트를 엽니다. `/login`은 에이전트 뷰에서 실행되고 로그인 대화 상자를 엽니다. `Background work is running` 종료 대화 상자는 `Move to background and exit`를 제공합니다. 종료 핸드오프는 백그라운드 서브에이전트도 포함하며, 이들은 실패로 보고되는 대신 다음 깨어날 때 트랜스크립트에서 재개됩니다. `claude --bg`는 `-p` 또는 `--print`와 결합되면 오류로 거부됩니다. 백그라운드 세션 호스트는 `connect: no route to host`로 실패하는 대신 첫 LAN 액세스 시 macOS 로컬 네트워크 권한을 요청합니다. |1176| v2.1.198 | 에이전트 뷰는 백그라운드 세션이 입력이 필요하거나, 완료되거나, 실패할 때 `preferredNotifChannel`을 통해 알림을 보내고 `agent_needs_input` 또는 `agent_completed` 유형으로 `Notification` 훅을 실행합니다. `claude attach <id>` 내의 `←` 및 `/exit`는 셸로 종료하는 대신 에이전트 뷰로 돌아갑니다. `Ctrl+Z`는 셸로 돌아갑니다. 작업을 워크트리에 격리한 백그라운드 세션은 완료될 때 먼저 묻는 대신 커밋하고, `main`이나 `master`가 아닌 자신의 격리된 브랜치를 푸시하며, 초안 풀 리퀘스트를 엽니다. `/login`은 에이전트 뷰에서 실행되고 로그인 대화 상자를 엽니다. `Background work is running` 종료 대화 상자는 `Move to background and exit`를 제공합니다. 종료 핸드오프는 백그라운드 서브에이전트도 포함하며, 이들은 실패로 보고되는 대신 다음 깨어날 때 트랜스크립트에서 재개됩니다. `claude --bg`는 `-p` 또는 `--print`와 결합되면 오류로 거부됩니다. 백그라운드 세션 호스트는 `connect: no route to host`로 실패하는 대신 첫 LAN 액세스 시 macOS 로컬 네트워크 권한을 요청합니다. |

1177| v2.1.196 | 단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 조용히 삭제되는 대신 우회 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로는 Windows를 포함하여 세션의 프로세스가 중지되거나, 다시 시작되거나, 업데이트되어도 유지됩니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하면 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접미사로 이름이 바뀝니다. |1177| v2.1.196 | 단일 `←` 누름이 포그라운드 세션을 백그라운드로 이동합니다. 이전 버전은 바닥글 힌트와 확인이 있는 두 번의 누름이 필요했습니다. `claude agents`에 전달된 `--dangerously-skip-permissions`는 조용히 삭제되는 대신 우회 면책 조항을 표시합니다. 이름을 지정하지 않은 대화형 세션은 세션 목록 및 `claude agents --json`에서 `my-app-3f`와 같은 기본 이름을 가집니다. 백그라운드 셸 명령 및 동적 워크플로는 Windows를 포함하여 세션의 프로세스가 중지되거나, 다시 시작되거나, 업데이트되어도 유지됩니다. `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1`을 설정하면 핸드오프를 끕니다. 다시 시작 시 비어 있는 것으로 잘못 읽은 트랜스크립트는 삭제되는 대신 `.orphaned-` 접미사로 이름이 바뀝니다. |

1178| v2.1.195 | Windows에서도 세션을 백그라운드로 이동할 때 진행 중인 작업이 이어집니다. 대신 중지하려면 `CLAUDE_DISABLE_ADOPT=1`을 설정합니다. `Completed` 그룹은 남은 수직 공간을 채우고 짧은 터미널에서 헤더가 압축됩니다. 이전 Claude Code 버전은 더 이상 최신 세션의 `state.json` 필드를 삭제하거나 해당 세션을 `claude agents`에서 숨기지 않습니다. 중지된 세션에 연결하면 최대 5초 동안 빈 화면을 표시하는 대신 즉시 전환됩니다. 연결을 수락할 수 없는 감독자는 자체적으로 종료되고 잠금을 해제합니다. |1178| v2.1.195 | Windows에서도 세션을 백그라운드로 이동할 때 진행 중인 백그라운드 작업이 이어집니다. 대신 중지하려면 `CLAUDE_DISABLE_ADOPT=1`을 설정합니다. `Completed` 그룹은 남은 수직 공간을 채우고 짧은 터미널에서 헤더가 압축됩니다. 이전 Claude Code 버전은 더 이상 최신 세션의 `state.json` 필드를 삭제하거나 해당 세션을 `claude agents`에서 숨기지 않습니다. 중지된 세션에 연결하면 최대 5초 동안 빈 화면을 표시하는 대신 즉시 전환됩니다. 연결을 수락할 수 없는 감독자는 자체적으로 종료되고 잠금을 해제합니다. |

1179| v2.1.191 | `claude --bg`에 서브에이전트와 일치하지 않는 `--agent` 이름을 지정하면 시작이 실패합니다: 세션은 기본 에이전트로 실행되는 대신 `--agent '<name>' not found` 오류로 즉시 종료됩니다. |1179| v2.1.191 | `claude --bg`에 서브에이전트와 일치하지 않는 `--agent` 이름을 지정하면 시작이 실패합니다: 세션은 기본 에이전트로 실행되는 대신 `--agent '<name>' not found` 오류로 즉시 종료됩니다. |

1180| v2.1.174 | 백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 잘못된 `Could not resolve authentication method` 오류를 수정합니다. |1180| v2.1.174 | 백그라운드 세션은 더 이상 감독자의 시작 셸에서 `ANTHROPIC_BASE_URL`과 같은 게이트웨이 엔드포인트 변수를 상속하지 않습니다. 감독자는 사전 준비된 워커에 새로운 자격 증명 스냅샷을 제공하여 잘못된 `Could not resolve authentication method` 오류를 수정합니다. |

1181| v2.1.172 | 디스패치 입력의 `/model`이 세션 범위 디스패치 모델 재정의를 설정합니다. |1181| v2.1.172 | 디스패치 입력의 `/model`이 세션 범위 디스패치 모델 재정의를 설정합니다. |

13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | 사용량 지표, GitHub 통합을 포함한 기여도 지표, 리더보드, 데이터 내보내기 | [세부 정보](#access-analytics-for-team-and-enterprise) |13| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | 사용량 지표, GitHub 통합을 포함한 기여도 지표, 리더보드, 데이터 내보내기 | [세부 정보](#access-analytics-for-team-and-enterprise) |

14| API (Claude Console) | [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | 사용량 지표, 지출 추적, 팀 인사이트 | [세부 정보](#access-analytics-for-api-customers) |14| API (Claude Console) | [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | 사용량 지표, 지출 추적, 팀 인사이트 | [세부 정보](#access-analytics-for-api-customers) |

15 15 

16Code Review에는 별도의 대시보드가 있습니다. 리뷰 활동 및 지출은 [사용량 보기](/docs/ko/code-review-costs#view-usage)를 참조하세요.

17 

16<h2 id="access-analytics-for-team-and-enterprise">18<h2 id="access-analytics-for-team-and-enterprise">

17 Team 및 Enterprise를 위한 분석 접근19 Team 및 Enterprise를 위한 분석 접근

18</h2>20</h2>

75| 세션이 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)인 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |75| 세션이 [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)인 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |

76| 게시가 [커넥터 호출](#pull-live-data-with-mcp-connectors) 또는 [파일 다운로드](#offer-a-file-download)와 같은 페이지에 대한 런타임 기능을 선언하는 경우 | 해당 게시 전에 확인을 요청합니다 |76| 게시가 [커넥터 호출](#pull-live-data-with-mcp-connectors) 또는 [파일 다운로드](#offer-a-file-download)와 같은 페이지에 대한 런타임 기능을 선언하는 경우 | 해당 게시 전에 확인을 요청합니다 |

77| 아티팩트를 공개적으로 공유한 경우 | 변경 전에 대화당 한 번 확인을 요청합니다 |77| 아티팩트를 공개적으로 공유한 경우 | 변경 전에 대화당 한 번 확인을 요청합니다 |

78| [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |

79| 사용자가 입력한 프롬프트가 아니라 세션에서 실행된 [예약 작업](/docs/ko/scheduled-tasks)이 시작한 턴에서 Claude가 게시하는 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |78| 사용자가 입력한 프롬프트가 아니라 세션에서 실행된 [예약 작업](/docs/ko/scheduled-tasks)이 시작한 턴에서 Claude가 게시하는 경우 | 각 아티팩트의 첫 번째 게시 전에 확인을 요청합니다 |

80| 사용자의 승인 없이는 Claude가 파일을 읽을 수 없는 경우 | 게시 전에 확인을 요청합니다. `Artifact` 도구에 대한 허용 규칙이 있어도 이 프롬프트는 생략되지 않습니다 |79| 사용자의 승인 없이는 Claude가 파일을 읽을 수 없는 경우 | 게시 전에 확인을 요청합니다. `Artifact` 도구에 대한 허용 규칙이 있어도 이 프롬프트는 생략되지 않습니다 |

80| [Manual](/docs/ko/permission-modes) 또는 `acceptEdits` 모드에서 Claude가 Manual 모드의 프로젝트 파일처럼 사용자의 승인 없이는 편집할 수 없는 아티팩트 파일에 작은 변경을 하는 경우 | 변경 사항을 게시하기 전에 확인을 요청합니다. 파일 편집에 사용자의 승인이 필요하므로 `Artifact` 도구에 대한 허용 규칙이 있어도 확인을 요청합니다 |

81 81 

82Claude는 세션의 [작업 디렉터리](/docs/ko/permissions#working-directories)와 페이지를 작성하는 임시 디렉터리에 있는 파일은 묻지 않고 읽습니다. Claude가 다른 폴더에서 프롬프트 없이 게시할 수 있도록 하려면 실행 시 [`--add-dir`](/docs/ko/cli-reference#cli-flags)로, 또는 세션 중에 `/add-dir`로 해당 폴더를 작업 디렉터리로 추가하십시오.82사용자의 승인 없이 Claude가 [작업 디렉터리](/docs/ko/permissions#working-directories) 외부의 파일을 읽을 수 있도록 하려면 실행 시 [`--add-dir`](/docs/ko/cli-reference#cli-flags)로, 또는 세션 중에 `/add-dir`로 해당 폴더를 작업 디렉터리로 추가하십시오. Claude는 이러한 디렉터리와 페이지를 작성하는 임시 디렉터리에 있는 파일은 이미 묻지 않고 읽습니다.

83 

84게시 프롬프트에 `Also makes 1 edit to that file on disk.`와 같은 문장이 포함되어 있으면 Claude가 아티팩트 파일을 변경하고 게시하는 작업을 한 단계로 수행하는 것입니다. 프롬프트를 승인하면 Claude Code는 페이지를 게시한 다음 변경 사항을 파일에 씁니다.

83 85 

84<h2 id="update-an-artifact">86<h2 id="update-an-artifact">

85 아티팩트 업데이트87 아티팩트 업데이트

149* **네트워크 액세스가 없는 클라우드 세션**: [클라우드 환경](/docs/ko/cloud-environments#access-levels)의 경우 **None** 수준에 해당합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 분류기가 대신 승인할 수 있으며, [Cowork](https://claude.com/product/cowork) 세션에서는 사용자만 승인할 수 있습니다.151* **네트워크 액세스가 없는 클라우드 세션**: [클라우드 환경](/docs/ko/cloud-environments#access-levels)의 경우 **None** 수준에 해당합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서는 분류기가 대신 승인할 수 있으며, [Cowork](https://claude.com/product/cowork) 세션에서는 사용자만 승인할 수 있습니다.

150* **다른 조직의 공개 아티팩트**: 자동 모드에서도 Claude Code는 먼저 사용자에게 묻습니다. `bypassPermissions` 모드처럼 Claude Code가 사용자에게 물을 수 없는 경우 Claude는 아티팩트를 읽을 수 없습니다. Claude는 [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 켜져 있는 동안에만 이러한 아티팩트를 읽을 수 있습니다.152* **다른 조직의 공개 아티팩트**: 자동 모드에서도 Claude Code는 먼저 사용자에게 묻습니다. `bypassPermissions` 모드처럼 Claude Code가 사용자에게 물을 수 없는 경우 Claude는 아티팩트를 읽을 수 없습니다. Claude는 [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 켜져 있는 동안에만 이러한 아티팩트를 읽을 수 있습니다.

151* **확인되지 않은 소유자 또는 네트워크 설정**: Claude Code가 아티팩트를 만든 사람을 확인할 수 없거나 클라우드 세션의 네트워크 설정을 확인할 수 없는 경우 사용자에게 묻으며, 사용자의 승인은 해당 요청 한 건에만 적용됩니다.153* **확인되지 않은 소유자 또는 네트워크 설정**: Claude Code가 아티팩트를 만든 사람을 확인할 수 없거나 클라우드 세션의 네트워크 설정을 확인할 수 없는 경우 사용자에게 묻으며, 사용자의 승인은 해당 요청 한 건에만 적용됩니다.

152* **플랜 모드 또는 기능 플래그 가져오기가 꺼진 경우**: [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에 있거나 [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 끈 경우, Claude Code는 Artifact 도구가 조직 내 다른 사람이 만든 아티팩트를 읽기 전에 사용자에게 묻습니다.154* **플랜 모드**: [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude Code가 Artifact 도구가 조직 내 다른 사람이 만든 아티팩트를 읽기 전에 사용자에게 묻습니다.

153 155 

154Claude가 WebFetch로 아티팩트를 읽을 때는 WebFetch 자체의 [프롬프트 규칙](/docs/ko/tools-reference#webfetch-tool-behavior)도 계속 적용됩니다.156Claude가 WebFetch로 아티팩트를 읽을 때는 WebFetch 자체의 [프롬프트 규칙](/docs/ko/tools-reference#webfetch-tool-behavior)도 계속 적용됩니다.

155 157 

102[Subagent](/docs/ko/sub-agents)는 Claude의 파일 편집 도구로 편집을 수행하지만, Claude Code는 일반적으로 세션의 checkpoint에서 이러한 편집을 캡처하지 않습니다. Rewind가 이를 복원하는지 여부는 subagent가 실행되는 방식에 따라 달라집니다:102[Subagent](/docs/ko/sub-agents)는 Claude의 파일 편집 도구로 편집을 수행하지만, Claude Code는 일반적으로 세션의 checkpoint에서 이러한 편집을 캡처하지 않습니다. Rewind가 이를 복원하는지 여부는 subagent가 실행되는 방식에 따라 달라집니다:

103 103 

104* **Foreground forked skill**: [foreground에서 실행되는 `context: fork`가 있는 skill](/docs/ko/skills#run-skills-in-a-subagent)은 사용자의 차례 동안 작업 트리를 편집하므로, rewind는 일반적으로 편집을 복원합니다. `background: false`를 설정하여 fork를 foreground에서 실행합니다. 몇 가지 상황([skills 페이지에 나열됨](/docs/ko/skills#run-skills-in-a-subagent))은 설정과 관계없이 foreground에서 실행됩니다.104* **Foreground forked skill**: [foreground에서 실행되는 `context: fork`가 있는 skill](/docs/ko/skills#run-skills-in-a-subagent)은 사용자의 차례 동안 작업 트리를 편집하므로, rewind는 일반적으로 편집을 복원합니다. `background: false`를 설정하여 fork를 foreground에서 실행합니다. 몇 가지 상황([skills 페이지에 나열됨](/docs/ko/skills#run-skills-in-a-subagent))은 설정과 관계없이 foreground에서 실행됩니다.

105* **다른 모든 subagent**: rewind는 편집을 복원하지 않습니다. git을 사용하여 되돌립니다. 여기에는 background에서 실행되는 forked skill(기본값)과 background [`/code-review --fix`](/docs/ko/code-review) 실행이 포함됩니다.105* **다른 모든 서브에이전트**: rewind는 대화에서 Claude가 이미 편집한 파일만 복원합니다. 다른 파일에 대한 서브에이전트의 편집은 그대로 남으므로 git을 사용하여 되돌립니다. 여기에는 background에서 실행되는 포크된 스킬(기본값)과 background [`/code-review --fix`](/docs/ko/code-review-local) 실행이 포함됩니다.

106 106 

107<h3 id="external-changes-not-tracked">107<h3 id="external-changes-not-tracked">

108 외부 변경 사항이 추적되지 않음108 외부 변경 사항이 추적되지 않음

392 392 

393질문 및 피드백은 [Claude Code 지원](https://support.claude.com/en/collections/14445694-claude-code)을 사용하거나 [Claude Code GitHub 저장소](https://github.com/anthropics/claude-code/issues)에서 이슈를 열어주세요. Anthropic 계정 팀에 문의할 수도 있습니다. 문제를 보고할 때 다음을 포함하세요:393질문 및 피드백은 [Claude Code 지원](https://support.claude.com/en/collections/14445694-claude-code)을 사용하거나 [Claude Code GitHub 저장소](https://github.com/anthropics/claude-code/issues)에서 이슈를 열어주세요. Anthropic 계정 팀에 문의할 수도 있습니다. 문제를 보고할 때 다음을 포함하세요:

394 394 

395* **Gateway 문제**: 해당 창의 gateway stderr, 시크릿을 가린 `gateway.yaml`, `/`의 랜딩 페이지에 표시된 gateway 버전, `/managed/settings`의 `x-cc-gateway-version` 응답 헤더, 최근에 변경된 사항395* **Gateway 문제**: 해당 창의 gateway stderr, 시크릿을 가린 `gateway.yaml`, `/`의 랜딩 페이지와 `/managed/settings`의 `x-cc-gateway-version` 응답 헤더에 표시되는 gateway 버전, 최근에 변경된 사항

396* **로그인 문제**: 개발자가 `claude --debug-file ./claude-debug.txt`를 실행하고 재현한 후 해당 파일과 동일한 창의 gateway 감사 로그를 전송396* **로그인 문제**: 개발자가 `claude --debug-file ./claude-debug.txt`를 실행하고 재현한 후 해당 파일과 동일한 창의 gateway 감사 로그를 전송

397* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청에 대한 gateway 감사 로그(어느 업스트림이 제공했는지 및 응답 상태 기록)397* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청에 대한 gateway 감사 로그(어느 업스트림이 제공했는지 및 응답 상태 기록)

398 398 

64`/web-setup` 안내(`/web-setup`이 저장하는 내용 및 제거 방법 포함)는 [터미널에서 연결](/docs/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.64`/web-setup` 안내(`/web-setup`이 저장하는 내용 및 제거 방법 포함)는 [터미널에서 연결](/docs/ko/web-quickstart#connect-from-your-terminal)을 참조하세요.

65 65 

66<Note>66<Note>

67 [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화되었거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직은 `/web-setup` 또는 기타 클라우드 세션 기능을 사용할 수 없습니다.67 [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화되었거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직은 `/web-setup` 또는 기타 클라우드 세션 기능을 사용할 수 없습니다. [고객 관리형 암호화 키](https://platform.claude.com/docs/en/manage-claude/cmek)(CMEK)를 사용하는 조직도 클라우드 세션을 시작할 수 없습니다.

68</Note>68</Note>

69 69 

70<h3 id="quick-setup-for-team-and-enterprise">70<h3 id="quick-setup-for-team-and-enterprise">

559 559 

560`matcher`는 hook을 `startup` 및 `resume` 이벤트로 제한하고, `$CLAUDE_PROJECT_DIR`은 리포지토리 루트로 확인되므로 hook은 세션의 작업 디렉토리에 관계없이 스크립트를 찾습니다.560`matcher`는 hook을 `startup` 및 `resume` 이벤트로 제한하고, `$CLAUDE_PROJECT_DIR`은 리포지토리 루트로 확인되므로 hook은 세션의 작업 디렉토리에 관계없이 스크립트를 찾습니다.

561 561 

562다음으로 `scripts/install_pkgs.sh`에서 스크립트를 만듭니다. 클라우드 외부에서는 즉시 종료된 후 종속성을 설치합니다.562다음으로 `scripts/install_pkgs.sh`에 스크립트를 만듭니다. 클라우드 외부에서는 즉시 종료하고, 그렇지 않으면 의존성을 설치합니다. 마지막으로 설치에 성공한 이후 `package.json`, `package-lock.json` 및 스크립트 자체가 변경되지 않았다면 `npm install`을 건너뜁니다.

563 563 

564```bash theme={null}564```bash theme={null}

565#!/bin/bash565#!/bin/bash

568 exit 0568 exit 0

569fi569fi

570 570 

571npm install571cd "$CLAUDE_PROJECT_DIR" || exit 1

572hashes=node_modules/.install_pkgs.sha256

573 

574if ! sha256sum --check --status "$hashes" 2>/dev/null; then

575 # Delete the old hashes first, so a failed install runs again next time

576 rm -f "$hashes"

577 if npm install; then

578 sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"

579 fi

580fi

581 

582# pip skips requirements that are already satisfied

572pip install -r requirements.txt583pip install -r requirements.txt

573exit 0584exit 0

574```585```

575 586 

576`CLAUDE_CODE_REMOTE` 확인은 설치를 클라우드 세션으로 범위를 지정하는 것입니다: 세션 VM의 환경은 해당 변수를 `true`로 전달하고, 로컬에서는 절대 `true`가 아니므로 노트북에서 스크립트는 아무것도 설치하기 전에 종료됩니다.587`CLAUDE_CODE_REMOTE` 확인은 설치를 클라우드 세션으로 범위를 지정하는 것입니다: 세션 VM의 환경은 해당 변수를 `true`로 전달하고, 로컬에서는 절대 `true`가 아니므로 노트북에서 스크립트는 아무것도 설치하기 전에 종료됩니다.

577 588 

578두 파일을 함께 사용하면 모든 클라우드 세션이 시작 시 새로운 `npm install` 및 `pip install`을 받으면서 로컬 세션은 영향을 받지 않습니다.589`npm install`이 성공했는지 확인하려면 클라우드 세션을 시작하고 Claude에 `node_modules/.install_pkgs.sha256`을 보여 달라고 요청합니다. 이 파일에는 세 파일 각각의 해시가 나열되어 있습니다. 파일이 없으면 Claude에 `npm install`을 실행하고 오류를 보고하도록 요청합니다.

590 

591<Note>

592 `npm install`이 워크스페이스의 `package.json`, `.npmrc` 또는 `postinstall` 스크립트의 입력 등 다른 파일을 읽는 경우, 해시를 저장하는 `sha256sum` 명령에 해당 파일을 추가합니다. 그렇지 않으면 해당 파일 중 하나가 변경된 후에도 이전 패키지가 유지됩니다.

593</Note>

579 594 

580<h4 id="limitations-in-cloud-sessions">595<h4 id="limitations-in-cloud-sessions">

581 클라우드 세션의 제한사항596 클라우드 세션의 제한사항

587* **클라우드 전용 범위 없음**: hook은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 `CLAUDE_CODE_REMOTE` 환경 변수가 `true`가 아닌 한 조기에 종료합니다. [종속성 설치 스크립트](#install-dependencies-with-a-sessionstart-hook)가 수행하는 방식입니다.602* **클라우드 전용 범위 없음**: hook은 로컬 및 클라우드 세션 모두에서 실행됩니다. 로컬 실행을 건너뛰려면 `CLAUDE_CODE_REMOTE` 환경 변수가 `true`가 아닌 한 조기에 종료합니다. [종속성 설치 스크립트](#install-dependencies-with-a-sessionstart-hook)가 수행하는 방식입니다.

588* **네트워크 액세스 필요**: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 **없음** 네트워크 액세스를 사용하면 이러한 hook이 실패합니다. **신뢰됨** 아래의 [기본 허용 목록](#default-allowed-domains)은 npm, PyPI, RubyGems 및 crates.io를 포함합니다.603* **네트워크 액세스 필요**: 설치 명령은 패키지 레지스트리에 도달해야 합니다. 환경이 **없음** 네트워크 액세스를 사용하면 이러한 hook이 실패합니다. **신뢰됨** 아래의 [기본 허용 목록](#default-allowed-domains)은 npm, PyPI, RubyGems 및 crates.io를 포함합니다.

589* **프록시 호환성**: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 [보안 프록시](#security-proxy)를 통과하고, 일부 패키지 관리자는 이와 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#default-deny-egress)에서 아웃바운드 트래픽은 대신 자신의 네트워크 경계를 통과합니다.604* **프록시 호환성**: Anthropic 호스팅 환경에서 모든 아웃바운드 트래픽은 [보안 프록시](#security-proxy)를 통과하고, 일부 패키지 관리자는 이와 올바르게 작동하지 않습니다. Bun은 알려진 예입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-deploy#default-deny-egress)에서 아웃바운드 트래픽은 대신 자신의 네트워크 경계를 통과합니다.

590* **시작 지연 추가**: hook은 세션이 시작되거나 재개될 때마다 실행되며, [환경 캐싱](#environment-caching)의 이점을 받는 설정 스크립트와 달리 실행됩니다. 설치 스크립트를 빠르게 유지하려면 종속성이 이미 있는지 확인한 후 재설치합니다.605* **시작 지연 추가**: 훅은 [환경 캐싱](#environment-caching)의 이점을 받는 설정 스크립트와 달리 세션이 시작되거나 재개될 때마다 실행됩니다. [의존성 설치 스크립트](#install-dependencies-with-a-sessionstart-hook)처럼 이미 완료된 작업을 건너뛰어 설치 스크립트를 빠르게 유지합니다.

591 606 

592기본 이미지를 사용자 정의하려면 설정 스크립트를 사용하여 [제공된 이미지](#installed-tools) 위에 필요한 항목을 설치하거나, `docker compose`를 사용하여 Claude와 함께 컨테이너로 자신의 이미지를 실행합니다. 기본 이미지를 완전히 교체하는 것은 아직 지원되지 않습니다.607기본 이미지를 사용자 정의하려면 설정 스크립트를 사용하여 [제공된 이미지](#installed-tools) 위에 필요한 항목을 설치하거나, `docker compose`를 사용하여 Claude와 함께 컨테이너로 자신의 이미지를 실행합니다. 기본 이미지를 완전히 교체하는 것은 아직 지원되지 않습니다.

593 608 

4 4 

5# Code Review5# Code Review

6 6 

7> 다중 에이전트 분석을 통해 전체 코드베이스를 검토하여 논리 오류, 보안 취약점 및 회귀를 감지하는 자동화된 PR 검토를 설정합니다7> Code Review로 GitHub 풀 리퀘스트의 버그를 찾아냅니다. Claude가 각 변경 사항을 리뷰하고, 결과를 검증하며, 인라인 댓글을 남깁니다. Team 및 Enterprise 플랜용

8 8 

9<Note>9Code Review를 사용하면 Claude가 GitHub 저장소의 풀 리퀘스트를 리뷰합니다. 여러 에이전트가 각 변경 사항을 주변 코드와 함께 읽으며 논리 오류, 보안 취약점, 손상된 엣지 케이스와 같은 문제를 찾습니다. 검증 단계에서는 결과를 보고하기 전에 코드와 대조하여 확인합니다.

10 Code Review는 리서치 프리뷰 상태이며 [Team 및 Enterprise](https://claude.ai/admin-settings/claude-code) 구독에서 사용 가능합니다. [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화되었거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직에서는 사용할 수 없으며, Anthropic의 BAA 적용 대상이 아닙니다. 다른 플랜에서는 `/code-review` 명령으로 [로컬에서 diff 검토](#review-a-diff-locally)할 수 있습니다.

11</Note>

12 

13Code Review는 GitHub 풀 요청을 분석하고 문제를 발견한 코드 라인에 인라인 댓글로 결과를 게시합니다. 전문화된 에이전트 집합이 전체 코드베이스의 맥락에서 코드 변경 사항을 검토하여 논리 오류, 보안 취약점, 손상된 엣지 케이스 및 미묘한 회귀를 찾습니다.

14 

15결과는 심각도별로 태그가 지정되며 PR을 승인하거나 차단하지 않으므로 기존 검토 워크플로우는 그대로 유지됩니다. 리포지토리에 `CLAUDE.md` 또는 `REVIEW.md` 파일을 추가하여 Claude가 플래그하는 항목을 조정할 수 있습니다.

16 

17관리되는 서비스 대신 자신의 CI 인프라에서 Claude를 실행하려면 [GitHub Actions](/docs/ko/github-actions) 또는 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 참조하십시오. 자체 호스팅 GitHub 인스턴스의 리포지토리의 경우 [GitHub Enterprise Server](/docs/ko/github-enterprise-server)를 참조하십시오.

18 

19이 페이지에서 다루는 내용:

20 

21* [검토 작동 방식](#how-reviews-work)

22* [설정](#set-up-code-review)

23* [`@claude review` 및 `@claude review always`를 사용한 수동 검토 트리거](#manually-trigger-reviews)

24* [`CLAUDE.md` 및 `REVIEW.md`를 사용한 검토 사용자 정의](#customize-reviews)

25* [가격](#pricing)

26* [실패한 실행 및 누락된 댓글 문제 해결](#troubleshooting)

27* [로컬에서 diff 검토](#review-a-diff-locally) - `/code-review` 명령 사용

28 

29<h2 id="how-reviews-work">

30 검토 작동 방식

31</h2>

32 

33관리자가 조직에 대해 Code Review를 [활성화](#set-up-code-review)하면 리포지토리의 구성된 동작에 따라 PR이 열릴 때, 모든 푸시 시 또는 수동으로 요청할 때 검토가 트리거됩니다. PR에서 `@claude review`를 [댓글로 작성](#manually-trigger-reviews)하면 모든 모드에서 검토가 시작됩니다.

34 

35검토가 실행되면 여러 에이전트가 Anthropic 인프라에서 병렬로 diff 및 주변 코드를 분석합니다. 각 에이전트는 다른 클래스의 문제를 찾고, 검증 단계에서 후보를 실제 코드 동작과 비교하여 거짓 양성을 필터링합니다. 결과는 중복 제거되고 심각도별로 순위가 지정되며 문제가 발견된 특정 라인에 인라인 댓글로 게시됩니다. 문제가 발견되지 않으면 Code Review는 GitHub 확인 실행을 업데이트하여 문제가 감지되지 않았음을 표시합니다. Claude는 또한 PR에 짧은 확인 댓글을 게시할 수 있습니다.

36 

37검토는 PR 크기 및 복잡도에 따라 비용이 증가하며 평균 20분 내에 완료됩니다. 관리자는 [분석 대시보드](#view-usage)를 통해 검토 활동 및 지출을 모니터링할 수 있습니다.

38 

39<h3 id="severity-levels">

40 심각도 수준

41</h3>

42 

43각 결과는 심각도 수준으로 태그가 지정됩니다:

44 

45| 마커 | 심각도 | 의미 |

46| :- | :- | :- |

47| 🔴 | Important | 병합 전에 수정해야 하는 버그 |

48| 🟡 | Nit | 경미한 문제, 수정할 가치가 있지만 차단하지는 않음 |

49| 🟣 | Pre-existing | 코드베이스에 존재하지만 이 PR에서 도입되지 않은 버그 |

50 

51결과에는 확장 가능한 **이 항목이 플래그된 이유** 섹션이 포함되어 있으므로 Claude가 문제를 플래그한 이유와 문제를 검증한 방법을 읽을 수 있습니다.

52 

53<h3 id="rate-and-reply-to-findings">

54 결과에 대한 평가 및 응답

55</h3>

56 

57Claude의 각 검토 댓글은 이미 👍 및 👎가 첨부되어 있으므로 두 버튼 모두 GitHub UI에 나타나 한 번의 클릭으로 평가할 수 있습니다. 결과가 유용했으면 👍을 클릭하고 잘못되었거나 노이즈가 많으면 👎를 클릭합니다. Anthropic은 PR이 병합된 후 반응 개수를 수집하고 이를 사용하여 검토자를 조정합니다. 반응은 재검토를 트리거하거나 PR의 어떤 것도 변경하지 않습니다.

58 

59인라인 댓글에 응답해도 Claude가 응답하거나 PR을 업데이트하도록 프롬프트하지 않습니다. 결과에 대해 조치하려면 코드를 수정하고 푸시합니다. PR이 푸시 트리거 검토에 구독되어 있으면 다음 실행이 문제가 수정되었을 때 스레드를 해결합니다. 푸시하지 않고 새로운 검토를 요청하려면 [최상위 PR 댓글](#manually-trigger-reviews)로 `@claude review`를 댓글로 작성합니다.

60 

61결과를 코드 변경 없이 해제하려면 해당 스레드를 해결합니다. 응답하는 것은 해제하지 않습니다.

62 

63<h3 id="check-run-output">

64 확인 실행 출력

65</h3>

66 

67인라인 검토 댓글 외에도 각 검토는 CI 확인과 함께 나타나는 **Claude Code Review** 확인 실행을 채웁니다. **Details** 링크를 확장하여 심각도별로 정렬된 모든 결과의 요약을 한 곳에서 확인합니다:

68 

69| 심각도 | 파일:라인 | 문제 |

70| - | - | - |

71| 🔴 Important | `src/auth/session.ts:142` | 토큰 새로고침이 로그아웃과 경쟁하여 오래된 세션이 활성 상태로 유지됨 |

72| 🟡 Nit | `src/auth/session.ts:88` | `parseExpiry`가 잘못된 입력에서 자동으로 0을 반환함 |

73 

74각 결과는 **Files changed** 탭의 주석으로도 나타나며 관련 diff 라인에 직접 표시됩니다. Important 결과는 빨간색 마커로 렌더링되고, nit은 노란색 경고로, 기존 버그는 회색 공지로 렌더링됩니다. 주석과 심각도 테이블은 인라인 검토 댓글과 독립적으로 확인 실행에 기록되므로 GitHub가 이동한 라인의 인라인 댓글을 거부하더라도 사용 가능한 상태로 유지됩니다.

75 

76확인 실행은 항상 중립적인 결론으로 완료되므로 분기 보호 규칙을 통해 병합을 차단하지 않습니다. Code Review 결과에 따라 병합을 제어하려면 자신의 CI에서 확인 실행 출력에서 심각도 분석을 읽으십시오. Details 텍스트의 마지막 라인은 워크플로우가 `gh` 및 jq로 구문 분석할 수 있는 기계 판독 가능한 댓글입니다. 확인 실행 ID를 찾으려면 커밋의 확인 실행을 `gh api repos/OWNER/REPO/commits/<commit-sha>/check-runs --jq '.check_runs[] | {id, name}'`로 나열하고 `Claude Code Review` 실행의 `id`를 가져옵니다. `OWNER`, `REPO`, `CHECK_RUN_ID`를 리포지토리 소유자, 리포지토리 이름, 해당 ID로 바꿉니다:

77 

78```bash theme={null}

79gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \

80 --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

81```

82 

83이는 심각도별 개수가 포함된 JSON 객체를 반환합니다(예: `{"normal": 2, "nit": 1, "pre_existing": 0}`). `normal` 키는 Important 결과의 개수를 보유합니다. 0이 아닌 값은 Claude가 병합 전에 수정할 가치가 있는 버그를 발견했음을 의미합니다.

84 

85<h3 id="what-code-review-checks">

86 Code Review가 확인하는 항목

87</h3>

88 

89기본적으로 Code Review는 정확성에 중점을 두고 있습니다: 형식 기본 설정이나 누락된 테스트 범위가 아닌 프로덕션을 중단할 버그입니다. 리포지토리에 [지침 파일을 추가](#customize-reviews)하여 확인하는 항목을 확장할 수 있습니다.

90 

91<h2 id="set-up-code-review">

92 Code Review 설정

93</h2>

94 

95관리자는 조직에 대해 한 번 Code Review를 활성화하고 포함할 리포지토리를 선택합니다.

96 

97<Steps>

98 <Step title="Claude Code 관리자 설정 열기">

99 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)로 이동하여 Code Review 섹션을 찾습니다. Claude 조직에서 Owner 또는 Primary Owner 역할이 필요하며 GitHub 조직에 GitHub 앱을 설치할 수 있는 권한이 필요합니다.

100 </Step>

101 

102 <Step title="설정 시작">

103 **Setup**을 클릭합니다. 이렇게 하면 GitHub 앱 설치 흐름이 시작됩니다.

104 </Step>

105 

106 <Step title="Claude GitHub 앱 설치">

107 프롬프트를 따라 Claude GitHub 앱을 설치합니다. GitHub 조직을 선택하여 검토하려는 리포지토리를 소유하고, 앱이 액세스할 수 있는 리포지토리를 선택하고, 요청된 권한을 승인합니다.

108 

109 PR을 검토하기 위해 Claude는 앱의 읽기 액세스를 통해 리포지토리 콘텐츠를 읽고, 쓰기 액세스를 통해 PR 및 확인에 댓글과 [확인 실행](#check-run-output)을 게시합니다. 설치 중에 [GitHub Actions](/docs/ko/github-actions)와 같은 다른 Claude 기능에서 공유하는 더 광범위한 권한 집합을 부여합니다. 전체 목록은 [GitHub 앱 권한](/docs/ko/github-actions#github-app-permissions)을 참조하십시오.

110 </Step>

111 

112 <Step title="리포지토리 선택">

113 Code Review를 활성화할 리포지토리를 선택합니다. 리포지토리가 보이지 않으면 설치 중에 Claude GitHub 앱에 액세스 권한을 부여했는지 확인하십시오. 나중에 더 많은 리포지토리를 추가할 수 있습니다.

114 </Step>

115 

116 <Step title="리포지토리별 검토 트리거 설정">

117 설정이 완료되면 Code Review 섹션에 리포지토리가 테이블에 표시됩니다. 각 리포지토리에 대해 **Review Behavior** 드롭다운을 사용하여 검토가 실행되는 시기를 선택합니다:

118 

119 * **Once after PR creation**: PR이 열리거나 검토 준비 완료로 표시될 때 한 번 검토가 실행됩니다

120 * **After every push**: PR 브랜치에 대한 모든 푸시에서 검토가 실행되어 PR이 진화함에 따라 새로운 문제를 감지하고 플래그된 문제를 수정할 때 스레드를 자동으로 해결합니다

121 * **Manual**: PR을 열거나 푸시해도 검토가 시작되지 않습니다. [`@claude review`](#manually-trigger-reviews)를 댓글로 작성하여 검토를 요청하거나, `@claude review always`를 작성하여 이후 푸시에 대한 검토에 PR을 구독합니다

122 

123 어떤 옵션을 선택하든 Claude는 [포크에서 PR을 검토](#review-pull-requests-from-forks)할 때만 누군가 `@claude review`를 댓글로 작성합니다.

124 

125 모든 푸시에서 검토하면 가장 많은 검토가 실행되고 비용이 가장 많이 듭니다. 수동 모드는 특정 PR을 검토에 옵트인하려는 트래픽이 많은 리포지토리나 PR이 준비될 때까지만 검토를 시작하려는 경우에 유용합니다.

126 </Step>

127</Steps>

128 

129리포지토리 테이블은 최근 활동을 기반으로 각 리포지토리의 평균 검토 비용도 표시합니다. 행 작업 메뉴를 사용하여 리포지토리별로 Code Review를 켜거나 끄거나 리포지토리를 완전히 제거할 수 있습니다.

130 

131설정을 확인하려면 테스트 PR을 열어보십시오. 자동 트리거를 선택한 경우 **Claude Code Review**라는 확인 실행이 몇 분 내에 나타납니다. 수동을 선택한 경우 PR에서 `@claude review`를 댓글로 작성하여 첫 번째 검토를 시작합니다. 확인 실행이 나타나지 않으면 리포지토리가 관리자 설정에 나열되어 있고 Claude GitHub 앱이 액세스할 수 있는지 확인하십시오.

132 10 

133<h2 id="manually-trigger-reviews">11결과는 [심각도](/docs/ko/code-review-pull-requests#severity-levels)별로 순위가 매겨져 해당 라인에 인라인 댓글로 게시되며, 풀 리퀘스트에는 요약과 확인 실행(check run)이 함께 표시됩니다. 리뷰는 풀 리퀘스트를 승인하거나 차단하지 않으므로 병합 결정은 팀에 그대로 남습니다.

134 수동으로 검토 트리거

135</h2>

136 

137댓글 명령은 요청 시 검토를 시작합니다. 이들은 리포지토리의 구성된 트리거와 관계없이 작동하므로 수동 모드에서 특정 PR을 검토에 옵트인하거나 다른 모드에서 즉시 재검토를 받을 수 있습니다.

138 12 

139| 명령 | 수행 작업 |13<img src="https://mintcdn.com/claude-code/gLJVaPQEgKC8ZyUD/images/code-review-pipeline.svg?fit=max&auto=format&n=gLJVaPQEgKC8ZyUD&q=85&s=0351c96df9efa3105172eb00a672f130" className="dark:hidden" alt="네 단계로 이루어진 리뷰 다이어그램. GitHub의 풀 리퀘스트가 Anthropic 인프라에서 병렬로 탐색하는 여러 에이전트에게 전달됩니다. 검증 단계에서 거짓 양성을 제거하고, 남은 결과는 중복 제거 후 심각도별로 순위가 매겨지며, 리뷰는 인라인 댓글, 요약 및 확인 실행을 GitHub에 다시 게시합니다." width="760" height="300" data-path="images/code-review-pipeline.svg" />

140| :- | :- |

141| `@claude review` | 향후 푸시에 PR을 구독하지 않고 단일 검토를 시작합니다 |

142| `@claude review always` | 검토를 시작하고 앞으로 푸시 트리거 검토에 PR을 구독합니다 |

143| `@claude review once` | `@claude review`와 동일합니다: 구독하지 않고 단일 검토를 시작합니다 |

144 14 

145수동 모드로 설정된 리포지토리의 높은 우선순위 PR과 같이 PR에 대한 모든 후속 푸시가 새로운 검토를 시작하기를 원할 때 `@claude review always`를 사용합니다. 기본 명령이 PR을 구독하지 않으므로 이후 푸시가 검토를 트리거하는지 여부를 변경하지 않고 일회성 두 번째 의견을 요청할 수 있습니다.15<img src="https://mintcdn.com/claude-code/gLJVaPQEgKC8ZyUD/images/code-review-pipeline-dark.svg?fit=max&auto=format&n=gLJVaPQEgKC8ZyUD&q=85&s=9cf26bde98f4e999d0d9ff5bf5bdff40" className="hidden dark:block" alt="네 단계로 이루어진 리뷰 다이어그램. GitHub의 풀 리퀘스트가 Anthropic 인프라에서 병렬로 탐색하는 여러 에이전트에게 전달됩니다. 검증 단계에서 거짓 양성을 제거하고, 남은 결과는 중복 제거 후 심각도별로 순위가 매겨지며, 리뷰는 인라인 댓글, 요약 및 확인 실행을 GitHub에 다시 게시합니다." width="760" height="300" data-path="images/code-review-pipeline-dark.svg" />

146 16 

147<Note>17<Note>

148 2026년 7월 업데이트 이전에는 `@claude review`가 PR을 푸시 트리거 검토에 구독했습니다. 해당 동작에 의존했다면 대신 `@claude review always`를 댓글로 작성하세요. `@claude review once`는 여전히 작동하며 기본 명령과 동일하게 동작합니다.18 Code Review는 AI를 사용하여 코드를 리뷰하므로 버그, 보안 취약점 또는 기타 문제를 놓칠 수 있습니다. 결과가 없는 리뷰가 코드에 오류가 없거나 안전하다는 것을 의미하지는 않습니다.

149</Note>19</Note>

150 20 

151이러한 명령 중 하나가 검토를 트리거하려면:21<span id="review-a-diff-locally" />

152 

153* 최상위 PR 댓글로 게시하고 diff 라인의 인라인 댓글로는 게시하지 않습니다

154* 댓글의 시작 부분에 명령을 입력하고, `once` 또는 `always`를 명령의 나머지 부분과 같은 라인에 입력합니다

155* 리포지토리에 대한 쓰기, 유지 관리 또는 관리자 권한이 있어야 합니다

156* PR은 열려 있어야 합니다

157 

158자동 트리거와 달리 수동 트리거는 명시적 요청이 초안 상태와 관계없이 지금 검토를 원한다는 신호이므로 초안 PR에서 실행됩니다.

159 

160해당 PR에서 검토가 이미 실행 중인 경우 요청은 진행 중인 검토가 완료될 때까지 대기열에 추가됩니다. PR의 확인 실행을 통해 진행 상황을 모니터링할 수 있습니다.

161 

162<h3 id="review-pull-requests-from-forks">

163 포크에서 풀 요청 검토

164</h3>

165 

166Claude는 리포지토리의 **검토 동작** 설정과 관계없이 포크의 풀 요청을 자동으로 검토하지 않습니다. 검토를 시작하려면 풀 요청에 `@claude review`를 댓글로 작성하세요. [댓글 명령의 요구 사항](#manually-trigger-reviews)은 여전히 적용되며 필요한 쓰기 액세스는 포크가 아닌 기본 리포지토리에 대한 것입니다.

167 22 

168포크 풀 요청의 다른 검토를 받으려면 새로운 `@claude review` 댓글을 게시하세요. `@claude review always`도 작동하지만 나중의 푸시에 대한 검토에 풀 요청을 구독하지 않습니다. 댓글 명령 외에는 포크 풀 요청에 대한 검토를 시작하지 않습니다:23Code Review를 켜려면 Claude 조직의 Owner가 [Code Review 설정](/docs/ko/code-review-setup)을 따릅니다. Claude는 이 서비스 없이도 코드를 리뷰할 수 있습니다. 모든 플랜에서 Claude Code 세션에서 [`/code-review`](/docs/ko/code-review-local)를 실행하거나, [모든 옵션을 비교](#compare-ways-to-get-a-review)해 보십시오.

169 24 

170* 확인 실행에서 **다시 실행**을 클릭해도 검토를 시작하지 않습니다25<h2 id="availability">

171* 새 커밋을 푸시해도 검토를 시작하지 않습니다. **모든 푸시 후**로 설정된 리포지토리에서도 마찬가지입니다26 사용 가능 여부

172 

173<h2 id="customize-reviews">

174 검토 사용자 정의

175</h2>27</h2>

176 28 

177Code Review는 리포지토리에서 두 개의 파일을 읽어 플래그할 항목을 안내합니다. 이들은 검토에 영향을 미치는 강도가 다릅니다:29Code Review를 설정하기 전에 조직이 자격 요건을 충족하는지 확인하십시오:

178 

179* **`CLAUDE.md`**: Claude Code가 검토뿐만 아니라 모든 작업에 사용하는 공유 프로젝트 지침입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고 새로 도입된 위반을 nit으로 플래그합니다.

180* **`REVIEW.md`**: 검토 전용 지침으로 검토 파이프라인의 에이전트가 결과를 찾고 검증하며 에이전트가 결과를 순위 지정하고 보고할 때 참조합니다. 이를 사용하여 팀이 플래그하려는 항목, 심각도 및 결과 보고 방식을 지정합니다.

181 

182<h3 id="claude-md">

183 CLAUDE.md

184</h3>

185 

186Code Review는 리포지토리의 `CLAUDE.md` 파일을 읽고 새로 도입된 위반을 [nit 수준](#severity-levels) 결과로 처리합니다. 이는 양방향으로 작동합니다: PR이 `CLAUDE.md` 문을 오래된 것으로 만드는 방식으로 코드를 변경하면 Claude는 문서도 업데이트해야 한다고 플래그합니다.

187 

188Claude는 디렉토리 계층 구조의 모든 수준에서 `CLAUDE.md` 파일을 읽으므로 하위 디렉토리의 `CLAUDE.md`의 규칙은 해당 경로 아래의 파일에만 적용됩니다. `CLAUDE.md` 작동 방식에 대한 자세한 내용은 [메모리 설명서](/docs/ko/memory)를 참조하십시오.

189 30 

190일반 Claude Code 세션에 적용하지 않으려는 검토 전용 지침의 경우 대신 [`REVIEW.md`](#review-md)를 사용하십시오.31* **플랜**: [Team 및 Enterprise](/docs/ko/feature-availability)

191 32* **코드 호스트**: [GitHub Enterprise Server](/docs/ko/github-enterprise-server) 및 데이터 레지던시가 적용된 GitHub Enterprise Cloud를 포함하여 GitHub에 호스팅된 저장소. 데이터 레지던시의 경우 Owner가 [GitHub Enterprise Server 관리자 설정](/docs/ko/github-enterprise-server#admin-setup)을 따르고 엔터프라이즈의 `ghe.com` 호스트 이름을 입력해야 합니다.

192<h3 id="review-md">33* **데이터 보존**: Code Review는 [Zero Data Retention](/docs/ko/zero-data-retention)이 활성화되었거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직에서는 사용할 수 없으며, Anthropic의 Business Associate Agreement(BAA) 적용 대상이 아닙니다.

193 REVIEW\.md34* **암호화 키**: Code Review는 아직 고객 관리형 암호화 키(CMEK)를 사용하는 조직에서 사용할 수 없습니다.

194</h3>35* **클라우드 제공업체**: 개발자가 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 통해 Claude Code를 사용하더라도 이러한 플랜 중 하나의 Claude 조직이 필요합니다

195 36 

196`REVIEW.md`는 리포지토리 루트의 파일로 Code Review를 리포지토리에 맞게 조정합니다. 검토 파이프라인에서 결과를 찾고 검증하는 에이전트는 Code Review의 기본 검토 지침과 함께 리포지토리의 검토 지침으로 그 내용을 받으며, 결과를 순위 지정하고 보고하는 에이전트는 심각도를 결정하고 검토를 작성하기 전에 이를 참조합니다.37<h2 id="set-up-and-use-code-review">

197 38 Code Review 설정 및 사용

198`REVIEW.md`에 적용하려는 규칙을 직접 입력합니다.

199 

200<h4 id="what-you-can-tune">

201 조정할 수 있는 항목

202</h4>

203 

204`REVIEW.md`는 자유 형식 마크다운이므로 검토 지침으로 표현할 수 있는 모든 것이 범위 내입니다. 아래 패턴은 실제로 가장 큰 영향을 미칩니다.

205 

206**심각도**: 리포지토리에 대해 🔴 Important가 의미하는 바를 재정의합니다. 기본 보정은 프로덕션 코드를 대상으로 합니다. 문서 리포지토리, 구성 리포지토리 또는 프로토타입은 훨씬 더 좁은 정의를 원할 수 있습니다. Important인 결과 클래스와 최대 Nit인 결과 클래스를 명시적으로 명시합니다. 다른 방향으로도 확대할 수 있습니다. 예를 들어 기본 nit이 아닌 Important로 `CLAUDE.md` 위반을 처리합니다.

207 

208**Nit 볼륨**: 단일 검토가 게시하는 🟡 Nit 댓글의 수를 제한합니다. 산문 및 구성 파일은 영원히 다듬어질 수 있습니다. "최대 5개의 nit을 보고하고 나머지를 요약에 개수로 언급"과 같은 제한은 검토를 실행 가능하게 유지합니다.

209 

210**규칙 건너뛰기**: Claude가 결과를 게시하지 않아야 하는 경로, 분기 패턴 및 결과 카테고리를 나열합니다. 일반적인 후보는 생성된 코드, lockfile, 공급된 종속성 및 기계 작성 분기이며, linting 또는 맞춤법 검사와 같이 CI가 이미 적용하는 모든 것입니다. 완전한 정밀 검사를 보장하지 않지만 일부 검토를 보장하는 경로의 경우 완전히 건너뛰는 대신 더 높은 기준을 설정합니다: "`scripts/`에서는 거의 확실하고 심각한 경우에만 보고합니다."

211 

212**리포지토리별 확인**: 모든 PR에서 플래그하려는 규칙을 추가합니다. 예: "새 API 경로에는 통합 테스트가 있어야 합니다." `REVIEW.md`가 모든 결과 찾기 및 검증 에이전트에 직접 도달하기 때문에 이들은 긴 `CLAUDE.md`의 동일한 규칙보다 더 안정적으로 도착합니다.

213 

214**검증 기준**: 결과 클래스가 게시되기 전에 증거를 요구합니다. 예를 들어 "동작 주장은 명명에서의 추론이 아닌 소스의 `file:line` 인용이 필요합니다"는 그렇지 않으면 작성자에게 왕복을 비용으로 하는 거짓 양성을 줄입니다.

215 

216**재검토 수렴**: PR이 이미 검토되었을 때 Claude가 어떻게 작동해야 하는지 알려줍니다. "첫 번째 검토 후 새로운 nit을 억제하고 Important 결과만 게시"와 같은 규칙은 한 줄 수정이 스타일만으로 7라운드에 도달하는 것을 방지합니다.

217 

218**요약 형태**: 검토 본문이 `2 factual, 4 style`과 같은 한 줄 집계로 시작하도록 요청하고 그것이 경우일 때 "factual 문제 없음"으로 시작하도록 요청합니다. 작성자는 세부 사항 전에 작업의 형태를 알고 싶어합니다.

219 

220<h4 id="example">

221 예시

222</h4>

223 

224이 `REVIEW.md`는 백엔드 서비스의 심각도를 재보정하고, nit을 제한하고, 생성된 파일을 건너뛰고, 리포지토리별 확인을 추가합니다.

225 

226```markdown theme={null}

227# 검토 지침

228 

229## Important가 여기서 의미하는 바

230 

231동작을 중단하거나 데이터를 유출하거나 롤백을 차단할 결과에 대해 Important를 예약합니다: 잘못된 논리, 범위가 지정되지 않은 데이터베이스 쿼리, 로그 또는 오류 메시지의 PII, 그리고 역호환되지 않는 마이그레이션입니다. 스타일, 명명 및 리팩토링 제안은 최대 Nit입니다.

232 

233## Nit 제한

234 

235검토당 최대 5개의 Nit을 보고합니다. 더 많이 발견한 경우 인라인으로 게시하는 대신 요약에서 "plus N similar items"라고 말합니다. 발견한 모든 것이 Nit인 경우 "No blocking issues"로 요약을 시작합니다.

236 

237## 보고하지 않음

238 

239- CI가 이미 적용하는 모든 것: lint, 형식, 타입 오류

240- `src/gen/` 아래의 생성된 파일 및 모든 `*.lock` 파일

241- 의도적으로 프로덕션 규칙을 위반하는 테스트 전용 코드

242 

243## 항상 확인

244 

245- 새 API 경로에는 통합 테스트가 있습니다

246- 로그 라인에 이메일 주소, 사용자 ID 또는 요청 본문이 포함되지 않습니다

247- 데이터베이스 쿼리는 호출자의 테넌트로 범위가 지정됩니다

248```

249 

250<h4 id="keep-it-focused">

251 초점 유지

252</h4>

253 

254길이는 비용이 있습니다: 긴 `REVIEW.md`는 가장 중요한 규칙을 희석합니다. 검토 동작을 변경하는 지침으로 유지하고 일반 프로젝트 컨텍스트는 `CLAUDE.md`에 남겨둡니다.

255 

256<h2 id="view-usage">

257 사용량 보기

258</h2>39</h2>

259 40 

260[claude.ai/analytics/code-review](https://claude.ai/analytics/code-review)로 이동하여 조직 전체의 Code Review 활동을 확인합니다. 대시보드는 다음을 표시합니다:41<span id="set-up-code-review" />

261 42 

262| 섹션 | 표시 내용 |43<span id="pricing" />

263| :- | :- |

264| PRs reviewed | 선택한 시간 범위 동안 검토된 풀 요청의 일일 개수 |

265| Code Review cost | 이번 달 현재까지의 Code Review 지출 |

266| Feedback | 개발자가 문제를 해결하여 자동으로 해결된 검토 댓글의 개수 |

267| Repository breakdown | 저장소별로 검토된 PR 개수, 해결된 댓글 개수, 리뷰 실행 횟수와 함께 추정 비용 및 PR별 보기 |

268 44 

269Code Review cost 카드는 현재 월이 선택된 경우에만 금액을 표시합니다. 분석의 비용 수치는 청구서와 다를 수 있습니다. Repository breakdown 비용은 할인이나 크레딧이 적용되기 전의 정가 기준으로 추정되며, Claude가 풀 리퀘스트에 게시한 리뷰만 포함합니다. 청구서와 정확히 일치하는 지출은 Anthropic 청구서를 참조하십시오.45<span id="manually-trigger-reviews" />

270 46 

271<h2 id="pricing">47<span id="customize-reviews" />

272 가격

273</h2>

274 

275Code Review는 토큰 사용량을 기반으로 청구됩니다. 각 검토는 평균 \$15-25의 비용이 소요되며, PR 크기, 코드베이스 복잡도 및 검증이 필요한 문제의 수에 따라 확장됩니다. Code Review 사용량은 [사용량 크레딧](https://support.claude.com/ko/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 별도로 청구되며 계획에 포함된 사용량에 포함되지 않습니다.

276 

277선택한 검토 트리거는 총 비용에 영향을 미칩니다:

278 

279* **PR 생성 후 한 번**: PR당 한 번 실행됩니다

280* **모든 푸시 후**: 각 푸시에서 실행되어 푸시 수만큼 비용이 곱해집니다

281* **수동**: 열린 PR이나 푸시에서 자동으로 검토가 실행되지 않으므로 누군가 요청한 검토에서만 비용이 발생합니다

282 48 

283PR 생성 후 한 번 또는 수동 모드에서 `@claude review always` [댓글을 작성](#manually-trigger-reviews)하면 PR이 푸시 트리거 검토에 옵트인되므로 해당 댓글 이후 푸시당 추가 비용이 발생합니다. 모든 푸시 후 모드에서는 푸시가 이미 검토를 트리거하므로 구독이 푸시당 비용을 변경하지 않습니다. `@claude review`를 댓글로 작성하면 향후 푸시에 구독하지 않고 단일 검토를 실행합니다. Claude는 [포크에서 풀 요청](#review-pull-requests-from-forks)을 누군가 `@claude review`를 댓글로 작성할 때만 검토하므로, 포크 풀 요청은 어떤 모드에서도 푸시당 비용이 발생하지 않습니다.49<span id="troubleshooting" />

284 50 

285비용은 조직이 다른 Claude Code 기능에 Amazon Bedrock 또는 Google Cloud의 Agent Platform을 사용하는지 여부와 관계없이 Anthropic 청구서에 나타납니다. Code Review의 월간 지출 한도를 설정하려면 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)로 이동하여 Claude Code Review 서비스의 한도를 구성합니다.51필요한 작업에 맞는 페이지를 선택하십시오:

286 52 

287지출을 모니터링하려면 [분석 대시보드](#view-usage)를 사용합니다.53<CardGroup cols={2}>

54 <Card title="Code Review 설정" icon="toggle-on" href="/docs/ko/code-review-setup">

55 요구 사항을 확인하고, Claude GitHub App을 설치하고, 저장소, 리뷰 수준 및 리뷰 실행 시기를 선택합니다

56 </Card>

288 57 

289<h2 id="troubleshooting">58 <Card title="Code Review 사용자 정의" icon="sliders" href="/docs/ko/code-review-customize">

290 문제 해결59 저장소의 `REVIEW.md` 및 `CLAUDE.md` 파일로 플래그되는 항목을 조정합니다

291</h2>60 </Card>

292 

293검토 실행은 최선의 노력입니다. 실패한 실행은 PR을 차단하지 않습니다. Code Review는 중단된 일부 검토를 자동으로 재시도합니다. 이 섹션에서는 검토를 다시 실행하는 방법과 확인 실행이 찾을 수 없는 문제를 보고할 때 어디를 봐야 하는지 다룹니다.

294 61 

295<h3 id="retrigger-a-failed-or-timed-out-review">62 <Card title="풀 리퀘스트에서 리뷰 읽기 및 요청" icon="code-pull-request" href="/docs/ko/code-review-pull-requests">

296 실패하거나 시간 초과된 검토 재트리거63 결과와 심각도를 읽고, 댓글로 다른 리뷰를 요청합니다

297</h3>64 </Card>

298 65 

299검토가 실패하거나 시간 제한을 초과하면 확인 실행이 **Code review failed** 또는 **Code review timed out** 같은 제목으로 완료됩니다. 결론은 여전히 중립적이므로 병합을 차단하는 것은 없습니다. 확인 실행의 요약에서 커밋의 새로운 검토가 자동으로 대기열에 추가되었다고 말하지 않으면 검토를 직접 다시 실행하십시오.66 <Card title="Code Review 문제 해결" icon="wrench" href="/docs/ko/code-review-troubleshooting">

67 시작되지 않았거나, 실패했거나, 예산 때문에 건너뛴 리뷰를 해결합니다

68 </Card>

300 69 

301검토를 다시 실행하려면 PR에서 `@claude review`를 댓글로 작성하십시오. 이렇게 하면 PR을 향후 푸시에 구독하지 않고 새로운 검토를 시작합니다. PR이 [포크에서](#review-pull-requests-from-forks) 나온 것이 아니면 GitHub의 Checks 탭에서 **Claude Code Review** 확인 옆의 **Re-run**을 클릭할 수 있습니다. 재실행도 PR을 구독하지 않고 새로운 검토를 시작합니다.70 <Card title="Code Review 비용 및 사용량" icon="chart-line" href="/docs/ko/code-review-costs">

71 리뷰 청구 방식을 확인하고, 지출을 추정하고, 월간 지출 한도를 설정하고, 리뷰 활동을 추적합니다

72 </Card>

73</CardGroup>

302 74 

303<h3 id="review-didn’t-run-and-the-pr-shows-a-budget-message">75<h2 id="how-reviews-work">

304 검토가 실행되지 않았고 PR이 예산 메시지를 표시합니다76 리뷰 작동 방식

305</h3>

306 

307조직의 Code Review 월간 지출 한도에 도달하거나 사용량 크레딧 잔액이 소진되면 Code Review는 검토를 건너뛰고 PR에 단일 댓글을 게시합니다. 댓글과 확인 실행 카드 모두 원인을 명시하고, 관리자가 문제를 해결할 수 있는 관리자 페이지로 연결됩니다:

308 

309* **지출 한도 도달**: 검토는 다음 청구 기간의 시작 시 재개되거나 관리자가 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)에서 한도를 높이면 즉시 재개됩니다

310* **사용량 크레딧 소진**: 관리자가 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)에서 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 추가하면 검토가 재개됩니다

311 

312<h3 id="find-issues-that-aren’t-showing-as-inline-comments">

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

314</h3>

315 

316확인 실행 제목이 문제가 발견되었다고 말하지만 diff에서 인라인 검토 댓글을 보지 못하면 결과가 표시되는 다른 위치를 확인하십시오:

317 

318* **Check run Details**: Checks 탭의 Claude Code Review 확인 옆에 있는 **Details**를 클릭합니다. 심각도 테이블은 인라인 댓글이 수락되었는지 여부와 관계없이 파일, 라인 및 요약과 함께 모든 결과를 나열합니다.

319* **Files changed annotations**: PR의 **Files changed** 탭을 엽니다. 결과는 검토 댓글과 별도로 diff 라인에 직접 첨부된 주석으로 렌더링됩니다.

320* **Review body**: 검토가 실행 중인 동안 PR을 푸시한 경우 일부 결과는 현재 diff에 더 이상 존재하지 않는 라인을 참조할 수 있습니다. 이들은 인라인 댓글이 아닌 검토 본문 텍스트의 **Additional findings** 제목 아래에 나타납니다.

321 

322<h2 id="review-a-diff-locally">

323 로컬에서 diff 검토

324</h2>77</h2>

325 78 

326[`/code-review` 명령](/docs/ko/commands)은 GitHub 앱을 설치하지 않고 터미널에서 diff를 검토합니다. 정확성 버그를 보고합니다. 모델과 effort 수준에 따라 검토에는 재사용, 단순화 및 효율성 정리도 포함됩니다.79<span id="what-code-review-checks" />

327 80 

328`/review`는 `/code-review`의 별칭입니다. v2.1.223 이전에는 GitHub pull request의 단일 패스, 읽기 전용 검토를 실행하는 별도의 명령이었습니다.81기본적으로 Code Review는 정확성에 중점을 둡니다. 형식 선호나 누락된 테스트 범위가 아니라 프로덕션을 중단시킬 버그입니다. 플래그되는 항목을 변경하려면 저장소에 [지침 파일을 추가](/docs/ko/code-review-customize)하십시오.

329 82 

330<Steps>83리뷰는 Anthropic 인프라에서 네 단계로 실행됩니다:

331 <Step title="/code-review 실행">

332 작업 중인 세션에서 다음 명령을 실행합니다:

333 84 

334 ```text theme={null}851. **찾기**: 여러 에이전트가 diff와 주변 코드를 병렬로 검사합니다.

335 /code-review862. **검증**: 검증 단계에서 후보 결과를 코드와 대조하여 확인하고 거짓 양성을 걸러냅니다.

336 ```873. **순위 지정**: 남은 결과는 중복 제거된 후 심각도별로 순위가 매겨집니다.

884. **게시**: 리뷰가 풀 리퀘스트에 결과를 게시합니다.

337 89 

338 이 명령은 업스트림보다 앞선 브랜치의 커밋과 커밋되지 않은 변경 사항을 검토하므로, 보고할 내용이 있으려면 브랜치에서 작업하거나 작업 트리에서 작업해야 합니다. 다른 항목을 검토하려면 대상을 전달합니다: 파일 경로, PR 번호, 브랜치 이름 또는 `main...my-feature`와 같은 ref 범위입니다.90각 리뷰는 풀 리퀘스트에 다음을 남깁니다:

339 91 

340 다음 플래그를 추가할 수도 있습니다:92* **결과**: 해당 라인의 인라인 댓글과 리뷰 본문의 요약

93* **확인 실행**: 이름은 **Claude Code Review**이며, 결과가 [세부 정보](/docs/ko/code-review-pull-requests#check-run-output)에 나열됩니다. 확인 실행은 실패로 종료되지 않습니다.

94* **아무것도 찾지 못한 경우**: 확인 실행의 제목이 **Code review found no issues**로 표시되며, Claude가 풀 리퀘스트에 같은 내용의 짧은 메모를 게시합니다

341 95 

342 * `--fix`: 검토 후 결과를 작업 트리에 적용합니다96Code Review는 리뷰가 실행될 Claude 모델을 선택하며, 관리자 설정에서는 모델 선택을 제공하지 않습니다. 리뷰를 더 철저하게 또는 덜 철저하게 하려면 [리뷰 수준](#review-levels)을 변경하십시오.

343 * `--comment`: GitHub 풀 리퀘스트에 인라인 댓글로 결과를 게시하거나, GitLab merge request에 단일 노트로 게시합니다

344 * `--post`: `github.com` 풀 리퀘스트의 `ultra` 클라우드 검토에서 시작 대화 상자에 완료된 결과를 PR에 게시하는 것을 미리 선택합니다. [풀 리퀘스트에 결과 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)를 참조하십시오. Claude Code v2.1.227 이상이 필요합니다

345 * `--max-findings <n>`, `--max-findings all` 또는 `--max-findings default`: 검토의 일반적인 제한 대신 최대 `n`개의 결과를 보고하거나, `all`을 사용하면 모든 결과를 보고합니다. 이후 검토는 `--max-findings default`를 전달할 때까지 입력한 값을 재사용합니다. Claude Code v2.1.288 이상이 필요합니다

346 97 

347 GitLab merge request에 대해 `--comment`를 전달하면, Claude Code는 GitLab의 `glab` CLI를 통해 결과를 게시합니다. Claude Code v2.1.257 이상이 필요합니다. `glab`이 설치되지 않은 경우, Claude는 대신 터미널에 결과를 출력합니다.98Owner가 Code Review를 켜면 각 저장소에는 [리뷰 실행 시기](/docs/ko/code-review-setup#set-when-reviews-run)에 대한 설정이 있습니다. 풀 리퀘스트가 열릴 때 한 번, 모든 푸시 후, 또는 요청 시에만 실행됩니다. 어떤 설정이든 저장소에 대한 쓰기 권한이 있는 사용자는 풀 리퀘스트에 `@claude review`를 댓글로 작성하여 [리뷰를 시작](/docs/ko/code-review-pull-requests#comment-commands)할 수 있습니다.

348 99 

349 merge request를 URL 또는 `!123` 참조로 전달합니다. Claude Code는 체크아웃의 origin이 `gitlab.com`에 있을 때만 숫자 또는 브랜치 이름을 merge request로 취급합니다. 자체 관리 GitLab 인스턴스에서는 URL 또는 `!123` 형식으로 전달합니다.100<h3 id="review-levels">

350 </Step>101 리뷰 수준

351 

352 <Step title="계속 작업">

353 검토는 자체 컨텍스트 윈도우를 가진 백그라운드 [subagent](/docs/ko/sub-agents)로 실행되므로 대화를 채우지 않습니다. 검토가 완료되면 결과가 대화에 도착합니다.

354 </Step>

355 

356 <Step title="결과에 대해 조치">

357 Claude에게 검토에서 발견한 내용을 수정하도록 요청합니다. `--fix` 또는 `--comment`를 전달한 경우, 검토가 이미 결과를 적용하거나 게시했습니다.

358 </Step>

359</Steps>

360 

361Claude는 호스트 애플리케이션이 아래에 설명된 결과 목록을 요청하는 경우에도 두 가지 실행 모두에서 회신의 텍스트로 결과를 보고합니다:

362 

363* 터미널 세션에서, `/code-review`는 [forked subagent](/docs/ko/skills#run-skills-in-a-subagent)로 검토를 실행합니다

364* 텍스트 또는 JSON 출력이 있는 `-p` 실행에서

365 

366결과 목록을 요청하는 호스트 애플리케이션(예: [데스크톱 앱](/docs/ko/desktop#review-your-code))에서는, Claude가 대신 [`ReportFindings` 도구](/docs/ko/tools-reference)를 통해 검토의 결과를 보고합니다. Claude Code는 보고서를 결과 목록으로 렌더링하며, 각 항목은 파일 위치, 한 문장 요약 및 결과에 카테고리 태그가 있을 때 `correctness`와 같은 카테고리 태그를 표시합니다. 호스트 요청은 모든 effort 수준에서 적용되며 Claude Code v2.1.218 이상이 필요합니다.

367 

368Claude가 나중에 세션에서 보고된 결과를 수정할 때, 다시 보고하며, Claude Code는 업데이트된 결과 목록의 각 결과를 수정됨, 건너뜀 또는 변경 필요 없음으로 표시합니다.

369 

370<h3 id="what-the-review-reads-and-edits">

371 검토가 읽고 편집하는 내용

372</h3>102</h3>

373 103 

374검토는 모든 Claude Code 세션처럼 `CLAUDE.md`를 따르지만, [`REVIEW.md`](#review-md)는 읽지 않습니다. 백그라운드 검토는 `--fix` 편집을 세션의 [checkpoints](/docs/ko/checkpointing#subagent-edits-not-restored) 외부에 적용하므로, `/rewind`는 이를 취소하지 않습니다. git을 사용하여 이를 되돌립니다. 검토가 [포그라운드에서 실행](#run-in-the-foreground)될 때, 자신의 차례 동안 작업 트리를 편집하므로, `/rewind`는 평소대로 편집을 복원합니다.104리뷰 수준은 각 리뷰의 철저함을 설정하며, 더 철저한 리뷰일수록 비용이 더 많이 듭니다:

375 105 

376<h3 id="tune-effort-and-arguments">106* **Quick**: 더 가벼운 검토입니다. 가장 빠른 수준이며 비용이 가장 낮습니다.

377 노력 및 인수 조정107* **Standard**: 깊이, 속도, 비용의 균형을 맞춥니다. 기본 수준입니다.

378</h3>108* **Deep**: 가장 철저한 검토입니다. 시간이 가장 오래 걸리고 비용이 가장 많이 듭니다.

379 109 

380[effort 수준](/docs/ko/model-config#adjust-effort-level)을 전달하여 범위와 신뢰도를 교환합니다. `low`에서 검토는 가장 확신하는 결과를 보고하므로 거짓 양성이 적습니다. `medium`부터 `max`까지는 검토가 범위를 확대합니다.110Owner는 [조직에 대해 하나의 수준을 선택](/docs/ko/code-review-setup#set-the-default-review-level)하고, 일상적인 코드베이스에는 Quick, 중요한 코드베이스에는 Deep처럼 개별 저장소에 별도의 수준을 지정할 수 있습니다. 각 리뷰의 비용에 영향을 주는 다른 요인은 [Code Review 비용 및 사용량](/docs/ko/code-review-costs)을 참조하십시오.

381 111 

382수준을 입력하지 않으면, 검토는 이전 세션에서도 입력한 `low`부터 `max`까지의 마지막 수준을 재사용하며, Claude Code는 `Reusing high effort, the level you typed last time`과 같은 알림을 표시합니다. `/code-review high`와 같은 수준을 입력하여 나중에 실행이 재사용할 내용을 변경합니다. 비대화형 `-p` 실행에서 전달하는 수준은 이를 업데이트하지 않습니다. `ultra`는 기억된 수준을 업데이트하거나 사용하지 않습니다. 수준을 입력한 적이 없으면, 검토는 세션의 현재 노력을 사용합니다. v2.1.223 이전에는 수준 없는 `/code-review`는 항상 세션의 현재 노력을 사용했습니다.112<h3 id="what-a-review-can-access">

383 113 리뷰가 액세스할 수 있는 항목

384노력 수준과 플래그 후, Claude Code는 다음 두 가지 방법 중 하나로 줄의 나머지를 읽습니다:

385 

386* **`ultra` 없음**: 남은 모든 것이 검토 대상입니다. 다른 명령 이름으로 시작하더라도 마찬가지입니다. `/code-review /fix-issue 123`은 `/fix-issue 123`을 대상 텍스트로 검토하며, 두 번째 [stacked skill](/docs/ko/skills#pass-arguments-to-skills)로 `/fix-issue`를 로드하지 않습니다. v2.1.218 이전에는 `/code-review` 후에 스택된 명령이 자체 스킬로 확장되었습니다.

387* **`ultra` 포함**: Claude Code는 단일 단어를 기본 브랜치 또는 PR 번호로 읽고, 브랜치 또는 PR을 명명하지 않는 더 긴 텍스트를 [검토에 첨부된 노트](/docs/ko/ultrareview#pass-a-request-in-plain-words)로 변환합니다. `/code-review ultra check my auth changes`는 현재 브랜치를 검토하며, Claude는 결과를 노트와 연관시킵니다.

388 

389<h3 id="run-in-the-foreground">

390 포그라운드에서 실행

391</h3>114</h3>

392 115 

393검토는 기본적으로 백그라운드에서 실행됩니다. v2.1.218 이전에는 대화 내에서 실행되었습니다. 다음과 같은 경우에는 포그라운드에서 실행됩니다:116리뷰는 Owner가 [설정 중에 설치](/docs/ko/code-review-setup#turn-on-code-review)한 Claude GitHub App을 통해 저장소에 접근합니다:

394 117 

395* 이전 검토가 아직 진행 중인 동안 `/code-review`를 다시 실행합니다118* **실행 위치**: Anthropic 인프라의 관리형 환경에서 실행됩니다. 리뷰는 [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 실행되지 않습니다.

396* 비대화형 모드에서 실행합니다. `-p` 플래그 또는 Agent SDK를 사용합니다. Claude Code는 검토를 기다리고 응답에 결과를 포함합니다. 단, `ultra`는 예외로, [클라우드 검토를 기다리지 않습니다](/docs/ko/ultrareview#run-ultrareview-non-interactively)119* **읽고 쓰는 항목**: 리뷰 내에서 저장소에 대한 액세스는 읽기 전용이며, 리뷰는 커밋을 푸시하지 않습니다. 풀 리퀘스트에서는 댓글과 [확인 실행](/docs/ko/code-review-pull-requests#check-run-output)을 게시하고, 자신의 이전 댓글 스레드를 해결하며, 댓글 명령에 👀로 반응할 수 있습니다. 앱 자체는 다른 Claude 기능과 공유하는 [더 광범위한 권한 집합](/docs/ko/github-actions#github-app-permissions)을 보유합니다.

397* [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars)를 `1`로 설정합니다. 이는 다른 모든 백그라운드 작업 기능도 끕니다120* **코드 검사 방식**: 리뷰는 코드를 빌드하거나 실행하지 않고 diff와 주변 코드를 읽는 방식으로 작동합니다.

398 121 

399<h3 id="let-claude-start-the-review">122<h3 id="who-controls-a-review">

400 Claude가 검토를 시작하도록 허용123 리뷰를 제어하는 주체

401</h3>124</h3>

402 125 

403Claude는 자체적으로 `/code-review`를 시작할 수 있습니다. 일반 언어로 변경 사항을 검토하도록 요청하면 명령을 입력하지 않고도 스킬을 실행할 수 있으며, `/code-review`를 프롬프트로 하는 [scheduled task](/docs/ko/scheduled-tasks)는 검토를 실행합니다.126* **시작할 수 있는 사람**: 리뷰가 자동으로 실행되는 경우, 풀 리퀘스트를 열거나 푸시하면 리뷰가 시작됩니다. 단, [초안과 포크는 예외](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks)입니다. [댓글 명령](/docs/ko/code-review-pull-requests#comment-commands)은 저장소에 대한 쓰기 권한이 있는 사람이 작성한 경우에만 리뷰를 시작합니다.

404 127* **따르는 지침**: base 또는 기본 브랜치의 `REVIEW.md`를 따르며, [풀 리퀘스트 자체의 변경 사항에서는 절대 읽지 않습니다](/docs/ko/code-review-customize#which-branch-review-md-is-read-from).

405예약된 작업은 [클라우드 검토](#escalate-to-ultrareview)를 시작하지 않으므로, `ultra` 인수 없이 `/code-review`를 예약합니다.

406 128 

407Claude와 예약된 작업이 검토를 시작하는 것을 중지하면서 `/code-review`를 입력할 수 있도록 유지하려면, `~/.claude/settings.json`과 같은 [settings file](/docs/ko/settings#where-settings-live)에 [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings) 항목을 추가합니다:129<h2 id="compare-ways-to-get-a-review">

408 130 리뷰를 받는 방법 비교

409```json theme={null}131</h2>

410{

411 "skillOverrides": {

412 "code-review": "user-invocable-only"

413 }

414}

415```

416 

417v2.1.246 이전에는 Claude가 Anthropic에서 가져온 기능 플래그가 켜진 경우에만 자체적으로 `/code-review`를 시작했습니다. [기능 플래그를 가져오지 않는 세션](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서는 `/code-review`가 입력할 때만 실행되었으며, 예약된 `/code-review`는 Claude에 일반 텍스트로 도달했습니다.

418 

419<h3 id="escalate-to-ultrareview">

420 ultrareview로 확대

421</h3>

422 

423`/code-review ultra --fix`는 클라우드에서 더 깊은 [ultrareview](/docs/ko/ultrareview)를 실행한 다음, 세션으로 돌아올 때 결과를 작업 트리에 적용합니다.

424 

425Ultrareview는 자체 범위를 사용합니다: 현재 브랜치와 저장소의 기본 브랜치, 그리고 작업 트리의 커밋되지 않은 및 스테이징된 변경 사항입니다. 자격 증명 또는 키처럼 명명된 파일의 커밋되지 않은 변경 사항(예: `.env` 및 `*.tfvars` 파일)의 경우, Claude Code는 [클라우드 세션에 로컬 저장소 업로드](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)에 대한 규칙을 따릅니다. 다른 기본과 비교하려면 `/code-review ultra develop`과 같은 브랜치 이름을 전달합니다.

426 

427대상이 `github.com` pull request인 경우, Claude가 [완료된 결과를 PR에 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)하도록 GitHub 계정의 댓글로 할 수 있습니다. Claude Code v2.1.227 이상이 필요합니다.

428 

429<Note>

430 Ultrareview는 claude.ai 계정으로 인증이 필요하며 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용할 수 없으며, Zero Data Retention이 활성화되었거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직에서도 사용할 수 없습니다. ultrareview를 사용할 수 없으면, `/code-review ultra`는 대신 세션에서 로컬 검토를 실행합니다.

431</Note>

432 132 

433스크립트 또는 CI 작업에서 클라우드 검토를 실행하려면 [`claude ultrareview` 하위 명령](/docs/ko/ultrareview#run-ultrareview-non-interactively)을 사용합니다. 이 명령은 결과를 기다린 후 stdout에 출력합니다.133사용 가능한 옵션을 찾으려면 **사용 가능 대상** 열을 플랜 및 코드 호스트와 비교하여 확인하십시오:

434 134 

435이 명령은 v2.1.147 이전에 `/simplify`로 명명되었으며, 기본적으로 수정 사항을 적용했습니다. `/simplify`는 버그를 찾지 않고 수정 사항을 적용하는 별도의 정리 전용 검토를 실행합니다. 버그 찾기를 위해 `/simplify`를 스크립트했다면, `/code-review --fix`로 전환합니다.135| 옵션 | 리뷰를 시작하는 방법 | 실행 위치 | 사용 가능 대상 |

136| :- | :- | :- | :- |

137| [Code Review](#how-reviews-work) | 각 저장소 설정에 따른 풀 리퀘스트 활동 또는 `@claude review` 댓글 | Anthropic 인프라 | Owner가 켠 후, GitHub 저장소를 보유한 Team 또는 Enterprise 플랜의 조직 |

138| [`/code-review`](/docs/ko/code-review-local) | 브랜치에서 명령을 실행 | Claude Code 세션 | 모든 플랜의 모든 사용자 |

139| [Ultrareview](/docs/ko/ultrareview) | Claude Code에서 시작 | 클라우드 샌드박스 | claude.ai 계정으로 로그인해야 합니다. 사용할 수 없는 환경은 [Ultrareview](/docs/ko/ultrareview)를 참조하십시오 |

140| [GitHub Actions](/docs/ko/github-actions) 또는 [GitLab CI/CD](/docs/ko/gitlab-ci-cd)를 사용한 자체 CI의 Claude | 모든 풀 리퀘스트 또는 merge request와 같은 파이프라인 이벤트 | 자체 CI 러너 | GitHub 또는 GitLab에서 Claude API 키 또는 클라우드 제공업체 자격 증명이 있는 모든 사용자 |

141| [서브에이전트](/docs/ko/sub-agents) 또는 [스킬](/docs/ko/skills)로 만든 자체 리뷰어 | 세션 중에 사용자 또는 Claude가 호출 | Claude Code를 실행하는 모든 위치 | 직접 작성하는 모든 사용자 |

436 142 

437<h2 id="related-resources">143<h2 id="related-resources">

438 관련 리소스144 관련 리소스

439</h2>145</h2>

440 146 

441* [Commands](/docs/ko/commands): 로컬 Claude Code 세션에서 `/code-review`를 실행하여 푸시 전에 diff를 확인합니다147* [GitHub Enterprise Server](/docs/ko/github-enterprise-server): 자체 호스팅 GitHub 인스턴스에서 Code Review를 사용합니다

442* [GitHub Actions](/docs/ko/github-actions): 코드 검토 이상의 사용자 정의 자동화를 위해 자신의 GitHub Actions 워크플로우에서 Claude를 실행합니다148* [GitHub App 권한](/docs/ko/github-actions#github-app-permissions): Claude GitHub App이 요청하는 전체 권한 집합

443* [GitLab CI/CD](/docs/ko/gitlab-ci-cd): GitLab 파이프라인을 위한 자체 호스팅 Claude 통합149* [How Anthropic secures its AI-native software development lifecycle](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle): 자동화된 리뷰가 Anthropic의 안전한 개발 프로세스의 한 계층으로 어떻게 적합한지에 대한 설명

444* [Memory](/docs/ko/memory): Claude Code 전체에서 `CLAUDE.md` 파일이 작동하는 방식

445* [Analytics](/docs/ko/analytics): 코드 검토 이상으로 Claude Code 사용량을 추적합니다

446* [How Anthropic secures its AI-native software development lifecycle](https://claude.com/blog/how-anthropic-secures-its-ai-native-software-development-lifecycle): 자동화된 검토가 Anthropic의 안전한 개발 프로세스의 한 계층으로 어떻게 적합한지에 대한 설명

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Code Review 비용 및 사용량

6 

7> 조직이 Claude Code Review에 지출하는 비용을 추정하고 상한을 설정합니다. 리뷰가 사용량 크레딧을 통해 청구되는 방식, 비용을 좌우하는 요인, 사용량을 추적하는 위치를 설명합니다.

8 

9[Code Review](/docs/ko/code-review)에는 리뷰당 고정 가격이 없습니다. 지출 금액은 각 리뷰의 비용과 실행되는 리뷰 수에 따라 달라집니다.

10 

11* **각 리뷰의 비용**: [리뷰 수준](/docs/ko/code-review-setup#set-the-default-review-level), 변경 사항의 크기, 주변 코드의 복잡도, 검증이 필요한 후보 이슈의 수에 따라 달라집니다

12* **리뷰 수**: 각 저장소에서 [리뷰가 실행되는 빈도](#how-often-reviews-run)에 따라 결정됩니다

13 

14<h2 id="pricing">

15 가격

16</h2>

17 

18Code Review는 플랜에 포함된 사용량과 별도로 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)을 통해 토큰 사용량 기준으로 청구됩니다. 리뷰 비용은 PR을 연 개발자나 리뷰를 요청한 개발자가 아니라 조직에 청구됩니다. 조직이 다른 Claude Code 기능에 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용하는지와 관계없이 비용은 Anthropic 청구서에 표시됩니다.

19 

20<h3 id="how-often-reviews-run">

21 리뷰가 실행되는 빈도

22</h3>

23 

24관리자 페이지에서 추가한 저장소는 **After every push**로 시작하며, 이 설정에서 가장 많은 리뷰가 실행됩니다. 각 저장소의 [**Review runs** 설정](/docs/ko/code-review-setup#set-when-reviews-run)에 따라 풀 리퀘스트가 받는 리뷰 수가 결정됩니다.

25 

26* **Once after PR creation**: 풀 리퀘스트가 열리거나, 다시 열리거나, 리뷰 준비 완료로 표시될 때 리뷰가 실행됩니다

27* **After every push**: 푸시할 때마다 실행되므로 비용이 푸시 횟수만큼 배가됩니다

28* **Manual (@claude review)**: 열기나 푸시 시 리뷰가 실행되지 않습니다

29 

30코멘트 명령, 초안, 포크에서 온 풀 리퀘스트는 이 횟수를 다음과 같이 조정합니다.

31 

32* **Once after PR creation 또는 Manual 모드에서 `@claude review always`**: [해당 PR을 푸시로 트리거되는 리뷰에 등록](/docs/ko/code-review-pull-requests#comment-commands)하므로, 해당 코멘트 이후 푸시할 때마다 추가 비용이 발생합니다

33* **After every push 모드에서 `@claude review always`**: 푸시가 이미 리뷰를 트리거하므로 구독해도 푸시당 비용은 변하지 않습니다

34* **`@claude review`**: 이후 푸시를 구독하지 않고 단일 리뷰를 실행합니다

35* **초안 및 포크에서 온 풀 리퀘스트**: [자동 리뷰가 둘 다 건너뛰므로](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks) 이에 대한 푸시는 리뷰를 추가하지 않습니다

36 

37<h2 id="estimate-your-spend">

38 지출 추정

39</h2>

40 

41광범위하게 도입하기 전에 소규모 파일럿을 실행하여 자체 풀 리퀘스트를 기반으로 월간 지출을 추정합니다.

42 

431. 파일럿을 위한 [월간 지출 한도](#limit-your-spend)를 설정합니다.

442. 몇 개의 대표 저장소에서 **Review runs**를 **Once after PR creation** 또는 \*\*Manual (@claude review)\*\*로 설정하고 Code Review를 켭니다.

453. 여러 리뷰가 실행된 후, [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review)의 **Code review** 섹션에 있는 **Repositories** 표의 **Average cost** 열에서 각 저장소의 리뷰당 평균 비용을 확인합니다.

464. 그 평균에 해당 저장소에서 한 달 동안 열리는 풀 리퀘스트 수를 곱합니다. **After every push**의 경우 풀 리퀘스트당 일반적인 푸시 횟수를 한 번 더 곱합니다.

47 

48저장소의 평균은 풀 리퀘스트의 크기와 선택한 리뷰 수준에 따라 달라집니다.

49 

50<h2 id="limit-your-spend">

51 지출 제한

52</h2>

53 

54Code Review의 월간 지출 한도를 설정하려면 [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage)로 이동하여 Claude Code Review 서비스의 한도를 구성합니다. 이 한도는 조직 전체에 적용됩니다.

55 

56Code Review는 다음 중 하나라도 소진되면 리뷰를 건너뜁니다.

57 

58* **Code Review 지출 한도**: Claude Code Review 서비스에 대해 설정한 월간 한도입니다. 다음 청구 기간이 시작될 때 재설정되며, 한도를 높이면 더 일찍 리뷰가 재개됩니다.

59* **조직 지출 한도**: 사용량 크레딧에 대한 조직의 전체 월간 지출 한도입니다. 같은 페이지에서 높일 수 있습니다.

60* **사용량 크레딧 잔액**: 조직의 사용량 크레딧 잔액입니다. 같은 페이지에서 크레딧을 추가할 수 있습니다.

61 

62Code Review는 남은 금액이 리뷰 한 건의 예상 비용보다 적을 때도 리뷰를 건너뜁니다. 리뷰를 건너뛰면 개발자에게 원인을 명시하고 사용량 설정으로 연결되는 [PR 코멘트](/docs/ko/code-review-troubleshooting#review-didn’t-run-and-the-pr-shows-a-budget-message)가 표시됩니다.

63 

64지출을 모니터링하려면 [분석 대시보드](#view-usage)를 사용합니다.

65 

66<h2 id="view-usage">

67 사용량 보기

68</h2>

69 

70[claude.ai/analytics/code-review](https://claude.ai/analytics/code-review)로 이동하여 조직 전체의 Code Review 활동을 확인합니다.

71 

72| 섹션 | 표시 내용 |

73| :- | :- |

74| PRs reviewed | 선택한 기간 동안 리뷰된 풀 리퀘스트의 일별 수 |

75| Code Review cost | 이번 달 현재까지의 Code Review 지출 |

76| Feedback | 개발자가 이슈를 해결하여 자동으로 해결 처리된 리뷰 코멘트 수 |

77| Repository breakdown | 저장소별 리뷰된 PR 수, 해결된 코멘트 수, 리뷰 실행 수와 함께 예상 비용 및 PR별 보기 |

78 

79Code Review cost 카드는 현재 월이 선택된 경우에만 금액을 표시합니다. 분석의 비용 수치는 청구서와 다를 수 있습니다. Repository breakdown 비용은 할인이나 크레딧을 적용하기 전의 정가로 추정되며, Claude가 풀 리퀘스트에 게시한 리뷰만 포함합니다. 청구서와 정확히 일치하는 지출은 Anthropic 청구서를 참조하십시오.

80 

81<h2 id="related-resources">

82 관련 리소스

83</h2>

84 

85* [Code Review 설정](/docs/ko/code-review-setup): 각 저장소에서 리뷰 수준과 리뷰 실행 시점을 선택하는 위치

86* [풀 리퀘스트에서 리뷰 읽기 및 요청](/docs/ko/code-review-pull-requests): 코멘트 명령, 포크에서 온 풀 리퀘스트, 리뷰를 건너뛸 때 개발자에게 표시되는 예산 메시지

87* [Code Review](/docs/ko/code-review): 리뷰가 확인하는 항목과 게시하는 내용

88* [효과적인 비용 관리](/docs/ko/costs): Claude Code의 나머지 기능에 대한 지출 제어 및 사용량 추적

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Code Review 사용자 지정

6 

7> REVIEW.md와 CLAUDE.md로 Code Review가 풀 리퀘스트에서 지적하는 항목을 조정합니다. 심각도를 재조정하고, 경로를 건너뛰고, 검사를 추가하고, 어떤 사본이 적용되는지 확인합니다.

8 

9저장소에 지침을 커밋하여 [Code Review](/docs/ko/code-review)가 해당 저장소에서 지적하는 항목을 변경할 수 있습니다. 이 방법으로 nit 수를 줄이거나, 생성된 파일에 대한 코멘트를 중단하거나, 팀이 중요하게 여기는 규칙을 추가할 수 있습니다. 지침은 다음 두 파일 중 하나에 작성합니다.

10 

11* **`CLAUDE.md`**: Claude Code가 리뷰를 포함한 모든 작업에서 읽는 [프로젝트 지침](/docs/ko/memory)입니다. Code Review는 이를 프로젝트 컨텍스트로 읽고, 이를 위반하는 변경 사항을 지적합니다.

12* **`REVIEW.md`**: 리뷰 전용 지침입니다. 팀이 무엇을 지적하기를 원하는지, 어떤 심각도로 지적할지, 무엇을 건너뛸지 명시하는 데 사용합니다.

13 

14저장소 루트에 `REVIEW.md`를 추가하고 병합합니다. 그런 다음 [기본 브랜치를 보호합니다](#which-branch-review-md-is-read-from).

15 

16<Note>

17 리뷰의 철저함이나 리뷰 실행 시점을 변경하려면 Owner에게 [리뷰 수준](/docs/ko/code-review-setup#set-the-default-review-level) 또는 [**Review runs** 설정](/docs/ko/code-review-setup#set-when-reviews-run)을 변경하도록 요청합니다.

18</Note>

19 

20<h2 id="use-claude-md-for-project-wide-rules">

21 프로젝트 전체 규칙에는 CLAUDE.md 사용

22</h2>

23 

24Code Review는 저장소의 `CLAUDE.md` 파일을 프로젝트 컨텍스트로 읽습니다. 이 파일의 규칙 중 하나를 위반하는 변경 사항은 문제에 맞는 [심각도 수준](/docs/ko/code-review-pull-requests#severity-levels)의 발견 사항이 됩니다.

25 

26리뷰는 저장소 루트의 `CLAUDE.md`와 변경된 각 파일의 상위 디렉터리에 있는 `CLAUDE.md` 파일을 읽습니다. 하위 디렉터리의 `CLAUDE.md`는 풀 리퀘스트가 해당 경로 아래의 파일을 변경할 때 읽힙니다.

27 

28<h2 id="use-review-md-for-review-only-rules">

29 리뷰 전용 규칙에는 REVIEW\.md 사용

30</h2>

31 

32`REVIEW.md`는 저장소 루트에 위치하며 Code Review를 저장소에 맞게 조정하는 파일입니다. 하위 디렉터리에 `REVIEW.md`를 추가하여 루트 파일에 더해 해당 경로 아래의 변경 사항에 대한 검사를 추가할 수도 있습니다.

33 

34문제를 찾는 에이전트와 이를 검증하는 에이전트는 Code Review의 기본 리뷰 지침과 함께 이 파일의 내용을 저장소의 리뷰 지침으로 전달받습니다. 최종 리뷰를 작성하는 단계는 심각도를 확정하고 요약을 작성하기 전에 이 파일을 참조합니다.

35 

36다음 예시 구조에는 루트 파일 하나와 하위 디렉터리 파일 하나가 있습니다.

37 

38```text theme={null}

39your-repo/

40├── REVIEW.md # Root file

41├── services/

42│ └── billing/

43│ └── REVIEW.md # Adds checks for changes under services/billing/

44└── src/

45```

46 

47하위 디렉터리 파일에 의존하기 전에 기본 브랜치를 보호하고 [브랜치 구성별로 리뷰가 읽는 항목](#what-a-review-reads-for-each-branch-setup)을 확인합니다.

48 

49<Note>

50 Code Review 서비스와 로컬 [`/code-review` 명령](/docs/ko/code-review-local)은 서로 별개의 도구이며, 읽는 파일도 다릅니다. 서비스는 `CLAUDE.md`와 `REVIEW.md`를 모두 읽습니다. 사용자의 로컬 머신에서 Claude Code 세션 안에서 실행하는 `/code-review` 명령은 `CLAUDE.md` 파일을 읽지만 `REVIEW.md`는 읽지 않습니다. 두 곳 모두에 적용하려는 지침은 `CLAUDE.md`에 작성하고, `REVIEW.md`에는 풀 리퀘스트 리뷰에 특화된 규칙만 둡니다.

51</Note>

52 

53<h3 id="example-review-md">

54 REVIEW\.md 예시

55</h3>

56 

57이 `REVIEW.md`는 백엔드 서비스에 맞게 심각도를 재조정하고, nit 수를 제한하고, 생성된 파일을 건너뛰고, 저장소별 검사를 추가합니다.

58 

59```markdown theme={null}

60# Review instructions

61 

62## What Important means here

63 

64Reserve Important for findings that would break behavior, leak data,

65or block a rollback: incorrect logic, unscoped database queries, PII

66in logs or error messages, and migrations that aren't backward

67compatible. Style, naming, and refactoring suggestions are Nit at

68most.

69 

70## Cap the nits

71 

72Report at most five Nits per review.

73 

74## Do not report

75 

76- Anything CI already enforces: lint, formatting, type errors

77- Generated files under `src/gen/` and any `*.lock` file

78- Test-only code that intentionally violates production rules

79 

80## Always check

81 

82- New API routes have an integration test

83- Log lines don't include email addresses, user IDs, or request bodies

84- Database queries are scoped to the caller's tenant

85```

86 

87<h3 id="choose-what-to-write-in-review-md">

88 REVIEW\.md에 작성할 내용 선택

89</h3>

90 

91`REVIEW.md`는 리뷰가 찾아내고 보고하는 내용을 변경하는 자유 형식 Markdown입니다. 리뷰의 형식은 변경하지 않습니다. 겪고 있는 문제를 찾은 다음 제시된 것과 같은 지침을 추가합니다. [예시](#example-review-md)는 처음 네 가지를 사용합니다.

92 

93* **잘못된 항목이 Important로 표시됨**: 저장소에 맞게 🔴 Important의 의미를 재정의합니다. 기본 보정은 프로덕션 코드를 대상으로 하며, 문서 저장소, 구성 저장소 또는 프로토타입에는 훨씬 좁은 정의가 적합할 수 있습니다. 어떤 유형의 발견 사항이 Important이고 어떤 유형이 최대 Nit인지 명시합니다. 예를 들어 모든 `CLAUDE.md` 위반을 Important로 취급하는 식으로 상향 조정할 수도 있습니다.

94* **nit이 너무 많음**: 단일 리뷰가 게시하는 🟡 Nit 코멘트 수를 제한합니다. "nit은 최대 5개까지만 보고"와 같은 제한을 두면 리뷰를 실행 가능한 상태로 유지할 수 있습니다.

95* **생성된 파일이나 CI가 이미 검사하는 항목에 대한 코멘트**: Claude가 발견 사항을 건너뛰어야 하는 경로와 발견 사항 범주를 나열합니다. 일반적인 대상은 생성된 코드, lockfile, vendored 의존성이며, 린팅이나 맞춤법 검사처럼 CI가 이미 강제하는 모든 항목도 포함됩니다. 어느 정도 리뷰는 필요하지만 전면적인 검토는 필요하지 않은 경로에는 대신 더 높은 기준을 설정합니다: "`scripts/`에서는 거의 확실하고 심각한 경우에만 보고."

96* **팀 규칙이 검사되지 않음**: "새 API 라우트에는 통합 테스트가 있어야 함"처럼 모든 풀 리퀘스트에서 지적하려는 규칙을 추가합니다.

97* **잘못된 것으로 판명되는 발견 사항**: 특정 유형의 발견 사항을 게시하기 전에 근거를 요구합니다. 예를 들어 "동작에 관한 주장에는 이름에서 추론한 것이 아닌 소스의 `file:line` 인용이 필요함"과 같은 지침은 작성자에게 불필요한 왕복을 초래할 수 있는 오탐을 줄입니다.

98 

99이러한 지침 중 일부는 [보호된 기본 브랜치에 루트 파일이 있어야 합니다](#which-branch-review-md-is-read-from).

100 

101`REVIEW.md`에는 리뷰 동작을 변경하는 지침만 두고, 일반적인 프로젝트 컨텍스트는 `CLAUDE.md`에 둡니다.

102 

103<h3 id="which-branch-review-md-is-read-from">

104 REVIEW\.md를 읽는 브랜치

105</h3>

106 

107Code Review는 풀 리퀘스트의 기본(base) 브랜치 또는 기본(default) 브랜치에서 `REVIEW.md`를 읽으며, 풀 리퀘스트 자체의 변경 사항에서는 절대 읽지 않습니다. 리뷰 동작을 변경하려면 `REVIEW.md` 변경 사항을 먼저 병합합니다.

108 

109`REVIEW.md`를 기본 브랜치에 두고 해당 브랜치를 보호합니다. 아래 표의 첫 번째 행처럼 리뷰가 보호된 기본 브랜치의 사본을 읽는 경우, 루트 파일의 다음 지침을 따릅니다.

110 

111* 발견 사항의 심각도 낮추기

112* 경로, 파일 또는 문제 유형 제외

113* nit 코멘트 수 제한

114 

115<h4 id="what-counts-as-branch-protection">

116 브랜치 보호로 인정되는 항목

117</h4>

118 

119Code Review는 다음 설정을 보호로 인정합니다.

120 

121* **기본 브랜치**: 클래식 브랜치 보호 규칙 또는 ruleset

122* **그 외 모든 브랜치**: ruleset만 해당

123 

124ruleset은 업데이트를 제한하거나 최소 한 번의 승인이 있는 풀 리퀘스트를 요구하는 경우 보호로 인정됩니다. 풀 리퀘스트를 요구하는 경우에는 새 푸시 시 해당 승인을 무효화하거나 마지막 푸시 이후에 승인이 이루어지도록 요구해야 합니다.

125 

126<h4 id="what-a-review-reads-for-each-branch-setup">

127 브랜치 구성별로 리뷰가 읽는 항목

128</h4>

129 

130아래 표의 첫 번째 열에서 저장소의 상황을 찾습니다.

131 

132| 브랜치 보호 | 읽는 사본 | 읽는 파일 |

133| :- | :- | :- |

134| 기본 브랜치가 보호되어 있고, 풀 리퀘스트가 기본 브랜치 또는 ruleset으로 보호되지 않는 브랜치를 대상으로 함 | 기본 브랜치 | 루트 및 하위 디렉터리 파일 |

135| 풀 리퀘스트가 ruleset으로 보호되는 다른 브랜치를 대상으로 함 | 해당 base 브랜치 | 루트 및 하위 디렉터리 파일 |

136| 기본 브랜치가 보호되어 있지 않고, base 브랜치에 어떤 종류의 보호 규칙도 없음 | 기본 브랜치 | 루트 파일 |

137| Code Review가 보호 설정을 확인할 수 없음. 보호되지 않은 기본 브랜치와 클래식 규칙만 있는 base 브랜치의 조합도 여기에 포함됨 | 없음 | 없음 |

138 

139check run에 `REVIEW.md`가 언급되는 경우 [The check run mentions REVIEW.md](/docs/ko/code-review-troubleshooting#the-check-run-mentions-review-md)를 참조합니다.

140 

141<h2 id="related-resources">

142 관련 리소스

143</h2>

144 

145* [Code Review](/docs/ko/code-review): 서비스의 개요와 리뷰 실행 방식

146* [풀 리퀘스트에서 리뷰 읽기 및 요청](/docs/ko/code-review-pull-requests#severity-levels): 각 심각도 수준의 의미와 발견 사항이 표시되는 방식

147* [Code Review 설정](/docs/ko/code-review-setup): Owner가 설정하는 리뷰 수준과 리뷰 실행 시점

148* [`/code-review`로 로컬에서 리뷰](/docs/ko/code-review-local): `/code-review` 명령, 인수 및 effort 수준

149* [메모리](/docs/ko/memory): Claude Code 전반에서 `CLAUDE.md` 파일이 작동하는 방식

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# /code-review로 로컬에서 리뷰하기

6 

7> Claude Code 세션에서 `/code-review`를 실행하여 브랜치 변경 사항의 버그를 찾고, 리뷰 대상을 풀 리퀘스트나 경로로 지정하며, Claude가 수정 사항을 적용하도록 합니다.

8 

9`/code-review`는 작업 중인 세션의 Claude Code 프롬프트에 입력하는 명령입니다. Claude는 브랜치의 변경 사항을 리뷰하고, 정확성 버그를 찾아, 발견한 내용을 대화에 보고합니다. 모델과 effort 수준에 따라 리뷰는 재사용, 단순화, 효율성 정리 항목도 다룹니다.

10 

11이 명령은 모든 플랜에서 작동합니다. 리뷰는 사용자 자신의 세션에서 실행되므로, 세션의 나머지 작업과 동일한 방식으로 플랜 사용량 또는 API 청구에 포함됩니다.

12 

13<Note>

14 GitHub에서 저장소의 모든 풀 리퀘스트를 자동으로 리뷰하려면 Owner가 조직에 대해 켜는 관리형 서비스인 [Code Review](/docs/ko/code-review)를 참조하세요.

15</Note>

16 

17`/review`는 `/code-review`의 별칭입니다. v2.1.223 이전에는 `/review`가 GitHub 풀 리퀘스트에 대해 단일 패스, 읽기 전용 리뷰를 실행하는 별도의 명령이었습니다.

18 

19<Steps>

20 <Step title="/code-review 실행">

21 다음 명령을 실행합니다.

22 

23 ```text theme={null}

24 /code-review

25 ```

26 

27 대상을 지정하지 않으면 리뷰는 현재 브랜치의 변경 사항을 다룹니다. 대신 풀 리퀘스트, 다른 브랜치, 경로 또는 커밋 범위를 리뷰 대상으로 지정하려면 [리뷰 대상 선택](#choose-what-to-review)을 참조하세요.

28 

29 플래그를 추가할 수도 있습니다.

30 

31 * `--fix`: 리뷰 후 발견 사항을 작업 트리에 적용하도록 Claude에 추가로 요청합니다. 수정 내용은 [권한 모드](/docs/ko/permission-modes)를 거칩니다.

32 * `--comment`: 발견 사항을 GitHub 풀 리퀘스트에는 인라인 댓글로, [GitLab 병합 요청](#post-findings-to-a-gitlab-merge-request)에는 단일 노트로 게시합니다

33 </Step>

34 

35 <Step title="작업 계속하기">

36 리뷰는 자체 컨텍스트 윈도우를 가진 백그라운드 [서브에이전트](/docs/ko/sub-agents)로 실행되므로 대화를 채우지 않습니다. 리뷰가 완료되면 발견 사항이 대화에 도착합니다.

37 </Step>

38 

39 <Step title="발견 사항에 대응하기">

40 리뷰에서 발견한 내용을 수정하도록 Claude에 요청합니다. `--fix` 또는 `--comment`를 사용하면 Claude가 리뷰의 일부로 발견 사항을 적용하거나 게시하며, 수정 내용에 대한 승인을 요청받을 수 있습니다.

41 </Step>

42</Steps>

43 

44<h2 id="choose-what-to-review">

45 리뷰 대상 선택

46</h2>

47 

48현재 브랜치가 아닌 다른 대상을 리뷰하려면 effort 수준과 플래그 뒤에 대상을 입력합니다. Claude는 해당 텍스트를 리뷰 대상으로 받습니다. 대상은 풀 리퀘스트 번호, 브랜치 이름, 파일 경로 또는 Git 리비전 범위일 수 있습니다. 첫 번째 열에서 리뷰하려는 항목을 찾아 두 번째 열에 표시된 내용을 입력하세요.

49 

50| 리뷰 대상 | 입력 |

51| :- | :- |

52| 현재 브랜치와 커밋되지 않은 변경 사항 | `/code-review` |

53| 최근 15개 커밋 | `/code-review HEAD~15..HEAD` |

54| 한 브랜치와 다른 브랜치 비교 | `/code-review main...my-feature` |

55| 단일 커밋(`abc1234`는 커밋 해시) | `/code-review abc1234^..abc1234` |

56| 번호로 지정한 풀 리퀘스트 | `/code-review 1234` |

57| 파일 또는 디렉터리 경로 | `/code-review src/auth` |

58 

59대상을 지정하지 않으면 `/code-review`는 업스트림 브랜치보다 앞선 브랜치의 커밋과 커밋되지 않은 변경 사항을 리뷰합니다. 브랜치에 업스트림이 없으면 Claude는 `main` 또는 이전 커밋과 비교합니다.

60 

61`ultra`를 사용하면 Claude Code는 [effort 수준과 플래그 뒤의 텍스트](#text-after-the-effort-level-and-flags)에서 설명하는 대로 대상을 다르게 해석합니다.

62 

63<h2 id="what-the-review-reads-and-edits">

64 리뷰가 읽고 수정하는 항목

65</h2>

66 

67리뷰를 실행하기 전에, 특히 `--fix`를 사용할 때는 다음 사항을 확인하세요.

68 

69* **수정**: `--fix` 없이 실행하면 리뷰 지침은 Claude에 보고서만 요청합니다. `--fix`를 사용하면 발견 사항을 작업 트리에 적용하도록 추가로 요청합니다. 어느 경우든 모든 수정은 권한 모드를 거칩니다.

70* **되감기**: 백그라운드 리뷰는 `--fix` 수정 내용을 세션의 [체크포인트](/docs/ko/checkpointing#subagent-edits-not-restored) 밖에서 적용합니다. 이후 `/rewind`는 Claude가 대화에서 이미 수정한 파일만 복원합니다. 다른 파일에 대한 리뷰의 수정 내용은 그대로 남으므로 git을 사용해 되돌리세요. 리뷰가 [포그라운드에서 실행](#run-in-the-foreground)되면 사용자 자신의 턴 동안 작업 트리를 수정하므로 `/rewind`가 평소처럼 해당 수정 내용을 복원합니다.

71* **지침**: 리뷰는 비대화형 `-p` 실행을 포함하여 `CLAUDE.md`를 따릅니다. `REVIEW.md`는 읽지 않습니다. 이 파일은 GitHub 풀 리퀘스트에 대한 관리형 [Code Review 서비스](/docs/ko/code-review-customize#use-review-md-for-review-only-rules)를 구성합니다.

72 

73<h2 id="how-findings-are-reported">

74 발견 사항 보고 방식

75</h2>

76 

77다음 두 가지 실행에서는 Claude가 발견 사항을 응답의 텍스트로 보고합니다.

78 

79* `/code-review`가 리뷰를 [분기된 서브에이전트](/docs/ko/skills#run-skills-in-a-subagent)로 실행하는 터미널 세션

80* 텍스트 또는 JSON 출력을 사용하는 `-p` 실행

81 

82[데스크톱 앱](/docs/ko/desktop#review-your-code)처럼 발견 사항 목록을 요청하는 호스트 애플리케이션에서는 Claude가 대신 [`ReportFindings` 도구](/docs/ko/tools-reference)를 통해 리뷰의 발견 사항을 보고합니다. 보고서는 발견 사항 목록으로 표시되며, 각 항목에는 파일 위치, 한 문장 요약, 그리고 발견 사항에 카테고리 태그가 있는 경우 `correctness` 같은 카테고리 태그가 표시됩니다. 호스트 요청은 모든 effort 수준에 적용되며 Claude Code v2.1.218 이상이 필요합니다.

83 

84Claude가 이후 세션에서 보고된 발견 사항을 수정하면 이를 다시 보고합니다. 그러면 Claude Code는 업데이트된 발견 사항 목록에서 각 발견 사항을 수정됨, 건너뜀 또는 변경 불필요로 표시합니다.

85 

86<h2 id="tune-effort-and-arguments">

87 effort 및 인수 조정

88</h2>

89 

90`--fix` 및 `--comment` 외에도 이 명령은 다음 플래그를 받습니다.

91 

92* `--post`: `github.com` 풀 리퀘스트에 대한 `ultra` 클라우드 리뷰에서, 실행 대화 상자에 완료된 발견 사항을 PR에 게시하는 옵션을 미리 선택합니다. [풀 리퀘스트에 발견 사항 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)를 참조하세요. Claude Code v2.1.227 이상이 필요합니다.

93* `--max-findings <n>`, `--max-findings all` 또는 `--max-findings default`: 리뷰의 일반적인 제한 대신 최대 `n`개의 발견 사항을 보고하거나, `all`을 사용하면 모든 발견 사항을 보고합니다. 리뷰가 발견 사항 도구를 통해 보고하는 경우 제한은 32개입니다. 이후 리뷰는 `--max-findings default`를 전달할 때까지 입력한 값을 재사용하지만, 비대화형 `-p` 실행에서 전달한 값은 기억되지 않습니다. Claude Code v2.1.288 이상이 필요합니다.

94 

95[effort 수준](/docs/ko/model-config#adjust-effort-level)을 전달하여 범위와 확신도 사이의 균형을 조정합니다. `low`에서는 리뷰가 가장 확신하는 발견 사항을 보고하므로 오탐이 줄어듭니다. `medium`부터 `max`까지는 리뷰의 범위가 넓어집니다.

96 

97수준을 입력하지 않으면 리뷰는 이전 세션에서 입력한 것이라도 마지막으로 입력한 `low`\~`max` 수준을 재사용합니다. Claude Code는 `Reusing high effort, the level you typed last time`과 같은 알림을 표시합니다. 다음 규칙에 따라 실행에 사용할 수준이 결정됩니다.

98 

99* **수준 입력**: `/code-review high`처럼 입력한 수준은 이후 실행에서 재사용하는 값을 변경합니다

100* **비대화형 실행**: 비대화형 `-p` 실행에서 전달한 수준은 기억된 수준을 업데이트하지 않습니다

101* **`ultra`**: 리뷰는 기억된 수준을 사용하지도 업데이트하지도 않습니다

102* **수준을 입력한 적 없음**: 리뷰는 세션의 현재 effort를 사용합니다

103 

104v2.1.223 이전에는 수준 없이 실행한 `/code-review`가 항상 세션의 현재 effort를 사용했습니다.

105 

106<h3 id="post-findings-to-a-gitlab-merge-request">

107 GitLab 병합 요청에 발견 사항 게시

108</h3>

109 

110GitLab 병합 요청에 `--comment`를 전달하면 Claude Code는 GitLab의 `glab` CLI를 통해 발견 사항을 게시합니다. Claude Code v2.1.257 이상이 필요합니다. `glab`이 설치되어 있지 않으면 Claude는 대신 터미널에 발견 사항을 출력합니다.

111 

112병합 요청은 URL 또는 `!123` 참조 형식으로 전달합니다. Claude Code는 체크아웃의 origin이 `gitlab.com`에 있을 때만 단순 번호나 브랜치 이름을 병합 요청으로 처리합니다. 자체 관리형 GitLab 인스턴스에서는 URL 또는 `!123` 형식을 전달하세요.

113 

114<h3 id="text-after-the-effort-level-and-flags">

115 effort 수준과 플래그 뒤의 텍스트

116</h3>

117 

118effort 수준과 플래그 뒤에서 Claude Code는 줄의 나머지 부분을 리뷰 대상으로 읽습니다. `ultra` 인수는 이 해석 방식을 변경합니다.

119 

120* **`ultra` 사용 시**: Claude Code는 단일 단어를 기본 브랜치 또는 PR 번호로 읽습니다. 브랜치나 PR을 지정하지 않는 더 긴 텍스트는 [리뷰에 첨부되는 메모](/docs/ko/ultrareview#pass-a-request-in-plain-words)가 됩니다. `/code-review ultra check my auth changes`는 현재 브랜치를 리뷰하며, Claude는 발견 사항을 메모와 연관 지어 설명합니다.

121* **`ultra` 미사용 시**: 남은 모든 내용은 다른 명령 이름으로 시작하더라도 리뷰 대상이 됩니다. `/code-review /fix-issue 123`은 `/fix-issue`를 두 번째 [스택 스킬](/docs/ko/skills#pass-arguments-to-skills)로 로드하는 대신 `/fix-issue 123`을 대상 텍스트로 하여 리뷰합니다. v2.1.218 이전에는 `/code-review` 뒤에 스택된 명령이 자체 스킬로 확장되었습니다.

122 

123<h2 id="run-in-the-foreground">

124 포그라운드에서 실행

125</h2>

126 

127리뷰를 포그라운드에서 실행하려면 다음 중 하나를 수행합니다.

128 

129* `-p` 플래그 또는 Agent SDK를 사용하여 비대화형 모드로 실행합니다. Claude Code는 리뷰를 기다린 후 응답에 발견 사항을 포함합니다. 단, `ultra`는 [클라우드 리뷰를 기다리지 않습니다](/docs/ko/ultrareview#run-ultrareview-non-interactively).

130* [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars)를 `1`로 설정합니다. 이 설정은 다른 모든 백그라운드 작업 기능도 끕니다

131* 이전 리뷰가 아직 진행 중일 때 `/code-review`를 다시 실행합니다

132 

133v2.1.218 이전에는 리뷰가 대화 내부에서 실행되었습니다.

134 

135<h2 id="let-claude-start-the-review">

136 Claude가 리뷰를 시작하도록 하기

137</h2>

138 

139Claude는 사용자가 명령을 입력하지 않아도 스스로 `/code-review`를 시작할 수 있습니다.

140 

141* **일반 언어로 요청할 때**: Claude에 변경 사항을 리뷰해 달라고 요청하면 Claude가 스킬을 실행할 수 있습니다

142* **예약 작업에서**: `/code-review`를 프롬프트로 사용하는 [예약 작업](/docs/ko/scheduled-tasks)이 리뷰를 실행합니다

143 

144예약 작업은 [클라우드 리뷰](#escalate-to-ultrareview)를 시작하지 않으므로 `ultra` 인수 없이 `/code-review`를 예약하세요.

145 

146`/code-review`를 직접 입력할 수 있도록 유지하면서 Claude와 예약 작업 모두 리뷰를 시작하지 못하게 하려면 `~/.claude/settings.json` 같은 [설정 파일](/docs/ko/settings#where-settings-live)에 [`skillOverrides`](/docs/ko/skills#override-skill-visibility-from-settings) 항목을 추가합니다.

147 

148```json theme={null}

149{

150 "skillOverrides": {

151 "code-review": "user-invocable-only"

152 }

153}

154```

155 

156v2.1.246 이전에는 Anthropic에서 가져온 기능 플래그가 켜져 있는 경우에만 Claude가 스스로 `/code-review`를 시작했습니다. [기능 플래그를 가져오지 않는 세션](/docs/ko/env-vars#features-that-need-feature-flag-fetching)에서는 `/code-review`가 사용자가 입력한 경우에만 실행되었으며, 예약된 `/code-review`는 일반 텍스트로 Claude에 전달되었습니다.

157 

158<h2 id="escalate-to-ultrareview">

159 ultrareview로 확장

160</h2>

161 

162`/code-review ultra --fix`는 클라우드에서 더 심층적인 [ultrareview](/docs/ko/ultrareview)를 실행한 다음, 발견 사항이 세션에 도착하면 이를 작업 트리에 적용하도록 Claude에 요청합니다.

163 

164Ultrareview는 자체 범위를 사용합니다.

165 

166* **비교 대상**: 현재 브랜치와 저장소의 기본 브랜치를 비교하며, 작업 트리의 커밋되지 않은 변경 사항과 스테이징된 변경 사항도 포함합니다

167* **민감한 파일**: `.env` 및 `*.tfvars` 파일처럼 자격 증명이나 키와 같은 이름을 가진 파일의 커밋되지 않은 변경 사항에 대해서는 Claude Code가 [로컬 저장소를 클라우드 세션에 업로드](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github)하는 규칙을 따릅니다

168* **다른 기준**: `/code-review ultra develop`처럼 브랜치 이름을 전달하여 다른 기준과 비교합니다

169 

170대상이 `github.com` 풀 리퀘스트인 경우, Claude가 사용자의 GitHub 계정으로 [완료된 발견 사항을 PR에 댓글로 게시](/docs/ko/ultrareview#post-findings-to-the-pull-request)하도록 할 수 있습니다. Claude Code v2.1.227 이상이 필요합니다.

171 

172<Note>

173 Ultrareview는 claude.ai 계정을 통한 인증이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에서는 사용할 수 없으며, Zero Data Retention이 활성화되어 있거나 [HIPAA 구성](/docs/ko/hipaa-setup)이 적용된 조직에서도 사용할 수 없습니다. 이러한 경우 `/code-review ultra`는 대신 세션에서 로컬 리뷰를 실행합니다. [고객 관리형 암호화 키](https://platform.claude.com/docs/en/manage-claude/cmek)(CMEK)를 사용하는 조직은 ultrareview를 실행할 수 없습니다. 변경 사항을 로컬에서 리뷰하려면 `/code-review`를 실행하세요.

174</Note>

175 

176스크립트나 CI 작업에서 클라우드 리뷰를 실행하려면 발견 사항을 기다린 후 stdout에 출력하는 [`claude ultrareview` 하위 명령](/docs/ko/ultrareview#run-ultrareview-non-interactively)을 사용하세요.

177 

178<h2 id="change-or-build-on-the-review">

179 리뷰 변경 또는 확장

180</h2>

181 

182`/code-review`는 [번들 스킬](/docs/ko/skills#bundled-skills)입니다. 지침이 Claude Code에 내장되어 있으므로 디스크에 열거나 편집할 `SKILL.md` 파일이 없습니다. 모든 리뷰에 프로젝트 규칙을 적용하려면 `CLAUDE.md`에 규칙을 추가하세요. 더 나아가려면 다음 페이지 중 하나에서 시작하세요.

183 

184* **명령 대체**: `code-review`라는 이름의 프로젝트 또는 개인 스킬이 번들 스킬 대신 실행되며, `/review` 별칭은 계속 번들 리뷰를 실행합니다. [같은 이름을 공유하는 스킬 해결](/docs/ko/skills#resolve-skills-that-share-a-name)을 참조하세요.

185* **자체 리뷰어 만들기**: 리뷰어 [서브에이전트](/docs/ko/sub-agents) 또는 리뷰 [스킬](/docs/ko/skills)을 작성합니다

186* **인접 명령 사용**: [`/simplify`](/docs/ko/commands)는 정리 목적으로만 리뷰하고 수정 사항을 적용하며, [`/verify`](/docs/ko/commands)는 앱을 실행하여 변경 사항이 작동하는지 확인합니다

187 

188이 명령은 v2.1.147 이전에는 `/simplify`라는 이름이었으며, 당시에는 기본적으로 수정 사항을 적용했습니다. 버그 찾기를 위해 `/simplify`를 스크립트로 사용했다면 `/code-review --fix`로 전환하세요.

189 

190<h2 id="related-resources">

191 관련 리소스

192</h2>

193 

194* [Code Review](/docs/ko/code-review): 조직의 GitHub 모든 풀 리퀘스트를 리뷰하는 관리형 서비스

195* [Ultrareview](/docs/ko/ultrareview): 더 심층적인 클라우드 리뷰의 설정, 제한 및 비용

196* [명령](/docs/ko/commands): `/code-review`, `/review`, `/simplify`, `/verify`에 대한 한 줄 참조

197* [스킬](/docs/ko/skills): 번들 스킬의 작동 방식과 직접 스킬을 작성하는 방법

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

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

6 

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

8 

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

10 

11Owner는 각 저장소에 대해 [리뷰가 실행되는 시점](/docs/ko/code-review-setup#set-when-reviews-run)과 [리뷰의 철저한 정도](/docs/ko/code-review-setup#set-the-default-review-level)를 제어합니다.

12 

13<Note>

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

15</Note>

16 

17<h2 id="severity-levels">

18 심각도 수준

19</h2>

20 

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

22 

23| 표시 | 심각도 | 의미 |

24| :- | :- | :- |

25| 🔴 | Important | 병합 전에 수정해야 하는 버그 |

26| 🟡 | Nit | 수정할 가치는 있지만 차단하지 않는 사소한 문제 |

27| 🟣 | Pre-existing | 코드베이스에 존재하지만 이 PR에서 도입되지 않은 버그 |

28 

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

30 

31Claude가 저장소에서 지적하는 항목이나 심각도 순위를 매기는 방식을 변경하려면 [Code Review 사용자 지정](/docs/ko/code-review-customize)을 참조하세요.

32 

33<h2 id="respond-to-findings">

34 발견 사항에 응답하기

35</h2>

36 

37저장소 자체 규칙에서 요구하지 않는 한, 발견 사항에 응답하지 않고도 병합할 수 있습니다. 브랜치 보호가 [대화 해결을 요구](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-conversation-resolution-before-merging)하는 경우, 병합하기 전에 각 발견 사항의 스레드를 해결해야 합니다.

38 

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

40 

41* **코드 변경 없이 해제하기**: GitHub에서 스레드를 직접 해결합니다. 답글만으로는 발견 사항이 해제되지 않습니다.

42* **문제 수정하기**: 코드를 변경하고 푸시합니다. 풀 리퀘스트의 다음 리뷰가 문제가 수정되었다고 판단하면 이전 스레드를 해결합니다. 해당 리뷰가 푸시 시 자동으로 실행되든 직접 요청하든 마찬가지입니다.

43* **설명하거나 이의 제기하기**: 댓글에 답글을 답니다. Claude는 즉시 응답하지 않으며, 답글로 리뷰가 시작되지도 않습니다. 풀 리퀘스트의 다음 리뷰가 이전 발견 사항에 달린 답글을 읽고, 스레드를 해결하거나 후속 답글 하나를 게시할 수 있습니다. 같은 종류의 발견 사항이 계속 반복된다면 관리자(maintainer)에게 [`REVIEW.md`](/docs/ko/code-review-customize#choose-what-to-write-in-review-md)에 규칙을 추가해 달라고 요청하세요.

44 

45푸시하지 않고 다음 리뷰를 받으려면 `@claude review`를 [최상위 풀 리퀘스트 댓글](#comment-commands)로 작성합니다.

46 

47<h2 id="check-run-output">

48 체크 실행 출력

49</h2>

50 

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

52 

53| 심각도 | 파일:줄 | 문제 |

54| - | - | - |

55| 🔴 Important | `src/auth/session.ts:142` | 토큰 갱신이 로그아웃과 경합하여 오래된 세션이 활성 상태로 남음 |

56| 🟡 Nit | `src/auth/session.ts:88` | `parseExpiry`가 잘못된 입력에 대해 조용히 0을 반환함 |

57 

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

59 

60체크 실행은 neutral로 종료되거나, 푸시에서 변경된 파일이 없어 자동 리뷰가 실행되지 않은 경우 skipped로 종료됩니다. 절대 실패로 종료되지 않으므로 완료된 리뷰로 인해 필수 체크가 실패하지 않습니다. 발견 사항이 보이지 않거나 리뷰가 실행되지 않았다면 [Code Review 문제 해결](/docs/ko/code-review-troubleshooting)을 참조하세요.

61 

62<h3 id="read-the-result-from-a-script">

63 스크립트에서 결과 읽기

64</h3>

65 

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

67 

68<Steps>

69 <Step title="체크 실행 ID 찾기">

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

71 

72 ```bash theme={null}

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

74 ```

75 </Step>

76 

77 <Step title="심각도별 개수 읽기">

78 `CHECK_RUN_ID`를 해당 ID로 바꿔 체크 실행에서 개수를 읽습니다.

79 

80 ```bash theme={null}

81 gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \

82 --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

83 ```

84 

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

86 </Step>

87 

88 <Step title="결과에 따라 조치하기">

89 스크립트가 다음 경우를 처리하도록 합니다.

90 

91 * **`normal`이 0보다 큰 경우**: 병합을 제어하려면 작업을 실패시킵니다. `normal` 키는 Important 발견 사항의 개수를 담고 있으므로, Claude가 병합 전에 수정할 가치가 있는 버그를 하나 이상 발견했다는 의미입니다.

92 * **해당 줄이 없는 경우**: 발견 사항이 0개인 것이 아니라 판정이 없는 것으로 처리합니다. 실패했거나, 시간 초과되었거나, 취소되었거나, 더 새로운 리뷰로 대체된 리뷰의 체크 실행에는 이 줄이 없으며, 일부 완료된 리뷰에도 없습니다.

93 </Step>

94</Steps>

95 

96<h2 id="request-a-review">

97 리뷰 요청하기

98</h2>

99 

100풀 리퀘스트가 초안이거나 포크에서 온 경우 자동 리뷰가 건너뛰므로 [댓글 명령으로 리뷰를 요청](#review-drafts-and-pull-requests-from-forks)합니다. 풀 리퀘스트에 리뷰를 받으려면 다음 중 하나를 수행합니다.

101 

102* **열거나 준비 완료로 표시하기**: **Once after PR creation** 또는 **After every push**로 설정된 저장소에서는 풀 리퀘스트를 열거나 다시 열거나, 초안을 리뷰 준비 완료로 표시하면 리뷰가 시작됩니다.

103* **명령을 댓글로 작성하기**: 풀 리퀘스트에 [`@claude review`](#comment-commands)를 게시합니다.

104* **커밋 푸시하기**: **After every push**로 설정된 저장소나 `@claude review always`로 구독한 풀 리퀘스트에서는 푸시하면 리뷰가 시작됩니다.

105* **Re-run 클릭하기**: 포크에서 오지 않은 풀 리퀘스트에서 리뷰가 실패하거나 시간 초과된 후, 체크 실행에서 [다시 실행](/docs/ko/code-review-troubleshooting#retrigger-a-failed-or-timed-out-review)합니다.

106* **자동 재시도 기다리기**: 세션이 중단된 리뷰는 자동으로 한 번 재시도됩니다. 재시도가 진행 중일 때는 [체크 실행의 요약](/docs/ko/code-review-troubleshooting#retrigger-a-failed-or-timed-out-review)에 표시됩니다.

107 

108<h3 id="comment-commands">

109 댓글 명령

110</h3>

111 

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

113 

114| 명령 | 동작 | 사용 시점 |

115| :- | :- | :- |

116| `@claude review` | 향후 푸시에 대해 PR을 구독하지 않고 단일 리뷰를 시작합니다 | Manual로 설정된 저장소의 풀 리퀘스트처럼 지금 한 번 리뷰를 받고 싶거나, 다른 모드에서 즉시 추가 리뷰를 받고 싶을 때 |

117| `@claude review always` | 리뷰를 시작하고 이후 푸시로 트리거되는 리뷰에 PR을 구독합니다 | Manual로 설정된 저장소의 우선순위가 높은 PR처럼 이후 모든 푸시마다 새 리뷰를 시작하고 싶을 때 |

118| `@claude review once` | `@claude review`와 동일: 구독하지 않고 단일 리뷰를 시작합니다 | `@claude review`와 동일한 경우 |

119 

120이러한 명령으로 리뷰를 시작하려면 다음 조건을 모두 충족해야 합니다.

121 

122* diff 줄의 인라인 댓글이나 리뷰 본문이 아닌, 새로운 최상위 풀 리퀘스트 댓글로 게시해야 합니다. 이전 댓글을 편집하는 것은 인정되지 않습니다.

123* 명령을 댓글의 맨 앞에 두고, `always`는 명령의 나머지 부분과 같은 줄에 있어야 합니다. 대소문자는 상관없습니다.

124* 저장소에 대한 write, maintain 또는 admin 권한이 필요합니다. Claude는 댓글을 작성한 각 사용자에 대해 GitHub에서 이를 확인하며, 봇의 댓글로는 리뷰가 시작되지 않습니다.

125* 풀 리퀘스트가 열려 있어야 합니다.

126 

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

128 

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

130 

131<Note>

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

133</Note>

134 

135<h3 id="what-a-later-review-covers">

136 이후 리뷰가 다루는 범위

137</h3>

138 

139푸시 후처럼 자체적으로 시작되는 이후 리뷰는 마지막 리뷰 이후 변경된 내용에 집중하며, Nit과 기존 발견 사항을 더 적게 게시합니다. 요약에는 제외한 항목의 개수가 "found and not posted" 또는 "outside the scope of this re-review and not posted."로 끝나는 줄에 표시됩니다.

140 

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

142 

143<h3 id="review-drafts-and-pull-requests-from-forks">

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

145</h3>

146 

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

148 

149* **초안 풀 리퀘스트**: 댓글 명령은 초안에서도 실행되므로 풀 리퀘스트를 준비 완료로 표시하기 전에 리뷰를 요청할 수 있습니다. `@claude review always` 이후에도 초안에 대한 푸시로는 리뷰가 시작되지 않습니다. 구독은 풀 리퀘스트를 준비 완료로 표시하면 적용됩니다.

150* **포크의 풀 리퀘스트**: 저장소의 **Review runs** 설정과 관계없이 Claude는 포크에서 온 풀 리퀘스트를 자동으로 리뷰하지 않습니다. 리뷰를 시작하려면 풀 리퀘스트에 `@claude review`를 댓글로 작성합니다. [댓글 명령의 조건](#comment-commands)은 그대로 적용되며, 필요한 쓰기 권한은 포크가 아닌 기본 저장소에 대한 것입니다.

151 

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

153 

154<h3 id="use-code-review-alongside-the-claude-code-github-action">

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

156</h3>

157 

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

159 

160<h2 id="related-resources">

161 관련 리소스

162</h2>

163 

164* [Code Review 문제 해결](/docs/ko/code-review-troubleshooting): 시작되지 않았거나, 실패했거나, 예산 때문에 건너뛴 리뷰

165* [Code Review](/docs/ko/code-review): 서비스 개요 및 리뷰 실행 방식

166* [Code Review 설정하기](/docs/ko/code-review-setup): Owner용, Code Review를 켜고 리뷰 실행 시점과 수준 선택

167* [Code Review 사용자 지정](/docs/ko/code-review-customize): `REVIEW.md`와 `CLAUDE.md`로 Claude가 지적하는 항목 변경

168* [Code Review 비용 및 사용량](/docs/ko/code-review-costs): 리뷰 요금 청구 방식과 지출 한도 설정 위치

169* [`/code-review`로 로컬에서 리뷰하기](/docs/ko/code-review-local): Claude Code 세션에서 브랜치 리뷰 실행

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Code Review 설정

6 

7> Claude 조직에서 Code Review를 켭니다. GitHub를 연결하고, Claude GitHub App을 설치하고, 저장소를 선택하고, 리뷰 실행 시점을 설정합니다

8 

9Claude 조직의 Owner는 claude.ai의 [**관리자 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review)에서 Code Review를 켭니다. 리뷰는 Anthropic 인프라에서 실행되므로 저장소에 워크플로 파일을 추가할 필요가 없습니다.

10 

11설정 후에는 각 저장소에서 리뷰의 철저함 수준과 실행 시점을 선택합니다. 리뷰 수준이 높을수록, 그리고 리뷰가 더 자주 실행될수록 비용이 더 많이 듭니다. [Code Review 비용](/docs/ko/code-review-costs#pricing)을 참조하세요.

12 

13<h2 id="what-you-need-to-turn-on-code-review">

14 Code Review를 켜는 데 필요한 사항

15</h2>

16 

17먼저 조직이 [Code Review 사용 자격을 갖추었는지](/docs/ko/code-review#availability) 확인합니다. 그런 다음 아래 접근 권한이 있는지, 또는 해당 권한을 가진 사람이 있는지 확인합니다.

18 

19| 접근 권한 | 필요한 작업 |

20| :- | :- |

21| Claude 조직의 [Owner 역할](/docs/ko/server-managed-settings#access-control) | 관리자 페이지의 모든 단계 |

22| GitHub 조직의 owner | Claude GitHub App 설치 및 [Claude 조직에 연결](/docs/ko/admin-setup#connected-github-accounts). owner가 아닌 경우, 시작하기 전에 owner에게 앱 설치와 연결을 요청하세요 |

23| Claude에 연결하는 GitHub 계정에서 추가하려는 각 저장소에 대한 쓰기 권한 | 저장소 추가 |

24 

25<h2 id="turn-on-code-review">

26 Code Review 켜기

27</h2>

28 

29<Steps>

30 <Step title="Allow code review 스위치 클릭">

31 [**관리자 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review)의 **Code review** 섹션으로 이동하여 **Allow code review** 스위치를 클릭합니다.

32 

33 대화 상자 없이 Code Review가 바로 켜진다면, 조직에 이미 Claude GitHub App이 연결되어 있거나 저장소가 추가되어 있는 것입니다. [저장소 더 추가하기](#add-more-repositories)로 이동한 후 마지막 단계를 위해 다시 돌아오세요.

34 </Step>

35 

36 <Step title="GitHub 계정 연결">

37 **Connect GitHub** 대화 상자가 열리면 **Connect**를 클릭합니다. 조직에서 GitHub Enterprise Server를 사용하는 경우, 먼저 대화 상자에서 인스턴스를 선택합니다. GitHub에서 Claude 인증을 요청한 후, **Add a repository** 대화 상자가 열린 상태로 관리자 페이지로 돌아옵니다.

38 

39 **Add a repository**가 바로 열렸다면 계정이 이미 연결된 것이므로 다음 단계로 넘어갑니다.

40 </Step>

41 

42 <Step title="Claude GitHub App 설치">

43 원하는 저장소가 **Add a repository** 대화 상자에 표시되거나 검색으로 찾을 수 있다면 다음 단계로 넘어갑니다. 대화 상자에는 Claude GitHub App이 접근할 수 있는 저장소만 표시되므로, 저장소가 없다면 앱을 설치합니다.

44 

45 * **Install GitHub App**을 클릭합니다. 표시되는 저장소가 없으면 대화 상자에 버튼으로 나타납니다. 그렇지 않으면 대화 상자의 GitHub 조직 필터 메뉴 하단에 있습니다. GitHub 설치 페이지가 새 탭에서 열립니다.

46 * 저장소를 소유한 GitHub 조직을 선택합니다.

47 * 앱이 접근할 수 있는 저장소를 선택합니다.

48 * 요청된 권한을 승인합니다. 이 권한 세트는 리뷰에 사용되는 범위보다 넓으며 [GitHub Actions](/docs/ko/github-actions) 같은 다른 Claude 기능과 공유됩니다. [리뷰가 접근할 수 있는 항목](/docs/ko/code-review#what-a-review-can-access)과 [전체 권한 목록](/docs/ko/github-actions#github-app-permissions)을 참조하세요.

49 * 설치가 완료되면 탭이 Claude로 돌아옵니다. **Finish connecting GitHub** 버튼이 표시되면 클릭하여 설치를 Claude 조직에 연결합니다.

50 * 관리자 페이지 탭으로 돌아가면 대화 상자의 목록이 새로 고쳐집니다.

51 </Step>

52 

53 <Step title="저장소 선택">

54 리뷰할 저장소를 선택한 후 **Continue**를 클릭합니다. 저장소를 추가하려면 연결한 GitHub 계정에 해당 저장소에 대한 쓰기 권한이 있어야 합니다. 나중에 [저장소를 더 추가](#add-more-repositories)할 수 있습니다.

55 </Step>

56 

57 <Step title="Finish 클릭">

58 이어서 **Code review is set up** 대화 상자가 나타납니다. **Finish**를 클릭하여 Code Review를 켭니다. 다른 방법으로 대화 상자를 닫으면 저장소는 추가된 상태로 유지되지만 **Allow code review**는 꺼진 상태로 남으며, 스위치에서 직접 켜야 합니다.

59 

60 각 저장소는 처음에 푸시할 때마다 리뷰하도록 설정되며, 이 설정에서 리뷰가 가장 많이 실행됩니다. 리뷰 횟수를 줄이려면 [리뷰 실행 시점을 설정](#set-when-reviews-run)하세요.

61 </Step>

62 

63 <Step title="테스트 풀 리퀘스트로 확인">

64 추가한 저장소 중 하나에서 테스트 풀 리퀘스트를 열고, 드래프트로 표시하지 않습니다. 몇 분 내에 **Claude Code Review**라는 이름의 check run이 나타납니다. 저장소를 이미 \*\*Manual (@claude review)\*\*로 설정했다면, 풀 리퀘스트에 `@claude review`라는 댓글을 달아 첫 리뷰를 시작합니다.

65 

66 check run이 나타나지 않으면 [테스트 풀 리퀘스트에 check run이 나타나지 않음](/docs/ko/code-review-troubleshooting#no-check-run-appears-on-the-test-pull-request)을 참조하세요.

67 

68 리뷰가 도착하면 개발자들에게 [풀 리퀘스트에서 리뷰 읽기 및 요청하기](/docs/ko/code-review-pull-requests)를 공유하세요. 이 문서에서는 심각도 수준, 댓글 명령, 발견 사항에 대응하는 방법을 다룹니다.

69 </Step>

70</Steps>

71 

72<h2 id="set-defaults-for-your-organization">

73 조직 기본값 설정

74</h2>

75 

76Owner는 리뷰의 철저함 수준과 실행 빈도를 결정합니다. 두 설정 모두 [**관리자 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review)의 **Code review** 섹션에 있습니다.

77 

78<h3 id="set-the-default-review-level">

79 기본 리뷰 수준 설정

80</h3>

81 

82리뷰 수준은 각 리뷰의 철저함을 결정하며, 더 철저한 리뷰일수록 비용이 더 많이 듭니다. 조직에 하나의 기본값을 설정하고 개별 저장소에서 이를 재정의할 수 있습니다.

83 

84| 수준 | 절충 사항 |

85| :- | :- |

86| Quick | 가벼운 검토. 가장 빠르고 비용이 가장 낮은 수준입니다 |

87| Standard | 깊이, 속도, 비용의 균형. 기본 수준입니다 |

88| Deep | 가장 철저한 검토. 시간이 가장 오래 걸리고 비용이 가장 많이 듭니다 |

89 

90* **조직 기본값**: **Review level**에서 수준을 선택하고 **Change level**로 확정합니다. 저장소에 별도 수준을 지정하지 않는 한 모든 저장소가 이 값을 사용합니다.

91* **개별 저장소**: 저장소 행에서 **Edit**를 클릭한 후 **Review level**을 선택합니다. 첫 번째 옵션인 **Default**는 조직 설정을 따릅니다. 수준은 선택하는 즉시 저장됩니다.

92 

93새 수준은 변경 후 시작되는 리뷰에 적용됩니다. 각 리뷰의 비용에 영향을 주는 다른 요인은 [Code Review 비용 및 사용량](/docs/ko/code-review-costs)을 참조하세요.

94 

95<h3 id="set-when-reviews-run">

96 리뷰 실행 시점 설정

97</h3>

98 

99각 저장소에는 자체 **Review runs** 설정이 있으며, 이 설정이 풀 리퀘스트가 리뷰되는 시점을 결정합니다.

100 

101* **Once after PR creation**: 풀 리퀘스트가 열리거나, 다시 열리거나, 리뷰 준비 완료로 표시될 때 리뷰가 실행됩니다

102* **After every push**: 풀 리퀘스트 브랜치에 푸시할 때 리뷰가 실행되어, 풀 리퀘스트가 발전함에 따라 새로운 문제를 포착하고 플래그된 문제를 수정하면 스레드를 자동으로 해결합니다

103* **Manual (@claude review)**: 풀 리퀘스트를 열거나 푸시해도 리뷰가 시작되지 않습니다. 리뷰를 요청하려면 [`@claude review`](/docs/ko/code-review-pull-requests#comment-commands) 댓글을 달고, 이후 푸시에도 리뷰를 받도록 풀 리퀘스트를 구독하려면 `@claude review always` 댓글을 답니다.

104 

105Manual은 특정 풀 리퀘스트만 선택적으로 리뷰하려는 트래픽이 많은 저장소나, 풀 리퀘스트가 준비된 후에만 리뷰를 시작하려는 경우에 유용합니다. 각 옵션이 비용에 미치는 영향을 비교하려면 [리뷰 실행 빈도](/docs/ko/code-review-costs#how-often-reviews-run)를 참조하세요.

106 

107설정을 변경하려면 **Repositories** 표에서 저장소 행의 **Edit**를 클릭하고 **Review runs** 옵션을 선택합니다. 선택은 즉시 저장되며, 표의 **Review runs** 열에는 Once per PR, Every push, Manual로 축약되어 표시됩니다.

108 

109* **드래프트 및 포크에서 온 풀 리퀘스트**: 어떤 옵션을 선택하든 [자동 리뷰는 둘 다 건너뜁니다](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks)

110* **새 저장소**: **Add a repository** 대화 상자에서 추가한 저장소는 **After every push**로 시작합니다. 해당 GitHub 조직이 [전체적으로 적용](#cover-a-whole-github-organization)된 경우에는 대신 해당 조직 행의 설정을 따릅니다.

111 

112<h3 id="turn-tip-comments-on-or-off">

113 팁 댓글 켜기 또는 끄기

114</h3>

115 

116팁 댓글은 리뷰가 시작되지 않을 때 Claude가 풀 리퀘스트에 게시하는 짧은 댓글로, 그 이유와 다음에 할 일을 알려 줍니다. **Show tips on pull requests**는 기본적으로 켜져 있습니다. 이 설정이 켜져 있으면 Claude는 다음 각 경우에 팁을 게시하여 설명합니다.

117 

118* **저장소가 Manual로 설정된 경우**: 댓글로 리뷰를 요청하는 방법

119* **풀 리퀘스트가 포크에서 온 경우**: 메인테이너가 리뷰를 요청할 수 있다는 점

120* **봇 또는 쓰기 권한이 없는 사람이 `@claude review` 댓글을 단 경우**: 리뷰가 시작되지 않았다는 점과 리뷰를 요청할 수 있는 사람

121* **GitHub 조직이 Claude 조직에 연결되지 않은 경우**: 리뷰가 일시 중지되었다는 점과 연결하는 방법

122 

123이러한 댓글을 중지하려면 설정을 끕니다.

124 

125<h3 id="what-developers-can-change">

126 개발자가 변경할 수 있는 항목

127</h3>

128 

129리뷰 수준, **Review runs** 설정, 리뷰 대상 저장소를 변경하려면 개발자가 Owner에게 요청해야 합니다. Owner 역할이 없어도 개발자는 GitHub에서 다음 작업을 할 수 있습니다.

130 

131* **리뷰 요청**: 풀 리퀘스트에 [`@claude review`](/docs/ko/code-review-pull-requests#comment-commands) 댓글을 답니다. 이 작업에는 저장소에 대한 쓰기 권한이 필요하며, 자동 리뷰가 건너뛰는 [드래프트 및 포크에서 온 풀 리퀘스트](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks)에서도 작동합니다.

132* **푸시할 때마다 리뷰를 받도록 풀 리퀘스트 구독**: Manual로 설정된 저장소 등에서 [드래프트가 아니거나 포크에서 오지 않은](/docs/ko/code-review-pull-requests#review-drafts-and-pull-requests-from-forks) 풀 리퀘스트에 `@claude review always` 댓글을 답니다

133* **리뷰가 플래그하는 항목 변경**: 예를 들어 검사를 추가하기 위해 저장소에 [`REVIEW.md` 및 `CLAUDE.md` 파일](/docs/ko/code-review-customize)을 커밋합니다

134 

135개발자가 요청한 리뷰는 [조직에 청구됩니다](/docs/ko/code-review-costs#pricing). Code Review의 월간 지출을 제한하려면 [지출 제한](/docs/ko/code-review-costs#limit-your-spend)을 참조하세요.

136 

137<h2 id="manage-repositories">

138 저장소 관리

139</h2>

140 

141저장소를 하나씩 추가하거나 GitHub 조직 전체를 한 번에 적용할 수 있으며, 원하지 않는 곳에서는 리뷰를 중지할 수 있습니다.

142 

143<h3 id="add-more-repositories">

144 저장소 더 추가하기

145</h3>

146 

147설정 후 저장소를 추가하려면 **Code review** 섹션의 **Repositories** 표 위에 있는 **Add**를 클릭합니다. **Add a repository** 대화 상자가 열립니다. 저장소를 선택하고 **Continue**를 클릭합니다.

148 

149* **저장소가 목록에 없는 경우**: [Add a repository에 저장소가 표시되지 않음](/docs/ko/code-review-troubleshooting#a-repository-isn’t-listed-in-add-a-repository)을 참조하세요.

150* **GitHub 조직의 모든 저장소를 원하는 경우**: 저장소를 하나씩 선택하는 대신 [조직 전체를 적용](#cover-a-whole-github-organization)합니다

151 

152<h3 id="cover-a-whole-github-organization">

153 GitHub 조직 전체 적용

154</h3>

155 

156GitHub 조직의 모든 저장소에서 Code Review를 켜려면 **Repositories** 표에서 해당 조직 행의 **Review runs**를 설정합니다. 이렇게 하면 나중에 추가되는 저장소를 포함하여 Claude GitHub App이 접근할 수 있는 해당 조직의 모든 저장소가 적용 대상이 됩니다. 이로 인해 지출이 크게 늘어날 수 있습니다. 다음 조건을 모두 충족해야 합니다.

157 

158* Claude에 연결한 GitHub 계정이 해당 GitHub 조직의 owner여야 합니다.

159* 조직이 github.com에 있어야 합니다. GitHub Enterprise Server 인스턴스와 개인 GitHub 계정은 해당되지 않습니다.

160* Claude 조직 또는 Code Review에 대한 [월간 지출 한도](/docs/ko/code-review-costs#limit-your-spend)가 설정되어 있어야 합니다.

161 

162조직 전체를 적용하려면 해당 행의 **Edit**를 클릭하고 **Review runs** 옵션을 선택한 후 확정합니다. 옵션은 [리뷰 실행 시점 설정](#set-when-reviews-run)의 세 가지 옵션에 **Off**가 추가된 것입니다.

163 

164확정하면 다음 변경 사항이 적용됩니다.

165 

166* **적용 범위**: 각 저장소는 다음 풀 리퀘스트부터 적용됩니다. Claude GitHub App이 모든 저장소가 아닌 선택한 저장소에만 설치된 경우 Claude는 해당 저장소만 리뷰합니다. 나머지 저장소도 적용하려면 GitHub에서 앱의 저장소 접근 권한을 변경하세요.

167* **기존 설정**: 개별적으로 설정한 저장소를 포함하여 해당 GitHub 조직의 모든 저장소가 선택한 옵션을 따릅니다. 행을 다시 설정해도 마찬가지입니다. 각 저장소 행에서 끈 저장소는 꺼진 상태로 유지됩니다.

168* **이후 개별 변경**: 나중에 조직과 다르게 설정한 저장소는 표에 **Custom**으로 표시됩니다.

169* **리뷰 수준**: 조직 행에는 자체 리뷰 수준이 없습니다.

170 

171<h3 id="turn-off-code-review-or-remove-a-repository">

172 Code Review 끄기 또는 저장소 제거

173</h3>

174 

175[**관리자 설정 > Claude Code**](https://claude.ai/admin-settings/claude-code#code-review)의 **Code review** 섹션에서 중지하려는 대상에 맞는 컨트롤을 선택합니다.

176 

177* **저장소 하나, 목록에는 유지**: 해당 행의 **Edit**를 클릭하고 **Code review**를 끕니다. 표에 저장소가 Off로 표시됩니다.

178* **저장소 하나, 제거**: 해당 행의 **Edit**를 클릭한 후 대화 상자 하단의 **Remove repository**를 클릭합니다. 해당 저장소의 리뷰가 중지되며, 이후 다른 Claude 조직이 해당 저장소를 설정할 수 있습니다. 저장소의 GitHub 조직이 전체적으로 적용된 동안에는 제거할 수 없으므로 대신 **Code review** 스위치를 끕니다.

179* **GitHub 조직 전체**: 조직 행의 **Edit**를 클릭하고 **Off**를 선택합니다. 이렇게 하면 해당 조직에서 하나씩 추가한 저장소도 꺼집니다.

180* **전체**: **Allow code review**를 끕니다. 어떤 저장소에서도 새 리뷰가 시작되지 않으며, 저장소 목록은 유지되므로 나중에 다시 켤 수 있습니다.

181 

182<h2 id="related-resources">

183 관련 리소스

184</h2>

185 

186* [Code Review 비용 및 사용량](/docs/ko/code-review-costs): 리뷰 수준과 리뷰 실행 시점이 지출에 미치는 영향, 지출 한도 설정 방법, 사용량 확인 위치

187* [풀 리퀘스트에서 리뷰 읽기 및 요청하기](/docs/ko/code-review-pull-requests): 개발자가 풀 리퀘스트에서 보는 내용과 댓글 명령

188* [Code Review 사용자 지정](/docs/ko/code-review-customize): `REVIEW.md` 및 `CLAUDE.md`로 Claude가 플래그하는 항목 조정

189* [GitHub Enterprise Server](/docs/ko/github-enterprise-server): 설정 전에 자체 호스팅 GitHub 인스턴스 연결

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Code Review 문제 해결

6 

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

8 

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

10 

11<h2 id="check-how-far-the-review-got">

12 리뷰 진행 상황 확인하기

13</h2>

14 

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

16 

17| 체크 실행 제목 | 의미 | 조치 |

18| :- | :- | :- |

19| **Code review queued...** 또는 **Code review in progress...** | 리뷰가 아직 완료되지 않았습니다 | 제목이 바뀔 때까지 기다립니다 |

20| **Code review found no issues** | 리뷰가 완료되었으며 지적할 사항을 찾지 못했습니다 | 조치가 필요하지 않습니다 |

21| 문제가 발견되었다는 제목 | 리뷰가 발견 사항과 함께 완료되었습니다 | diff에서 발견 사항이 보이지 않으면 [인라인 댓글로 표시되지 않는 문제 찾기](#find-issues-that-aren’t-showing-as-inline-comments)를 참조하세요 |

22| **Code review skipped — no new changes** | 최근 푸시에 대해 자동 리뷰가 실행되지 않았습니다 | 그래도 리뷰를 받으려면 `@claude review`라고 댓글을 작성합니다 |

23| **Code review failed** 또는 **Code review timed out** | 리뷰가 완료되지 않았습니다 | 다시 실행하려면 [실패하거나 시간 초과된 리뷰 다시 트리거하기](#retrigger-a-failed-or-timed-out-review)를 참조하세요 |

24| **Code review declined** | 리뷰가 실행되지 않았습니다 | 체크 실행의 요약을 읽습니다. 요약에 예산이나 지출 한도가 언급되어 있으면 [리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요 |

25| 체크 실행 없음 | 리뷰가 시작되지 않았습니다 | `@claude review`라고 댓글을 작성합니다. 그 후에도 체크 실행이 나타나지 않으면 [댓글 명령으로 리뷰가 시작되지 않는 경우](#a-comment-command-didn’t-start-a-review)를 참조하세요 |

26 

27<h2 id="a-review-didn’t-start">

28 리뷰가 시작되지 않는 경우

29</h2>

30 

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

32 

33<h3 id="a-comment-command-didn’t-start-a-review">

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

35</h3>

36 

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

38 

39* **이 저장소에 Code Review가 켜져 있지 않음**: Claude가 명령에 대한 응답으로 댓글이나 체크 실행을 게시하지 않습니다. Owner에게 [저장소 추가](/docs/ko/code-review-setup#add-more-repositories)를 요청합니다.

40* **댓글이 조건을 충족하지 않음**: 새 최상위 댓글이 아니라 인라인 댓글이나 리뷰 본문이었거나, 명령이 댓글의 시작 부분에 있지 않았습니다. 새 댓글을 게시하지 않고 이전 댓글을 편집한 경우도 인정되지 않으며, 풀 리퀘스트가 열려 있어야 합니다. [댓글 명령의 조건](/docs/ko/code-review-pull-requests#comment-commands)을 확인하고 이를 충족하는 새 댓글을 게시합니다.

41* **쓰기 권한이 없음**: 저장소에 대한 write, maintain 또는 admin 권한이 필요하며, 포크에서 생성된 풀 리퀘스트의 경우 기본 저장소에 대한 권한이 기준이 됩니다. 조직에서 팁을 켜 둔 경우 Claude가 "No review was started: manual reviews can only be requested by someone with write access to this repository."라고 답장합니다. 쓰기 권한이 있는 사람에게 대신 댓글을 작성해 달라고 요청합니다.

42* **예산 소진**: Claude가 "⚠️ Code review skipped"로 시작하는 댓글을 게시합니다. [리뷰가 실행되지 않고 PR에 예산 메시지가 표시되는 경우](#review-didn’t-run-and-the-pr-shows-a-budget-message)를 참조하세요.

43 

44<h3 id="review-didn’t-run-and-the-pr-shows-a-budget-message">

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

46</h3>

47 

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

49 

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

51 

52* **"has reached its monthly code review spending cap"**: [Code Review의 월간 지출 한도](/docs/ko/code-review-costs#limit-your-spend)에 도달했습니다. 리뷰는 다음 청구 기간이 시작될 때 재개됩니다. 더 일찍 리뷰를 받으려면 관리자에게 한도를 높여 달라고 요청합니다.

53* **"has no extra usage available to pay for this review"**: 조직의 [사용량 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 잔액이 비어 있거나, 전체 월간 지출 한도에 도달했습니다. 관리자에게 사용량 크레딧을 추가하거나 해당 한도를 높여 달라고 요청합니다.

54* **"is too low to start another review"**: 남은 예산이나 잔액이 리뷰 1회의 예상 비용보다 적습니다. 관리자에게 한도를 높이거나 사용량 크레딧을 추가해 달라고 요청합니다.

55