Documentation — Spybara

claude-apps-gateway-deploy.md +28 −26

Details

6 6

7> IdP에 게이트웨이를 등록하고, 컨테이너를 빌드하며, Kubernetes 또는 Cloud Run에 배포하고 운영합니다: 상태 확인, 시크릿 로테이션, 업그레이드 및 보안.7> IdP에 게이트웨이를 등록하고, 컨테이너를 빌드하며, Kubernetes 또는 Cloud Run에 배포하고 운영합니다: 상태 확인, 시크릿 로테이션, 업그레이드 및 보안.

8 8

9이 페이지는 [Claude 앱 게이트웨이](/ko/claude-apps-gateway) 실행의 운영 측면을 다룹니다: 게이트웨이를 ID 공급자(IdP)에 등록하고, 게이트웨이를 컨테이너로 배포하며, 일상적으로 운영합니다. 게이트웨이가 부팅 시 읽는 `gateway.yaml` 파일의 모든 옵션에 대해서는 [구성 참조](/ko/claude-apps-gateway-config)를 참조하세요.9이 페이지는 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway) 실행의 운영 측면을 다룹니다: 게이트웨이를 ID 공급자(IdP)에 등록하고, 게이트웨이를 컨테이너로 배포하며, 일상적으로 운영합니다. 게이트웨이가 부팅 시 읽는 `gateway.yaml` 파일의 모든 옵션에 대해서는 [구성 참조](/docs/ko/claude-apps-gateway-config)를 참조하세요.

10 10

11프로덕션 배포는 순서대로 4단계를 따르며, 아래 섹션이 이를 일치시킵니다. 처음 두 단계는 선택을 하는 곳이고, 나머지 두 단계는 실행 중일 때 참조할 참고 자료입니다.11프로덕션 배포는 순서대로 4단계를 따르며, 아래 섹션이 이를 일치시킵니다. 처음 두 단계는 선택을 하는 곳이고, 나머지 두 단계는 실행 중일 때 참조할 참고 자료입니다.

12 12

31 31

32모든 OIDC 호환 IdP가 작동합니다: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate 등. IdP는 세 가지 요구사항을 충족해야 합니다:32모든 OIDC 호환 IdP가 작동합니다: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, PingFederate 등. IdP는 세 가지 요구사항을 충족해야 합니다:

33 33

34* `/.well-known/openid-configuration`을 프로덕션에서 HTTPS를 통해 제공합니다. 게이트웨이는 [`http://` 발급자](/ko/claude-apps-gateway-config#oidc)를 허용하며, 루프백 발급자는 추가로 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`이 필요합니다34* `/.well-known/openid-configuration`을 프로덕션에서 HTTPS를 통해 제공합니다. 게이트웨이는 [`http://` 발급자](/docs/ko/claude-apps-gateway-config#oidc)를 허용하며, 루프백 발급자는 추가로 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`이 필요합니다

35* 인증 코드 흐름을 지원합니다. PKCE(Proof Key for Code Exchange)는 기본적으로 활성화되어 있습니다. 이를 지원하지 않는 IdP의 경우 `oidc.use_pkce: false`로 비활성화하세요35* 인증 코드 흐름을 지원합니다. PKCE(Proof Key for Code Exchange)는 기본적으로 활성화되어 있습니다. 이를 지원하지 않는 IdP의 경우 `oidc.use_pkce: false`로 비활성화하세요

36* id\_token에서 `email`을 반환하고 선택적으로 `groups`를 반환하거나, `oidc.userinfo_fallback: true`를 사용하여 userinfo 엔드포인트에서 제공합니다36* id\_token에서 `email`을 반환하고 선택적으로 `groups`를 반환하거나, `oidc.userinfo_fallback: true`를 사용하여 userinfo 엔드포인트에서 제공합니다

37 37

41 41

42* **Okta**: `https://example.okta.com`의 조직 인증 서버는 `email` 및 `groups`를 생략하는 얇은 id\_token을 반환하므로, 이를 `issuer`로 사용할 때마다 `oidc.userinfo_fallback: true`를 설정하세요. `https://example.okta.com/oauth2/default`와 같은 id\_token에 `email` 및 선택적으로 `groups`를 포함하는 사용자 정의 인증 서버는 이를 직접 내보내며 폴백이 필요하지 않습니다. Okta는 `oidc.scopes`에서 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가 이를 허용할 때만 `groups`를 내보냅니다. `userinfo_fallback`은 IdP가 요청하지 않은 클레임을 채울 수 없습니다.42* **Okta**: `https://example.okta.com`의 조직 인증 서버는 `email` 및 `groups`를 생략하는 얇은 id\_token을 반환하므로, 이를 `issuer`로 사용할 때마다 `oidc.userinfo_fallback: true`를 설정하세요. `https://example.okta.com/oauth2/default`와 같은 id\_token에 `email` 및 선택적으로 `groups`를 포함하는 사용자 정의 인증 서버는 이를 직접 내보내며 폴백이 필요하지 않습니다. Okta는 `oidc.scopes`에서 `groups` 범위가 요청되고 앱의 그룹 클레임 필터가 이를 허용할 때만 `groups`를 내보냅니다. `userinfo_fallback`은 IdP가 요청하지 않은 클레임을 채울 수 없습니다.

43* **Microsoft Entra ID**: `issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`. Entra는 이름이 아닌 그룹 개체 ID를 내보내므로, `managed.policies.match.groups`에서 GUID를 사용하거나 인간이 읽을 수 있는 이름을 위해 앱 역할을 사용하세요. 테넌트가 `groups` 대신 `roles` 아래에 역할을 내보내는 경우 `oidc.groups_claim: roles`을 설정하세요.43* **Microsoft Entra ID**: `issuer` = `https://login.microsoftonline.com/<tenant-id>/v2.0`. Entra는 이름이 아닌 그룹 개체 ID를 내보내므로, `managed.policies.match.groups`에서 GUID를 사용하거나 인간이 읽을 수 있는 이름을 위해 앱 역할을 사용하세요. 테넌트가 `groups` 대신 `roles` 아래에 역할을 내보내는 경우 `oidc.groups_claim: roles`을 설정하세요.

44* **Google Workspace**: `issuer` = `https://accounts.google.com`. Google의 id\_token은 그룹을 전달하지 않습니다. Google을 IdP로 사용하여 그룹 기반 `allowed_groups` 또는 `managed.policies`를 사용하려면 [`oidc.google_groups`](/ko/claude-apps-gateway-config#oidc)를 구성하세요. 이는 도메인 전체 위임이 있는 서비스 계정을 사용하여 Admin SDK Directory API를 통해 각 사용자의 그룹을 조회합니다. 이 없이는 멤버십 게이팅을 위해 `oidc.allowed_email_domains`를 사용하고 정책 할당을 위해 `managed.policies.match.email_domain`을 사용하세요. Google은 또한 표준 `offline_access` 범위를 무시합니다. 새로고침 토큰의 경우 `oidc.scopes: [openid, profile, email]`과 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`를 설정하세요.44* **Google Workspace**: `issuer` = `https://accounts.google.com`. Google의 id\_token은 그룹을 전달하지 않습니다. Google을 IdP로 사용하여 그룹 기반 `allowed_groups` 또는 `managed.policies`를 사용하려면 [`oidc.google_groups`](/docs/ko/claude-apps-gateway-config#oidc)를 구성하세요. 이는 도메인 전체 위임이 있는 서비스 계정을 사용하여 Admin SDK Directory API를 통해 각 사용자의 그룹을 조회합니다. 이 없이는 멤버십 게이팅을 위해 `oidc.allowed_email_domains`를 사용하고 정책 할당을 위해 `managed.policies.match.email_domain`을 사용하세요. Google은 또한 표준 `offline_access` 범위를 무시합니다. 새로고침 토큰의 경우 `oidc.scopes: [openid, profile, email]`과 `oidc.extra_auth_params: { access_type: offline, prompt: consent }`를 설정하세요.

45 45

46위에서 다루지 않은 ID 공급자에 대한 지원은 [문제 해결](#troubleshooting)을 참조하세요.46위에서 다루지 않은 ID 공급자에 대한 지원은 [문제 해결](#troubleshooting)을 참조하세요.

47 47

48<Warning>48<Warning>

49 새로고침 토큰을 사용하면 게이트웨이가 개발자를 브라우저로 다시 보내지 않고 개발자의 세션을 자동으로 갱신할 수 있습니다. 또한 IdP가 사용자를 비활성화할 때 다음 새로고침이 실패하고 세션이 `ttl_hours` 내에 종료되므로 프로비저닝 해제를 주도합니다. 게이트웨이는 기본적으로 새로고침 토큰을 얻기 위해 `offline_access`를 요청합니다. IdP가 오프라인 액세스에 대한 명시적 동의를 요구하는 경우 OAuth 클라이언트를 구성하여 이를 허용하세요.49 새로고침 토큰을 사용하면 게이트웨이가 개발자를 브라우저로 다시 보내지 않고 개발자의 세션을 자동으로 갱신할 수 있습니다. 또한 IdP가 사용자를 비활성화할 때 다음 새로고침이 실패하고 세션이 `ttl_hours` 내에 종료되므로 프로비저닝 해제를 주도합니다. 게이트웨이는 기본적으로 새로고침 토큰을 얻기 위해 `offline_access`를 요청합니다. IdP가 오프라인 액세스에 대한 명시적 동의를 요구하는 경우 OAuth 클라이언트를 구성하여 이를 허용하세요.

50 50

51 IdP가 전혀 새로고침 토큰을 발급할 수 없는 경우, 게이트웨이는 여전히 작동하지만 자동 갱신이 없으므로 개발자는 세션이 만료될 때 브라우저 로그인을 다시 실행합니다. 이것이 매시간 발생하지 않도록 하려면 [`session.ttl_hours`](/ko/claude-apps-gateway-config#session)를 `8` 또는 `12`로 올리세요. 트레이드오프는 프로비저닝 해제 지연입니다. 새로고침 토큰이 없으면 비활성화된 사용자는 더 긴 TTL이 경과할 때까지 액세스를 유지합니다.51 IdP가 전혀 새로고침 토큰을 발급할 수 없는 경우, 게이트웨이는 여전히 작동하지만 자동 갱신이 없으므로 개발자는 세션이 만료될 때 브라우저 로그인을 다시 실행합니다. 이것이 매시간 발생하지 않도록 하려면 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 `8` 또는 `12`로 올리세요. 트레이드오프는 프로비저닝 해제 지연입니다. 새로고침 토큰이 없으면 비활성화된 사용자는 더 긴 TTL이 경과할 때까지 액세스를 유지합니다.

52</Warning>52</Warning>

53 53

54<h2 id="deployment">54<h2 id="deployment">

62몇 가지 결정이 실행 위치 이상으로 배포를 형성합니다:62몇 가지 결정이 실행 위치 이상으로 배포를 형성합니다:

63 63

64* **비용**: 게이트웨이에 대한 별도의 라이선스 또는 사용자당 요금이 없습니다. 이는 `claude` 바이너리의 일부입니다. 기존 클라우드 또는 Anthropic 약정을 통해 추론에 대해 비용을 지불하고, 컨테이너 및 텔레메트리 수집기의 컴퓨팅을 지불합니다.64* **비용**: 게이트웨이에 대한 별도의 라이선스 또는 사용자당 요금이 없습니다. 이는 `claude` 바이너리의 일부입니다. 기존 클라우드 또는 Anthropic 약정을 통해 추론에 대해 비용을 지불하고, 컨테이너 및 텔레메트리 수집기의 컴퓨팅을 지불합니다.

65* **우회**: 게이트웨이는 모델로의 유일한 경로가 이를 통과하도록 강제하지 않습니다. 자신의 자격 증명이 있는 개발자는 여전히 공급자를 직접 호출할 수 있으므로, 해당 경로를 닫는 것은 네트워크 정책 결정입니다. 예를 들어 `api.anthropic.com`으로의 송신을 게이트웨이를 제외하고 차단합니다. 해당 송신을 차단하면 각 개발자의 머신에서 `api.anthropic.com`을 호출하는 [WebFetch 도메인 안전 확인](/ko/data-usage#webfetch-domain-safety-check)도 중단됩니다. 관리형 정책에서 `skipWebFetchPreflight: true`를 설정하여 비활성화하세요.65* **우회**: 게이트웨이는 모델로의 유일한 경로가 이를 통과하도록 강제하지 않습니다. 자신의 자격 증명이 있는 개발자는 여전히 공급자를 직접 호출할 수 있으므로, 해당 경로를 닫는 것은 네트워크 정책 결정입니다. 예를 들어 `api.anthropic.com`으로의 송신을 게이트웨이를 제외하고 차단합니다. 해당 송신을 차단하면 각 개발자의 머신에서 `api.anthropic.com`을 호출하는 [WebFetch 도메인 안전 확인](/docs/ko/data-usage#webfetch-domain-safety-check)도 중단됩니다. 관리형 정책에서 `skipWebFetchPreflight: true`를 설정하여 비활성화하세요.

66* **다중 게이트웨이**: 각 게이트웨이는 자신의 구성을 가진 별도의 배포입니다. CLI는 게이트웨이 호스트명별로 신뢰 지문 및 자격 증명을 저장하므로, 다른 팀이 충돌 없이 다른 게이트웨이에 연결할 수 있습니다. 여러 OIDC 발급자를 제공하려면 별도의 인스턴스를 실행하세요.66* **다중 게이트웨이**: 각 게이트웨이는 자신의 구성을 가진 별도의 배포입니다. CLI는 게이트웨이 호스트명별로 신뢰 지문 및 자격 증명을 저장하므로, 다른 팀이 충돌 없이 다른 게이트웨이에 연결할 수 있습니다. 여러 OIDC 발급자를 제공하려면 별도의 인스턴스를 실행하세요.

67* **서버리스**: Cloud Run이 작동합니다. 콜드 OIDC 검색을 피하려면 `min-instances: 1`을 설정하세요. Lambda 및 Cloud Functions는 작동하지 않습니다. 게이트웨이는 장기 실행 HTTP 서버이기 때문입니다.67* **서버리스**: Cloud Run이 작동합니다. 콜드 OIDC 검색을 피하려면 `min-instances: 1`을 설정하세요. Lambda 및 Cloud Functions는 작동하지 않습니다. 게이트웨이는 장기 실행 HTTP 서버이기 때문입니다.

68 68

69여기의 모든 프로덕션 토폴로지는 일반 HTTP 복제본 앞에 Ingress, Cloud Run의 프론트 엔드 또는 ALB와 같은 L7 프록시를 배치합니다. [`listen.trusted_proxies`](/ko/claude-apps-gateway-config#listen)를 프록시의 소스 범위로 설정하여 게이트웨이가 `X-Forwarded-For`에서 클라이언트 IP를 읽도록 하세요. 게이트웨이는 TCP 피어가 신뢰할 수 있을 때만 헤더를 인정합니다. [Google Cloud 작동 예제](/ko/claude-apps-gateway-on-gcp)는 토폴로지별 구체적인 값을 가지고 있습니다. 신뢰할 수 있는 프록시가 없으면, 모든 요청이 프록시의 IP에서 오는 것으로 나타나므로 IP당 속도 제한이 하나의 공유 버킷으로 축소되고 감사 이벤트에 프록시의 IP가 기록됩니다.69여기의 모든 프로덕션 토폴로지는 일반 HTTP 복제본 앞에 Ingress, Cloud Run의 프론트 엔드 또는 ALB와 같은 L7 프록시를 배치합니다. [`listen.trusted_proxies`](/docs/ko/claude-apps-gateway-config#listen)를 프록시의 소스 범위로 설정하여 게이트웨이가 `X-Forwarded-For`에서 클라이언트 IP를 읽도록 하세요. 게이트웨이는 TCP 피어가 신뢰할 수 있을 때만 헤더를 인정합니다. [Google Cloud 작동 예제](/docs/ko/claude-apps-gateway-on-gcp)는 토폴로지별 구체적인 값을 가지고 있습니다. 신뢰할 수 있는 프록시가 없으면, 모든 요청이 프록시의 IP에서 오는 것으로 나타나므로 IP당 속도 제한이 하나의 공유 버킷으로 축소되고 감사 이벤트에 프록시의 IP가 기록됩니다.

70 70

71<h3 id="container-image">71<h3 id="container-image">

72 컨테이너 이미지72 컨테이너 이미지

74 74

75표준 Claude Code 릴리스의 네이티브 `claude` 바이너리 주위에 자신의 이미지를 빌드하세요:75표준 Claude Code 릴리스의 네이티브 `claude` 바이너리 주위에 자신의 이미지를 빌드하세요:

76 76

~~771. 고정된 릴리스에서 이미지 아키텍처용 Linux 빌드를 다운로드하세요. 다운로드 URL은 [특정 버전 설치](/ko/setup#install-a-specific-version)를 참조하세요.~~771. 고정된 릴리스에서 이미지 아키텍처용 Linux 빌드를 다운로드하세요. 다운로드 URL은 [특정 버전 설치](/docs/ko/setup#install-a-specific-version)를 참조하세요.

~~782. [바이너리 무결성 및 코드 서명](/ko/setup#binary-integrity-and-code-signing)에 설명된 대로 릴리스의 GPG 서명된 `manifest.json`에 대해 확인하세요.~~782. [바이너리 무결성 및 코드 서명](/docs/ko/setup#binary-integrity-and-code-signing)에 설명된 대로 릴리스의 GPG 서명된 `manifest.json`에 대해 확인하세요.

793. 빌드 컨텍스트에 복사하세요.793. 빌드 컨텍스트에 복사하세요.

80 80

81빌드가 릴리스 호스트에 도달할 수 없는 경우 릴리스를 내부 레지스트리로 미러링하고 플릿이 실행하는 버전을 고정하세요.81빌드가 릴리스 호스트에 도달할 수 없는 경우 릴리스를 내부 레지스트리로 미러링하고 플릿이 실행하는 버전을 고정하세요.

82 82

83바이너리 외에도 이미지는 다음이 필요합니다:83바이너리 외에도 이미지는 다음이 필요합니다:

84 84

85* **glibc 기반 이미지**: glibc 빌드의 유일한 동적 종속성은 glibc 라이브러리입니다. Musl 기반 이미지는 `linux-x64-musl` 또는 `linux-arm64-musl` 빌드와 추가 패키지가 필요합니다. [Alpine Linux 설정](/ko/setup#alpine-linux-and-musl-based-distributions)을 참조하세요.85* **glibc 기반 이미지**: glibc 빌드의 유일한 동적 종속성은 glibc 라이브러리입니다. Musl 기반 이미지는 `linux-x64-musl` 또는 `linux-arm64-musl` 빌드와 추가 패키지가 필요합니다. [Alpine Linux 설정](/docs/ko/setup#alpine-linux-and-musl-based-distributions)을 참조하세요.

86* **쓰기 가능한 상태 디렉토리**: 게이트웨이는 모든 사용자로 실행되지만, 최소 이미지에는 쓰기 가능한 홈이 없습니다. `CLAUDE_CONFIG_DIR`을 `/tmp/.claude`와 같은 쓰기 가능한 경로로 설정하세요.86* **쓰기 가능한 상태 디렉토리**: 게이트웨이는 모든 사용자로 실행되지만, 최소 이미지에는 쓰기 가능한 홈이 없습니다. `CLAUDE_CONFIG_DIR`을 `/tmp/.claude`와 같은 쓰기 가능한 경로로 설정하세요.

87* **컨테이너 명령**: `claude gateway --config /etc/claude/gateway.yaml`. 구성 파일은 읽기 전용으로 마운트되고 시크릿은 환경 변수로 제공됩니다. 게이트웨이는 `listen.port`에서 수신하며, 기본값은 `8080`입니다.87* **컨테이너 명령**: `claude gateway --config /etc/claude/gateway.yaml`. 구성 파일은 읽기 전용으로 마운트되고 시크릿은 환경 변수로 제공됩니다. 게이트웨이는 `listen.port`에서 수신하며, 기본값은 `8080`입니다.

88 88

99<Note>99<Note>

100 **워크로드 ID**100 **워크로드 ID**

101 101

102 정적 키보다 플랫폼의 워크로드 ID를 선호하세요: EKS의 Bedrock용 IRSA, GKE의 Agent Platform용 Workload Identity, AKS의 Foundry용 워크로드 ID. 업스트림 블록에서 `auth: {}`를 설정하거나 Foundry의 경우 `use_azure_ad: true`를 설정하면, 게이트웨이는 해당 공급자의 기본 자격 증명 체인을 통해 포드의 ID를 선택합니다. Bedrock 업스트림을 GKE에서 사용하는 경우와 같은 클라우드 간 페어링의 경우, 업스트림의 `auth` 블록에서 명시적 자격 증명을 설정하세요. [`upstreams` 참조](/ko/claude-apps-gateway-config#upstreams)는 플랫폼별 설정 세부사항을 가지고 있습니다.102 정적 키보다 플랫폼의 워크로드 ID를 선호하세요: EKS의 Bedrock용 IRSA, GKE의 Agent Platform용 Workload Identity, AKS의 Foundry용 워크로드 ID. 업스트림 블록에서 `auth: {}`를 설정하거나 Foundry의 경우 `use_azure_ad: true`를 설정하면, 게이트웨이는 해당 공급자의 기본 자격 증명 체인을 통해 포드의 ID를 선택합니다. Bedrock 업스트림을 GKE에서 사용하는 경우와 같은 클라우드 간 페어링의 경우, 업스트림의 `auth` 블록에서 명시적 자격 증명을 설정하세요. [`upstreams` 참조](/docs/ko/claude-apps-gateway-config#upstreams)는 플랫폼별 설정 세부사항을 가지고 있습니다.

103</Note>103</Note>

104 104

105<h3 id="cloud-run">105<h3 id="cloud-run">

109서비스를 다음과 같이 구성하세요:109서비스를 다음과 같이 구성하세요:

110 110

111* `listen.port`를 기본값 `8080`으로 유지하세요. 이는 Cloud Run의 기본 `PORT`와 일치하거나 `port: ${PORT}`를 설정하세요111* `listen.port`를 기본값 `8080`으로 유지하세요. 이는 Cloud Run의 기본 `PORT`와 일치하거나 `port: ${PORT}`를 설정하세요

112* `public_url`을 외부에서 도달 가능한 원본으로 설정하세요. 프로덕션의 경우 이는 일반적으로 내부 로드 밸런서의 호스트명입니다. `/login`이 [공개 주소를 거부](/ko/claude-apps-gateway#prerequisites)하고 `*.run.app` URL이 하나로 확인되므로, Cloud Run URL 단독은 `curl` 또는 브라우저 스모크 테스트에만 작동합니다. 예외는 `*.run.app`이 Private Service Connect를 통해 프라이빗으로 확인되고 Cloud DNS 프라이빗 영역이 있는 네트워크입니다. 해당 토폴로지에서 Cloud Run URL은 유효한 `public_url`입니다. [Google Cloud 작동 예제](/ko/claude-apps-gateway-on-gcp#deploy-the-gateway)는 둘 다 다룹니다.112* `public_url`을 외부에서 도달 가능한 원본으로 설정하세요. 프로덕션의 경우 이는 일반적으로 내부 로드 밸런서의 호스트명입니다. `/login`이 [공개 주소를 거부](/docs/ko/claude-apps-gateway#prerequisites)하고 `*.run.app` URL이 하나로 확인되므로, Cloud Run URL 단독은 `curl` 또는 브라우저 스모크 테스트에만 작동합니다. 예외는 `*.run.app`이 Private Service Connect를 통해 프라이빗으로 확인되고 Cloud DNS 프라이빗 영역이 있는 네트워크입니다. 해당 토폴로지에서 Cloud Run URL은 유효한 `public_url`입니다. [Google Cloud 작동 예제](/docs/ko/claude-apps-gateway-on-gcp#deploy-the-gateway)는 둘 다 다룹니다.

113* 구성을 시크릿 볼륨으로 마운트하세요113* 구성을 시크릿 볼륨으로 마운트하세요

114* 첫 번째 요청에서 콜드 OIDC 검색을 피하려면 `min-instances: 1`을 설정하세요114* 첫 번째 요청에서 콜드 OIDC 검색을 피하려면 `min-instances: 1`을 설정하세요

115 115

116<Note>116<Note>

117 Cloud Run 또는 GKE, Cloud SQL 및 Secret Manager를 다루는 Google Cloud의 완전한 작동 예제는 [Google Cloud에 배포](/ko/claude-apps-gateway-on-gcp)를 참조하세요.117 Cloud Run 또는 GKE, Cloud SQL 및 Secret Manager를 다루는 Google Cloud의 완전한 작동 예제는 [Google Cloud에 배포](/docs/ko/claude-apps-gateway-on-gcp)를 참조하세요.

118</Note>118</Note>

119 119

120<h3 id="push-the-gateway-url-to-developer-machines">120<h3 id="push-the-gateway-url-to-developer-machines">

121 게이트웨이 URL을 개발자 머신으로 푸시121 게이트웨이 URL을 개발자 머신으로 푸시

122</h3>122</h3>

123 123

124게이트웨이가 제공되면, MDM을 통해 또는 OS별 `managed-settings.json`을 직접 작성하여 관리형 설정을 통해 각 개발자의 머신으로 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 푸시하세요. 이 없이는 `/login`이 게이트웨이 옵션이 없는 표준 계정 선택기를 표시합니다. 파일 경로는 [클라이언트 측 관리형 설정](/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.124게이트웨이가 제공되면, MDM을 통해 또는 OS별 `managed-settings.json`을 직접 작성하여 관리형 설정을 통해 각 개발자의 머신으로 `forceLoginMethod` 및 `forceLoginGatewayUrl`을 푸시하세요. 이 없이는 `/login`이 게이트웨이 옵션이 없는 표준 계정 선택기를 표시합니다. 파일 경로는 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.

125 125

126<h2 id="operations">126<h2 id="operations">

127 운영127 운영

160 160

161* **기존 세션**: 베어러 토큰은 JWT 시크릿으로 로컬에서 검증되고, 세션 새로고침은 저장소를 건드리지 않으며, 게이트웨이 프로세스는 여전히 추론을 제공할 수 있습니다161* **기존 세션**: 베어러 토큰은 JWT 시크릿으로 로컬에서 검증되고, 세션 새로고침은 저장소를 건드리지 않으며, 게이트웨이 프로세스는 여전히 추론을 제공할 수 있습니다

162* **새로운 로그인**: Postgres가 복구될 때까지 실패합니다. 장치 흐름 및 속도 제한 카운터가 Postgres에 있기 때문입니다162* **새로운 로그인**: Postgres가 복구될 때까지 실패합니다. 장치 흐름 및 속도 제한 카운터가 Postgres에 있기 때문입니다

163* **[지출 제한 적용](/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 차단하는 것을 선호하면 닫힌 상태로 뒤집으세요163* **[지출 제한 적용](/docs/ko/claude-apps-gateway-spend-limits#postgres-availability)**: 중단 중에 기본적으로 열린 상태로 실패하므로 추론이 계속 흐릅니다. 차단하는 것을 선호하면 닫힌 상태로 뒤집으세요

164* **준비**: `/readyz`는 중단 중에 준비되지 않음을 보고하므로, 준비에 대한 트래픽을 게이트하는 오케스트레이터는 Postgres가 복구될 때까지 모든 복제본을 한 번에 로테이션에서 제거합니다. 해당 토폴로지에서 게이트웨이가 여전히 제공할 수 있는 추론을 포함한 모든 트래픽은 로드 밸런서에서 실패합니다. `/healthz`의 생존 프로브는 계속 통과하므로 복제본은 다시 시작되지 않습니다. 로그인한 개발자가 저장소 중단을 통해 계속 작동하도록 하려면 준비 프로브를 `/healthz`로 지정하세요. 비용은 새로운 로그인이 여전히 준비됨을 보고하는 복제본에 대해 실패한다는 것입니다.164* **준비**: `/readyz`는 중단 중에 준비되지 않음을 보고하므로, 준비에 대한 트래픽을 게이트하는 오케스트레이터는 Postgres가 복구될 때까지 모든 복제본을 한 번에 로테이션에서 제거합니다. 해당 토폴로지에서 게이트웨이가 여전히 제공할 수 있는 추론을 포함한 모든 트래픽은 로드 밸런서에서 실패합니다. `/healthz`의 생존 프로브는 계속 통과하므로 복제본은 다시 시작되지 않습니다. 로그인한 개발자가 저장소 중단을 통해 계속 작동하도록 하려면 준비 프로브를 `/healthz`로 지정하세요. 비용은 새로운 로그인이 여전히 준비됨을 보고하는 복제본에 대해 실패한다는 것입니다.

165 165

166IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고, 새로운 로그인 및 새로고침은 실패합니다. IdP가 자주 유지보수 창을 가지면 더 긴 `ttl_hours`를 설정하세요.166IdP가 다운되면, 기존 세션은 `ttl_hours`까지 작동하고, 새로운 로그인 및 새로고침은 실패합니다. IdP가 자주 유지보수 창을 가지면 더 긴 `ttl_hours`를 설정하세요.

193 193

19430초 루프는 TTL을 지난 `kv` 행을 만료하고, 시간별 스윕은 지출 테이블의 보존 창을 적용하므로 아무것도 무한정 증가하지 않습니다. [지출 제한](/ko/claude-apps-gateway-spend-limits)이 구성되지 않으면 `kv`만 작성됩니다. 보안 정책이 애플리케이션 역할의 DDL을 금지하면 이러한 테이블과 `_migrations`을 관리자 역할로 미리 생성하고 앱 역할에 각각에 대해 `SELECT, INSERT, UPDATE, DELETE`를 부여하세요.19430초 루프는 TTL을 지난 `kv` 행을 만료하고, 시간별 스윕은 지출 테이블의 보존 창을 적용하므로 아무것도 무한정 증가하지 않습니다. [지출 제한](/docs/ko/claude-apps-gateway-spend-limits)이 구성되지 않으면 `kv`만 작성됩니다. 보안 정책이 애플리케이션 역할의 DDL을 금지하면 이러한 테이블과 `_migrations`을 관리자 역할로 미리 생성하고 앱 역할에 각각에 대해 `SELECT, INSERT, UPDATE, DELETE`를 부여하세요.

195 195

196지출 제한이 사용 중이면, 손실된 데이터베이스는 개발자 재로그인뿐만 아니라 손실된 지출 추적 및 상한을 의미하므로 정기적인 백업을 실행하세요. 보존을 기다리지 않고 떠난 개발자 하나를 즉시 지우려면 `DELETE FROM principal_emails WHERE principal = '<sub>'`을 직접 실행하세요. 이는 이메일, 이름 및 그룹을 보유하는 유일한 테이블을 제거합니다. `spend` 및 `admin_audit` 행은 의사명 OIDC `sub`만 참조합니다.196지출 제한이 사용 중이면, 손실된 데이터베이스는 개발자 재로그인뿐만 아니라 손실된 지출 추적 및 상한을 의미하므로 정기적인 백업을 실행하세요. 보존을 기다리지 않고 떠난 개발자 하나를 즉시 지우려면 `DELETE FROM principal_emails WHERE principal = '<sub>'`을 직접 실행하세요. 이는 이메일, 이름 및 그룹을 보유하는 유일한 테이블을 제거합니다. `spend` 및 `admin_audit` 행은 의사명 OIDC `sub`만 참조합니다.

197 197

218| 데이터 | 경로 | 게이트웨이에서 Anthropic으로 전송됨 |218| 데이터 | 경로 | 게이트웨이에서 Anthropic으로 전송됨 |

219| ---------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------- |219| ---------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------- |

237 237

238두 가지 위협은 범위를 벗어났습니다. 이는 보안할 인프라입니다:238두 가지 위협은 범위를 벗어났습니다. 이는 보안할 인프라입니다:

239 239

240* **손상된 게이트웨이 호스트**: 호스트는 업스트림 자격 증명을 보유하고 [관리형 설정](/ko/claude-apps-gateway-config#managed)을 모든 연결된 개발자에게 배포하므로, 게이트웨이 구성에 대한 제어는 MDM에 대한 제어와 비교할 수 있습니다. CLI의 일회성 승인 대화는 셸 가능 설정의 자동 변경을 제한하지만 호스트 보안을 대체하지 않습니다.240* **손상된 게이트웨이 호스트**: 호스트는 업스트림 자격 증명을 보유하고 [관리형 설정](/docs/ko/claude-apps-gateway-config#managed)을 모든 연결된 개발자에게 배포하므로, 게이트웨이 구성에 대한 제어는 MDM에 대한 제어와 비교할 수 있습니다. CLI의 일회성 승인 대화는 셸 가능 설정의 자동 변경을 제한하지만 호스트 보안을 대체하지 않습니다.

241* **악의적인 OIDC 공급자**: 공급자는 게이트웨이가 신뢰하는 id\_token에 서명하므로 모든 ID를 주장할 수 있습니다. IdP 검증 및 보안은 귀사의 책임입니다.241* **악의적인 OIDC 공급자**: 공급자는 게이트웨이가 신뢰하는 id\_token에 서명하므로 모든 ID를 주장할 수 있습니다. IdP 검증 및 보안은 귀사의 책임입니다.

242 242

243<h3 id="user-code-brute-force-resistance">243<h3 id="user-code-brute-force-resistance">

246 246

247개발자가 `/device` 검증 페이지에 입력하는 `user_code`는 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.247개발자가 `/device` 검증 페이지에 입력하는 `user_code`는 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.

248 248

249게이트웨이는 [`rate_limits`](/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.249게이트웨이는 [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.

250 250

251<h3 id="compliance-posture">251<h3 id="compliance-posture">

252 규정 준수 태세252 규정 준수 태세

255* **데이터 거주지**: 게이트웨이의 자체 데이터 평면은 Anthropic API가 구성된 업스트림인 경우를 제외하고 Anthropic에 아무것도 보내지 않습니다. 그 경우 기존 데이터 처리 계약이 추론 경로에 적용됩니다. 텔레메트리, 감사, ID 및 설정은 구성한 대상으로만 이동합니다.255* **데이터 거주지**: 게이트웨이의 자체 데이터 평면은 Anthropic API가 구성된 업스트림인 경우를 제외하고 Anthropic에 아무것도 보내지 않습니다. 그 경우 기존 데이터 처리 계약이 추론 경로에 적용됩니다. 텔레메트리, 감사, ID 및 설정은 구성한 대상으로만 이동합니다.

256* **호스트 프로세스 트래픽**: 호스트 프로세스는 Claude Code CLI이며, 시작 분석 및 업데이트 확인을 Anthropic으로 보낼 수 있습니다. 엄격한 송신 배포의 경우 게이트웨이의 컨테이너 환경에서 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`을 설정하세요.256* **호스트 프로세스 트래픽**: 호스트 프로세스는 Claude Code CLI이며, 시작 분석 및 업데이트 확인을 Anthropic으로 보낼 수 있습니다. 엄격한 송신 배포의 경우 게이트웨이의 컨테이너 환경에서 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`을 설정하세요.

257* **클라이언트 분석**: CLI는 게이트웨이에 로그인하는 동안 자신의 사용 분석을 비활성화하고, 오류 보고는 타사 API 표면에서 기본적으로 꺼져 있습니다.257* **클라이언트 분석**: CLI는 게이트웨이에 로그인하는 동안 자신의 사용 분석을 비활성화하고, 오류 보고는 타사 API 표면에서 기본적으로 꺼져 있습니다.

258* **클라이언트 머신**: 개발자의 CLI는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 및 `skipWebFetchPreflight: true`가 설정되지 않으면 여전히 WebFetch 호스트명 확인 및 버전 확인을 Anthropic으로 보냅니다. [데이터 사용](/ko/data-usage)을 참조하세요.258* **클라이언트 머신**: 개발자의 CLI는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` 및 `skipWebFetchPreflight: true`가 설정되지 않으면 여전히 WebFetch 호스트명 확인 및 버전 확인을 Anthropic으로 보냅니다. [데이터 사용](/docs/ko/data-usage)을 참조하세요.

259* **설문 조사 평가**: 게이트웨이 자격 증명은 Anthropic 바운드 평가 싱크를 비활성화하므로 평가는 Anthropic으로 전송되지 않습니다.259* **설문 조사 평가**: 게이트웨이 자격 증명은 Anthropic 바운드 평가 싱크를 비활성화하므로 평가는 Anthropic으로 전송되지 않습니다.

260* **트랜스크립트 공유**: 설문 조사의 트랜스크립트 공유 프롬프트에서 예를 선택하면 Anthropic으로 업로드하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 파일을 작성합니다.260* **트랜스크립트 공유**: 설문 조사의 트랜스크립트 공유 프롬프트에서 예를 선택하면 Anthropic으로 업로드하는 대신 `~/.claude/feedback-bundles/` 아래의 로컬 파일을 작성합니다.

261* **클라이언트 업데이트**: 업데이트 확인은 게이트웨이 트래픽과 별개입니다. 자신의 배포를 통해 버전을 고정하고 노트북이 릴리스를 가져오면 안 되면 `DISABLE_UPDATES`를 설정하세요. `DISABLE_AUTOUPDATER`는 `claude update`가 여전히 작동하는 동안 백그라운드 업데이트만 중지합니다.261* **클라이언트 업데이트**: 업데이트 확인은 게이트웨이 트래픽과 별개입니다. 자신의 배포를 통해 버전을 고정하고 노트북이 릴리스를 가져오면 안 되면 `DISABLE_UPDATES`를 설정하세요. `DISABLE_AUTOUPDATER`는 `claude update`가 여전히 작동하는 동안 백그라운드 업데이트만 중지합니다.

262* **TLS**: 프로덕션에서 `public_url`을 HTTPS를 통해 제공하세요. 게이트웨이의 자체 리스너를 통해 `listen.tls`를 사용하거나 `listen.public_url`이 설정된 일반 HTTP 복제본 앞의 TLS 종료 ingress에서. 게이트웨이는 일반 HTTP를 거부하지 않습니다. IdP는 프로덕션에서 HTTPS를 제공해야 하고, Postgres는 `?sslmode=require`를 지원합니다. ingress에서 `Strict-Transport-Security`를 설정하세요.262* **TLS**: 프로덕션에서 `public_url`을 HTTPS를 통해 제공하세요. 게이트웨이의 자체 리스너를 통해 `listen.tls`를 사용하거나 `listen.public_url`이 설정된 일반 HTTP 복제본 앞의 TLS 종료 ingress에서. 게이트웨이는 일반 HTTP를 거부하지 않습니다. IdP는 프로덕션에서 HTTPS를 제공해야 하고, Postgres는 `?sslmode=require`를 지원합니다. ingress에서 `Strict-Transport-Security`를 설정하세요.

263* **취약점 공개**: [보안 문제 보고](/ko/security#reporting-security-issues)를 따르세요263* **취약점 공개**: [보안 문제 보고](/docs/ko/security#reporting-security-issues)를 따르세요

264 264

265<h2 id="troubleshooting">265<h2 id="troubleshooting">

266 문제 해결266 문제 해결

272* **로그인 문제**: 개발자는 `claude --debug-file ./claude-debug.txt`를 실행하고, 재현하며, 해당 파일과 동일한 창의 게이트웨이 감사 로그를 보냅니다272* **로그인 문제**: 개발자는 `claude --debug-file ./claude-debug.txt`를 실행하고, 재현하며, 해당 파일과 동일한 창의 게이트웨이 감사 로그를 보냅니다

273* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청의 게이트웨이 감사 로그(어느 업스트림이 제공했는지 및 응답 상태를 기록함)273* **추론 문제**: 요청된 모델, 구성된 업스트림, 요청의 게이트웨이 감사 로그(어느 업스트림이 제공했는지 및 응답 상태를 기록함)

274 274

275게이트웨이의 stderr에는 감사 이벤트 스트림이 포함되고, 감사 로그는 개발자 신원을 기록하며, 디버그 파일은 개발자 머신의 hook 및 MCP 서버 출력을 기록합니다. 공개 이슈에 게시하기 전에 이를 검토하고 제거해주시기 바랍니다.

276

275| 증상 | 원인 | 수정 |277| 증상 | 원인 | 수정 |

276| ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |278| ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

277| 개발자의 `/login`이 **Cloud 게이트웨이** 화면 대신 표준 계정 선택기를 표시합니다 | `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 해당 머신의 관리형 설정에 설정되지 않음 | [관리형 설정 파일](/ko/claude-apps-gateway#set-the-gateway-url)을 장치에 배포하세요. `/login`은 거기서 게이트웨이 URL을 읽습니다 |279| 개발자의 `/login`이 **Cloud 게이트웨이** 화면 대신 표준 계정 선택기를 표시합니다 | `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 해당 머신의 관리형 설정에 설정되지 않음 | [관리형 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 장치에 배포하세요. `/login`은 거기서 게이트웨이 URL을 읽습니다 |

278| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` 표시 | 설치된 Claude Code 빌드가 게이트웨이 지원보다 앞서갑니다 | 개발자가 Claude Code를 Cloud 게이트웨이 지원을 포함하는 릴리스로 업데이트하도록 하세요 |280| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` 표시 | 설치된 Claude Code 빌드가 게이트웨이 지원보다 앞서갑니다 | 개발자가 Claude Code를 Cloud 게이트웨이 지원을 포함하는 릴리스로 업데이트하도록 하세요 |

279| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 게이트웨이 호스트명이 적어도 하나의 공개 IP 주소로 확인됩니다. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 프라이빗이어야 합니다. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름입니다. AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환합니다. Anthropic이 운영하는 공개 게이트웨이 엔드포인트는 확인에서 제외되며, `/login`은 `https://`를 통해 이들을 허용합니다. v2.1.206 이전에는 `/login`이 다른 공개 주소처럼 이들을 거부했습니다 | 게이트웨이 이름이 개발자 머신에서 프라이빗 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [프라이빗 네트워크 전제조건](/ko/claude-apps-gateway#prerequisites)을 참조하세요. |281| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 게이트웨이 호스트명이 적어도 하나의 공개 IP 주소로 확인됩니다. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 프라이빗이어야 합니다. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름입니다. AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환합니다. Anthropic이 운영하는 공개 게이트웨이 엔드포인트는 확인에서 제외되며, `/login`은 `https://`를 통해 이들을 허용합니다. v2.1.206 이전에는 `/login`이 다른 공개 주소처럼 이들을 거부했습니다 | 게이트웨이 이름이 개발자 머신에서 프라이빗 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [프라이빗 네트워크 전제조건](/docs/ko/claude-apps-gateway#prerequisites)을 참조하세요. |

280| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 게이트웨이 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됩니다. 호스트가 프라이빗 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않습니다 | 개발자의 머신에서 `NO_PROXY`에 게이트웨이 호스트를 추가하여 연결이 직접이거나 호스트명이 프라이빗 주소로 확인되는 프록시를 사용하세요 |282| CLI `/login`: `Gateway login requires a direct connection and does not support connecting through an HTTP proxy` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 게이트웨이 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됩니다. 호스트가 프라이빗 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않습니다 | 개발자의 머신에서 `NO_PROXY`에 게이트웨이 호스트를 추가하여 연결이 직접이거나 호스트명이 프라이빗 주소로 확인되는 프록시를 사용하세요 |

282| 부팅이 `store.postgres_url`을 명명하는 구성 검증 오류로 종료됩니다 | Postgres가 구성되지 않음. 게이트웨이는 Postgres가 필요합니다 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |284| 부팅이 `store.postgres_url`을 명명하는 구성 검증 오류로 종료됩니다 | Postgres가 구성되지 않음. 게이트웨이는 Postgres가 필요합니다 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

284| 부팅이 `config.load` 후 OIDC 검색 오류로 종료됩니다 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않습니다 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 프라이빗 PKI의 경우 `ca_cert_pem`을 설정하세요. |286| 부팅이 `config.load` 후 OIDC 검색 오류로 종료됩니다 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않습니다 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 프라이빗 PKI의 경우 `ca_cert_pem`을 설정하세요. |

286| `/oauth/callback`이 "Sign-in could not be completed" 표시 | 이메일 도메인이 거부되었거나, id\_token 검증이 실패했거나, `email_verified`가 명시적으로 `false`입니다. 게이트웨이는 항상 이를 거부하며 재정의가 없습니다 | `allowed_email_domains`를 확인하고 IdP가 검증된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에 이메일을 내보내면 `oidc.email_claim`을 설정하세요. |288| `/oauth/callback`이 "Sign-in could not be completed" 표시 | 이메일 도메인이 거부되었거나, id\_token 검증이 실패했거나, `email_verified`가 명시적으로 `false`입니다. 게이트웨이는 항상 이를 거부하며 재정의가 없습니다 | `allowed_email_domains`를 확인하고 IdP가 검증된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에 이메일을 내보내면 `oidc.email_claim`을 설정하세요. |

293| 로그인이 IdP에서 완료되지만 콜백이 실패합니다. Chrome에서 CSP 오류 또는 Safari에서 "this sign-in link has expired" | IdP가 `response_mode=form_post`를 통해 코드를 반환했으며, 이는 POST를 통해 `/oauth/callback`으로 교차 원본을 자동 제출합니다. Chrome은 엄격한 CSP에서 이를 차단합니다. Safari는 제출을 허용하지만 콜백은 쿼리 문자열만 읽습니다. | IdP가 `response_mode=query`를 준수하는지 확인하세요. 게이트웨이가 명시적으로 요청하므로 콜백은 일반 리디렉션입니다 |295| 로그인이 IdP에서 완료되지만 콜백이 실패합니다. Chrome에서 CSP 오류 또는 Safari에서 "this sign-in link has expired" | IdP가 `response_mode=form_post`를 통해 코드를 반환했으며, 이는 POST를 통해 `/oauth/callback`으로 교차 원본을 자동 제출합니다. Chrome은 엄격한 CSP에서 이를 차단합니다. Safari는 제출을 허용하지만 콜백은 쿼리 문자열만 읽습니다. | IdP가 `response_mode=query`를 준수하는지 확인하세요. 게이트웨이가 명시적으로 요청하므로 콜백은 일반 리디렉션입니다 |

296| CLI `/login`: "Could not verify the gateway's TLS certificate" 또는 `SELF_SIGNED_CERT_IN_CHAIN` | 게이트웨이의 TLS 체인이 CLI 호스트의 신뢰 저장소에 없는 프라이빗 CA로 서명됩니다 | Claude Code는 기본적으로 네이티브 바이너리 및 Node 22.15 이상에서 OS 신뢰 저장소를 읽습니다. [`CLAUDE_CODE_CERT_STORE`](/ko/network-config#ca-certificate-store)는 이 동작을 제어합니다. CA가 OS 신뢰 저장소에 설치되면 개발자가 현재 런타임에 있는지 확인하세요. 그렇지 않으면 시작 전에 `NODE_EXTRA_CA_CERTS`를 CA 인증서 PEM으로 설정하세요. 첫 연결 지문 프롬프트는 여전히 적용됩니다. |298| CLI `/login`: "Could not verify the gateway's TLS certificate" 또는 `SELF_SIGNED_CERT_IN_CHAIN` | 게이트웨이의 TLS 체인이 CLI 호스트의 신뢰 저장소에 없는 프라이빗 CA로 서명됩니다 | Claude Code는 기본적으로 네이티브 바이너리 및 Node 22.15 이상에서 OS 신뢰 저장소를 읽습니다. [`CLAUDE_CODE_CERT_STORE`](/docs/ko/network-config#ca-certificate-store)는 이 동작을 제어합니다. CA가 OS 신뢰 저장소에 설치되면 개발자가 현재 런타임에 있는지 확인하세요. 그렇지 않으면 시작 전에 `NODE_EXTRA_CA_CERTS`를 CA 인증서 PEM으로 설정하세요. 첫 연결 지문 프롬프트는 여전히 적용됩니다. |

297 299

298<h2 id="related">300<h2 id="related">

299 관련301 관련

300</h2>302</h2>

301 303

302* [Claude 앱 게이트웨이 개요](/ko/claude-apps-gateway): 빠른 시작 및 개발자 연결304* [Claude 앱 게이트웨이 개요](/docs/ko/claude-apps-gateway): 빠른 시작 및 개발자 연결

303* [구성 참조](/ko/claude-apps-gateway-config): 모든 `gateway.yaml` 옵션305* [구성 참조](/docs/ko/claude-apps-gateway-config): 모든 `gateway.yaml` 옵션

commands.md +78 −78

Details

10 10

11`/`를 입력하면 사용 가능한 모든 명령어를 볼 수 있으며, `/` 다음에 문자를 입력하여 필터링할 수 있습니다.11`/`를 입력하면 사용 가능한 모든 명령어를 볼 수 있으며, `/` 다음에 문자를 입력하여 필터링할 수 있습니다.

12 12

13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 [skills](/ko/skills#pass-arguments-to-skills)는 예외입니다. skill 호출 뒤에 더 많은 skills가 따르는 경우(예: `/skill-a /skill-b do XYZ`), 시작 부분에 명명된 모든 skill을 로드하고 후행 텍스트를 각각에 인수로 전달합니다. 최대 6개의 skills를 연결할 수 있습니다.13명령어는 메시지의 시작 부분에서만 인식됩니다. 명령어 이름 다음에 오는 텍스트는 인수로 전달됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 [skills](/docs/ko/skills#pass-arguments-to-skills)는 예외입니다. skill 호출 뒤에 더 많은 skills가 따르는 경우(예: `/skill-a /skill-b do XYZ`), 시작 부분에 명명된 모든 skill을 로드하고 후행 텍스트를 각각에 인수로 전달합니다. 최대 6개의 skills를 연결할 수 있습니다.

14 14

15Claude가 응답하는 동안 명령어를 보내면 현재 턴이 완료된 후 대기열에 들어가 실행됩니다. `/status`, `/tasks`, `/usage`와 같은 일부 명령어는 응답을 중단하지 않고 즉시 실행됩니다.15Claude가 응답하는 동안 명령어를 보내면 현재 턴이 완료된 후 대기열에 들어가 실행됩니다. `/status`, `/tasks`, `/usage`와 같은 일부 명령어는 응답을 중단하지 않고 즉시 실행됩니다.

16 16

20 20

21대부분의 명령어는 프로젝트 설정부터 변경 사항 배포까지 세션의 특정 지점에서 유용합니다.21대부분의 명령어는 프로젝트 설정부터 변경 사항 배포까지 세션의 특정 지점에서 유용합니다.

22 22

23**리포지토리의 첫 번째 세션.** `/init`을 실행하여 시작 `CLAUDE.md`를 생성한 다음, `/memory`를 실행하여 이를 개선합니다. `/mcp`를 사용하여 프로젝트에 필요한 모든 서버를 설정하고, Claude에게 원하는 [subagent](/ko/sub-agents)를 생성하도록 요청하며, `/permissions`을 실행하여 승인 규칙을 설정합니다.23**리포지토리의 첫 번째 세션.** `/init`을 실행하여 시작 `CLAUDE.md`를 생성한 다음, `/memory`를 실행하여 이를 개선합니다. `/mcp`를 사용하여 프로젝트에 필요한 모든 서버를 설정하고, Claude에게 원하는 [subagent](/docs/ko/sub-agents)를 생성하도록 요청하며, `/permissions`을 실행하여 승인 규칙을 설정합니다.

24 24

25**작업 중.** `/plan`은 큰 변경 전에 plan mode로 전환합니다. `/model` 및 `/effort`는 사용 중인 모델과 적용하는 추론의 양을 조정합니다. 대화가 길어지면 `/context`는 윈도우를 채우는 것을 보여주고 `/compact`는 이를 요약하여 공간을 확보합니다. `/btw`를 사용하여 대화 기록에 추가되지 않아야 하는 빠른 여담을 남깁니다.25**작업 중.** `/plan`은 큰 변경 전에 plan mode로 전환합니다. `/model` 및 `/effort`는 사용 중인 모델과 적용하는 추론의 양을 조정합니다. 대화가 길어지면 `/context`는 윈도우를 채우는 것을 보여주고 `/compact`는 이를 요약하여 공간을 확보합니다. `/btw`를 사용하여 대화 기록에 추가되지 않아야 하는 빠른 여담을 남깁니다.

26 26

27**병렬로 작업 실행.** Claude는 부작업을 [subagent](/ko/sub-agents)에게 위임하고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.27**병렬로 작업 실행.** Claude는 부작업을 [subagent](/docs/ko/sub-agents)에게 위임하고, `/tasks`는 현재 세션의 백그라운드에서 실행 중인 작업을 나열합니다. `/background`는 전체 세션을 분리하여 [background agent](/docs/ko/agent-view)로 계속 실행되도록 하고 터미널을 해제합니다. 코드베이스에 걸친 큰 변경의 경우, `/batch`는 이를 독립적인 단위로 분해하고 각각을 자신의 [worktree](/docs/ko/worktrees)에서 실행합니다. [병렬로 agent 실행](/docs/ko/agents)을 참조하여 이러한 접근 방식이 어떻게 관련되는지 확인하십시오.

28 28

29**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 빠른 단일 패스 읽기 전용 검토를 제공하며, `/code-review <level> <pr#>`은 다중 agent 검토를 실행하고, `/security-review`는 diff를 보안 취약점에 대해 확인합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.29**배포 전.** `/diff`는 변경된 내용을 표시하고, `/code-review`는 diff를 정확성 버그 및 정리에 대해 확인하며 `--fix`로 결과를 적용할 수 있고, `/review`는 GitHub pull request에서 빠른 단일 패스 읽기 전용 검토를 제공하며, `/code-review <level> <pr#>`은 다중 agent 검토를 실행하고, `/security-review`는 diff를 보안 취약점에 대해 확인합니다. `/code-review ultra`는 클라우드에서 다중 agent 검토를 실행합니다.

30 30

38 38

39아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. 대부분은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 두 가지 종류의 항목이 표시됩니다:39아래 표는 Claude Code에 포함된 모든 명령어를 나열합니다. 대부분은 CLI에 코딩된 동작을 가진 기본 제공 명령어입니다. 두 가지 종류의 항목이 표시됩니다:

40 40

41* **[Skill](/ko/skills#bundled-skills)**: 번들 skill입니다. 직접 작성하는 skills와 같은 방식으로 작동합니다. Claude에 전달되는 프롬프트이며, Claude는 관련이 있을 때 자동으로 호출할 수도 있습니다.41* **[Skill](/docs/ko/skills#bundled-skills)**: 번들 skill입니다. 직접 작성하는 skills와 같은 방식으로 작동합니다. Claude에 전달되는 프롬프트이며, Claude는 관련이 있을 때 자동으로 호출할 수도 있습니다.

~~42* **[Workflow](/ko/workflows#bundled-workflows)**: 많은 subagents에 걸쳐 작업을 펼치고 백그라운드에서 실행되는 번들 [dynamic workflow](/ko/workflows)입니다.~~42* **[Workflow](/docs/ko/workflows#bundled-workflows)**: 많은 subagents에 걸쳐 작업을 펼치고 백그라운드에서 실행되는 번들 [dynamic workflow](/docs/ko/workflows)입니다.

43 43

~~44자신만의 명령어를 추가하려면 [skills](/ko/skills)를 참조하세요.~~44자신만의 명령어를 추가하려면 [skills](/docs/ko/skills)를 참조하세요.

45 45

46아래 표에서 `<arg>`는 필수 인수를 나타내고 `[arg]`는 선택적 인수를 나타냅니다.46아래 표에서 `<arg>`는 필수 인수를 나타내고 `[arg]`는 선택적 인수를 나타냅니다.

47 47

51 51

52| 명령어 | 목적 |52| 명령어 | 목적 |

53| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |53| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 부분 경로를 입력하면 일치하는 디렉토리 제안이 표시됩니다. `Tab`을 눌러 하나를 수락합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |54| `/add-dir <path>` | 현재 세션 중에 파일 액세스를 위한 작업 디렉토리를 추가합니다. 부분 경로를 입력하면 일치하는 디렉토리 제안이 표시됩니다. `Tab`을 눌러 하나를 수락합니다. 대부분의 `.claude/` 구성은 추가된 디렉토리에서 [발견되지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration). 나중에 `--continue` 또는 `--resume`을 사용하여 추가된 디렉토리에서 세션을 재개할 수 있습니다 |

55| `/advisor [model\|off]` | [advisor tool](/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다 |55| `/advisor [model\|off]` | [advisor tool](/docs/ko/advisor)을 활성화 또는 비활성화합니다. 이 도구는 작업 중 주요 순간에 두 번째 모델에 지침을 요청합니다. `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+) 또는 전체 모델 ID를 허용합니다. 인수 없이 선택기를 엽니다 |

56| `/agents` | {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`를 실행하면 Claude에 [subagents](/ko/sub-agents)를 만들거나 관리하도록 요청하거나, `.claude/agents/` 또는 `~/.claude/agents/`를 직접 편집하도록 상기시키는 메시지를 인쇄합니다. {/* max-version: 2.1.197 */}v2.1.197 이전에는 subagent 구성을 만들고 관리하기 위한 대화형 인터페이스를 엽니다 |56| `/agents` | {/* min-version: 2.1.198 */}v2.1.198부터 `/agents`를 실행하면 Claude에 [subagents](/docs/ko/sub-agents)를 만들거나 관리하도록 요청하거나, `.claude/agents/` 또는 `~/.claude/agents/`를 직접 편집하도록 상기시키는 메시지를 인쇄합니다. {/* max-version: 2.1.197 */}v2.1.197 이전에는 subagent 구성을 만들고 관리하기 위한 대화형 인터페이스를 엽니다 |

57| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 클라우드 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/ko/claude-code-on-the-web)에 대한 액세스가 필요합니다 |57| `/autofix-pr [prompt]` | 현재 브랜치의 PR을 감시하고 CI가 실패하거나 검토자가 댓글을 남길 때 수정 사항을 푸시하는 [Claude Code on the web](/docs/ko/claude-code-on-the-web#auto-fix-pull-requests) 세션을 생성합니다. `gh pr view`를 사용하여 체크아웃된 브랜치에서 열린 PR을 감지합니다. 다른 PR을 감시하려면 먼저 해당 브랜치를 체크아웃하세요. 기본적으로 클라우드 세션은 모든 CI 실패 및 검토 댓글을 수정하도록 지시받습니다. 프롬프트를 전달하여 다른 지침을 제공합니다. 예를 들어 `/autofix-pr only fix lint and type errors`. `gh` CLI 및 [Claude Code on the web](/docs/ko/claude-code-on-the-web)에 대한 액세스가 필요합니다 |

58| `/background [prompt]` | 현재 세션을 [background agent](/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |58| `/background [prompt]` | 현재 세션을 [background agent](/docs/ko/agent-view)로 분리하여 실행하고 이 터미널을 해제합니다. 분리하기 전에 한 가지 더 지침을 보내려면 프롬프트를 전달합니다. `claude agents`로 세션을 모니터링합니다. 별칭: `/bg` |

59| `/batch <instruction>` | **[Skill](/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/ko/worktrees)에서 단위당 하나의 [background subagent](/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |59| `/batch <instruction>` | **[Skill](/docs/ko/skills#bundled-skills).** 코드베이스 전체에서 대규모 변경 사항을 병렬로 조율합니다. 코드베이스를 연구하고, 작업을 5\~30개의 독립적인 단위로 분해하고, 계획을 제시합니다. 승인되면 격리된 [git worktree](/docs/ko/worktrees)에서 단위당 하나의 [background subagent](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)를 생성합니다. 각 subagent는 해당 단위를 구현하고, 테스트를 실행하고, pull request를 엽니다. git 리포지토리가 필요합니다. 예: `/batch migrate src/ from Solid to React` |

60| `/branch [name]` | 이 시점에서 현재 대화의 브랜치를 만듭니다. 다른 방향을 시도할 수 있도록 현재 상태의 대화를 잃지 않습니다. 브랜치로 전환하고 원본을 보존하며, `/resume`을 사용하여 돌아갈 수 있습니다. 자신이 복사본으로 전환하는 대신 백그라운드 subagent에 부작업을 넘기려면 `/fork`를 사용하세요 |60| `/branch [name]` | 이 시점에서 현재 대화의 브랜치를 만듭니다. 다른 방향을 시도할 수 있도록 현재 상태의 대화를 잃지 않습니다. 브랜치로 전환하고 원본을 보존하며, `/resume`을 사용하여 돌아갈 수 있습니다. 자신이 복사본으로 전환하는 대신 백그라운드 subagent에 부작업을 넘기려면 `/fork`를 사용하세요 |

62| `/cd <path>` | {/* min-version: 2.1.169 */}이 세션을 새 작업 디렉토리로 이동합니다. 대화의 프롬프트 캐시는 보존됩니다. 새 디렉토리의 [`CLAUDE.md`](/ko/memory)는 시스템 프롬프트를 다시 빌드하는 대신 메시지로 추가됩니다. 세션은 새 디렉토리의 프로젝트 저장소로 재배치되므로 `--resume` 및 `--continue`가 거기서 찾습니다. 이전에 작업하지 않은 디렉토리를 신뢰하도록 프롬프트합니다. {/* min-version: 2.1.206 */}부분 경로를 입력하면 일치하는 디렉토리 제안이 표시됩니다. `Tab`을 눌러 하나를 수락합니다. 제안은 Claude Code v2.1.206 이상이 필요합니다. 세션을 이동하지 않고 추가 디렉토리에 액세스를 부여하려면 `/add-dir`을 사용하세요. [`Cd` permission rules](/ko/permissions#cd)로 `/cd` 대상을 제한하거나 비활성화합니다. Claude Code v2.1.169 이상이 필요합니다. 이전 버전은 `Unknown command: /cd`를 보고합니다 |62| `/cd <path>` | {/* min-version: 2.1.169 */}이 세션을 새 작업 디렉토리로 이동합니다. 대화의 프롬프트 캐시는 보존됩니다. 새 디렉토리의 [`CLAUDE.md`](/docs/ko/memory)는 시스템 프롬프트를 다시 빌드하는 대신 메시지로 추가됩니다. 세션은 새 디렉토리의 프로젝트 저장소로 재배치되므로 `--resume` 및 `--continue`가 거기서 찾습니다. 이전에 작업하지 않은 디렉토리를 신뢰하도록 프롬프트합니다. {/* min-version: 2.1.206 */}부분 경로를 입력하면 일치하는 디렉토리 제안이 표시됩니다. `Tab`을 눌러 하나를 수락합니다. 제안은 Claude Code v2.1.206 이상이 필요합니다. 세션을 이동하지 않고 추가 디렉토리에 액세스를 부여하려면 `/add-dir`을 사용하세요. [`Cd` permission rules](/docs/ko/permissions#cd)로 `/cd` 대상을 제한하거나 비활성화합니다. Claude Code v2.1.169 이상이 필요합니다. 이전 버전은 `Unknown command: /cd`를 보고합니다 |

64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |64| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/docs/ko/skills#bundled-skills).** 프로젝트의 언어(Python, TypeScript, Java, Go, Ruby, C#, PHP 또는 cURL) 및 Managed Agents 참조에 대한 Claude API 참조 자료를 로드합니다. 도구 사용, 스트리밍, 배치, 구조화된 출력 및 일반적인 함정을 다룹니다. 또한 코드가 `anthropic` 또는 `@anthropic-ai/sdk`를 가져올 때 자동으로 활성화됩니다. `/claude-api migrate`를 실행하여 기존 Claude API 코드를 최신 모델로 업그레이드합니다. Claude는 스캔할 파일과 대상 모델을 묻고, 모델 ID, thinking 구성 및 버전 간에 변경된 기타 매개변수를 업데이트합니다. `/claude-api managed-agents-onboard`를 실행하여 처음부터 새로운 Managed Agent를 만드는 대화형 안내를 받습니다 |

65| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. `/resume`으로 이전 대화를 재개하거나, 같은 Claude Code 프로세스에서 {/* min-version: 2.1.191 */}}[rewind 메뉴의 이전 세션 항목](/ko/checkpointing#rewind-past-a-cleared-conversation)에서 복원합니다. 별칭: `/reset`, `/new` |65| `/clear [name]` | 빈 컨텍스트로 새 대화를 시작합니다. 이름을 전달하여 `/resume` 선택기에서 이전 대화에 레이블을 지정합니다. 같은 대화를 계속하면서 컨텍스트를 확보하려면 `/compact`를 대신 사용하세요. `/resume`으로 이전 대화를 재개하거나, 같은 Claude Code 프로세스에서 {/* min-version: 2.1.191 */}}[rewind 메뉴의 이전 세션 항목](/docs/ko/checkpointing#rewind-past-a-cleared-conversation)에서 복원합니다. 별칭: `/reset`, `/new` |

66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/ko/skills#bundled-skills).** 현재 diff를 정확성 버그에 대해 검토하고 재사용, 단순화 및 효율성 정리에 대해 검토합니다. `--fix`를 전달하여 결과를 작업 트리에 적용하고, `--comment`를 전달하여 현재 GitHub PR에 인라인 댓글로 게시하거나, `ultra`를 전달하여 깊은 [cloud review](/ko/ultrareview)를 실행합니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 정리만 수행하는 별도의 검토를 실행합니다. 노력 수준 및 대상 지정에 대해서는 [Review a diff locally](/ko/code-review#review-a-diff-locally)를 참조하세요 |66| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [target]` | **[Skill](/docs/ko/skills#bundled-skills).** 현재 diff를 정확성 버그에 대해 검토하고 재사용, 단순화 및 효율성 정리에 대해 검토합니다. `--fix`를 전달하여 결과를 작업 트리에 적용하고, `--comment`를 전달하여 현재 GitHub PR에 인라인 댓글로 게시하거나, `ultra`를 전달하여 깊은 [cloud review](/docs/ko/ultrareview)를 실행합니다. {/* min-version: 2.1.154 */}v2.1.154부터 `/simplify`는 버그를 찾지 않고 정리만 수행하는 별도의 검토를 실행합니다. 노력 수준 및 대상 지정에 대해서는 [Review a diff locally](/docs/ko/code-review#review-a-diff-locally)를 참조하세요 |

67| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용합니다. 인수 없이 실행하면 무작위 색상을 선택합니다. [Remote Control](/ko/remote-control)이 연결되면 색상이 claude.ai/code와 동기화됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다 |67| `/color [color\|default]` | 현재 세션의 프롬프트 바 색상을 설정합니다. 사용 가능한 색상: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. 초기화하려면 `default`를 사용합니다. 인수 없이 실행하면 무작위 색상을 선택합니다. [Remote Control](/docs/ko/remote-control)이 연결되면 색상이 claude.ai/code와 동기화됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다 |

68| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/ko/context-window#what-survives-compaction)을 참조하세요 |68| `/compact [instructions]` | 지금까지의 대화를 요약하여 컨텍스트를 확보합니다. 선택적으로 요약에 대한 포커스 지침을 전달합니다. [compaction이 규칙, skills 및 메모리 파일을 처리하는 방법](/docs/ko/context-window#what-survives-compaction)을 참조하세요 |

69| `/config [key=value ...]` | [Settings](/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/ko/output-styles) 및 기타 기본 설정을 조정합니다. {/* min-version: 2.1.181 */}v2.1.181부터 하나 이상의 `key=value` 쌍을 전달하여 인터페이스를 열지 않고 설정을 직접 설정할 수 있습니다. 예를 들어 `/config thinking=false`. {/* min-version: 2.1.182 */}v2.1.182부터 명명된 약칭 키도 허용됩니다. 예를 들어 `/config theme=dark` 또는 `/config model=sonnet`. `key=value` 형식은 비대화형 모드(`-p`)와 Claude 모바일 앱에서 [Remote Control](/ko/remote-control)을 통해서도 작동합니다. `/config --help`를 실행하여 설정할 수 있는 모든 키를 나열합니다. 별칭: `/settings` |69| `/config [key=value ...]` | [Settings](/docs/ko/settings) 인터페이스를 열어 테마, 모델, [output style](/docs/ko/output-styles) 및 기타 기본 설정을 조정합니다. {/* min-version: 2.1.181 */}v2.1.181부터 하나 이상의 `key=value` 쌍을 전달하여 인터페이스를 열지 않고 설정을 직접 설정할 수 있습니다. 예를 들어 `/config thinking=false`. {/* min-version: 2.1.182 */}v2.1.182부터 명명된 약칭 키도 허용됩니다. 예를 들어 `/config theme=dark` 또는 `/config model=sonnet`. `key=value` 형식은 비대화형 모드(`-p`)와 Claude 모바일 앱에서 [Remote Control](/docs/ko/remote-control)을 통해서도 작동합니다. `/config --help`를 실행하여 설정할 수 있는 모든 키를 나열합니다. 별칭: `/settings` |

70| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |70| `/context [all]` | 현재 컨텍스트 사용량을 색상 그리드로 시각화합니다. 컨텍스트 집약적 도구, 메모리 부풀림 및 용량 경고에 대한 최적화 제안을 표시합니다. [fullscreen mode](/docs/ko/fullscreen)에서는 항목별 분석이 그리드를 표시하기 위해 축소됩니다. `all`을 전달하여 확장합니다 |

71| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |71| `/copy [N]` | 마지막 어시스턴트 응답을 클립보드에 복사합니다. 숫자 `N`을 전달하여 N번째 최신 응답을 복사합니다: `/copy 2`는 두 번째 마지막 응답을 복사합니다. 코드 블록이 있을 때는 개별 블록 또는 전체 응답을 선택할 수 있는 대화형 선택기를 표시합니다. 선택기에서 `w`를 누르면 클립보드 대신 파일에 선택 항목을 작성하며, 이는 SSH를 통해 유용합니다 |

73| `/dataviz [request]` | **[Skill](/ko/skills#bundled-skills).** 차트, 그래프 및 대시보드에 대한 디자인 지침입니다. Claude는 데이터에 대한 차트 형식을 선택하고, 역할별로 색상을 할당하고, 번들 스크립트를 사용하여 색맹 안전성 및 대비에 대한 팔레트를 검증하고, 마크, 상호 작용 및 접근성 규칙을 적용합니다. 자신의 팔레트로 바꿀 수 있는 브랜드 중립 자리 표시자 팔레트를 사용합니다. {/* min-version: 2.1.198 */}Claude Code v2.1.198 이상이 필요합니다 |73| `/dataviz [request]` | **[Skill](/docs/ko/skills#bundled-skills).** 차트, 그래프 및 대시보드에 대한 디자인 지침입니다. Claude는 데이터에 대한 차트 형식을 선택하고, 역할별로 색상을 할당하고, 번들 스크립트를 사용하여 색맹 안전성 및 대비에 대한 팔레트를 검증하고, 마크, 상호 작용 및 접근성 규칙을 적용합니다. 자신의 팔레트로 바꿀 수 있는 브랜드 중립 자리 표시자 팔레트를 사용합니다. {/* min-version: 2.1.198 */}Claude Code v2.1.198 이상이 필요합니다 |

74| `/debug [description]` | **[Skill](/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |74| `/debug [description]` | **[Skill](/docs/ko/skills#bundled-skills).** 현재 세션에 대해 디버그 로깅을 활성화하고 세션 디버그 로그를 읽어 문제를 해결합니다. 디버그 로깅은 `claude --debug`로 시작하지 않는 한 기본적으로 꺼져 있으므로, 세션 중간에 `/debug`를 실행하면 그 시점부터 로그 캡처를 시작합니다. 선택적으로 분석에 초점을 맞추기 위해 문제를 설명합니다 |

75| `/deep-research <question>` | **[Workflow](/ko/workflows#bundled-workflows).** 질문에 대한 웹 검색을 펼치고, 소스를 가져와 교차 검증하고, 인용된 보고서를 종합합니다 |75| `/deep-research <question>` | **[Workflow](/docs/ko/workflows#bundled-workflows).** 질문에 대한 웹 검색을 펼치고, 소스를 가져와 교차 검증하고, 인용된 보고서를 종합합니다 |

77| `/design-sync [hint]` | **[Skill](/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |77| `/design-sync [hint]` | **[Skill](/docs/ko/skills#bundled-skills).** 리포지토리의 React design system을 변환하고 [Claude Design](https://claude.ai/design)에 업로드하여 생성하는 디자인이 실제 구성 요소를 사용하도록 합니다. 선택적으로 design system의 이름을 지정합니다. 예를 들어 `/design-sync Acme DS`. 첫 번째 동기화는 모든 구성 요소를 확인하며 큰 리포지토리에서는 몇 시간이 걸릴 수 있습니다. Anthropic API에서 사용 가능합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Claude Platform on AWS에서는 기본 도구가 claude.ai에 도달할 수 없으므로 명령어를 사용할 수 없습니다 |

79| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다. Enter를 눌러 선택한 파일의 diff를 열고, 위/아래 또는 PageUp/PageDown으로 스크롤하고, Esc를 눌러 파일 목록으로 돌아갑니다. {/* min-version: 2.1.198 */}v2.1.198부터 열린 뷰어는 또한 리포지토리의 git 상태가 다른 터미널의 브랜치 전환 또는 커밋과 같이 세션 외부에서 변경될 때 자동으로 새로 고쳐집니다 |79| `/diff` | 커밋되지 않은 변경 사항과 턴별 diff를 표시하는 대화형 diff 뷰어를 엽니다. 왼쪽/오른쪽 화살표를 사용하여 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래를 사용하여 파일을 탐색합니다. Enter를 눌러 선택한 파일의 diff를 열고, 위/아래 또는 PageUp/PageDown으로 스크롤하고, Esc를 눌러 파일 목록으로 돌아갑니다. {/* min-version: 2.1.198 */}v2.1.198부터 열린 뷰어는 또한 리포지토리의 git 상태가 다른 터미널의 브랜치 전환 또는 커밋과 같이 세션 외부에서 변경될 때 자동으로 새로 고쳐집니다 |

80| `/doctor` | **[Skill](/ko/skills#bundled-skills).** 설정 검사를 실행하여 문제를 진단하고 수정할 수 있습니다. 중복 또는 남은 설치, `PATH` 문제 및 구문 분석할 수 없는 설정 파일을 포함한 설치 상태를 확인합니다. 사용하지 않는 skills, MCP 서버 및 plugins와 컨텍스트 비용을 찾고, 느린 [hooks](/ko/hooks)를 표시하고, 최신 버전을 확인합니다. 로컬 `CLAUDE.md` 파일을 체크인된 파일과 중복 제거하고, 체크인된 [`CLAUDE.md`](/ko/memory) 파일을 코드베이스에서 파생될 수 있는 콘텐츠를 잘라내어 정리하고, 항상 로드되는 지침을 [skills](/ko/skills)로 마이그레이션하고 요청 시 로드되는 중첩 `CLAUDE.md` 파일로 마이그레이션합니다. 정리는 디렉토리 레이아웃, 종속성 목록 및 아키텍처 개요와 같은 섹션을 자르고, 도구 기본값과 다른 함정, 근거 및 규칙을 유지합니다. 또한 [auto mode](/ko/permissions#permission-modes)를 기본값으로 설정하고 자주 거부되는 읽기 전용 명령어를 [사전 승인](/ko/permissions)하도록 제안합니다. 먼저 결과를 보고하고 변경하기 전에 확인을 요청합니다. 터미널에서 `claude doctor`는 세션을 시작하지 않고 읽기 전용 설치 진단을 인쇄합니다. 별칭: `/checkup`. {{/* min-version: 2.1.206 */}}}`CLAUDE.md` 정리 검사는 Claude Code v2.1.206 이상이 필요합니다. v2.1.206 이전에는 버전 검사가 [설치된 cask의 채널](/ko/setup#configure-release-channel) 대신 `autoUpdatesChannel` 설정에 대해 Homebrew 설치를 비교했습니다. {{/* min-version: 2.1.205 */}}v2.1.205 이전에는 `/doctor`가 읽기 전용 진단 화면을 열었고 `f`를 누르면 보고서를 Claude로 보냈습니다 |80| `/doctor` | **[Skill](/docs/ko/skills#bundled-skills).** 설정 검사를 실행하여 문제를 진단하고 수정할 수 있습니다. 중복 또는 남은 설치, `PATH` 문제 및 구문 분석할 수 없는 설정 파일을 포함한 설치 상태를 확인합니다. 사용하지 않는 skills, MCP 서버 및 plugins와 컨텍스트 비용을 찾고, 느린 [hooks](/docs/ko/hooks)를 표시하고, 최신 버전을 확인합니다. 로컬 `CLAUDE.md` 파일을 체크인된 파일과 중복 제거하고, 체크인된 [`CLAUDE.md`](/docs/ko/memory) 파일을 코드베이스에서 파생될 수 있는 콘텐츠를 잘라내어 정리하고, 항상 로드되는 지침을 [skills](/docs/ko/skills)로 마이그레이션하고 요청 시 로드되는 중첩 `CLAUDE.md` 파일로 마이그레이션합니다. 정리는 디렉토리 레이아웃, 종속성 목록 및 아키텍처 개요와 같은 섹션을 자르고, 도구 기본값과 다른 함정, 근거 및 규칙을 유지합니다. 또한 [auto mode](/docs/ko/permissions#permission-modes)를 기본값으로 설정하고 자주 거부되는 읽기 전용 명령어를 [사전 승인](/docs/ko/permissions)하도록 제안합니다. 먼저 결과를 보고하고 변경하기 전에 확인을 요청합니다. 터미널에서 `claude doctor`는 세션을 시작하지 않고 읽기 전용 설치 진단을 인쇄합니다. 별칭: `/checkup`. {{/* min-version: 2.1.206 */}}}`CLAUDE.md` 정리 검사는 Claude Code v2.1.206 이상이 필요합니다. v2.1.206 이전에는 버전 검사가 [설치된 cask의 채널](/docs/ko/setup#configure-release-channel) 대신 `autoUpdatesChannel` 설정에 대해 Homebrew 설치를 비교했습니다. {{/* min-version: 2.1.205 */}}v2.1.205 이전에는 `/doctor`가 읽기 전용 진단 화면을 열었고 `f`를 누르면 보고서를 Claude로 보냈습니다 |

81| `/effort [level\|auto]` | 모델 [effort level](/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며, `max` 및 `ultracode`는 세션 전용입니다. `ultracode`는 `xhigh` reasoning과 자동 [workflow](/ko/workflows#let-claude-decide-with-ultracode) 조율을 결합하는 Claude Code 설정입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 수준 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다. Fable 5, Opus 4.8 및 Opus 4.7에서는 [model-default effort hold](/ko/model-config#adjust-effort-level)가 적용되는 동안 비대화형 `/effort`가 `Not applied`를 보고하므로 대신 시작 시 `--effort`를 전달하세요 |81| `/effort [level\|auto]` | 모델 [effort level](/docs/ko/model-config#adjust-effort-level)을 설정합니다. `low`, `medium`, `high`, `xhigh`, `max` 또는 `ultracode`를 허용합니다. 사용 가능한 수준은 모델에 따라 다르며, `max` 및 `ultracode`는 세션 전용입니다. `ultracode`는 `xhigh` reasoning과 자동 [workflow](/docs/ko/workflows#let-claude-decide-with-ultracode) 조율을 결합하는 Claude Code 설정입니다. `auto`는 모델 기본값으로 재설정합니다. 인수 없이 대화형 슬라이더를 엽니다. 왼쪽 및 오른쪽 화살표를 사용하여 수준을 선택하고 `Enter`를 눌러 적용합니다. 현재 응답이 완료될 때까지 기다리지 않고 즉시 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 수준 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다. Fable 5, Opus 4.8 및 Opus 4.7에서는 [model-default effort hold](/docs/ko/model-config#adjust-effort-level)가 적용되는 동안 비대화형 `/effort`가 `Not applied`를 보고하므로 대신 시작 시 `--effort`를 전달하세요 |

82| `/exit` | CLI를 종료합니다. 연결된 [background session](/ko/agent-view#attach-to-a-session)에서 이 명령어는 분리하고 세션은 계속 실행됩니다. 별칭: `/quit` |82| `/exit` | CLI를 종료합니다. 연결된 [background session](/docs/ko/agent-view#attach-to-a-session)에서 이 명령어는 분리하고 세션은 계속 실행됩니다. 별칭: `/quit` |

84| `/fast [on\|off]` | [fast mode](/ko/fast-mode)를 켜거나 끕니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서 `/fast`는 fast mode를 [`--settings`](/ko/cli-reference#cli-flags) 값으로 시작한 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`. 토글은 현재 세션에만 적용되고 기본값으로 저장되지 않으며, 다른 비대화형 세션에서는 명령어가 fast mode를 사용할 수 없다고 보고합니다. Claude Code v2.1.205 이상이 필요합니다 |84| `/fast [on\|off]` | [fast mode](/docs/ko/fast-mode)를 켜거나 끕니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서 `/fast`는 fast mode를 [`--settings`](/docs/ko/cli-reference#cli-flags) 값으로 시작한 세션에서만 작동합니다. 예를 들어 `claude -p --settings '{"fastMode": true}'`. 토글은 현재 세션에만 적용되고 기본값으로 저장되지 않으며, 다른 비대화형 세션에서는 명령어가 fast mode를 사용할 수 없다고 보고합니다. Claude Code v2.1.205 이상이 필요합니다 |

85| `/feedback [report]` | 피드백을 제출하거나, 버그를 보고하거나, 대화를 공유합니다. Anthropic에 보내려면 [authentication](/ko/authentication)이 필요합니다. 별칭: `/bug`, `/share` |85| `/feedback [report]` | 피드백을 제출하거나, 버그를 보고하거나, 대화를 공유합니다. Anthropic에 보내려면 [authentication](/docs/ko/authentication)이 필요합니다. 별칭: `/bug`, `/share` |

86| `/fewer-permission-prompts` | **[Skill](/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |86| `/fewer-permission-prompts` | **[Skill](/docs/ko/skills#bundled-skills).** 트랜스크립트에서 일반적인 읽기 전용 Bash 및 MCP 도구 호출을 스캔한 다음, 권한 프롬프트를 줄이기 위해 프로젝트 `.claude/settings.json`에 우선순위가 지정된 허용 목록을 추가합니다 |

87| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. {/* min-version: 2.1.198 */}v2.1.198부터 도구 호출 요약은 또한 턴에서 시작된 subagents의 개수를 세고 완료된 백그라운드 작업 알림을 단일 개수로 축소합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능합니다 |87| `/focus` | 포커스 뷰를 전환합니다. 마지막 프롬프트, 편집 diffstats가 있는 한 줄 도구 호출 요약 및 최종 응답만 표시합니다. {/* min-version: 2.1.198 */}v2.1.198부터 도구 호출 요약은 또한 턴에서 시작된 subagents의 개수를 세고 완료된 백그라운드 작업 알림을 단일 개수로 축소합니다. 선택 항목은 세션 전체에서 유지됩니다. 설정에서 [`viewMode`](/docs/ko/settings#available-settings)를 설정하여 재정의할 수 있습니다. [fullscreen rendering](/docs/ko/fullscreen)에서만 사용 가능합니다 |

88| `/fork <directive>` | {/* min-version: 2.1.161 */}}[forked subagent](/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |88| `/fork <directive>` | {/* min-version: 2.1.161 */}}[forked subagent](/docs/ko/sub-agents#fork-the-current-conversation)를 생성합니다. 이는 전체 대화를 상속하고 지시문에서 작업하는 백그라운드 subagent이며, 당신은 계속 진행합니다. 그 결과는 완료되면 당신의 대화로 돌아옵니다. 대화의 복사본으로 자신이 전환하려면 `/branch`를 사용하세요. v2.1.161 이전에는 `/fork`가 `/branch`의 별칭입니다 |

89| `/goal [condition\|clear]` | [goal](/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |89| `/goal [condition\|clear]` | [goal](/docs/ko/goal)을 설정합니다. Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업합니다. 인수 없이 현재 또는 가장 최근에 달성한 goal을 표시합니다. `clear`, `stop`, `off`, `reset`, `none` 또는 `cancel`은 활성 goal을 조기에 제거합니다 |

90| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. [troubleshooting](/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |90| `/heapdump` | JavaScript 힙 스냅샷 및 메모리 분석을 `~/Desktop`에 작성하거나, Desktop 폴더가 없는 Linux의 경우 홈 디렉토리에 작성하여 높은 메모리 사용량을 진단합니다. `.heapsnapshot` 파일에는 전체 대화 및 자격 증명이 포함되므로 공유하지 마세요. [troubleshooting](/docs/ko/troubleshooting#high-cpu-or-memory-usage)을 참조하세요 |

93| `/ide` | IDE 통합을 관리하고 상태를 표시합니다 |93| `/ide` | IDE 통합을 관리하고 상태를 표시합니다 |

96| `/install-github-app` | 리포지토리에 대해 Claude GitHub App을 설치합니다. 선택적 단계로 [GitHub Actions](/ko/github-actions) 워크플로우 및 시크릿을 설정합니다. 리포지토리를 선택하고 통합을 구성하는 과정을 안내합니다 |96| `/install-github-app` | 리포지토리에 대해 Claude GitHub App을 설치합니다. 선택적 단계로 [GitHub Actions](/docs/ko/github-actions) 워크플로우 및 시크릿을 설정합니다. 리포지토리를 선택하고 통합을 구성하는 과정을 안내합니다 |

101| `/loop [interval] [prompt]` | **[Skill](/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 [사용 가능한 경우](/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) Claude가 자동 유지 관리 검사를 실행하거나 `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |101| `/loop [interval] [prompt]` | **[Skill](/docs/ko/skills#bundled-skills).** 세션이 열려 있는 동안 프롬프트를 반복적으로 실행합니다. 간격을 생략하면 Claude가 반복 사이에 자동으로 속도를 조절합니다. 프롬프트를 생략하면 [사용 가능한 경우](/docs/ko/scheduled-tasks#run-the-built-in-maintenance-prompt) Claude가 자동 유지 관리 검사를 실행하거나 `.claude/loop.md`의 프롬프트를 실행합니다. 예: `/loop 5m check if the deploy finished`. [Run prompts on a schedule](/docs/ko/scheduled-tasks)을 참조하세요. 별칭: `/proactive` |

102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | MCP 서버 연결 및 OAuth 인증을 관리합니다. 인수 없이 실행하여 대화형 목록을 열거나, `reconnect <server>`를 전달하여 연결이 끊긴 서버를 다시 연결하거나, `enable`/`disable`을 서버 이름 또는 `all`과 함께 전달하여 대화 상자를 열지 않고 연결 상태를 변경합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능하며, 인수 없이 실행하면 목록을 열지 않고 서버 상태의 텍스트 요약을 인쇄합니다. Claude Code v2.1.205 이상이 필요합니다 |102| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | MCP 서버 연결 및 OAuth 인증을 관리합니다. 인수 없이 실행하여 대화형 목록을 열거나, `reconnect <server>`를 전달하여 연결이 끊긴 서버를 다시 연결하거나, `enable`/`disable`을 서버 이름 또는 `all`과 함께 전달하여 대화 상자를 열지 않고 연결 상태를 변경합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능하며, 인수 없이 실행하면 목록을 열지 않고 서버 상태의 텍스트 요약을 인쇄합니다. Claude Code v2.1.205 이상이 필요합니다 |

105| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 모델 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다 |105| `/model [model]` | AI 모델을 전환하고 새 세션의 기본값으로 저장합니다. 이를 지원하는 모델의 경우 왼쪽/오른쪽 화살표를 사용하여 [effort level을 조정](/docs/ko/model-config#adjust-effort-level)합니다. 인수 없이 선택기를 엽니다. 행에서 `s`를 눌러 현재 세션에만 전환합니다. 대화에 이전 출력이 있을 때 선택기가 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다. 확인되면 현재 응답이 완료될 때까지 기다리지 않고 변경 사항이 적용됩니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 모델 인수와 함께 사용 가능하며, 현재 세션에만 적용되고 기본값으로 저장되지 않습니다. Claude Code v2.1.205 이상이 필요합니다 |

107| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |107| `/permissions` | 도구 권한에 대한 허용, 요청 및 거부 규칙을 관리합니다. 범위별로 규칙을 보고, 규칙을 추가 또는 제거하고, 작업 디렉토리를 관리하며, [최근 자동 모드 거부](/docs/ko/auto-mode-config#review-denials)를 검토할 수 있는 대화형 대화 상자를 엽니다. 별칭: `/allowed-tools` |

108| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |108| `/plan [description]` | 프롬프트에서 직접 plan mode로 들어갑니다. 선택적 설명을 전달하여 plan mode로 들어가고 즉시 해당 작업으로 시작합니다. 예를 들어 `/plan fix the auth bug` |

109| `/plugin [subcommand]` | Claude Code [plugins](/ko/plugins)를 관리합니다. 인수 없이 실행하여 플러그인 메뉴를 열거나, `list`, `install`, `enable` 또는 `disable`과 같은 subcommand를 전달하여 직접 작동합니다 |109| `/plugin [subcommand]` | Claude Code [plugins](/docs/ko/plugins)를 관리합니다. 인수 없이 실행하여 플러그인 메뉴를 열거나, `list`, `install`, `enable` 또는 `disable`과 같은 subcommand를 전달하여 직접 작동합니다 |

111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |111| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}v2.1.91에서 제거됨. 대신 Claude에 직접 pull request 댓글을 보도록 요청하세요. 이전 버전에서는 GitHub pull request의 댓글을 가져와 표시합니다. 현재 브랜치의 PR을 자동으로 감지하거나 PR URL 또는 번호를 전달합니다. `gh` CLI가 필요합니다 |

113| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 Claude Platform on AWS에서는 사용할 수 없습니다 |113| `/radio` | Claude FM lo-fi 라디오를 브라우저에서 엽니다. 브라우저를 사용할 수 없을 때 스트림 URL을 인쇄합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 Claude Platform on AWS에서는 사용할 수 없습니다 |

115| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다. {{/* min-version: 2.1.208 */}}노트는 Claude가 보는 대화에 들어가지 않고 트랜스크립트에 표시됩니다. v2.1.208 이전에는 본 노트가 대화에 들어갔으며, 모든 버전을 표시할 때 전체 변경 로그를 포함했습니다 |115| `/release-notes` | 대화형 버전 선택기에서 변경 로그를 봅니다. 특정 버전을 선택하여 해당 릴리스 노트를 보거나, 모든 버전을 표시하도록 선택합니다. {{/* min-version: 2.1.208 */}}노트는 Claude가 보는 대화에 들어가지 않고 트랜스크립트에 표시됩니다. v2.1.208 이전에는 본 노트가 대화에 들어갔으며, 모든 버전을 표시할 때 전체 변경 로그를 포함했습니다 |

116| `/reload-plugins [--force]` | 모든 활성 [plugins](/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드가 로드된 MCP 도구를 변경하고 프롬프트 캐시를 무효화할 때, 명령어는 경고하고 `--force`를 전달하지 않으면 건너뜁니다 |116| `/reload-plugins [--force]` | 모든 활성 [plugins](/docs/ko/plugins)를 다시 로드하여 재시작하지 않고 보류 중인 변경 사항을 적용합니다. 각 다시 로드된 구성 요소의 개수를 보고하고 로드 오류를 표시합니다. 다시 로드가 로드된 MCP 도구를 변경하고 프롬프트 캐시를 무효화할 때, 명령어는 경고하고 `--force`를 전달하지 않으면 건너뜁니다 |

117| `/reload-skills` | {/* min-version: 2.1.152 */}}[skill](/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다. v2.1.152에서 추가됨 |117| `/reload-skills` | {/* min-version: 2.1.152 */}}[skill](/docs/ko/skills) 및 명령어 디렉토리를 다시 스캔하여 세션 중에 디스크에서 추가되거나 변경된 skills를 재시작하지 않고 사용할 수 있도록 합니다. 사용 가능한 skills의 개수와 추가되거나 제거된 skills의 개수를 보고합니다. v2.1.152에서 추가됨 |

118| `/remote-control` | 이 세션을 claude.ai에서 [Remote Control](/ko/remote-control)할 수 있도록 합니다. {{/* min-version: 2.1.206 */}}로그아웃 상태에서 실행하면 Remote Control에 claude.ai 구독이 필요하다고 인쇄하고 로그인 방법을 알려줍니다. v2.1.206 이전에는 `Unknown command: /remote-control`을 보고했습니다. 별칭: `/rc` |118| `/remote-control` | 이 세션을 claude.ai에서 [Remote Control](/docs/ko/remote-control)할 수 있도록 합니다. {{/* min-version: 2.1.206 */}}로그아웃 상태에서 실행하면 Remote Control에 claude.ai 구독이 필요하다고 인쇄하고 로그인 방법을 알려줍니다. v2.1.206 이전에는 `Unknown command: /remote-control`을 보고했습니다. 별칭: `/rc` |

120| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다 |120| `/rename [name]` | 현재 세션의 이름을 바꾸고 프롬프트 바에 이름을 표시합니다. 이름이 없으면 대화 기록에서 자동으로 생성합니다. {/* min-version: 2.1.205 */}비대화형 모드(`-p`)에서도 사용 가능합니다. Claude Code v2.1.205 이상이 필요합니다 |

121| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 실행 중인 세션은 여기서 재개할 수 없으므로 `claude agents`에서 연결하거나 먼저 중지하세요. 별칭: `/continue` |121| `/resume [session]` | ID 또는 이름으로 대화를 재개하거나 세션 선택기를 엽니다. v2.1.144부터 [background sessions](/docs/ko/agent-view)이 선택기에 `bg`로 표시됩니다. 실행 중인 세션은 여기서 재개할 수 없으므로 `claude agents`에서 연결하거나 먼저 중지하세요. 별칭: `/continue` |

122| `/review [PR]` | {/* min-version: 2.1.202 */}}GitHub pull request를 번호로 빠른 단일 패스, 읽기 전용 검토를 실행합니다. 인수 없이 선택할 열린 PR을 나열합니다. PR 번호 뒤의 텍스트는 추가 검토 지침이 됩니다. v2.1.186부터 v2.1.201까지 `/review`는 `/code-review medium`과 동일한 다중 agent 엔진을 실행했습니다. 선택한 노력 수준에서 다중 agent 검토의 경우 [`/code-review <level> <pr#>`](/ko/code-review#review-a-diff-locally)를 사용하세요. 클라우드 기반 검토의 경우 [`/code-review ultra`](/ko/ultrareview)를 참조하세요 |122| `/review [PR]` | {/* min-version: 2.1.202 */}}GitHub pull request를 번호로 빠른 단일 패스, 읽기 전용 검토를 실행합니다. 인수 없이 선택할 열린 PR을 나열합니다. PR 번호 뒤의 텍스트는 추가 검토 지침이 됩니다. v2.1.186부터 v2.1.201까지 `/review`는 `/code-review medium`과 동일한 다중 agent 엔진을 실행했습니다. 선택한 노력 수준에서 다중 agent 검토의 경우 [`/code-review <level> <pr#>`](/docs/ko/code-review#review-a-diff-locally)를 사용하세요. 클라우드 기반 검토의 경우 [`/code-review ultra`](/docs/ko/ultrareview)를 참조하세요 |

123| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |123| `/rewind` | 대화 및/또는 코드를 이전 지점으로 되감기하거나 선택한 메시지에서 요약합니다. [checkpointing](/docs/ko/checkpointing)을 참조하세요. 별칭: `/checkpoint`, `/undo` |

124| `/run` | **[Skill](/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트나 타입 검사가 아닌 실행 중인 앱에서 변경 사항이 작동하는 것을 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |124| `/run` | **[Skill](/docs/ko/skills#bundled-skills).** 프로젝트의 앱을 시작하고 구동하여 테스트나 타입 검사가 아닌 실행 중인 앱에서 변경 사항이 작동하는 것을 확인합니다. [Run and verify your app](/docs/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

125| `/run-skill-generator` | **[Skill](/ko/skills#bundled-skills).** 깨끗한 환경에서 프로젝트의 앱을 빌드, 시작 및 구동하는 방법을 `/run` 및 `/verify`에 가르치고, 프로젝트별 [skill](/ko/skills#run-and-verify-your-app)을 작성합니다. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |125| `/run-skill-generator` | **[Skill](/docs/ko/skills#bundled-skills).** 깨끗한 환경에서 프로젝트의 앱을 빌드, 시작 및 구동하는 방법을 `/run` 및 `/verify`에 가르치고, 프로젝트별 [skill](/docs/ko/skills#run-and-verify-your-app)을 작성합니다. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

127| `/schedule [description]` | [routines](/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Anthropic 관리 클라우드 인프라에서 실행됩니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |127| `/schedule [description]` | [routines](/docs/ko/routines)를 만들거나, 업데이트하거나, 나열하거나, 실행합니다. Anthropic 관리 클라우드 인프라에서 실행됩니다. Claude가 설정 과정을 대화형으로 안내합니다. 별칭: `/routines` |

128| `/scroll-speed` | 마우스 휠 [scroll speed](/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |128| `/scroll-speed` | 마우스 휠 [scroll speed](/docs/ko/fullscreen#mouse-wheel-scrolling)를 대화형으로 조정합니다. 대화 상자가 열려 있는 동안 스크롤할 수 있는 눈금자를 사용하여 변경 사항을 미리 봅니다. [fullscreen rendering](/docs/ko/fullscreen)에서만 사용 가능하며 JetBrains IDE 터미널에서는 사용할 수 없습니다 |

130| `/setup-bedrock` | [Amazon Bedrock](/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Amazon Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |130| `/setup-bedrock` | [Amazon Bedrock](/docs/ko/amazon-bedrock) 인증, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_BEDROCK=1`이 설정되어 있을 때만 표시됩니다. 처음 Amazon Bedrock을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

131| `/setup-vertex` | [Google Cloud의 Agent Platform](/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Google Cloud의 Agent Platform을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |131| `/setup-vertex` | [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 인증, 프로젝트, 지역 및 모델 핀을 대화형 마법사를 통해 구성합니다. `CLAUDE_CODE_USE_VERTEX=1`이 설정되어 있을 때만 표시됩니다. 처음 Google Cloud의 Agent Platform을 사용하는 사용자는 로그인 화면에서도 이 마법사에 액세스할 수 있습니다 |

132| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |132| `/simplify [target]` | {/* min-version: 2.1.154 */}}**[Skill](/docs/ko/skills#bundled-skills).** 변경된 코드를 정리 기회에 대해 검토하고 수정 사항을 적용합니다. 4개의 검토 [agents](/docs/ko/sub-agents)가 병렬로 실행되어 기존 헬퍼의 재사용, 단순화, 효율성 및 변경이 추상화의 올바른 수준에 있는지 여부를 다룹니다. v2.1.154부터 검토는 정확성 버그를 찾지 않습니다. 버그를 찾으려면 `/code-review`를 사용하세요. 이전 버전에서 `/simplify`는 `/code-review --fix`와 동일합니다. 특정 대상을 검토하려면 경로 또는 PR 참조를 전달합니다 |

133| `/skills` | 사용 가능한 [skills](/ko/skills)를 나열합니다. {/* min-version: 2.1.121 */}}v2.1.121부터 입력하여 이름으로 목록을 필터링합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill의 가시성을 순환](/ko/skills#override-skill-visibility-from-settings)한 다음 `Enter`를 눌러 저장합니다 |133| `/skills` | 사용 가능한 [skills](/docs/ko/skills)를 나열합니다. {/* min-version: 2.1.121 */}}v2.1.121부터 입력하여 이름으로 목록을 필터링합니다. `t`를 눌러 토큰 수로 정렬합니다. `Space`를 눌러 [Claude 또는 `/` 메뉴에서 skill의 가시성을 순환](/docs/ko/skills#override-skill-visibility-from-settings)한 다음 `Enter`를 눌러 저장합니다 |

138| `/stop` | 현재 [background session](/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |138| `/stop` | 현재 [background session](/docs/ko/agent-view)을 중지합니다. 백그라운드 세션에 연결되어 있을 때만 사용 가능합니다. 트랜스크립트 및 모든 worktree는 유지됩니다. 중지하지 않고 분리하려면 `/exit`를 사용하거나 `←`를 누르세요 |

140| `/team-onboarding` | Claude Code 사용 기록에서 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령어 및 MCP 서버 사용을 분석하고 팀원이 첫 메시지로 붙여넣어 빠르게 설정할 수 있는 markdown 가이드를 생성합니다. claude.ai 구독자의 Pro, Max, Team 및 Enterprise 요금제의 경우, 팀원이 Claude Code에서 직접 열 수 있는 공유 링크도 반환합니다 |140| `/team-onboarding` | Claude Code 사용 기록에서 팀 온보딩 가이드를 생성합니다. Claude는 지난 30일간의 세션, 명령어 및 MCP 서버 사용을 분석하고 팀원이 첫 메시지로 붙여넣어 빠르게 설정할 수 있는 markdown 가이드를 생성합니다. claude.ai 구독자의 Pro, Max, Team 및 Enterprise 요금제의 경우, 팀원이 Claude Code에서 직접 열 수 있는 공유 링크도 반환합니다 |

141| `/teleport` | [Claude Code on the web](/ko/claude-code-on-the-web#from-web-to-terminal) 세션을 이 터미널로 가져옵니다. 선택기를 열고 브랜치와 대화를 가져옵니다. `/tp`로도 사용 가능합니다. claude.ai 구독이 필요합니다 |141| `/teleport` | [Claude Code on the web](/docs/ko/claude-code-on-the-web#from-web-to-terminal) 세션을 이 터미널로 가져옵니다. 선택기를 열고 브랜치와 대화를 가져옵니다. `/tp`로도 사용 가능합니다. claude.ai 구독이 필요합니다 |

142| `/terminal-setup` | Shift+Enter 및 기타 바로 가기에 대한 터미널 키바인딩을 구성합니다. VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed와 같이 필요한 터미널에서만 표시됩니다 |142| `/terminal-setup` | Shift+Enter 및 기타 바로 가기에 대한 터미널 키바인딩을 구성합니다. VS Code, Cursor, Devin Desktop, Alacritty 또는 Zed와 같이 필요한 터미널에서만 표시됩니다 |

143| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |143| `/theme` | 색상 테마를 변경합니다. 터미널의 어두운 또는 밝은 배경을 따르는 `auto` 옵션, 밝은 색과 어두운 색 변형, 색맹 접근 가능(daltonized) 테마, 터미널의 색상 팔레트를 사용하는 ANSI 테마 및 `~/.claude/themes/` 또는 plugins의 [custom themes](/docs/ko/terminal-config#create-a-custom-theme)를 포함합니다. \*\*New custom theme…\*\*를 선택하여 새로 만듭니다 |

144| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |144| `/tui [default\|fullscreen]` | 터미널 UI 렌더러를 설정하고 대화를 유지하면서 다시 시작합니다. `fullscreen`은 [flicker-free alt-screen renderer](/docs/ko/fullscreen)를 활성화합니다. 인수 없이 활성 렌더러를 인쇄합니다 |

146| `/ultrareview [PR]` | [ultrareview](/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. 선호되는 호출은 이제 `/code-review ultra`이며, `/ultrareview`는 별칭으로 유지됩니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |146| `/ultrareview [PR]` | [ultrareview](/docs/ko/ultrareview)를 사용하여 클라우드 샌드박스에서 깊은 다중 agent 코드 검토를 실행합니다. 선호되는 호출은 이제 `/code-review ultra`이며, `/ultrareview`는 별칭으로 유지됩니다. Pro 및 Max에서 3회 무료 실행을 포함한 후 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)가 필요합니다 |

148| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. Pro, Max, Team 또는 Enterprise 요금제에서는 skill, subagent, plugin 및 MCP 서버별 사용량 분석을 포함합니다. 자세한 내용은 [cost tracking guide](/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |148| `/usage` | 세션 비용, 요금제 사용 제한 및 활동 통계를 표시합니다. Pro, Max, Team 또는 Enterprise 요금제에서는 skill, subagent, plugin 및 MCP 서버별 사용량 분석을 포함합니다. 자세한 내용은 [cost tracking guide](/docs/ko/costs#using-the-%2Fusage-command)를 참조하세요. `/cost` 및 `/stats`는 별칭입니다 |

149| `/usage-credits` | 제한에 도달했을 때 계속 작업할 수 있도록 사용 크레딧을 구성합니다. Pro 및 Max 요금제에서는 사용 크레딧을 구매하고, 월간 지출 제한을 설정하고, 자동 재로드를 구성할 수 있는 [in-CLI dialog](/ko/costs#set-a-spend-limit-on-pro-and-max)를 엽니다. Claude Code v2.1.207 이전 버전 및 다른 요금제에서는 사용 크레딧 청구 페이지를 브라우저에서 엽니다. 단, Team 및 Enterprise 구성원이 청구 액세스 권한이 없으면 CLI에서 관리자에게 사용 크레딧 요청을 보냅니다. {{/* min-version: 2.1.205 */}}SSH를 통한 경우처럼 브라우저를 열 수 없을 때, 명령어는 대신 방문할 URL을 인쇄합니다. Claude Code v2.1.205 이상이 필요하며, 이전 버전은 그 경우 아무것도 표시하지 않았습니다. 이전에는 `/extra-usage` |149| `/usage-credits` | 제한에 도달했을 때 계속 작업할 수 있도록 사용 크레딧을 구성합니다. Pro 및 Max 요금제에서는 사용 크레딧을 구매하고, 월간 지출 제한을 설정하고, 자동 재로드를 구성할 수 있는 [in-CLI dialog](/docs/ko/costs#set-a-spend-limit-on-pro-and-max)를 엽니다. Claude Code v2.1.207 이전 버전 및 다른 요금제에서는 사용 크레딧 청구 페이지를 브라우저에서 엽니다. 단, Team 및 Enterprise 구성원이 청구 액세스 권한이 없으면 CLI에서 관리자에게 사용 크레딧 요청을 보냅니다. {{/* min-version: 2.1.205 */}}SSH를 통한 경우처럼 브라우저를 열 수 없을 때, 명령어는 대신 방문할 URL을 인쇄합니다. Claude Code v2.1.205 이상이 필요하며, 이전 버전은 그 경우 아무것도 표시하지 않았습니다. 이전에는 `/extra-usage` |

150| `/verify` | **[Skill](/ko/skills#bundled-skills).** 테스트나 타입 검사가 아닌 프로젝트의 앱을 빌드하고 실행하고 결과를 관찰하여 코드 변경이 수행해야 할 작업을 수행하는지 확인합니다. [Run and verify your app](/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |150| `/verify` | **[Skill](/docs/ko/skills#bundled-skills).** 테스트나 타입 검사가 아닌 프로젝트의 앱을 빌드하고 실행하고 결과를 관찰하여 코드 변경이 수행해야 할 작업을 수행하는지 확인합니다. [Run and verify your app](/docs/ko/skills#run-and-verify-your-app)을 참조하세요. {/* min-version: 2.1.145 */}}Claude Code v2.1.145 이상이 필요합니다 |

151| `/vim` | {/* max-version: 2.1.91 */}}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |151| `/vim` | {/* max-version: 2.1.91 */}}v2.1.92에서 제거됨. Vim과 Normal 편집 모드 사이를 전환하려면 `/config` → Editor mode를 사용하세요 |

152| `/voice [hold\|tap\|off]` | [voice dictation](/ko/voice-dictation)을 전환하거나 특정 모드에서 활성화합니다. Claude.ai 계정이 필요합니다 |152| `/voice [hold\|tap\|off]` | [voice dictation](/docs/ko/voice-dictation)을 전환하거나 특정 모드에서 활성화합니다. Claude.ai 계정이 필요합니다 |

153| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |153| `/web-setup` | 로컬 `gh` CLI 자격 증명을 사용하여 GitHub 계정을 [Claude Code on the web](/docs/ko/web-quickstart#connect-from-your-terminal)에 연결합니다. `/schedule`은 GitHub가 연결되지 않은 경우 자동으로 이를 요청합니다 |

154| `/workflows` | [workflow](/ko/workflows#watch-the-run) 진행 상황 뷰를 열어 실행 중이거나 완료된 workflows를 감시하고, 일시 중지하고, 재개하거나, 저장합니다 |154| `/workflows` | [workflow](/docs/ko/workflows#watch-the-run) 진행 상황 뷰를 열어 실행 중이거나 완료된 workflows를 감시하고, 일시 중지하고, 재개하거나, 저장합니다 |

155 155

156<h2 id="mcp-prompts">156<h2 id="mcp-prompts">

157 MCP 프롬프트157 MCP 프롬프트

158</h2>158</h2>

159 159

160MCP 서버는 명령어로 나타나는 프롬프트를 노출할 수 있습니다. 이들은 `/mcp__<server>__<prompt>` 형식을 사용하며 연결된 서버에서 동적으로 발견됩니다. 자세한 내용은 [MCP prompts](/ko/mcp#use-mcp-prompts-as-commands)를 참조하세요.160MCP 서버는 명령어로 나타나는 프롬프트를 노출할 수 있습니다. 이들은 `/mcp__<server>__<prompt>` 형식을 사용하며 연결된 서버에서 동적으로 발견됩니다. 자세한 내용은 [MCP prompts](/docs/ko/mcp#use-mcp-prompts-as-commands)를 참조하세요.

161 161

162<h2 id="see-also">162<h2 id="see-also">

163 참고 항목163 참고 항목

164</h2>164</h2>

165 165

166* [Skills](/ko/skills): 자신만의 명령어 만들기166* [Skills](/docs/ko/skills): 자신만의 명령어 만들기

167* [대화형 모드](/ko/interactive-mode): 키보드 바로 가기, Vim 모드 및 명령어 기록167* [대화형 모드](/docs/ko/interactive-mode): 키보드 바로 가기, Vim 모드 및 명령어 기록

168* [CLI 참조](/ko/cli-reference): 시작 시간 플래그168* [CLI 참조](/docs/ko/cli-reference): 시작 시간 플래그

hooks.md +62 −62

Details

7> Claude Code hook 이벤트, 구성 스키마, JSON 입출력 형식, 종료 코드, 비동기 hook, HTTP hook, 프롬프트 hook, MCP 도구 hook에 대한 참조입니다.7> Claude Code hook 이벤트, 구성 스키마, JSON 입출력 형식, 종료 코드, 비동기 hook, HTTP hook, 프롬프트 hook, MCP 도구 hook에 대한 참조입니다.

8 8

9<Tip>9<Tip>

~~10 예제가 포함된 빠른 시작 가이드는 [hook으로 워크플로우 자동화](/ko/hooks-guide)를 참조하세요.~~10 예제가 포함된 빠른 시작 가이드는 [hook으로 워크플로우 자동화](/docs/ko/hooks-guide)를 참조하세요.

11</Tip>11</Tip>

12 12

13Hook은 Claude Code의 수명 주기에서 특정 지점에 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트 또는 LLM 프롬프트입니다. 이 참조를 사용하여 이벤트 스키마, 구성 옵션, JSON 입출력 형식, 비동기 hook, HTTP hook, MCP 도구 hook과 같은 고급 기능을 조회할 수 있습니다. 처음으로 hook을 설정하는 경우 대신 [가이드](/ko/hooks-guide)부터 시작하세요.13Hook은 Claude Code의 수명 주기에서 특정 지점에 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트 또는 LLM 프롬프트입니다. 이 참조를 사용하여 이벤트 스키마, 구성 옵션, JSON 입출력 형식, 비동기 hook, HTTP hook, MCP 도구 hook과 같은 고급 기능을 조회할 수 있습니다. 처음으로 hook을 설정하는 경우 대신 [가이드](/docs/ko/hooks-guide)부터 시작하세요.

14 14

15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">

16 Hook 수명 주기16 Hook 수명 주기

52| `TaskCompleted` | When a task is being marked as completed |52| `TaskCompleted` | When a task is being marked as completed |

53| `Stop` | When Claude finishes responding |53| `Stop` | When Claude finishes responding |

54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |54| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

57| `ConfigChange` | When a configuration file changes during a session |57| `ConfigChange` | When a configuration file changes during a session |

58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |59| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

~~60| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |~~60| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

62| `PreCompact` | Before context compaction |62| `PreCompact` | Before context compaction |

63| `PostCompact` | After context compaction completes |63| `PostCompact` | After context compaction completes |

64| `Elicitation` | When an MCP server requests user input during a tool call |64| `Elicitation` | When an MCP server requests user input during a tool call |

147 }147 }

148 ```148 ```

149 149

150 명령이 `rm file.txt`와 같은 더 안전한 `rm` 변형이었다면 스크립트는 대신 `exit 0`을 실행합니다. 출력이 없는 종료 코드 0은 hook이 보고할 결정이 없다는 의미이므로 도구 호출은 일반적인 [권한 흐름](/ko/permissions)을 통해 계속됩니다. hook은 호출을 거부할 수 있지만 침묵을 유지하는 것은 이를 승인하지 않습니다.150 명령이 `rm file.txt`와 같은 더 안전한 `rm` 변형이었다면 스크립트는 대신 `exit 0`을 실행합니다. 출력이 없는 종료 코드 0은 hook이 보고할 결정이 없다는 의미이므로 도구 호출은 일반적인 [권한 흐름](/docs/ko/permissions)을 통해 계속됩니다. hook은 호출을 거부할 수 있지만 침묵을 유지하는 것은 이를 승인하지 않습니다.

151 </Step>151 </Step>

152 152

153 <Step title="Claude Code가 결과에 따라 행동">153 <Step title="Claude Code가 결과에 따라 행동">

190 190

191설정 파일 해결에 대한 자세한 내용은 [설정](/ko/settings)을 참조하세요.191설정 파일 해결에 대한 자세한 내용은 [설정](/docs/ko/settings)을 참조하세요.

192 192

193엔터프라이즈 관리자는 `allowManagedHooksOnly`를 사용하여 사용자, 프로젝트 및 plugin hook을 차단할 수 있습니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 plugin의 hook은 면제되므로 관리자는 조직 마켓플레이스를 통해 검증된 hook을 배포할 수 있습니다. [Hook 구성](/ko/settings#hook-configuration)을 참조하세요.193엔터프라이즈 관리자는 `allowManagedHooksOnly`를 사용하여 사용자, 프로젝트 및 plugin hook을 차단할 수 있습니다. 관리형 설정 `enabledPlugins`에서 강제 활성화된 plugin의 hook은 면제되므로 관리자는 조직 마켓플레이스를 통해 검증된 hook을 배포할 수 있습니다. [Hook 구성](/docs/ko/settings#hook-configuration)을 참조하세요.

194 194

195<h3 id="matcher-patterns">195<h3 id="matcher-patterns">

196 Matcher 패턴196 Matcher 패턴

260 260

261`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay`, `CwdChanged`는 matcher를 지원하지 않으며 모든 발생에서 항상 발생합니다. 이러한 이벤트에 `matcher` 필드를 추가하면 자동으로 무시됩니다.261`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay`, `CwdChanged`는 matcher를 지원하지 않으며 모든 발생에서 항상 발생합니다. 이러한 이벤트에 `matcher` 필드를 추가하면 자동으로 무시됩니다.

262 262

263도구 이벤트의 경우 개별 hook 핸들러에서 [`if` 필드](#common-fields)를 설정하여 더 좁게 필터링할 수 있습니다. `if`는 [권한 규칙 구문](/ko/permissions)을 사용하여 도구 이름과 인수를 함께 일치시키므로 `"Bash(git *)"` 는 `git *` 패턴과 일치하는 모든 하위 명령에서 실행되고 `"Edit(*.ts)"`는 TypeScript 파일에만 실행됩니다.263도구 이벤트의 경우 개별 hook 핸들러에서 [`if` 필드](#common-fields)를 설정하여 더 좁게 필터링할 수 있습니다. `if`는 [권한 규칙 구문](/docs/ko/permissions)을 사용하여 도구 이름과 인수를 함께 일치시키므로 `"Bash(git *)"` 는 `git *` 패턴과 일치하는 모든 하위 명령에서 실행되고 `"Edit(*.ts)"`는 TypeScript 파일에만 실행됩니다.

264 264

265<h4 id="match-mcp-tools">265<h4 id="match-mcp-tools">

266 MCP 도구 일치266 MCP 도구 일치

267</h4>267</h4>

268 268

269[MCP](/ko/mcp) 서버 도구는 도구 이벤트 (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`)에서 일반 도구로 나타나므로 다른 도구 이름과 동일한 방식으로 일치시킬 수 있습니다.269[MCP](/docs/ko/mcp) 서버 도구는 도구 이벤트 (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`)에서 일반 도구로 나타나므로 다른 도구 이름과 동일한 방식으로 일치시킬 수 있습니다.

270 270

271MCP 도구는 `mcp__<server>__<tool>` 명명 패턴을 따릅니다. 예를 들어:271MCP 도구는 `mcp__<server>__<tool>` 명명 패턴을 따릅니다. 예를 들어:

272 272

282 282

283정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `mcp__brave-search`와 같은 bare 하이픈이 있는 접두사가 앵커 없는 정규식으로 평가되고 해당 서버의 모든 도구와 일치합니다. `mcp__brave-search__.*` 형식은 모든 버전에서 작동합니다.283정확한 일치 집합의 하이픈은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전에서는 `mcp__brave-search`와 같은 bare 하이픈이 있는 접두사가 앵커 없는 정규식으로 평가되고 해당 서버의 모든 도구와 일치합니다. `mcp__brave-search__.*` 형식은 모든 버전에서 작동합니다.

284 284

285[plugin 번들 MCP 서버](/ko/mcp#plugin-provided-mcp-servers)의 도구는 plugin 이름을 포함하는 범위가 지정된 서버 세그먼트를 사용합니다: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. bare 서버 키에 대해 작성된 matcher는 이러한 도구에 대해 발생하지 않습니다. `my-plugin`이라는 plugin이 `db` 키 아래에 서버를 번들하는 경우 `query` 도구는 `mcp__plugin_my-plugin_db__query`로 나타나므로 해당 서버의 모든 도구에 대한 matcher는 `mcp__plugin_my-plugin_db__.*`입니다. 핸들러의 [`if` 필드](#common-fields)에서 동일한 범위가 지정된 도구 이름을 사용합니다. 범위가 지정된 이름이 구축되는 방식에 대해서는 [Plugin 제공 MCP 서버](/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.285[plugin 번들 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 도구는 plugin 이름을 포함하는 범위가 지정된 서버 세그먼트를 사용합니다: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. bare 서버 키에 대해 작성된 matcher는 이러한 도구에 대해 발생하지 않습니다. `my-plugin`이라는 plugin이 `db` 키 아래에 서버를 번들하는 경우 `query` 도구는 `mcp__plugin_my-plugin_db__query`로 나타나므로 해당 서버의 모든 도구에 대한 matcher는 `mcp__plugin_my-plugin_db__.*`입니다. 핸들러의 [`if` 필드](#common-fields)에서 동일한 범위가 지정된 도구 이름을 사용합니다. 범위가 지정된 이름이 구축되는 방식에 대해서는 [Plugin 제공 MCP 서버](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.

286 286

287이 예제는 모든 memory 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:287이 예제는 모든 memory 서버 작업을 기록하고 모든 MCP 서버의 쓰기 작업을 검증합니다:

288 288

321 321

322* **[명령 hook](#command-hook-fields)** (`type: "command"`): 셸 명령을 실행합니다. 스크립트는 이벤트의 [JSON 입력](#hook-input-and-output)을 stdin에서 받고 종료 코드와 stdout을 통해 결과를 다시 전달합니다.322* **[명령 hook](#command-hook-fields)** (`type: "command"`): 셸 명령을 실행합니다. 스크립트는 이벤트의 [JSON 입력](#hook-input-and-output)을 stdin에서 받고 종료 코드와 stdout을 통해 결과를 다시 전달합니다.

323* **[HTTP hook](#http-hook-fields)** (`type: "http"`): 이벤트의 JSON 입력을 HTTP POST 요청으로 URL에 전송합니다. 엔드포인트는 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용하여 응답 본문을 통해 결과를 다시 전달합니다.323* **[HTTP hook](#http-hook-fields)** (`type: "http"`): 이벤트의 JSON 입력을 HTTP POST 요청으로 URL에 전송합니다. 엔드포인트는 명령 hook과 동일한 [JSON 출력 형식](#json-output)을 사용하여 응답 본문을 통해 결과를 다시 전달합니다.

324* **[MCP 도구 hook](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): 이미 연결된 [MCP 서버](/ko/mcp)의 도구를 호출합니다. 도구의 텍스트 출력은 명령 hook stdout처럼 처리됩니다.324* **[MCP 도구 hook](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): 이미 연결된 [MCP 서버](/docs/ko/mcp)의 도구를 호출합니다. 도구의 텍스트 출력은 명령 hook stdout처럼 처리됩니다.

325* **[프롬프트 hook](#prompt-and-agent-hook-fields)** (`type: "prompt"`): Claude 모델에 단일 턴 평가를 위한 프롬프트를 전송합니다. 모델은 yes/no 결정을 JSON으로 반환합니다. [프롬프트 기반 hook](#prompt-based-hooks)을 참조하세요.325* **[프롬프트 hook](#prompt-and-agent-hook-fields)** (`type: "prompt"`): Claude 모델에 단일 턴 평가를 위한 프롬프트를 전송합니다. 모델은 yes/no 결정을 JSON으로 반환합니다. [프롬프트 기반 hook](#prompt-based-hooks)을 참조하세요.

326* **[에이전트 hook](#prompt-and-agent-hook-fields)** (`type: "agent"`): Read, Grep, Glob과 같은 도구를 사용하여 결정을 반환하기 전에 조건을 확인할 수 있는 subagent를 생성합니다. 에이전트 hook은 실험적이며 변경될 수 있습니다. [에이전트 기반 hook](#agent-based-hooks)을 참조하세요.326* **[에이전트 hook](#prompt-and-agent-hook-fields)** (`type: "agent"`): Read, Grep, Glob과 같은 도구를 사용하여 결정을 반환하기 전에 조건을 확인할 수 있는 subagent를 생성합니다. 에이전트 hook은 실험적이며 변경될 수 있습니다. [에이전트 기반 hook](#agent-based-hooks)을 참조하세요.

327 327

328일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제거되고 HTTP hook은 URL로 중복 제거됩니다.328일치하는 모든 hook은 병렬로 실행되며 동일한 핸들러는 자동으로 중복 제거됩니다. 명령 hook은 명령 문자열과 `args`로 중복 제거되고 HTTP hook은 URL로 중복 제거됩니다.

329 329

330핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다. {/* min-version: 2.1.199 */}v2.1.199부터 [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/ko/env-vars)는 로컬 세션이 활성 Remote Control 연결을 가지고 있는 동안 [Remote Control](/ko/remote-control) 세션 ID로 설정됩니다.330핸들러는 현재 디렉토리에서 Claude Code의 환경으로 실행됩니다. `$CLAUDE_CODE_REMOTE` 환경 변수는 원격 웹 환경에서 `"true"`로 설정되고 로컬 CLI에서는 설정되지 않습니다. {/* min-version: 2.1.199 */}v2.1.199부터 [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/ko/env-vars)는 로컬 세션이 활성 Remote Control 연결을 가지고 있는 동안 [Remote Control](/docs/ko/remote-control) 세션 ID로 설정됩니다.

331 331

332<h4 id="common-fields">332<h4 id="common-fields">

333 공통 필드333 공통 필드

338| 필드 | 필수 | 설명 |338| 필드 | 필수 | 설명 |

339| :-------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |339| :-------------- | :-- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

340| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |340| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |

341| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook 명령은 도구 호출이 패턴과 일치할 때만 실행됩니다. [Bash 일치 테이블](#bash-if-matching) 아래에서 Bash 패턴이 하위 명령, `$()`, 백틱에 대해 어떻게 평가되는지 확인하세요. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/ko/permissions)과 동일한 구문을 사용합니다 |341| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook 명령은 도구 호출이 패턴과 일치할 때만 실행됩니다. [Bash 일치 테이블](#bash-if-matching) 아래에서 Bash 패턴이 하위 명령, `$()`, 백틱에 대해 어떻게 평가되는지 확인하세요. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/docs/ko/permissions)과 동일한 구문을 사용합니다 |

342| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: `command`, `http`, `mcp_tool`의 경우 600; `prompt`의 경우 30; `agent`의 경우 60. [`UserPromptSubmit`](#userpromptsubmit)은 `command`, `http`, `mcp_tool`의 기본값을 30으로 낮추고 [`MessageDisplay`](#messagedisplay)는 10으로 낮춥니다 |342| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: `command`, `http`, `mcp_tool`의 경우 600; `prompt`의 경우 30; `agent`의 경우 60. [`UserPromptSubmit`](#userpromptsubmit)은 `command`, `http`, `mcp_tool`의 기본값을 30으로 낮추고 [`MessageDisplay`](#messagedisplay)는 10으로 낮춥니다 |

343| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |343| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |

344| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |344| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |

357 357

358필터는 또한 Bash 명령을 구문 분석할 수 없을 때 열려 있으므로 패턴과 관계없이 hook을 실행합니다. `if` 필터는 최선의 노력이므로 hard allow 또는 deny를 적용하려면 hook 대신 [권한 시스템](/ko/permissions)을 사용하세요.358필터는 또한 Bash 명령을 구문 분석할 수 없을 때 열려 있으므로 패턴과 관계없이 hook을 실행합니다. `if` 필터는 최선의 노력이므로 hard allow 또는 deny를 적용하려면 hook 대신 [권한 시스템](/docs/ko/permissions)을 사용하세요.

359 359

360<h4 id="command-hook-fields">360<h4 id="command-hook-fields">

361 명령 hook 필드361 명령 hook 필드

406}406}

407```407```

408 408

409두 형식 모두 동일한 [경로 자리 표시자](#reference-scripts-by-path)를 지원하며 생성된 프로세스에서 환경 변수 `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`로 내보내므로 스크립트는 시작 방식과 관계없이 `process.env.CLAUDE_PLUGIN_ROOT`를 읽을 수 있습니다. Plugin hook은 추가로 [`${user_config.*}`](/ko/plugins-reference#user-configuration) 값을 대체합니다. exec 형식에서만: 값은 `command` 및 각 `args` 요소로 일반 문자열로 대체되므로 셸이 다시 구문 분석하지 않습니다.409두 형식 모두 동일한 [경로 자리 표시자](#reference-scripts-by-path)를 지원하며 생성된 프로세스에서 환경 변수 `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`로 내보내므로 스크립트는 시작 방식과 관계없이 `process.env.CLAUDE_PLUGIN_ROOT`를 읽을 수 있습니다. Plugin hook은 추가로 [`${user_config.*}`](/docs/ko/plugins-reference#user-configuration) 값을 대체합니다. exec 형식에서만: 값은 `command` 및 각 `args` 요소로 일반 문자열로 대체되므로 셸이 다시 구문 분석하지 않습니다.

410 410

411`${user_config.*}`를 참조하는 셸 형식 plugin hook 명령은 대신 [오류](/ko/errors#plugin-command-references-user-config)로 실패합니다. 셸 형식 hook에서 옵션 값을 사용하려면 `$CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수 (예: `webhook_url` 옵션의 경우 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`)를 읽거나 `args`를 설정하여 hook을 exec 형식으로 전환합니다. v2.1.207 이전에는 셸 형식 plugin hook 명령도 `${user_config.*}`를 대체했습니다.411`${user_config.*}`를 참조하는 셸 형식 plugin hook 명령은 대신 [오류](/docs/ko/errors#plugin-command-references-user-config)로 실패합니다. 셸 형식 hook에서 옵션 값을 사용하려면 `$CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수 (예: `webhook_url` 옵션의 경우 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`)를 읽거나 `args`를 설정하여 hook을 exec 형식으로 전환합니다. v2.1.207 이전에는 셸 형식 plugin hook 명령도 `${user_config.*}`를 대체했습니다.

412 412

413<Note>413<Note>

414 Exec 형식에서 `command`는 실행 파일 이름 또는 경로만입니다. `command`가 경로 구분자가 없는 bare 이름이고 `args`와 함께 공백을 포함하면 Claude Code는 경고를 기록합니다. 생성이 실패하기 때문입니다: `node script.js`라는 이름의 실행 파일이 없습니다. 추가 토큰을 `args`로 이동합니다. `C:\Program Files\nodejs\node.exe`와 같은 공백이 있는 절대 경로는 단일 유효한 실행 파일이며 경고를 트리거하지 않습니다.414 Exec 형식에서 `command`는 실행 파일 이름 또는 경로만입니다. `command`가 경로 구분자가 없는 bare 이름이고 `args`와 함께 공백을 포함하면 Claude Code는 경고를 기록합니다. 생성이 실패하기 때문입니다: `node script.js`라는 이름의 실행 파일이 없습니다. 추가 토큰을 `args`로 이동합니다. `C:\Program Files\nodejs\node.exe`와 같은 공백이 있는 절대 경로는 단일 유효한 실행 파일이며 경고를 트리거하지 않습니다.

463 463

464| 필드 | 필수 | 설명 |464| 필드 | 필수 | 설명 |

465| :------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |465| :------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

466| `server` | 예 | 구성된 MCP 서버의 이름. [plugin 번들 서버](/ko/mcp#plugin-provided-mcp-servers)의 경우 범위가 지정된 이름 `plugin:<plugin-name>:<server-name>` (예: `plugin:my-plugin:db`)이며 bare 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다 |466| `server` | 예 | 구성된 MCP 서버의 이름. [plugin 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 경우 범위가 지정된 이름 `plugin:<plugin-name>:<server-name>` (예: `plugin:my-plugin:db`)이며 bare 서버 키가 아닙니다. 서버는 이미 연결되어 있어야 합니다. hook은 OAuth 또는 연결 흐름을 트리거하지 않습니다 |

467| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |467| `tool` | 예 | 해당 서버에서 호출할 도구의 이름 |

468| `input` | 아니오 | 도구에 전달되는 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 치환을 지원합니다 (예: `"${tool_input.file_path}"`) |468| `input` | 아니오 | 도구에 전달되는 인수. 문자열 값은 hook의 [JSON 입력](#hook-input-and-output)에서 `${path}` 치환을 지원합니다 (예: `"${tool_input.file_path}"`) |

469 469

510 510

511프로젝트 또는 plugin 루트를 기준으로 hook 스크립트를 참조하려면 이러한 자리 표시자를 사용합니다. hook이 실행될 때의 작업 디렉토리와 관계없이:511프로젝트 또는 plugin 루트를 기준으로 hook 스크립트를 참조하려면 이러한 자리 표시자를 사용합니다. hook이 실행될 때의 작업 디렉토리와 관계없이:

512 512

513* `${CLAUDE_PROJECT_DIR}`: 프로젝트 루트. Claude Code는 또한 이 변수를 [stdio MCP 서버](/ko/mcp#option-3-add-a-local-stdio-server)와 plugin LSP 서버의 환경에서 설정합니다.513* `${CLAUDE_PROJECT_DIR}`: 프로젝트 루트. Claude Code는 또한 이 변수를 [stdio MCP 서버](/docs/ko/mcp#option-3-add-a-local-stdio-server)와 plugin LSP 서버의 환경에서 설정합니다.

514* `${CLAUDE_PLUGIN_ROOT}`: plugin의 설치 디렉토리, [plugin](/ko/plugins)과 함께 번들된 스크립트의 경우. plugin 업데이트 시마다 변경됩니다.514* `${CLAUDE_PLUGIN_ROOT}`: plugin의 설치 디렉토리, [plugin](/docs/ko/plugins)과 함께 번들된 스크립트의 경우. plugin 업데이트 시마다 변경됩니다.

515* `${CLAUDE_PLUGIN_DATA}`: plugin의 [지속적 데이터 디렉토리](/ko/plugins-reference#persistent-data-directory), plugin 업데이트를 거쳐 유지되어야 하는 종속성 및 상태의 경우.515* `${CLAUDE_PLUGIN_DATA}`: plugin의 [지속적 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory), plugin 업데이트를 거쳐 유지되어야 하는 종속성 및 상태의 경우.

516 516

517경로 자리 표시자를 참조하는 모든 hook에 대해 [exec 형식](#exec-form-and-shell-form)을 선호합니다. Exec 형식은 각 `args` 요소를 셸 토큰화 없이 하나의 인수로 전달하므로 공백이나 특수 문자가 있는 경로는 따옴표가 필요하지 않습니다. 셸 형식에서는 각 자리 표시자를 큰따옴표로 감싸세요.517경로 자리 표시자를 참조하는 모든 hook에 대해 [exec 형식](#exec-form-and-shell-form)을 선호합니다. Exec 형식은 각 `args` 요소를 셸 토큰화 없이 하나의 인수로 전달하므로 공백이나 특수 문자가 있는 경로는 따옴표가 필요하지 않습니다. 셸 형식에서는 각 자리 표시자를 큰따옴표로 감싸세요.

518 518

566 }566 }

567 ```567 ```

568 568

569 plugin hook 생성에 대한 자세한 내용은 [plugin 컴포넌트 참조](/ko/plugins-reference#hooks)를 참조하세요.569 plugin hook 생성에 대한 자세한 내용은 [plugin 컴포넌트 참조](/docs/ko/plugins-reference#hooks)를 참조하세요.

570 </Tab>570 </Tab>

571</Tabs>571</Tabs>

572 572

574 Skill 및 에이전트의 Hook574 Skill 및 에이전트의 Hook

575</h3>575</h3>

576 576

577설정 파일 및 plugin 외에도 hook은 frontmatter를 사용하여 [skill](/ko/skills) 및 [subagent](/ko/sub-agents)에서 직접 정의할 수 있습니다. 이러한 hook은 컴포넌트의 수명 주기로 범위가 지정되며 해당 컴포넌트가 활성화되어 있을 때만 실행됩니다.577설정 파일 및 plugin 외에도 hook은 frontmatter를 사용하여 [skill](/docs/ko/skills) 및 [subagent](/docs/ko/sub-agents)에서 직접 정의할 수 있습니다. 이러한 hook은 컴포넌트의 수명 주기로 범위가 지정되며 해당 컴포넌트가 활성화되어 있을 때만 실행됩니다.

578 578

579모든 hook 이벤트가 지원됩니다. subagent의 경우 `Stop` hook은 subagent가 완료될 때 발생하는 이벤트이므로 자동으로 `SubagentStop`으로 변환됩니다.579모든 hook 이벤트가 지원됩니다. subagent의 경우 `Stop` hook은 subagent가 완료될 때 발생하는 이벤트이므로 자동으로 `SubagentStop`으로 변환됩니다.

580 580

643| 필드 | 설명 |643| 필드 | 설명 |

644| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |644| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

646| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상 필요 |646| `prompt_id` | 현재 처리 중인 사용자 프롬프트를 식별하는 UUID입니다. [OpenTelemetry 이벤트의 `prompt.id` 속성](/docs/ko/monitoring-usage#event-correlation-attributes)과 일치하므로 hook 출력을 단일 프롬프트의 원격 분석과 연관시킬 수 있습니다. 첫 번째 사용자 입력까지 없습니다. {/* min-version: 2.1.196 */}Claude Code v2.1.196 이상 필요 |

647| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |647| `transcript_path` | 대화 JSON 경로입니다. 트랜스크립트 파일은 비동기적으로 기록되며 메모리 내 대화보다 뒤떨어질 수 있으므로 hook이 발생할 때 현재 턴의 가장 최근 메시지를 아직 포함하지 않을 수 있습니다. 현재 턴의 최종 어시스턴트 텍스트가 필요한 hook은 트랜스크립트를 읽는 대신 [Stop](#stop) 및 [SubagentStop](#subagentstop)에서 `last_assistant_message`를 사용해야 합니다 |

648| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |648| `cwd` | hook이 호출될 때의 현재 작업 디렉토리 |

649| `permission_mode` | 현재 [권한 모드](/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. **수동**으로 표시된 모드는 `"default"`로 도착하며 `"manual"`로 도착하지 않으므로 `"default"`와 일치하는 스크립트는 계속 작동합니다. 모든 이벤트가 이 필드를 받는 것은 아닙니다. 각 [hook 이벤트](#hook-events) 섹션의 JSON 예제를 확인하세요 |649| `permission_mode` | 현재 [권한 모드](/docs/ko/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` 또는 `"bypassPermissions"`. **수동**으로 표시된 모드는 `"default"`로 도착하며 `"manual"`로 도착하지 않으므로 `"default"`와 일치하는 스크립트는 계속 작동합니다. 모든 이벤트가 이 필드를 받는 것은 아닙니다. 각 [hook 이벤트](#hook-events) 섹션의 JSON 예제를 확인하세요 |

650| `effort` | 활성 [노력 수준](/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 요청된 모델 노력이 현재 모델이 지원하는 것을 초과하면 이는 모델이 실제로 사용한 다운그레이드된 수준입니다. Ultracode는 별개의 수준이 아니며 `"xhigh"`로 보고됩니다. 객체는 [상태 줄](/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |650| `effort` | 활성 [노력 수준](/docs/ko/model-config#adjust-effort-level)을 보유하는 `level` 필드가 있는 객체: `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 요청된 모델 노력이 현재 모델이 지원하는 것을 초과하면 이는 모델이 실제로 사용한 다운그레이드된 수준입니다. Ultracode는 별개의 수준이 아니며 `"xhigh"`로 보고됩니다. 객체는 [상태 줄](/docs/ko/statusline#available-data) `effort` 필드와 일치합니다. `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`과 같은 도구 사용 컨텍스트 내에서 발생하는 이벤트에 대해 현재 모델이 노력 매개변수를 지원할 때 존재합니다. 수준은 `$CLAUDE_EFFORT` 환경 변수로 hook 명령 및 Bash 도구에서도 사용 가능합니다. |

652 652

653`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:653`--agent`로 실행하거나 subagent 내부에서 실행할 때 두 개의 추가 필드가 포함됩니다:

655| 필드 | 설명 |655| 필드 | 설명 |

656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |656| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

658| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [사용자 정의 subagent](/ko/sub-agents)의 경우 이는 에이전트의 frontmatter에서 `name` 필드이며 파일명이 아닙니다. [플러그인](/ko/plugins)에서 제공하는 subagent의 경우 이는 `my-plugin:reviewer`와 같은 플러그인 범위 식별자이며 bare frontmatter 이름이 아닙니다. 플러그인 범위 이름에 대해 matcher를 작성하는 방법은 [SubagentStart](#subagentstart)를 참조하세요. |658| `agent_type` | 에이전트 이름 (예: `"Explore"` 또는 `"security-reviewer"`). 세션이 `--agent`를 사용하거나 hook이 subagent 내부에서 발생할 때 존재합니다. subagent의 경우 subagent의 유형이 세션의 `--agent` 값보다 우선합니다. [사용자 정의 subagent](/docs/ko/sub-agents)의 경우 이는 에이전트의 frontmatter에서 `name` 필드이며 파일명이 아닙니다. [플러그인](/docs/ko/plugins)에서 제공하는 subagent의 경우 이는 `my-plugin:reviewer`와 같은 플러그인 범위 식별자이며 bare frontmatter 이름이 아닙니다. 플러그인 범위 이름에 대해 matcher를 작성하는 방법은 [SubagentStart](#subagentstart)를 참조하세요. |

659 659

660`SessionStart` hook만 `model` 필드를 받을 수 있으며 존재가 보장되지 않습니다. `$CLAUDE_MODEL` 환경 변수는 없습니다. hook 프로세스는 부모 환경을 상속하므로 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만 세션 중에 `/model`로 모델을 전환할 때 해당 값은 변경되지 않습니다. 상속되지 않는 변수 집합이 하나 있습니다: Claude Code는 [hook을 포함한 생성하는 모든 서브프로세스에서 `OTEL_*` 내보내기 변수를 제거합니다](/ko/monitoring-usage#administrator-configuration).660`SessionStart` hook만 `model` 필드를 받을 수 있으며 존재가 보장되지 않습니다. `$CLAUDE_MODEL` 환경 변수는 없습니다. hook 프로세스는 부모 환경을 상속하므로 셸에서 설정한 경우 `$ANTHROPIC_MODEL`을 읽을 수 있지만 세션 중에 `/model`로 모델을 전환할 때 해당 값은 변경되지 않습니다. 상속되지 않는 변수 집합이 하나 있습니다: Claude Code는 [hook을 포함한 생성하는 모든 서브프로세스에서 `OTEL_*` 내보내기 변수를 제거합니다](/docs/ko/monitoring-usage#administrator-configuration).

661 661

662예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:662예를 들어 Bash 명령에 대한 `PreToolUse` hook은 stdin에서 다음을 받습니다:

663 663

776 hook당 하나의 접근 방식을 선택해야 합니다. 둘 다 선택하지 마세요: 종료 코드만 사용하여 신호하거나 종료 0으로 JSON을 인쇄하여 구조화된 제어를 합니다. Claude Code는 종료 0에서만 JSON을 처리합니다. 종료 2로 나가면 JSON은 무시됩니다.776 hook당 하나의 접근 방식을 선택해야 합니다. 둘 다 선택하지 마세요: 종료 코드만 사용하여 신호하거나 종료 0으로 JSON을 인쇄하여 구조화된 제어를 합니다. Claude Code는 종료 0에서만 JSON을 처리합니다. 종료 2로 나가면 JSON은 무시됩니다.

777</Note>777</Note>

778 778

779hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 인쇄하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [JSON 검증 실패](/ko/hooks-guide#json-validation-failed)를 참조하세요.779hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 인쇄하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [JSON 검증 실패](/docs/ko/hooks-guide#json-validation-failed)를 참조하세요.

780 780

781hook 출력 문자열 (`additionalContext`, `systemMessage`, 및 일반 stdout)은 10,000자로 제한됩니다. 이 제한을 초과하는 출력은 파일에 저장되고 미리보기 및 파일 경로로 바뀌며, 큰 도구 결과가 처리되는 방식과 동일합니다.781hook 출력 문자열 (`additionalContext`, `systemMessage`, 및 일반 stdout)은 10,000자로 제한됩니다. 이 제한을 초과하는 출력은 파일에 저장되고 미리보기 및 파일 경로로 바뀌며, 큰 도구 결과가 처리되는 방식과 동일합니다.

782 782

868* **조건부 프로젝트 규칙**: 방금 편집한 파일에 적용되는 테스트 명령, 이 worktree에서 읽기 전용인 디렉토리868* **조건부 프로젝트 규칙**: 방금 편집한 파일에 적용되는 테스트 명령, 이 worktree에서 읽기 전용인 디렉토리

869* **외부 데이터**: 사용자에게 할당된 열린 문제, 최근 CI 결과, 내부 서비스에서 가져온 콘텐츠869* **외부 데이터**: 사용자에게 할당된 열린 문제, 최근 CI 결과, 내부 서비스에서 가져온 콘텐츠

870 870

871변경되지 않는 지침의 경우 [CLAUDE.md](/ko/memory)를 선호합니다. 스크립트를 실행하지 않고 로드되며 정적 프로젝트 규칙의 표준 위치입니다.871변경되지 않는 지침의 경우 [CLAUDE.md](/docs/ko/memory)를 선호합니다. 스크립트를 실행하지 않고 로드되며 정적 프로젝트 규칙의 표준 위치입니다.

872 872

873명령형 시스템 지침이 아닌 사실 진술로 텍스트를 작성합니다. "배포 대상은 프로덕션입니다" 또는 "이 리포지토리는 `bun test`를 사용합니다"와 같은 표현은 프로젝트 정보로 읽힙니다. 대역 외 시스템 명령으로 표현된 텍스트는 Claude의 프롬프트 주입 방어를 트리거할 수 있으며, 이로 인해 Claude가 텍스트를 컨텍스트로 취급하는 대신 사용자에게 표시합니다.873명령형 시스템 지침이 아닌 사실 진술로 텍스트를 작성합니다. "배포 대상은 프로덕션입니다" 또는 "이 리포지토리는 `bun test`를 사용합니다"와 같은 표현은 프로젝트 정보로 읽힙니다. 대역 외 시스템 명령으로 표현된 텍스트는 Claude의 프롬프트 주입 방어를 트리거할 수 있으며, 이로 인해 Claude가 텍스트를 컨텍스트로 취급하는 대신 사용자에게 표시합니다.

874 874

950 </Tab>950 </Tab>

951</Tabs>951</Tabs>

952 952

953Bash 명령 검증, 프롬프트 필터링, 자동 승인 스크립트를 포함한 확장 예제는 가이드의 [자동화할 수 있는 것](/ko/hooks-guide#what-you-can-automate)과 [Bash 명령 검증기 참조 구현](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)을 참조하세요.953Bash 명령 검증, 프롬프트 필터링, 자동 승인 스크립트를 포함한 확장 예제는 가이드의 [자동화할 수 있는 것](/docs/ko/hooks-guide#what-you-can-automate)과 [Bash 명령 검증기 참조 구현](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)을 참조하세요.

954 954

955<h2 id="hook-events">955<h2 id="hook-events">

956 Hook 이벤트956 Hook 이벤트

962 SessionStart962 SessionStart

963</h3>963</h3>

964 964

965Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 문제나 코드베이스의 최근 변경 사항과 같은 개발 컨텍스트를 로드하거나 환경 변수를 설정하는 데 유용합니다. 스크립트가 필요하지 않은 정적 컨텍스트의 경우 [CLAUDE.md](/ko/memory)를 사용하세요.965Claude Code가 새 세션을 시작하거나 기존 세션을 재개할 때 실행됩니다. 기존 문제나 코드베이스의 최근 변경 사항과 같은 개발 컨텍스트를 로드하거나 환경 변수를 설정하는 데 유용합니다. 스크립트가 필요하지 않은 정적 컨텍스트의 경우 [CLAUDE.md](/docs/ko/memory)를 사용하세요.

966 966

967SessionStart는 모든 세션에서 실행되므로 이러한 hook을 빠르게 유지하세요. `type: "command"` 및 `type: "mcp_tool"` hook만 지원됩니다.967SessionStart는 모든 세션에서 실행되므로 이러한 hook을 빠르게 유지하세요. `type: "command"` 및 `type: "mcp_tool"` hook만 지원됩니다.

968 968

1008| 필드 | 설명 |1008| 필드 | 설명 |

1009| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1009| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1010| `additionalContext` | Claude의 컨텍스트 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |1010| `additionalContext` | Claude의 컨텍스트 시작 부분에 추가되는 문자열. 첫 번째 프롬프트 전에 추가됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하여 텍스트가 전달되는 방식과 포함할 내용을 확인하세요 |

1011| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |1011| `initialUserMessage` | 세션의 첫 번째 사용자 메시지로 사용되는 문자열. [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 적용되며, 프롬프트가 제공되지 않으면 첫 번째 턴이 됩니다. 프롬프트가 제공되면 다음 턴으로 따릅니다. `additionalContext`와 달리 기존 턴에 첨부되는 이것은 턴을 생성합니다 |

1012| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"` 또는 `"resume"`일 때만 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |1012| `sessionTitle` | 세션 제목을 설정합니다. `/rename`과 동일한 효과입니다. 시작 폴더, git 분기 또는 worktree 이름에서 세션을 자동으로 이름 지정하는 데 사용합니다. `source`가 `"startup"` 또는 `"resume"`일 때만 적용됩니다; `"clear"` 및 `"compact"`에서는 무시됩니다 |

1014| `reloadSkills` | 부울. `true`일 때 Claude Code는 SessionStart hook이 완료된 후 [skill](/ko/skills) 및 명령 디렉토리를 다시 스캔하므로 hook이 설치한 skill은 첫 번째 프롬프트부터 같은 세션에서 사용 가능합니다 |1014| `reloadSkills` | 부울. `true`일 때 Claude Code는 SessionStart hook이 완료된 후 [skill](/docs/ko/skills) 및 명령 디렉토리를 다시 스캔하므로 hook이 설치한 skill은 첫 번째 프롬프트부터 같은 세션에서 사용 가능합니다 |

1015 1015

1016```json theme={null}1016```json theme={null}

1017{1017{

1085 Setup1085 Setup

1086</h3>1086</h3>

1087 1087

1088`--init-only`로 Claude Code를 시작하거나 [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.1088`--init-only`로 Claude Code를 시작하거나 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 `--init` 또는 `--maintenance`로 시작할 때만 발생합니다. 일반 시작 시에는 발생하지 않습니다. 일회성 종속성 설치 또는 CI 또는 스크립트에서 명시적으로 트리거하는 예약된 정리에 사용합니다. 일반 세션 시작과 별도입니다. 세션별 초기화의 경우 [SessionStart](#sessionstart)를 대신 사용합니다.

1089 1089

1090matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:1090matcher 값은 hook을 트리거한 CLI 플래그에 해당합니다:

1091 1091

1096 1096

1097`--init-only`는 Setup hook과 `startup` matcher가 있는 SessionStart hook을 실행한 다음 대화를 시작하지 않고 종료합니다. `--init` 및 `--maintenance`는 `-p`와 결합할 때만 Setup hook을 발생시킵니다; 대화형 세션에서 이 두 플래그는 현재 Setup hook을 발생시키지 않습니다.1097`--init-only`는 Setup hook과 `startup` matcher가 있는 SessionStart hook을 실행한 다음 대화를 시작하지 않고 종료합니다. `--init` 및 `--maintenance`는 `-p`와 결합할 때만 Setup hook을 발생시킵니다; 대화형 세션에서 이 두 플래그는 현재 Setup hook을 발생시키지 않습니다.

1098 1098

1099Setup은 모든 시작 시 발생하지 않으므로 종속성이 설치된 plugin은 Setup만으로는 의존할 수 없습니다. 실제 패턴은 첫 사용 시 종속성을 확인하고 누락되면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`를 테스트하고 없으면 `npm install`을 실행하는 hook 또는 skill입니다. 설치된 종속성을 저장할 위치는 [지속적 데이터 디렉토리](/ko/plugins-reference#persistent-data-directory)를 참조하세요.1099Setup은 모든 시작 시 발생하지 않으므로 종속성이 설치된 plugin은 Setup만으로는 의존할 수 없습니다. 실제 패턴은 첫 사용 시 종속성을 확인하고 누락되면 설치하는 것입니다. 예를 들어 `${CLAUDE_PLUGIN_DATA}/node_modules`를 테스트하고 없으면 `npm install`을 실행하는 hook 또는 skill입니다. 설치된 종속성을 저장할 위치는 [지속적 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory)를 참조하세요.

1100 1100

1101<h4 id="setup-input">1101<h4 id="setup-input">

1102 Setup 입력1102 Setup 입력

1118 Setup 결정 제어1118 Setup 결정 제어

1119</h4>1119</h4>

1120 1120

1121Setup hook은 차단할 수 없습니다. 0이 아닌 종료 코드 (2 포함)는 stderr을 사용자에게 `<hook name> hook error` 알림으로 표시하고 실행이 계속됩니다. [비대화형 모드](/ko/headless)에서 hook 출력은 `--verbose`로 시작할 때만 나타납니다.1121Setup hook은 차단할 수 없습니다. 0이 아닌 종료 코드 (2 포함)는 stderr을 사용자에게 `<hook name> hook error` 알림으로 표시하고 실행이 계속됩니다. [비대화형 모드](/docs/ko/headless)에서 hook 출력은 `--verbose`로 시작할 때만 나타납니다.

1122 1122

1123Claude의 컨텍스트에 정보를 전달하려면 JSON 출력에서 `additionalContext`를 반환합니다; 일반 stdout은 디버그 로그에만 작성됩니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:1123Claude의 컨텍스트에 정보를 전달하려면 JSON 출력에서 `additionalContext`를 반환합니다; 일반 stdout은 디버그 로그에만 작성됩니다. 모든 hook에 사용 가능한 [JSON 출력 필드](#json-output) 외에도 이러한 이벤트 특정 필드를 반환할 수 있습니다:

1124 1124

1188 1188

1189시간 초과에 도달한 `UserPromptSubmit` hook은 취소되고 `additionalContext`를 포함한 출력이 삭제됩니다. 프롬프트는 여전히 해당 컨텍스트 없이 Claude에 도달합니다. v2.1.196부터 트랜스크립트는 hook의 이름, 발생한 시간 초과, 출력이 삭제되었음을 나타내는 알림을 표시합니다. 이전 버전은 알림 없이 hook을 취소합니다.1189시간 초과에 도달한 `UserPromptSubmit` hook은 취소되고 `additionalContext`를 포함한 출력이 삭제됩니다. 프롬프트는 여전히 해당 컨텍스트 없이 Claude에 도달합니다. v2.1.196부터 트랜스크립트는 hook의 이름, 발생한 시간 초과, 출력이 삭제되었음을 나타내는 알림을 표시합니다. 이전 버전은 알림 없이 hook을 취소합니다.

1190 1190

1191[Agent SDK callback hook](/ko/agent-sdk/hooks)이 `UserPromptSubmit`에서 시간 초과에 도달하면 hook의 이름과 시간 초과를 나타내는 메시지로 프롬프트를 차단합니다. 왜냐하면 callback은 실패하지 않아야 하는 정책 게이트로 작동할 수 있기 때문입니다. 세션이 계속됩니다. v2.1.208 이전에는 callback 시간 초과가 실행 오류로 턴을 종료했습니다.1191[Agent SDK callback hook](/docs/ko/agent-sdk/hooks)이 `UserPromptSubmit`에서 시간 초과에 도달하면 hook의 이름과 시간 초과를 나타내는 메시지로 프롬프트를 차단합니다. 왜냐하면 callback은 실패하지 않아야 하는 정책 게이트로 작동할 수 있기 때문입니다. 세션이 계속됩니다. v2.1.208 이전에는 callback 시간 초과가 실행 오류로 턴을 종료했습니다.

1192 1192

1193<h4 id="userpromptsubmit-input">1193<h4 id="userpromptsubmit-input">

1194 UserPromptSubmit 입력1194 UserPromptSubmit 입력

1443Claude가 도구 매개변수를 생성한 후 도구 호출을 처리하기 전에 실행됩니다. 도구 이름에서 일치합니다: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, 모든 [MCP 도구 이름](#match-mcp-tools).1443Claude가 도구 매개변수를 생성한 후 도구 호출을 처리하기 전에 실행됩니다. 도구 이름에서 일치합니다: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, 모든 [MCP 도구 이름](#match-mcp-tools).

1444 1444

1445<Warning>1445<Warning>

1446 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조하는](/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다: Claude Code는 프롬프트를 구축하는 동안 해당 내용을 삽입하므로 `Read`와 일치하는 hook을 포함하여 PreToolUse hook이 발생하지 않습니다. 특정 경로를 `@` 참조에서 차단하려면 [`Read` 거부 규칙](/ko/permissions#read-and-edit)을 대신 사용하세요.1446 PreToolUse는 Claude가 도구를 호출할 때만 실행됩니다. [프롬프트에서 `@`로 참조하는](/docs/ko/common-workflows#reference-files-and-directories) 파일은 도구 호출 없이 추가됩니다: Claude Code는 프롬프트를 구축하는 동안 해당 내용을 삽입하므로 `Read`와 일치하는 hook을 포함하여 PreToolUse hook이 발생하지 않습니다. 특정 경로를 `@` 참조에서 차단하려면 [`Read` 거부 규칙](/docs/ko/permissions#read-and-edit)을 대신 사용하세요.

1447</Warning>1447</Warning>

1448 1448

1449[PreToolUse 결정 제어](#pretooluse-decision-control)를 사용하여 도구 사용을 허용, 거부, 요청 또는 연기합니다.1449[PreToolUse 결정 제어](#pretooluse-decision-control)를 사용하여 도구 사용을 허용, 거부, 요청 또는 연기합니다.

1464| :------------------ | :-- | :----------------- | :--------------------------------------------------------------------------------------- |1464| :------------------ | :-- | :----------------- | :--------------------------------------------------------------------------------------- |

1467| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초). [최대](/ko/tools-reference#bash-tool-behavior) 이상의 값은 거부되지 않고 최대값으로 감소됩니다 |1467| `timeout` | 숫자 | `120000` | 선택적 시간 초과 (밀리초). [최대](/docs/ko/tools-reference#bash-tool-behavior) 이상의 값은 거부되지 않고 최대값으로 감소됩니다 |

1469 1469

1470<h5 id="write">1470<h5 id="write">

1556 Agent1556 Agent

1557</h5>1557</h5>

1558 1558

1559[subagent](/ko/sub-agents)를 생성합니다.1559[subagent](/docs/ko/sub-agents)를 생성합니다.

1560 1560

1561| 필드 | 유형 | 예제 | 설명 |1561| 필드 | 유형 | 예제 | 설명 |

1562| :-------------- | :-- | :------------------------- | :------------------ |1562| :-------------- | :-- | :------------------------- | :------------------ |

1599 ExitPlanMode1599 ExitPlanMode

1600</h5>1600</h5>

1601 1601

1602Claude가 [plan 모드](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.1602Claude가 [plan 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 떠나기 전에 계획을 제시하고 사용자에게 승인을 요청합니다. Claude는 도구를 호출하기 전에 계획을 파일에 디스크에 작성하므로 모델의 리터럴 `tool_input`은 일반적으로 비어 있습니다. Claude Code는 hook에 전달하기 전에 계획 내용과 파일 경로를 주입합니다.

1603 1603

1604| 필드 | 유형 | 예제 | 설명 |1604| 필드 | 유형 | 예제 | 설명 |

1605| :--------------- | :-- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |1605| :--------------- | :-- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |

1617 1617

1618| 필드 | 설명 |1618| 필드 | 설명 |

1619| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1619| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1620| `permissionDecision` | `"allow"`는 권한 시스템을 우회합니다. `"deny"`는 도구 호출을 방지합니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 재개하도록 연기합니다. [권한 거부 및 요청 규칙](/ko/permissions#manage-permissions)은 hook이 반환하는 것과 관계없이 여전히 평가됩니다 |1620| `permissionDecision` | `"allow"`는 권한 시스템을 우회합니다. `"deny"`는 도구 호출을 방지합니다. `"ask"`는 사용자에게 확인을 요청합니다. `"defer"`는 나중에 재개하도록 연기합니다. [권한 거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 hook이 반환하는 것과 관계없이 여전히 평가됩니다 |

1621| `permissionDecisionReason` | `"allow"` 및 `"ask"`의 경우 사용자에게 표시되지만 Claude에는 표시되지 않습니다. `"deny"`의 경우 Claude에 표시됩니다. `"defer"`의 경우 무시됩니다 |1621| `permissionDecisionReason` | `"allow"` 및 `"ask"`의 경우 사용자에게 표시되지만 Claude에는 표시되지 않습니다. `"deny"`의 경우 Claude에 표시됩니다. `"defer"`의 경우 무시됩니다 |

1622| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. `"allow"`와 결합하여 자동 승인하거나 `"ask"`와 결합하여 수정된 입력을 사용자에게 표시합니다. `"defer"`의 경우 무시됩니다 |1622| `updatedInput` | 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. `"allow"`와 결합하여 자동 승인하거나 `"ask"`와 결합하여 수정된 입력을 사용자에게 표시합니다. `"defer"`의 경우 무시됩니다 |

1623| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. `"defer"`의 경우 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |1623| `additionalContext` | 도구 결과와 함께 Claude의 컨텍스트에 추가되는 문자열. `"defer"`의 경우 무시됩니다. [Claude를 위한 컨텍스트 추가](#add-context-for-claude)를 참조하세요 |

1640}1640}

1641```1641```

1642 1642

1643`AskUserQuestion` 및 `ExitPlanMode`는 사용자 상호 작용이 필요하며 일반적으로 [비대화형 모드](/ko/headless)에서 `-p` 플래그로 차단합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 해당 요구 사항을 충족합니다: hook은 stdin에서 도구의 입력을 읽고 자신의 UI를 통해 답변을 수집하고 `updatedInput`에서 반환하여 도구가 프롬프트 없이 실행되도록 합니다. `"allow"`만 반환하는 것은 이러한 도구에 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 에코백하고 각 질문의 텍스트를 선택한 답변으로 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.1643`AskUserQuestion` 및 `ExitPlanMode`는 사용자 상호 작용이 필요하며 일반적으로 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그로 차단합니다. `permissionDecision: "allow"`를 `updatedInput`과 함께 반환하면 해당 요구 사항을 충족합니다: hook은 stdin에서 도구의 입력을 읽고 자신의 UI를 통해 답변을 수집하고 `updatedInput`에서 반환하여 도구가 프롬프트 없이 실행되도록 합니다. `"allow"`만 반환하는 것은 이러한 도구에 충분하지 않습니다. `AskUserQuestion`의 경우 원본 `questions` 배열을 에코백하고 각 질문의 텍스트를 선택한 답변으로 매핑하는 [`answers`](#askuserquestion) 객체를 추가합니다.

1644 1644

1645Connector 도구 ([조직이 `ask`로 설정](/ko/mcp#organization-controls-on-connector-tools))는 hook이 `"allow"`를 반환하더라도 프롬프트합니다.1645Connector 도구 ([조직이 `ask`로 설정](/docs/ko/mcp#organization-controls-on-connector-tools))는 hook이 `"allow"`를 반환하더라도 프롬프트합니다.

1646 1646

1647v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 더 엄격합니다: hook은 `updatedInput`이 있거나 없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code는 hook이 도구가 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.1647v2.1.199부터 [`_meta["anthropic/requiresUserInteraction"]`](/docs/ko/mcp#require-approval-for-a-specific-tool)로 표시된 MCP 도구는 더 엄격합니다: hook은 `updatedInput`이 있거나 없이 `"allow"`로 승인 프롬프트를 건너뛸 수 없습니다. Claude Code는 hook이 도구가 필요한 상호 작용을 수집했는지 확인할 수 없기 때문입니다.

1648 1648

1649<Note>1649<Note>

1650 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만 이 이벤트에는 더 이상 사용되지 않습니다. 대신 `hookSpecificOutput.permissionDecision` 및 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. 더 이상 사용되지 않는 값 `"approve"` 및 `"block"`은 각각 `"allow"` 및 `"deny"`로 매핑됩니다. PostToolUse 및 Stop과 같은 다른 이벤트는 계속 최상위 `decision` 및 `reason`을 현재 형식으로 사용합니다.1650 PreToolUse는 이전에 최상위 `decision` 및 `reason` 필드를 사용했지만 이 이벤트에는 더 이상 사용되지 않습니다. 대신 `hookSpecificOutput.permissionDecision` 및 `hookSpecificOutput.permissionDecisionReason`을 사용합니다. 더 이상 사용되지 않는 값 `"approve"` 및 `"block"`은 각각 `"allow"` 및 `"deny"`로 매핑됩니다. PostToolUse 및 Stop과 같은 다른 이벤트는 계속 최상위 `decision` 및 `reason`을 현재 형식으로 사용합니다.

1654 도구 호출을 나중에 재개하도록 연기1654 도구 호출을 나중에 재개하도록 연기

1655</h4>1655</h4>

1656 1656

1657`"defer"`는 Claude Code를 subprocess로 실행하고 JSON 출력을 읽는 Agent SDK 앱 또는 Claude Code 위에 구축된 사용자 정의 UI와 같은 통합을 위한 것입니다. 이를 통해 호출 프로세스가 Claude를 도구 호출에서 일시 중지하고 자신의 인터페이스를 통해 입력을 수집하고 중단된 위치에서 재개할 수 있습니다. Claude Code는 [비대화형 모드](/ko/headless)에서 `-p` 플래그를 사용할 때만 이 값을 준수합니다. 대화형 세션에서는 경고를 기록하고 hook 결과를 무시합니다.1657`"defer"`는 Claude Code를 subprocess로 실행하고 JSON 출력을 읽는 Agent SDK 앱 또는 Claude Code 위에 구축된 사용자 정의 UI와 같은 통합을 위한 것입니다. 이를 통해 호출 프로세스가 Claude를 도구 호출에서 일시 중지하고 자신의 인터페이스를 통해 입력을 수집하고 중단된 위치에서 재개할 수 있습니다. Claude Code는 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그를 사용할 때만 이 값을 준수합니다. 대화형 세션에서는 경고를 기록하고 hook 결과를 무시합니다.

1658 1658

1659일반적인 경우는 `AskUserQuestion` 도구입니다: Claude가 사용자에게 뭔가를 묻고 싶지만 답변할 터미널이 없습니다. 왕복은 다음과 같이 작동합니다:1659일반적인 경우는 `AskUserQuestion` 도구입니다: Claude가 사용자에게 뭔가를 묻고 싶지만 답변할 터미널이 없습니다. 왕복은 다음과 같이 작동합니다:

1660 1660

1736 1736

1737| 필드 | 설명 |1737| 필드 | 설명 |

1738| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |1738| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |

1739| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [권한 거부 및 요청 규칙](/ko/permissions#manage-permissions)은 여전히 평가되므로 hook이 `"allow"`를 반환해도 일치하는 거부 규칙을 재정의하지 않습니다 |1739| `behavior` | `"allow"`는 권한을 부여하고, `"deny"`는 거부합니다. [권한 거부 및 요청 규칙](/docs/ko/permissions#manage-permissions)은 여전히 평가되므로 hook이 `"allow"`를 반환해도 일치하는 거부 규칙을 재정의하지 않습니다 |

1740| `updatedInput` | `"allow"`만 해당: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. 수정된 입력은 거부 및 요청 규칙에 대해 다시 평가됩니다 |1740| `updatedInput` | `"allow"`만 해당: 실행 전에 도구의 입력 매개변수를 수정합니다. 전체 입력 객체를 바꾸므로 변경되지 않은 필드를 수정된 필드와 함께 포함합니다. 수정된 입력은 거부 및 요청 규칙에 대해 다시 평가됩니다 |

1773 1773

1774<Note>1774<Note>

1775 `setMode`와 `bypassPermissions`는 세션이 이미 bypass 모드를 사용 가능하게 시작된 경우에만 적용됩니다: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, 또는 설정의 `permissions.defaultMode: "bypassPermissions"`, 그리고 모드가 [`permissions.disableBypassPermissionsMode`](/ko/permissions#managed-settings)에 의해 비활성화되지 않은 경우입니다. 그렇지 않으면 업데이트는 작동하지 않습니다. `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 절대 유지되지 않습니다.1775 `setMode`와 `bypassPermissions`는 세션이 이미 bypass 모드를 사용 가능하게 시작된 경우에만 적용됩니다: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, 또는 설정의 `permissions.defaultMode: "bypassPermissions"`, 그리고 모드가 [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)에 의해 비활성화되지 않은 경우입니다. 그렇지 않으면 업데이트는 작동하지 않습니다. `bypassPermissions`는 `destination`과 관계없이 `defaultMode`로 절대 유지되지 않습니다.

1776</Note>1776</Note>

1777 1777

1778모든 항목의 `destination` 필드는 변경이 메모리에만 유지되는지 또는 설정 파일에 유지되는지를 결정합니다.1778모든 항목의 `destination` 필드는 변경이 메모리에만 유지되는지 또는 설정 파일에 유지되는지를 결정합니다.

1991 PermissionDenied1991 PermissionDenied

1992</h3>1992</h3>

1993 1993

1994[자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 도구 호출을 거부할 때 실행됩니다. 이 hook은 자동 모드에서만 발생합니다: 권한 대화 상자를 수동으로 거부할 때, `PreToolUse` hook이 호출을 차단할 때, 또는 `deny` 규칙이 일치할 때 실행되지 않습니다. 이를 사용하여 분류기 거부를 기록하고, 구성을 조정하거나, 모델이 도구 호출을 재시도할 수 있음을 알립니다.1994[자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 도구 호출을 거부할 때 실행됩니다. 이 hook은 자동 모드에서만 발생합니다: 권한 대화 상자를 수동으로 거부할 때, `PreToolUse` hook이 호출을 차단할 때, 또는 `deny` 규칙이 일치할 때 실행되지 않습니다. 이를 사용하여 분류기 거부를 기록하고, 구성을 조정하거나, 모델이 도구 호출을 재시도할 수 있음을 알립니다.

1995 1995

1996도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.1996도구 이름에서 일치합니다. PreToolUse와 동일한 값입니다.

1997 1997

2058 2058

2059`agent_needs_input` 및 `agent_completed` 유형은 Claude Code v2.1.198 이상이 필요합니다.2059`agent_needs_input` 및 `agent_completed` 유형은 Claude Code v2.1.198 이상이 필요합니다.

2060 2060

2111 SubagentStart2111 SubagentStart

2112</h3>2112</h3>

2113 2113

2114Agent 도구를 통해 Claude Code subagent가 생성될 때 실행됩니다. 에이전트 유형 이름으로 필터링할 matcher를 지원합니다. 기본 제공 에이전트의 경우 이는 `general-purpose`, `Explore`, `Plan`과 같은 에이전트 이름입니다. [사용자 정의 subagent](/ko/sub-agents)의 경우 이는 파일명이 아닌 에이전트의 frontmatter의 `name` 필드입니다.2114Agent 도구를 통해 Claude Code subagent가 생성될 때 실행됩니다. 에이전트 유형 이름으로 필터링할 matcher를 지원합니다. 기본 제공 에이전트의 경우 이는 `general-purpose`, `Explore`, `Plan`과 같은 에이전트 이름입니다. [사용자 정의 subagent](/docs/ko/sub-agents)의 경우 이는 파일명이 아닌 에이전트의 frontmatter의 `name` 필드입니다.

2115 2115

2116[plugin](/ko/plugins)에서 제공하는 subagent의 경우 에이전트 유형은 `my-plugin:reviewer`와 같은 plugin 범위 식별자이며, 파일명이 아닙니다. 콜론은 plugin 범위 이름을 정규식 경로에 배치하므로 정확한 일치를 위해 matcher를 `^` 및 `$`로 고정합니다: `^my-plugin:reviewer$`.2116[plugin](/docs/ko/plugins)에서 제공하는 subagent의 경우 에이전트 유형은 `my-plugin:reviewer`와 같은 plugin 범위 식별자이며, 파일명이 아닙니다. 콜론은 plugin 범위 이름을 정규식 경로에 배치하므로 정확한 일치를 위해 matcher를 `^` 및 `$`로 고정합니다: `^my-plugin:reviewer$`.

2117 2117

2118<h4 id="subagentstart-input">2118<h4 id="subagentstart-input">

2119 SubagentStart 입력2119 SubagentStart 입력

2245 TaskCompleted2245 TaskCompleted

2246</h3>2246</h3>

2247 2247

2248작업이 완료로 표시될 때 실행됩니다. 이는 두 가지 상황에서 발생합니다: 모든 에이전트가 TaskUpdate 도구를 통해 명시적으로 작업을 완료로 표시할 때 또는 [에이전트 팀](/ko/agent-teams) 팀원이 진행 중인 작업으로 자신의 턴을 마칠 때입니다. 이를 사용하여 테스트 통과 또는 lint 검사와 같은 완료 기준을 적용하기 전에 작업을 닫을 수 있습니다.2248작업이 완료로 표시될 때 실행됩니다. 이는 두 가지 상황에서 발생합니다: 모든 에이전트가 TaskUpdate 도구를 통해 명시적으로 작업을 완료로 표시할 때 또는 [에이전트 팀](/docs/ko/agent-teams) 팀원이 진행 중인 작업으로 자신의 턴을 마칠 때입니다. 이를 사용하여 테스트 통과 또는 lint 검사와 같은 완료 기준을 적용하기 전에 작업을 닫을 수 있습니다.

2249 2249

2250`TaskCompleted` hook이 코드 2로 종료되면 작업이 완료로 표시되지 않고 stderr 메시지가 모델에 피드백으로 피드백됩니다. 팀원을 다시 실행하는 대신 완전히 중지하려면 `{"continue": false, "stopReason": "..."}`이 있는 JSON을 반환합니다. TaskCompleted hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.2250`TaskCompleted` hook이 코드 2로 종료되면 작업이 완료로 표시되지 않고 stderr 메시지가 모델에 피드백으로 피드백됩니다. 팀원을 다시 실행하는 대신 완전히 중지하려면 `{"continue": false, "stopReason": "..."}`이 있는 JSON을 반환합니다. TaskCompleted hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.

2251 2251

2310메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 중지가 사용자 중단으로 인해 발생한 경우 실행되지 않습니다. API 오류는 [StopFailure](#stopfailure) 대신 발생합니다.2310메인 Claude Code 에이전트가 응답을 마쳤을 때 실행됩니다. 중지가 사용자 중단으로 인해 발생한 경우 실행되지 않습니다. API 오류는 [StopFailure](#stopfailure) 대신 발생합니다.

2311 2311

2312<Tip>2312<Tip>

2313 [`/goal`](/ko/goal) 명령은 세션 범위 prompt 기반 Stop hook의 기본 제공 바로 가기입니다. 조건이 유지될 때까지 Claude가 계속 작동하도록 하되 hook 구성을 작성하지 않으려는 경우 사용합니다.2313 [`/goal`](/docs/ko/goal) 명령은 세션 범위 prompt 기반 Stop hook의 기본 제공 바로 가기입니다. 조건이 유지될 때까지 Claude가 계속 작동하도록 하되 hook 구성을 작성하지 않으려는 경우 사용합니다.

2314</Tip>2314</Tip>

2315 2315

2316<h4 id="stop-input">2316<h4 id="stop-input">

2443 TeammateIdle2443 TeammateIdle

2444</h3>2444</h3>

2445 2445

2446[에이전트 팀](/ko/agent-teams) 팀원이 자신의 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 이를 사용하여 lint 검사 통과 또는 출력 파일 존재 확인과 같은 팀원이 작업을 중지하기 전에 품질 게이트를 적용합니다.2446[에이전트 팀](/docs/ko/agent-teams) 팀원이 자신의 턴을 마친 후 유휴 상태가 되려고 할 때 실행됩니다. 이를 사용하여 lint 검사 통과 또는 출력 파일 존재 확인과 같은 팀원이 작업을 중지하기 전에 품질 게이트를 적용합니다.

2447 2447

2448`TeammateIdle` hook이 코드 2로 종료되면 팀원은 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다. 팀원을 다시 실행하는 대신 완전히 중지하려면 `{"continue": false, "stopReason": "..."}`이 있는 JSON을 반환합니다. TeammateIdle hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.2448`TeammateIdle` hook이 코드 2로 종료되면 팀원은 stderr 메시지를 피드백으로 받고 유휴 상태가 되는 대신 계속 작업합니다. 팀원을 다시 실행하는 대신 완전히 중지하려면 `{"continue": false, "stopReason": "..."}`이 있는 JSON을 반환합니다. TeammateIdle hook은 matcher를 지원하지 않으며 모든 발생에서 발생합니다.

2449 2449

2657 WorktreeCreate2657 WorktreeCreate

2658</h3>2658</h3>

2659 2659

2660`claude --worktree`를 실행하거나 [subagent가 `isolation: "worktree"`를 사용](/ko/sub-agents#choose-the-subagent-scope)할 때 Claude Code는 `git worktree`를 사용하여 격리된 작업 복사본을 생성합니다. WorktreeCreate hook을 구성하면 기본 git 동작을 대체하여 SVN, Perforce 또는 Mercurial과 같은 다른 버전 제어 시스템을 사용할 수 있습니다.2660`claude --worktree`를 실행하거나 [subagent가 `isolation: "worktree"`를 사용](/docs/ko/sub-agents#choose-the-subagent-scope)할 때 Claude Code는 `git worktree`를 사용하여 격리된 작업 복사본을 생성합니다. WorktreeCreate hook을 구성하면 기본 git 동작을 대체하여 SVN, Perforce 또는 Mercurial과 같은 다른 버전 제어 시스템을 사용할 수 있습니다.

2661 2661

2662hook은 생성된 worktree 디렉토리의 절대 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉토리로 사용합니다. 명령 hook은 stdout에 경로를 인쇄합니다; HTTP hook은 `hookSpecificOutput.worktreePath`를 반환합니다.2662hook은 생성된 worktree 디렉토리의 절대 경로를 반환해야 합니다. Claude Code는 이 경로를 격리된 세션의 작업 디렉토리로 사용합니다. 명령 hook은 stdout에 경로를 인쇄합니다; HTTP hook은 `hookSpecificOutput.worktreePath`를 반환합니다.

2663 2663

3108 중지하기 전에 여러 조건 확인3108 중지하기 전에 여러 조건 확인

3109</h3>3109</h3>

3110 3110

3111이 `Stop` hook은 Claude가 중지하기 전에 세 가지 조건을 확인하는 자세한 프롬프트를 사용합니다. `SubagentStop` hook은 [subagent](/ko/sub-agents)가 중지해야 하는지 평가하는 동일한 형식을 사용합니다. `"ok"`가 `false`이면 Claude는 제공된 이유를 다음 명령으로 받으며 계속 작업합니다:3111이 `Stop` hook은 Claude가 중지하기 전에 세 가지 조건을 확인하는 자세한 프롬프트를 사용합니다. `SubagentStop` hook은 [subagent](/docs/ko/sub-agents)가 중지해야 하는지 평가하는 동일한 형식을 사용합니다. `"ok"`가 `false`이면 Claude는 제공된 이유를 다음 명령으로 받으며 계속 작업합니다:

3112 3112

3113```json theme={null}3113```json theme={null}

3114{3114{

3381 3381

3382더 세밀한 hook 일치 세부 정보를 보려면 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose`를 설정하여 hook matcher 수 및 쿼리 일치와 같은 추가 로그 줄을 확인합니다.3382더 세밀한 hook 일치 세부 정보를 보려면 `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose`를 설정하여 hook matcher 수 및 쿼리 일치와 같은 추가 로그 줄을 확인합니다.

3383 3383

3384hook이 발생하지 않음, 무한 Stop hook 루프 또는 구성 오류와 같은 일반적인 문제 해결은 가이드의 [제한 사항 및 문제 해결](/ko/hooks-guide#limitations-and-troubleshooting)을 참조하세요. 더 광범위한 진단 안내는 `/context`, `/doctor` 및 설정 우선순위를 다루는 [구성 디버그](/ko/debug-your-config)를 참조하세요.3384hook이 발생하지 않음, 무한 Stop hook 루프 또는 구성 오류와 같은 일반적인 문제 해결은 가이드의 [제한 사항 및 문제 해결](/docs/ko/hooks-guide#limitations-and-troubleshooting)을 참조하세요. 더 광범위한 진단 안내는 `/context`, `/doctor` 및 설정 우선순위를 다루는 [구성 디버그](/docs/ko/debug-your-config)를 참조하세요.

hooks-guide.md +50 −50

Details

10 10

11판단이 필요한 결정의 경우 결정론적 규칙이 아닌 경우, [프롬프트 기반 hooks](#prompt-based-hooks) 또는 [에이전트 기반 hooks](#agent-based-hooks)를 사용할 수도 있습니다. 이들은 Claude 모델을 사용하여 조건을 평가합니다.11판단이 필요한 결정의 경우 결정론적 규칙이 아닌 경우, [프롬프트 기반 hooks](#prompt-based-hooks) 또는 [에이전트 기반 hooks](#agent-based-hooks)를 사용할 수도 있습니다. 이들은 Claude 모델을 사용하여 조건을 평가합니다.

12 12

13Claude Code를 확장하는 다른 방법은 [skills](/ko/skills)를 참조하여 Claude에 추가 지침과 실행 가능한 명령을 제공하고, [subagents](/ko/sub-agents)를 사용하여 격리된 컨텍스트에서 작업을 실행하며, [plugins](/ko/plugins)를 사용하여 프로젝트 전체에서 공유할 확장을 패키징합니다.13Claude Code를 확장하는 다른 방법은 [skills](/docs/ko/skills)를 참조하여 Claude에 추가 지침과 실행 가능한 명령을 제공하고, [subagents](/docs/ko/sub-agents)를 사용하여 격리된 컨텍스트에서 작업을 실행하며, [plugins](/docs/ko/plugins)를 사용하여 프로젝트 전체에서 공유할 확장을 패키징합니다.

14 14

15<Tip>15<Tip>

16 이 가이드는 일반적인 사용 사례와 시작 방법을 다룹니다. 전체 이벤트 스키마, JSON 입출력 형식 및 비동기 hooks 및 MCP 도구 hooks와 같은 고급 기능은 [Hooks 참조](/ko/hooks)를 참조하세요.16 이 가이드는 일반적인 사용 사례와 시작 방법을 다룹니다. 전체 이벤트 스키마, JSON 입출력 형식 및 비동기 hooks 및 MCP 도구 hooks와 같은 고급 기능은 [Hooks 참조](/docs/ko/hooks)를 참조하세요.

17</Tip>17</Tip>

18 18

19<h2 id="set-up-your-first-hook">19<h2 id="set-up-your-first-hook">

85 자동화할 수 있는 것85 자동화할 수 있는 것

86</h2>86</h2>

87 87

88Hooks를 사용하면 Claude Code의 라이프사이클의 주요 지점에서 코드를 실행할 수 있습니다: 편집 후 파일 형식 지정, 실행 전 명령 차단, Claude가 입력이 필요할 때 알림 전송, 세션 시작 시 컨텍스트 주입 등. 전체 hook 이벤트 목록은 [Hooks 참조](/ko/hooks#hook-lifecycle)를 참조하세요.88Hooks를 사용하면 Claude Code의 라이프사이클의 주요 지점에서 코드를 실행할 수 있습니다: 편집 후 파일 형식 지정, 실행 전 명령 차단, Claude가 입력이 필요할 때 알림 전송, 세션 시작 시 컨텍스트 주입 등. 전체 hook 이벤트 목록은 [Hooks 참조](/docs/ko/hooks#hook-lifecycle)를 참조하세요.

89 89

90각 예제에는 [설정 파일](#configure-hook-location)에 추가하는 즉시 사용 가능한 구성 블록이 포함되어 있습니다.90각 예제에는 [설정 파일](#configure-hook-location)에 추가하는 즉시 사용 가능한 구성 블록이 포함되어 있습니다.

91 91

92별도의 모델 검토를 실행하고 결과를 세션에 다시 피드백하는 hooks의 프로덕션 예제는 [`security-guidance` 플러그인이 Claude Code와 통합되는 방식](/ko/security-guidance#how-the-plugin-integrates-with-claude-code)을 참조하세요.92별도의 모델 검토를 실행하고 결과를 세션에 다시 피드백하는 hooks의 프로덕션 예제는 [`security-guidance` 플러그인이 Claude Code와 통합되는 방식](/docs/ko/security-guidance#how-the-plugin-integrates-with-claude-code)을 참조하세요.

93 93

94<h3 id="get-notified-when-claude-needs-input">94<h3 id="get-notified-when-claude-needs-input">

95 Claude가 입력이 필요할 때 알림 받기95 Claude가 입력이 필요할 때 알림 받기

186 186

187`agent_needs_input` 및 `agent_completed` matcher는 Claude Code v2.1.198 이상이 필요합니다.187`agent_needs_input` 및 `agent_completed` matcher는 Claude Code v2.1.198 이상이 필요합니다.

188 188

189`/hooks`를 입력하고 `Notification`을 선택하여 hook이 등록되었는지 확인합니다. 전체 이벤트 스키마는 [Notification 참조](/ko/hooks#notification)를 참조하세요.189`/hooks`를 입력하고 `Notification`을 선택하여 hook이 등록되었는지 확인합니다. 전체 이벤트 스키마는 [Notification 참조](/docs/ko/hooks#notification)를 참조하세요.

190 190

191<h3 id="auto-format-code-after-edits">191<h3 id="auto-format-code-after-edits">

192 편집 후 코드 자동 형식 지정192 편집 후 코드 자동 형식 지정

309}309}

310```310```

311 311

312`echo`를 `git log --oneline -5`와 같이 동적 출력을 생성하는 모든 명령으로 바꿀 수 있습니다. 모든 세션 시작 시 컨텍스트를 주입하려면 [CLAUDE.md](/ko/memory) 사용을 고려하세요. 환경 변수는 [`CLAUDE_ENV_FILE`](/ko/hooks#persist-environment-variables)을 참조하세요.312`echo`를 `git log --oneline -5`와 같이 동적 출력을 생성하는 모든 명령으로 바꿀 수 있습니다. 모든 세션 시작 시 컨텍스트를 주입하려면 [CLAUDE.md](/docs/ko/memory) 사용을 고려하세요. 환경 변수는 [`CLAUDE_ENV_FILE`](/docs/ko/hooks#persist-environment-variables)을 참조하세요.

313 313

314<h3 id="audit-configuration-changes">314<h3 id="audit-configuration-changes">

315 구성 변경 감사315 구성 변경 감사

337}337}

338```338```

339 339

340Matcher는 구성 유형으로 필터링합니다: `user_settings`, `project_settings`, `local_settings`, `policy_settings` 또는 `skills`. 변경이 적용되지 않도록 차단하려면 종료 코드 2로 종료하거나 `{"decision": "block"}`을 반환합니다. 전체 입력 스키마는 [ConfigChange 참조](/ko/hooks#configchange)를 참조하세요.340Matcher는 구성 유형으로 필터링합니다: `user_settings`, `project_settings`, `local_settings`, `policy_settings` 또는 `skills`. 변경이 적용되지 않도록 차단하려면 종료 코드 2로 종료하거나 `{"decision": "block"}`을 반환합니다. 전체 입력 스키마는 [ConfigChange 참조](/docs/ko/hooks#configchange)를 참조하세요.

341 341

342<h3 id="reload-environment-when-directory-or-files-change">342<h3 id="reload-environment-when-directory-or-files-change">

343 디렉토리 또는 파일이 변경될 때 환경 다시 로드343 디렉토리 또는 파일이 변경될 때 환경 다시 로드

376 376

377`direnv allow`를 `.envrc`가 있는 각 디렉토리에서 한 번 실행하여 direnv가 이를 로드할 수 있도록 허용합니다. direnv 대신 devbox 또는 nix를 사용하는 경우 `direnv export bash` 대신 `devbox shellenv` 또는 `devbox global shellenv`를 사용하면 동일한 패턴이 작동합니다.377`direnv allow`를 `.envrc`가 있는 각 디렉토리에서 한 번 실행하여 direnv가 이를 로드할 수 있도록 허용합니다. direnv 대신 devbox 또는 nix를 사용하는 경우 `direnv export bash` 대신 `devbox shellenv` 또는 `devbox global shellenv`를 사용하면 동일한 패턴이 작동합니다.

378 378

379모든 디렉토리 변경이 아닌 특정 파일에 반응하려면 `FileChanged`를 `matcher`와 함께 사용하여 감시할 파일 이름을 나열합니다 (파이프로 구분). 감시 목록을 구성하기 위해 이 값은 정규식으로 평가되지 않고 리터럴 파일 이름으로 분할됩니다. [FileChanged](/ko/hooks#filechanged)를 참조하여 파일이 변경될 때 어떤 hook 그룹이 실행되는지 필터링하는 방법도 확인하세요. 이 예제는 작업 디렉토리에서 `.envrc` 및 `.env`를 감시합니다:379모든 디렉토리 변경이 아닌 특정 파일에 반응하려면 `FileChanged`를 `matcher`와 함께 사용하여 감시할 파일 이름을 나열합니다 (파이프로 구분). 감시 목록을 구성하기 위해 이 값은 정규식으로 평가되지 않고 리터럴 파일 이름으로 분할됩니다. [FileChanged](/docs/ko/hooks#filechanged)를 참조하여 파일이 변경될 때 어떤 hook 그룹이 실행되는지 필터링하는 방법도 확인하세요. 이 예제는 작업 디렉토리에서 `.envrc` 및 `.env`를 감시합니다:

380 380

381```json theme={null}381```json theme={null}

382{382{

396}396}

397```397```

398 398

399입력 스키마, `watchPaths` 출력 및 `CLAUDE_ENV_FILE` 세부 정보는 [CwdChanged](/ko/hooks#cwdchanged) 및 [FileChanged](/ko/hooks#filechanged) 참조 항목을 참조하세요.399입력 스키마, `watchPaths` 출력 및 `CLAUDE_ENV_FILE` 세부 정보는 [CwdChanged](/docs/ko/hooks#cwdchanged) 및 [FileChanged](/docs/ko/hooks#filechanged) 참조 항목을 참조하세요.

400 400

401<h3 id="auto-approve-specific-permission-prompts">401<h3 id="auto-approve-specific-permission-prompts">

402 특정 권한 프롬프트 자동 승인402 특정 권한 프롬프트 자동 승인

431대신 특정 권한 모드를 설정하려면 hook의 출력에 `setMode` 항목이 있는 `updatedPermissions` 배열이 포함될 수 있습니다. `mode` 값은 `default`, `acceptEdits` 또는 `bypassPermissions`과 같은 모든 권한 모드이며 `destination: "session"`은 현재 세션에만 적용합니다.431대신 특정 권한 모드를 설정하려면 hook의 출력에 `setMode` 항목이 있는 `updatedPermissions` 배열이 포함될 수 있습니다. `mode` 값은 `default`, `acceptEdits` 또는 `bypassPermissions`과 같은 모든 권한 모드이며 `destination: "session"`은 현재 세션에만 적용합니다.

432 432

433<Note>433<Note>

434 `bypassPermissions`은 세션이 이미 bypass 모드로 시작된 경우에만 적용됩니다: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` 또는 설정의 `permissions.defaultMode: "bypassPermissions"`이며 [`permissions.disableBypassPermissionsMode`](/ko/permissions#managed-settings)로 비활성화되지 않습니다. 이는 `defaultMode`로 절대 지속되지 않습니다.434 `bypassPermissions`은 세션이 이미 bypass 모드로 시작된 경우에만 적용됩니다: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` 또는 설정의 `permissions.defaultMode: "bypassPermissions"`이며 [`permissions.disableBypassPermissionsMode`](/docs/ko/permissions#managed-settings)로 비활성화되지 않습니다. 이는 `defaultMode`로 절대 지속되지 않습니다.

435</Note>435</Note>

436 436

437세션을 `acceptEdits`로 전환하려면 hook이 이 JSON을 stdout에 작성합니다:437세션을 `acceptEdits`로 전환하려면 hook이 이 JSON을 stdout에 작성합니다:

450}450}

451```451```

452 452

453Matcher를 가능한 한 좁게 유지합니다. `.*`와 일치하거나 matcher를 비워두면 파일 쓰기 및 셸 명령을 포함한 모든 권한 프롬프트를 자동 승인합니다. 전체 결정 필드 집합은 [PermissionRequest 참조](/ko/hooks#permissionrequest-decision-control)를 참조하세요.453Matcher를 가능한 한 좁게 유지합니다. `.*`와 일치하거나 matcher를 비워두면 파일 쓰기 및 셸 명령을 포함한 모든 권한 프롬프트를 자동 승인합니다. 전체 결정 필드 집합은 [PermissionRequest 참조](/docs/ko/hooks#permissionrequest-decision-control)를 참조하세요.

454 454

455<h2 id="how-hooks-work">455<h2 id="how-hooks-work">

456 Hooks 작동 방식456 Hooks 작동 방식

482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |482| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |484| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

486| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |486| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

494각 hook에는 실행 방식을 결정하는 `type`이 있습니다. 대부분의 hooks는 `"type": "command"`를 사용하여 셸 명령을 실행합니다. 네 가지 다른 유형을 사용할 수 있습니다:494각 hook에는 실행 방식을 결정하는 `type`이 있습니다. 대부분의 hooks는 `"type": "command"`를 사용하여 셸 명령을 실행합니다. 네 가지 다른 유형을 사용할 수 있습니다:

495 495

496* `"type": "http"`: 이벤트 데이터를 URL에 POST합니다. [HTTP hooks](#http-hooks)를 참조하세요.496* `"type": "http"`: 이벤트 데이터를 URL에 POST합니다. [HTTP hooks](#http-hooks)를 참조하세요.

497* `"type": "mcp_tool"`: 이미 연결된 MCP 서버에서 도구를 호출합니다. [MCP tool hooks](/ko/hooks#mcp-tool-hook-fields)를 참조하세요.497* `"type": "mcp_tool"`: 이미 연결된 MCP 서버에서 도구를 호출합니다. [MCP tool hooks](/docs/ko/hooks#mcp-tool-hook-fields)를 참조하세요.

498* `"type": "prompt"`: 단일 턴 LLM 평가입니다. [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.498* `"type": "prompt"`: 단일 턴 LLM 평가입니다. [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.

499* `"type": "agent"`: 도구 액세스를 통한 다중 턴 검증입니다. 에이전트 hooks는 실험적이며 변경될 수 있습니다. [에이전트 기반 hooks](#agent-based-hooks)를 참조하세요.499* `"type": "agent"`: 도구 액세스를 통한 다중 턴 검증입니다. 에이전트 hooks는 실험적이며 변경될 수 있습니다. [에이전트 기반 hooks](#agent-based-hooks)를 참조하세요.

500 500

556}556}

557```557```

558 558

559스크립트는 해당 JSON을 구문 분석하고 해당 필드에 대해 작동할 수 있습니다. `UserPromptSubmit` hooks는 `prompt` 텍스트를 대신 받고, `SessionStart` hooks는 `source` (startup, resume, clear, compact)를 받으며, 등등입니다. 공유 필드는 참조의 [공통 입력 필드](/ko/hooks#common-input-fields)를 참조하고 각 이벤트별 섹션에서 이벤트별 스키마를 참조하세요.559스크립트는 해당 JSON을 구문 분석하고 해당 필드에 대해 작동할 수 있습니다. `UserPromptSubmit` hooks는 `prompt` 텍스트를 대신 받고, `SessionStart` hooks는 `source` (startup, resume, clear, compact)를 받으며, 등등입니다. 공유 필드는 참조의 [공통 입력 필드](/docs/ko/hooks#common-input-fields)를 참조하고 각 이벤트별 섹션에서 이벤트별 스키마를 참조하세요.

560 560

561<h4 id="hook-output">561<h4 id="hook-output">

562 Hook 출력562 Hook 출력

579 579

580종료 코드는 다음에 일어날 일을 결정합니다:580종료 코드는 다음에 일어날 일을 결정합니다:

581 581

582* **Exit 0**: hook은 이의를 제기하지 않으며 작업이 정상적으로 진행됩니다. `PreToolUse` hook의 경우 이것은 도구 호출을 승인하지 않습니다: 정상적인 [권한 흐름](/ko/permissions)이 여전히 적용됩니다. `UserPromptSubmit`, `UserPromptExpansion` 및 `SessionStart` hooks의 경우 stdout에 쓰는 모든 것이 Claude의 컨텍스트에 추가됩니다.582* **Exit 0**: hook은 이의를 제기하지 않으며 작업이 정상적으로 진행됩니다. `PreToolUse` hook의 경우 이것은 도구 호출을 승인하지 않습니다: 정상적인 [권한 흐름](/docs/ko/permissions)이 여전히 적용됩니다. `UserPromptSubmit`, `UserPromptExpansion` 및 `SessionStart` hooks의 경우 stdout에 쓰는 모든 것이 Claude의 컨텍스트에 추가됩니다.

583* **Exit 2**: 작업이 차단됩니다. stderr에 이유를 쓰면 Claude가 피드백으로 받아 조정할 수 있습니다. 일부 이벤트는 차단될 수 없습니다: `SessionStart`, `Setup`, `Notification` 및 기타의 경우 exit 2는 stderr를 사용자에게 표시하고 실행이 계속됩니다. 이벤트별 전체 목록은 [이벤트별 exit 코드 2 동작](/ko/hooks#exit-code-2-behavior-per-event)을 참조하세요.583* **Exit 2**: 작업이 차단됩니다. stderr에 이유를 쓰면 Claude가 피드백으로 받아 조정할 수 있습니다. 일부 이벤트는 차단될 수 없습니다: `SessionStart`, `Setup`, `Notification` 및 기타의 경우 exit 2는 stderr를 사용자에게 표시하고 실행이 계속됩니다. 이벤트별 전체 목록은 [이벤트별 exit 코드 2 동작](/docs/ko/hooks#exit-code-2-behavior-per-event)을 참조하세요.

584* **다른 종료 코드**: 작업이 진행됩니다. 트랜스크립트는 `<hook name> hook error` 공지를 표시한 후 stderr의 첫 번째 줄을 표시합니다. 전체 stderr는 [디버그 로그](/ko/hooks#debug-hooks)로 이동합니다.584* **다른 종료 코드**: 작업이 진행됩니다. 트랜스크립트는 `<hook name> hook error` 공지를 표시한 후 stderr의 첫 번째 줄을 표시합니다. 전체 stderr는 [디버그 로그](/docs/ko/hooks#debug-hooks)로 이동합니다.

585 585

586<h4 id="structured-json-output">586<h4 id="structured-json-output">

587 구조화된 JSON 출력587 구조화된 JSON 출력

607 607

608`"deny"`를 사용하면 Claude Code는 도구 호출을 취소하고 `permissionDecisionReason`을 Claude에게 피드백으로 전달합니다. 이 `permissionDecision` 값은 `PreToolUse`에만 해당합니다:608`"deny"`를 사용하면 Claude Code는 도구 호출을 취소하고 `permissionDecisionReason`을 Claude에게 피드백으로 전달합니다. 이 `permissionDecision` 값은 `PreToolUse`에만 해당합니다:

609 609

610* `"allow"`: 대화형 권한 프롬프트를 건너뜁니다. 거부 및 요청 규칙을 포함한 엔터프라이즈 관리형 거부 목록은 여전히 적용됩니다. 조직이 `ask`로 설정한 [커넥터 도구](/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구에 대한 프롬프트도 마찬가지입니다.610* `"allow"`: 대화형 권한 프롬프트를 건너뜁니다. 거부 및 요청 규칙을 포함한 엔터프라이즈 관리형 거부 목록은 여전히 적용됩니다. 조직이 `ask`로 설정한 [커넥터 도구](/docs/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구에 대한 프롬프트도 마찬가지입니다.

611* `"deny"`: 도구 호출을 취소하고 이유를 Claude에 전송합니다611* `"deny"`: 도구 호출을 취소하고 이유를 Claude에 전송합니다

612* `"ask"`: 일반적으로 사용자에게 권한 프롬프트를 표시합니다612* `"ask"`: 일반적으로 사용자에게 권한 프롬프트를 표시합니다

613 613

614네 번째 값인 `"defer"`는 `-p` 플래그가 있는 [비대화형 모드](/ko/headless)에서 사용 가능합니다. 도구 호출을 보존하여 프로세스를 종료하므로 Agent SDK 래퍼가 입력을 수집하고 재개할 수 있습니다. 참조의 [나중에 도구 호출 연기](/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.614네 번째 값인 `"defer"`는 `-p` 플래그가 있는 [비대화형 모드](/docs/ko/headless)에서 사용 가능합니다. 도구 호출을 보존하여 프로세스를 종료하므로 Agent SDK 래퍼가 입력을 수집하고 재개할 수 있습니다. 참조의 [나중에 도구 호출 연기](/docs/ko/hooks#defer-a-tool-call-for-later)를 참조하세요.

615 615

616`"allow"`를 반환하면 대화형 프롬프트를 건너뜁니다. 하지만 [권한 규칙](/ko/permissions#manage-permissions)을 재정의하지 않습니다. 거부 규칙이 도구 호출과 일치하면 hook이 `"allow"`를 반환하더라도 호출이 차단됩니다. 요청 규칙이 일치하면 사용자가 여전히 프롬프트됩니다. 조직이 `ask`로 설정한 [커넥터 도구](/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구도 마찬가지입니다. 이는 [관리형 설정](/ko/settings#settings-files)을 포함한 모든 설정 범위의 거부 규칙이 hook 승인보다 항상 우선한다는 의미입니다.616`"allow"`를 반환하면 대화형 프롬프트를 건너뜁니다. 하지만 [권한 규칙](/docs/ko/permissions#manage-permissions)을 재정의하지 않습니다. 거부 규칙이 도구 호출과 일치하면 hook이 `"allow"`를 반환하더라도 호출이 차단됩니다. 요청 규칙이 일치하면 사용자가 여전히 프롬프트됩니다. 조직이 `ask`로 설정한 [커넥터 도구](/docs/ko/mcp#organization-controls-on-connector-tools) 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구도 마찬가지입니다. 이는 [관리형 설정](/docs/ko/settings#settings-files)을 포함한 모든 설정 범위의 거부 규칙이 hook 승인보다 항상 우선한다는 의미입니다.

617 617

618다른 이벤트는 다른 결정 패턴을 사용합니다. 예를 들어 `PostToolUse` 및 `Stop` hooks는 최상위 `decision: "block"` 필드를 사용하고 `PermissionRequest`는 `hookSpecificOutput.decision.behavior`를 사용합니다. 이벤트별 전체 분석은 참조의 [요약 표](/ko/hooks#decision-control)를 참조하세요.618다른 이벤트는 다른 결정 패턴을 사용합니다. 예를 들어 `PostToolUse` 및 `Stop` hooks는 최상위 `decision: "block"` 필드를 사용하고 `PermissionRequest`는 `hookSpecificOutput.decision.behavior`를 사용합니다. 이벤트별 전체 분석은 참조의 [요약 표](/docs/ko/hooks#decision-control)를 참조하세요.

619 619

620`UserPromptSubmit` hooks의 경우 `hookSpecificOutput.additionalContext`를 대신 사용하여 Claude의 컨텍스트에 텍스트를 주입합니다. `additionalContext`를 `hookSpecificOutput` 내에 중첩하세요. JSON의 최상위 수준에 배치하면 Claude Code는 이를 자동으로 무시합니다. 예를 들어 이 출력은 모든 프롬프트에 현재 브랜치 상태를 추가합니다:620`UserPromptSubmit` hooks의 경우 `hookSpecificOutput.additionalContext`를 대신 사용하여 Claude의 컨텍스트에 텍스트를 주입합니다. `additionalContext`를 `hookSpecificOutput` 내에 중첩하세요. JSON의 최상위 수준에 배치하면 Claude Code는 이를 자동으로 무시합니다. 예를 들어 이 출력은 모든 프롬프트에 현재 브랜치 상태를 추가합니다:

621 621

628}628}

629```629```

630 630

631프롬프트 차단 및 세션 제목 설정을 포함한 전체 출력 형태는 [UserPromptSubmit 결정 제어](/ko/hooks#userpromptsubmit-decision-control)를 참조하세요.631프롬프트 차단 및 세션 제목 설정을 포함한 전체 출력 형태는 [UserPromptSubmit 결정 제어](/docs/ko/hooks#userpromptsubmit-decision-control)를 참조하세요.

632 632

633`type: "prompt"`를 사용하는 Hooks는 출력을 다르게 처리합니다: [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.633`type: "prompt"`를 사용하는 Hooks는 출력을 다르게 처리합니다: [프롬프트 기반 hooks](#prompt-based-hooks)를 참조하세요.

634 634

653}653}

654```654```

655 655

656`"Edit|Write"` matcher는 Claude가 `Edit` 또는 `Write` 도구를 사용할 때만 발생하고 `Bash`, `Read` 또는 다른 도구를 사용할 때는 발생하지 않습니다. Claude Code v2.1.191 이상에서는 쉼표도 같은 방식으로 대안을 구분하므로 `"Edit, Write"`는 동등합니다. [Matcher 패턴](/ko/hooks#matcher-patterns)을 참조하여 일반 이름과 정규식이 평가되는 방식을 확인하세요.656`"Edit|Write"` matcher는 Claude가 `Edit` 또는 `Write` 도구를 사용할 때만 발생하고 `Bash`, `Read` 또는 다른 도구를 사용할 때는 발생하지 않습니다. Claude Code v2.1.191 이상에서는 쉼표도 같은 방식으로 대안을 구분하므로 `"Edit, Write"`는 동등합니다. [Matcher 패턴](/docs/ko/hooks#matcher-patterns)을 참조하여 일반 이름과 정규식이 평가되는 방식을 확인하세요.

657 657

658<Note>658<Note>

659 Claude는 또한 `Bash` 도구를 통해 셸 명령을 실행하여 파일을 생성하거나 수정할 수 있습니다. Hook이 규정 준수 스캔 또는 감사 로깅과 같이 모든 파일 변경을 확인해야 하는 경우 턴당 한 번 작업 트리를 스캔하는 [`Stop`](/ko/hooks#stop) hook을 추가합니다. 호출당 범위를 대신 원하면 `Bash`도 일치시키고 스크립트가 `git status --porcelain`으로 수정되고 추적되지 않은 파일을 나열하도록 합니다.659 Claude는 또한 `Bash` 도구를 통해 셸 명령을 실행하여 파일을 생성하거나 수정할 수 있습니다. Hook이 규정 준수 스캔 또는 감사 로깅과 같이 모든 파일 변경을 확인해야 하는 경우 턴당 한 번 작업 트리를 스캔하는 [`Stop`](/docs/ko/hooks#stop) hook을 추가합니다. 호출당 범위를 대신 원하면 `Bash`도 일치시키고 스크립트가 `git status --porcelain`으로 수정되고 추적되지 않은 파일을 나열하도록 합니다.

660</Note>660</Note>

661 661

662각 이벤트 유형은 특정 필드에서 일치합니다:662각 이벤트 유형은 특정 필드에서 일치합니다:

681| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | matcher 지원 없음 | 모든 발생에서 항상 발생 |681| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | matcher 지원 없음 | 모든 발생에서 항상 발생 |

682 682

706 </Tab>706 </Tab>

707 707

708 <Tab title="MCP 도구 일치">708 <Tab title="MCP 도구 일치">

709 MCP 도구는 기본 제공 도구와 다른 명명 규칙을 사용합니다: `mcp__<server>__<tool>`. 여기서 `<server>`는 MCP 서버 이름이고 `<tool>`은 제공하는 도구입니다. 예를 들어 `mcp__github__search_repositories` 또는 `mcp__filesystem__read_file`. [플러그인 번들 서버](/ko/mcp#plugin-provided-mcp-servers)의 도구는 대신 `mcp__plugin_my-plugin_db__query`와 같은 범위가 지정된 서버 세그먼트를 사용합니다. 정규식 matcher를 사용하여 특정 서버의 모든 도구를 대상으로 하거나 `mcp__.*__write.*`와 같은 패턴으로 서버 전체에서 일치합니다. 참조의 [MCP 도구 일치](/ko/hooks#match-mcp-tools)를 참조하여 전체 예제 목록을 확인하세요.709 MCP 도구는 기본 제공 도구와 다른 명명 규칙을 사용합니다: `mcp__<server>__<tool>`. 여기서 `<server>`는 MCP 서버 이름이고 `<tool>`은 제공하는 도구입니다. 예를 들어 `mcp__github__search_repositories` 또는 `mcp__filesystem__read_file`. [플러그인 번들 서버](/docs/ko/mcp#plugin-provided-mcp-servers)의 도구는 대신 `mcp__plugin_my-plugin_db__query`와 같은 범위가 지정된 서버 세그먼트를 사용합니다. 정규식 matcher를 사용하여 특정 서버의 모든 도구를 대상으로 하거나 `mcp__.*__write.*`와 같은 패턴으로 서버 전체에서 일치합니다. 참조의 [MCP 도구 일치](/docs/ko/hooks#match-mcp-tools)를 참조하여 전체 예제 목록을 확인하세요.

710 710

711 아래 명령은 hook의 JSON 입력에서 `jq`를 사용하여 도구 이름을 추출하고 stderr에 씁니다. stderr는 stdout을 깨끗하게 유지하고 메시지를 [디버그 로그](/ko/hooks#debug-hooks)로 보냅니다:711 아래 명령은 hook의 JSON 입력에서 `jq`를 사용하여 도구 이름을 추출하고 stderr에 씁니다. stderr는 stdout을 깨끗하게 유지하고 메시지를 [디버그 로그](/docs/ko/hooks#debug-hooks)로 보냅니다:

712 712

713 ```json theme={null}713 ```json theme={null}

714 {714 {

752 </Tab>752 </Tab>

753</Tabs>753</Tabs>

754 754

755전체 matcher 구문은 [Hooks 참조](/ko/hooks#configuration)를 참조하세요.755전체 matcher 구문은 [Hooks 참조](/docs/ko/hooks#configuration)를 참조하세요.

756 756

757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">757<h4 id="filter-by-tool-name-and-arguments-with-the-if-field">

758 도구 이름 및 인수로 `if` 필드를 사용하여 필터링758 도구 이름 및 인수로 `if` 필드를 사용하여 필터링

759</h4>759</h4>

760 760

761`if` 필드는 [권한 규칙 구문](/ko/permissions)을 사용하여 도구 이름과 인수를 함께 사용하여 hooks를 필터링하므로 hook 프로세스는 도구 호출이 일치할 때만 생성됩니다. 이는 도구 이름만으로 그룹 수준에서 필터링하는 `matcher`를 초과합니다.761`if` 필드는 [권한 규칙 구문](/docs/ko/permissions)을 사용하여 도구 이름과 인수를 함께 사용하여 hooks를 필터링하므로 hook 프로세스는 도구 호출이 일치할 때만 생성됩니다. 이는 도구 이름만으로 그룹 수준에서 필터링하는 `matcher`를 초과합니다.

762 762

763예를 들어 모든 Bash 명령이 아닌 `git` 명령을 사용할 때만 hook을 실행하려면:763예를 들어 모든 Bash 명령이 아닌 `git` 명령을 사용할 때만 hook을 실행하려면:

764 764

793 793

794필터는 또한 실패 시 열려 있으므로 Bash 명령을 구문 분석할 수 없을 때 패턴에 관계없이 hook을 실행합니다. 필터는 최선의 노력이므로 하드 허용 또는 거부를 적용하려면 hook 대신 [권한 시스템](/ko/permissions)을 사용합니다.794필터는 또한 실패 시 열려 있으므로 Bash 명령을 구문 분석할 수 없을 때 패턴에 관계없이 hook을 실행합니다. 필터는 최선의 노력이므로 하드 허용 또는 거부를 적용하려면 hook 대신 [권한 시스템](/docs/ko/permissions)을 사용합니다.

795 795

796`if` 필드는 권한 규칙과 동일한 패턴을 허용합니다: `"Bash(git *)"`, `"Edit(*.ts)"` 등. 여러 도구 이름을 일치시키려면 각각 자신의 `if` 값을 가진 별도의 핸들러를 사용하거나 파이프 교대가 지원되는 `matcher` 수준에서 일치합니다.796`if` 필드는 권한 규칙과 동일한 패턴을 허용합니다: `"Bash(git *)"`, `"Edit(*.ts)"` 등. 여러 도구 이름을 일치시키려면 각각 자신의 `if` 값을 가진 별도의 핸들러를 사용하거나 파이프 교대가 지원되는 `matcher` 수준에서 일치합니다.

797 797

814 814

815Claude Code에서 [`/hooks`](/ko/hooks#the-%2Fhooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다.815Claude Code에서 [`/hooks`](/docs/ko/hooks#the-%2Fhooks-menu)를 실행하여 이벤트별로 그룹화된 모든 구성된 hooks를 찾아봅니다.

816 816

817모든 hooks를 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다. 관리형 설정에서 구성된 Hooks는 `disableAllHooks`도 설정되지 않는 한 실행됩니다.817모든 hooks를 비활성화하려면 설정 파일에서 `"disableAllHooks": true`를 설정합니다. 관리형 설정에서 구성된 Hooks는 `disableAllHooks`도 설정되지 않는 한 실행됩니다.

818 818

851}851}

852```852```

853 853

854전체 구성 옵션은 참조의 [프롬프트 기반 hooks](/ko/hooks#prompt-based-hooks)를 참조하세요.854전체 구성 옵션은 참조의 [프롬프트 기반 hooks](/docs/ko/hooks#prompt-based-hooks)를 참조하세요.

855 855

856<h2 id="agent-based-hooks">856<h2 id="agent-based-hooks">

857 에이전트 기반 hooks857 에이전트 기반 hooks

858</h2>858</h2>

859 859

860<Warning>860<Warning>

861 에이전트 hooks는 실험적입니다. 동작 및 구성은 향후 릴리스에서 변경될 수 있습니다. 프로덕션 워크플로우의 경우 [명령 hooks](/ko/hooks#command-hook-fields)를 선호합니다.861 에이전트 hooks는 실험적입니다. 동작 및 구성은 향후 릴리스에서 변경될 수 있습니다. 프로덕션 워크플로우의 경우 [명령 hooks](/docs/ko/hooks#command-hook-fields)를 선호합니다.

862</Warning>862</Warning>

863 863

864검증에 파일 검사 또는 명령 실행이 필요한 경우 `type: "agent"` hooks를 사용합니다. 단일 LLM 호출을 수행하는 프롬프트 hooks와 달리 에이전트 hooks는 파일을 읽고 코드를 검색하며 결정을 반환하기 전에 다른 도구를 사용할 수 있는 subagent를 생성합니다.864검증에 파일 검사 또는 명령 실행이 필요한 경우 `type: "agent"` hooks를 사용합니다. 단일 LLM 호출을 수행하는 프롬프트 hooks와 달리 에이전트 hooks는 파일을 읽고 코드를 검색하며 결정을 반환하기 전에 다른 도구를 사용할 수 있는 subagent를 생성합니다.

887 887

888Hook 입력 데이터만으로 결정을 내릴 수 있을 때 프롬프트 hooks를 사용합니다. 코드베이스의 실제 상태에 대해 무언가를 확인해야 할 때 에이전트 hooks를 사용합니다.888Hook 입력 데이터만으로 결정을 내릴 수 있을 때 프롬프트 hooks를 사용합니다. 코드베이스의 실제 상태에 대해 무언가를 확인해야 할 때 에이전트 hooks를 사용합니다.

889 889

890전체 구성 옵션은 참조의 [에이전트 기반 hooks](/ko/hooks#agent-based-hooks)를 참조하세요.890전체 구성 옵션은 참조의 [에이전트 기반 hooks](/docs/ko/hooks#agent-based-hooks)를 참조하세요.

891 891

892<h2 id="http-hooks">892<h2 id="http-hooks">

893 HTTP hooks893 HTTP hooks

920}920}

921```921```

922 922

923엔드포인트는 명령 hooks와 동일한 [출력 형식](/ko/hooks#json-output)을 사용하여 JSON 응답 본문을 반환해야 합니다. 도구 호출을 차단하려면 적절한 `hookSpecificOutput` 필드와 함께 2xx 응답을 반환합니다. HTTP 상태 코드만으로는 작업을 차단할 수 없습니다.923엔드포인트는 명령 hooks와 동일한 [출력 형식](/docs/ko/hooks#json-output)을 사용하여 JSON 응답 본문을 반환해야 합니다. 도구 호출을 차단하려면 적절한 `hookSpecificOutput` 필드와 함께 2xx 응답을 반환합니다. HTTP 상태 코드만으로는 작업을 차단할 수 없습니다.

924 924

925헤더 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars` 배열에 나열된 변수만 해결됩니다. 다른 모든 `$VAR` 참조는 비어 있습니다.925헤더 값은 `$VAR_NAME` 또는 `${VAR_NAME}` 구문을 사용한 환경 변수 보간을 지원합니다. `allowedEnvVars` 배열에 나열된 변수만 해결됩니다. 다른 모든 `$VAR` 참조는 비어 있습니다.

926 926

927전체 구성 옵션 및 응답 처리는 참조의 [HTTP hooks](/ko/hooks#http-hook-fields)를 참조하세요.927전체 구성 옵션 및 응답 처리는 참조의 [HTTP hooks](/docs/ko/hooks#http-hook-fields)를 참조하세요.

928 928

929<h2 id="limitations-and-troubleshooting">929<h2 id="limitations-and-troubleshooting">

930 제한 사항 및 문제 해결930 제한 사항 및 문제 해결

942 * `prompt`: 30초.942 * `prompt`: 30초.

943 * `agent`: 60초.943 * `agent`: 60초.

944* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.944* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.

945* `PermissionRequest` hooks는 [비대화형 모드](/ko/headless)에서 `-p` 플래그와 함께 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.945* `PermissionRequest` hooks는 [비대화형 모드](/docs/ko/headless)에서 `-p` 플래그와 함께 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.

946* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/ko/hooks#stopfailure)를 발생시킵니다.946* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/docs/ko/hooks#stopfailure)를 발생시킵니다.

947* 여러 `PreToolUse` hooks가 [`updatedInput`](/ko/hooks#pretooluse)을 반환하여 도구의 인수를 다시 쓸 때 마지막으로 완료된 것이 우선합니다. Hooks는 병렬로 실행되므로 순서는 비결정적입니다. 동일한 도구의 입력을 수정하는 hook이 두 개 이상 있는 것을 피합니다.947* 여러 `PreToolUse` hooks가 [`updatedInput`](/docs/ko/hooks#pretooluse)을 반환하여 도구의 인수를 다시 쓸 때 마지막으로 완료된 것이 우선합니다. Hooks는 병렬로 실행되므로 순서는 비결정적입니다. 동일한 도구의 입력을 수정하는 hook이 두 개 이상 있는 것을 피합니다.

948 948

949<h3 id="hooks-and-permission-modes">949<h3 id="hooks-and-permission-modes">

950 Hooks 및 권한 모드950 Hooks 및 권한 모드

952 952

953`PreToolUse` hooks는 모든 권한 모드 확인 전에 발생합니다. `permissionDecision: "deny"`를 반환하는 hook은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.953`PreToolUse` hooks는 모든 권한 모드 확인 전에 발생합니다. `permissionDecision: "deny"`를 반환하는 hook은 `bypassPermissions` 모드 또는 `--dangerously-skip-permissions`에서도 도구를 차단합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.

954 954

955반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않으며, 조직이 `ask`로 설정한 [커넥터 도구](/ko/mcp#organization-controls-on-connector-tools) 또는 [`requiresUserInteraction`](/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구의 프롬프트를 억제할 수 없습니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.955반대는 사실이 아닙니다: `"allow"`를 반환하는 hook은 설정의 거부 규칙을 우회하지 않으며, 조직이 `ask`로 설정한 [커넥터 도구](/docs/ko/mcp#organization-controls-on-connector-tools) 또는 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구의 프롬프트를 억제할 수 없습니다. Hooks는 제한을 강화할 수 있지만 권한 규칙이 허용하는 것을 초과하여 완화할 수 없습니다.

956 956

957<h3 id="hook-not-firing">957<h3 id="hook-not-firing">

958 Hook이 발생하지 않음958 Hook이 발생하지 않음

976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh976 echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh

977 echo $? # 종료 코드 확인977 echo $? # 종료 코드 확인

978 ```978 ```

979* "command not found"가 표시되면 절대 경로를 사용하거나 `${CLAUDE_PROJECT_DIR}`을 사용하여 스크립트를 참조합니다. 셸 인용을 완전히 피하려면 `"args": []`를 추가하여 [exec form](/ko/hooks#exec-form-and-shell-form)으로 전환하면 셸 없이 스크립트를 직접 생성합니다979* "command not found"가 표시되면 절대 경로를 사용하거나 `${CLAUDE_PROJECT_DIR}`을 사용하여 스크립트를 참조합니다. 셸 인용을 완전히 피하려면 `"args": []`를 추가하여 [exec form](/docs/ko/hooks#exec-form-and-shell-form)으로 전환하면 셸 없이 스크립트를 직접 생성합니다

980* "jq: command not found"가 표시되면 `jq`를 설치하거나 JSON 구문 분석을 위해 Python/Node.js를 사용합니다980* "jq: command not found"가 표시되면 `jq`를 설치하거나 JSON 구문 분석을 위해 Python/Node.js를 사용합니다

981* 스크립트가 실행되지 않으면 실행 가능하게 만듭니다: `chmod +x ./my-hook.sh`981* 스크립트가 실행되지 않으면 실행 가능하게 만듭니다: `chmod +x ./my-hook.sh`

982 982

1007# ... hook 로직의 나머지1007# ... hook 로직의 나머지

1008```1008```

1009 1009

1010Hook이 수렴하기 위해 8번 이상의 반복이 필요한 경우 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/ko/env-vars)으로 상한을 올립니다.1010Hook이 수렴하기 위해 8번 이상의 반복이 필요한 경우 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/ko/env-vars)으로 상한을 올립니다.

1011 1011

1012<h3 id="json-validation-failed">1012<h3 id="json-validation-failed">

1013 JSON 검증 실패1013 JSON 검증 실패

1045 자세히 알아보기1045 자세히 알아보기

1046</h2>1046</h2>

1047 1047

1048* [Hooks 참조](/ko/hooks): 전체 이벤트 스키마, JSON 출력 형식, 비동기 hooks 및 MCP 도구 hooks1048* [Hooks 참조](/docs/ko/hooks): 전체 이벤트 스키마, JSON 출력 형식, 비동기 hooks 및 MCP 도구 hooks

1049* [보안 고려 사항](/ko/hooks#security-considerations): 공유 또는 프로덕션 환경에서 hooks를 배포하기 전에 검토합니다1049* [보안 고려 사항](/docs/ko/hooks#security-considerations): 공유 또는 프로덕션 환경에서 hooks를 배포하기 전에 검토합니다

1050* [Bash 명령 검증기 예제](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): 완전한 참조 구현1050* [Bash 명령 검증기 예제](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py): 완전한 참조 구현

plugins-reference.md +44 −44

Details

7> Claude Code 플러그인 시스템의 완전한 기술 참조, 스키마, CLI 명령어 및 컴포넌트 사양 포함.7> Claude Code 플러그인 시스템의 완전한 기술 참조, 스키마, CLI 명령어 및 컴포넌트 사양 포함.

8 8

9<Tip>9<Tip>

10 플러그인을 설치하려고 하시나요? [플러그인 발견 및 설치](/ko/discover-plugins)를 참조하세요. 플러그인 생성에 대해서는 [플러그인](/ko/plugins)을 참조하세요. 플러그인 배포에 대해서는 [플러그인 마켓플레이스](/ko/plugin-marketplaces)를 참조하세요.10 플러그인을 설치하려고 하시나요? [플러그인 발견 및 설치](/docs/ko/discover-plugins)를 참조하세요. 플러그인 생성에 대해서는 [플러그인](/docs/ko/plugins)을 참조하세요. 플러그인 배포에 대해서는 [플러그인 마켓플레이스](/docs/ko/plugin-marketplaces)를 참조하세요.

11</Tip>11</Tip>

12 12

13이 참조는 Claude Code 플러그인 시스템의 완전한 기술 사양을 제공하며, 컴포넌트 스키마, CLI 명령어 및 개발 도구를 포함합니다.13이 참조는 Claude Code 플러그인 시스템의 완전한 기술 사양을 제공하며, 컴포넌트 스키마, CLI 명령어 및 개발 도구를 포함합니다.

48 48

49플러그인에 `skills/` 디렉토리가 없고 `skills` manifest 필드가 없으면, 플러그인 루트의 `SKILL.md`가 단일 skill로 로드됩니다. frontmatter `name` 필드를 설정하여 skill의 호출 이름을 제어하세요. 이 필드가 없으면 Claude Code는 설치 디렉토리 이름으로 폴백되며, 마켓플레이스에서 설치된 플러그인의 경우 매 업데이트마다 변경되는 버전 문자열입니다. 둘 이상의 skill을 제공하는 플러그인의 경우 위에 표시된 `skills/` 디렉토리 레이아웃을 사용하세요.49플러그인에 `skills/` 디렉토리가 없고 `skills` manifest 필드가 없으면, 플러그인 루트의 `SKILL.md`가 단일 skill로 로드됩니다. frontmatter `name` 필드를 설정하여 skill의 호출 이름을 제어하세요. 이 필드가 없으면 Claude Code는 설치 디렉토리 이름으로 폴백되며, 마켓플레이스에서 설치된 플러그인의 경우 매 업데이트마다 변경되는 버전 문자열입니다. 둘 이상의 skill을 제공하는 플러그인의 경우 위에 표시된 `skills/` 디렉토리 레이아웃을 사용하세요.

50 50

~~51완전한 세부 정보는 [Skills](/ko/skills)를 참조하세요.~~51완전한 세부 정보는 [Skills](/docs/ko/skills)를 참조하세요.

52 52

53<h3 id="agents">53<h3 id="agents">

54 Agents54 Agents

79 79

80**통합 지점**:80**통합 지점**:

81 81

82* Agents는 [@-mention 타입어헤드](/ko/sub-agents#invoke-subagents-explicitly)에 `my-plugin:code-reviewer`와 같은 범위가 지정된 이름으로 나타나며, 플러그인이 활성화되면 표시됩니다.82* Agents는 [@-mention 타입어헤드](/docs/ko/sub-agents#invoke-subagents-explicitly)에 `my-plugin:code-reviewer`와 같은 범위가 지정된 이름으로 나타나며, 플러그인이 활성화되면 표시됩니다.

83* Claude는 작업 컨텍스트에 따라 agents를 자동으로 호출할 수 있습니다.83* Claude는 작업 컨텍스트에 따라 agents를 자동으로 호출할 수 있습니다.

84* Agents는 사용자가 수동으로 호출할 수 있습니다.84* Agents는 사용자가 수동으로 호출할 수 있습니다.

85* 플러그인 agents는 기본 제공 Claude agents와 함께 작동합니다.85* 플러그인 agents는 기본 제공 Claude agents와 함께 작동합니다.

86 86

~~87완전한 세부 정보는 [Subagents](/ko/sub-agents)를 참조하세요.~~87완전한 세부 정보는 [Subagents](/docs/ko/sub-agents)를 참조하세요.

88 88

89<h3 id="hooks">89<h3 id="hooks">

90 Hooks90 Hooks

116}116}

117```117```

118 118

119플러그인 hooks는 [사용자 정의 hooks](/ko/hooks)와 동일한 라이프사이클 이벤트에 응답합니다:119플러그인 hooks는 [사용자 정의 hooks](/docs/ko/hooks)와 동일한 라이프사이클 이벤트에 응답합니다:

120 120

121| Event | When it fires |121| Event | When it fires |

122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |122| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |142| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |144| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

146| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |146| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |

155 155

156* `command`: 셸 명령어 또는 스크립트 실행156* `command`: 셸 명령어 또는 스크립트 실행

157* `http`: 이벤트 JSON을 URL로 POST 요청으로 전송157* `http`: 이벤트 JSON을 URL로 POST 요청으로 전송

158* `mcp_tool`: 구성된 [MCP server](/ko/mcp)에서 도구 호출158* `mcp_tool`: 구성된 [MCP server](/docs/ko/mcp)에서 도구 호출

159* `prompt`: LLM으로 프롬프트 평가 (컨텍스트에 대해 `$ARGUMENTS` 플레이스홀더 사용)159* `prompt`: LLM으로 프롬프트 평가 (컨텍스트에 대해 `$ARGUMENTS` 플레이스홀더 사용)

160* `agent`: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행160* `agent`: 복잡한 검증 작업을 위해 도구가 있는 에이전트 검증자 실행

161 161

162플러그인의 자체 [번들 MCP server](#mcp-servers)를 대상으로 하는 Hooks는 범위가 지정된 이름을 사용해야 합니다. 도구 매처 및 `if` 필드는 범위가 지정된 도구 이름 `mcp__plugin_<plugin-name>_<server-name>__<tool>`을 사용하고, `mcp_tool` hook의 `server` 필드는 `plugin:<plugin-name>:<server-name>`을 사용합니다. 베어 서버 키에 대해 작성된 매처는 절대 실행되지 않습니다. [MCP 도구 매칭](/ko/hooks#match-mcp-tools) 및 [플러그인 제공 MCP servers](/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.162플러그인의 자체 [번들 MCP server](#mcp-servers)를 대상으로 하는 Hooks는 범위가 지정된 이름을 사용해야 합니다. 도구 매처 및 `if` 필드는 범위가 지정된 도구 이름 `mcp__plugin_<plugin-name>_<server-name>__<tool>`을 사용하고, `mcp_tool` hook의 `server` 필드는 `plugin:<plugin-name>:<server-name>`을 사용합니다. 베어 서버 키에 대해 작성된 매처는 절대 실행되지 않습니다. [MCP 도구 매칭](/docs/ko/hooks#match-mcp-tools) 및 [플러그인 제공 MCP servers](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하세요.

163 163

164<h3 id="mcp-servers">164<h3 id="mcp-servers">

165 MCP servers165 MCP servers

300 300

301플러그인은 플러그인이 활성화될 때 Claude Code가 자동으로 시작하는 백그라운드 monitors를 선언할 수 있습니다. 각 monitor는 세션 동안 셸 명령어를 실행하고 모든 stdout 라인을 Claude에게 알림으로 전달하므로 Claude는 로그 항목, 상태 변경 또는 폴링된 이벤트에 반응할 수 있으며 자신이 watch를 시작하도록 요청받을 필요가 없습니다.301플러그인은 플러그인이 활성화될 때 Claude Code가 자동으로 시작하는 백그라운드 monitors를 선언할 수 있습니다. 각 monitor는 세션 동안 셸 명령어를 실행하고 모든 stdout 라인을 Claude에게 알림으로 전달하므로 Claude는 로그 항목, 상태 변경 또는 폴링된 이벤트에 반응할 수 있으며 자신이 watch를 시작하도록 요청받을 필요가 없습니다.

302 302

303플러그인 monitors는 [Monitor tool](/ko/tools-reference#monitor-tool)과 동일한 메커니즘을 사용하며 해당 가용성 제약을 공유합니다. 이들은 대화형 CLI 세션에서만 실행되고, [hooks](#hooks)와 동일한 신뢰 수준에서 샌드박스 없이 실행되며, Monitor tool을 사용할 수 없는 호스트에서는 건너뜁니다.303플러그인 monitors는 [Monitor tool](/docs/ko/tools-reference#monitor-tool)과 동일한 메커니즘을 사용하며 해당 가용성 제약을 공유합니다. 이들은 대화형 CLI 세션에서만 실행되고, [hooks](#hooks)와 동일한 신뢰 수준에서 샌드박스 없이 실행되며, Monitor tool을 사용할 수 없는 호스트에서는 건너뜁니다.

304 304

305**위치**: 플러그인 루트의 `monitors/monitors.json` 또는 plugin.json에 인라인305**위치**: 플러그인 루트의 `monitors/monitors.json` 또는 plugin.json에 인라인

306 306

342 342

343`command` 값은 [경로 대체](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` 및 환경의 모든 `${ENV_VAR}`을 지원합니다. 스크립트가 플러그인 자체 디렉토리에서 실행되어야 하는 경우 명령어 앞에 `cd "${CLAUDE_PLUGIN_ROOT}" && `를 붙이세요.343`command` 값은 [경로 대체](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}` 및 환경의 모든 `${ENV_VAR}`을 지원합니다. 스크립트가 플러그인 자체 디렉토리에서 실행되어야 하는 경우 명령어 앞에 `cd "${CLAUDE_PLUGIN_ROOT}" && `를 붙이세요.

344 344

345monitor `command`는 [`${user_config.*}`](#user-configuration) 값을 참조할 수 없습니다. 명령어는 셸을 통해 실행되므로 Claude Code는 값을 대체하는 대신 [오류](/ko/errors#plugin-command-references-user-config)로 monitor를 거부합니다. Monitor 프로세스는 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수를 받지 않으므로 monitor 스크립트가 자신이 소유한 구성 파일에서 값을 읽도록 하세요. v2.1.207 이전에는 monitor 명령어가 `${user_config.*}` 값을 대체했습니다.345monitor `command`는 [`${user_config.*}`](#user-configuration) 값을 참조할 수 없습니다. 명령어는 셸을 통해 실행되므로 Claude Code는 값을 대체하는 대신 [오류](/docs/ko/errors#plugin-command-references-user-config)로 monitor를 거부합니다. Monitor 프로세스는 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수를 받지 않으므로 monitor 스크립트가 자신이 소유한 구성 파일에서 값을 읽도록 하세요. v2.1.207 이전에는 monitor 명령어가 `${user_config.*}` 값을 대체했습니다.

346 346

347세션 중간에 플러그인을 비활성화해도 이미 실행 중인 monitors는 중지되지 않습니다. 세션이 끝날 때 중지됩니다.347세션 중간에 플러그인을 비활성화해도 이미 실행 중인 monitors는 중지되지 않습니다. 세션이 끝날 때 중지됩니다.

348 348

383 383

384플러그인은 다른 Claude Code 구성과 동일한 범위 시스템을 사용합니다. 설치 지침 및 범위 플래그는 [플러그인 설치](/ko/discover-plugins#install-plugins)를 참조하세요. 범위에 대한 완전한 설명은 [구성 범위](/ko/settings#configuration-scopes)를 참조하세요.384플러그인은 다른 Claude Code 구성과 동일한 범위 시스템을 사용합니다. 설치 지침 및 범위 플래그는 [플러그인 설치](/docs/ko/discover-plugins#install-plugins)를 참조하세요. 범위에 대한 완전한 설명은 [구성 범위](/docs/ko/settings#configuration-scopes)를 참조하세요.

385 385

386***386***

387 387

395 395

396| 무엇을 가지고 있는지 | 무엇인지 |396| 무엇을 가지고 있는지 | 무엇인지 |

397| :-------------------------------------------- | :------------------------------------------------------------------- |397| :-------------------------------------------- | :------------------------------------------------------------------- |

401 401

406| Skills 디렉토리 | 범위 | 로드 |406| Skills 디렉토리 | 범위 | 로드 |

407| :---------------------- | :------- | :--------------------------------------------- |407| :---------------------- | :------- | :--------------------------------------------- |

410 410

411프로젝트 범위 플러그인은 저장소에 체크인되고 복제하는 모든 협력자에게 도달합니다. 해당 콘텐츠는 저장소에서 오므로 `.claude/settings.json`을 관리하는 것과 동일한 신뢰 게이트 후에만 로드되며, 코드를 실행하는 컴포넌트는 추가로 제한됩니다:411프로젝트 범위 플러그인은 저장소에 체크인되고 복제하는 모든 협력자에게 도달합니다. 해당 콘텐츠는 저장소에서 오므로 `.claude/settings.json`을 관리하는 것과 동일한 신뢰 게이트 후에만 로드되며, 코드를 실행하는 컴포넌트는 추가로 제한됩니다:

412 412

413* 선언하는 MCP servers는 프로젝트 `.mcp.json`과 동일한 [서버별 승인](/ko/mcp)을 거칩니다.413* 선언하는 MCP servers는 프로젝트 `.mcp.json`과 동일한 [서버별 승인](/docs/ko/mcp)을 거칩니다.

414* LSP servers는 작업 공간을 신뢰한 후에만 시작됩니다.414* LSP servers는 작업 공간을 신뢰한 후에만 시작됩니다.

415* [백그라운드 monitors](#monitors)는 로드되지 않습니다.415* [백그라운드 monitors](#monitors)는 로드되지 않습니다.

416 416

417개인 범위 플러그인에는 이러한 제한이 없습니다.417개인 범위 플러그인에는 이러한 제한이 없습니다.

418 418

419<Warning>419<Warning>

420 프로젝트 범위 `@skills-dir` 플러그인은 Claude Code를 시작하는 디렉토리의 `.claude/skills/`에서만 로드됩니다. 일반 skills 및 commands가 하는 것처럼 [저장소 루트로 이동](/ko/skills#automatic-discovery-from-parent-and-nested-directories)하지 않으므로 서브디렉토리에서 시작하면 저장소 루트에 있는 플러그인을 놓칩니다. 저장소 루트에서 시작하거나 디렉토리를 변경한 후 `/reload-plugins`를 실행하세요.420 프로젝트 범위 `@skills-dir` 플러그인은 Claude Code를 시작하는 디렉토리의 `.claude/skills/`에서만 로드됩니다. 일반 skills 및 commands가 하는 것처럼 [저장소 루트로 이동](/docs/ko/skills#automatic-discovery-from-parent-and-nested-directories)하지 않으므로 서브디렉토리에서 시작하면 저장소 루트에 있는 플러그인을 놓칩니다. 저장소 루트에서 시작하거나 디렉토리를 변경한 후 `/reload-plugins`를 실행하세요.

421</Warning>421</Warning>

422 422

423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">423<h3 id="edit-reload-and-disable-a-skills-directory-plugin">

424 Skills-directory 플러그인 편집, 다시 로드 및 비활성화424 Skills-directory 플러그인 편집, 다시 로드 및 비활성화

425</h3>425</h3>

426 426

427skill의 `SKILL.md`에 대한 변경 사항은 현재 세션에서 즉시 적용됩니다. `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`와 같은 플러그인의 다른 컴포넌트에 대한 변경 사항은 그렇지 않습니다. `/reload-plugins`를 실행하거나 Claude Code를 다시 시작하여 이들을 선택하세요. [라이브 변경 감지](/ko/skills#live-change-detection)를 참조하세요.427skill의 `SKILL.md`에 대한 변경 사항은 현재 세션에서 즉시 적용됩니다. `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`와 같은 플러그인의 다른 컴포넌트에 대한 변경 사항은 그렇지 않습니다. `/reload-plugins`를 실행하거나 Claude Code를 다시 시작하여 이들을 선택하세요. [라이브 변경 감지](/docs/ko/skills#live-change-detection)를 참조하세요.

428 428

429skills-directory 플러그인 로드를 중지하려면 해당 폴더를 삭제하거나 이름으로 비활성화하세요. 마켓플레이스에서 아무것도 설치되지 않았으므로 `uninstall` 단계가 없습니다.429skills-directory 플러그인 로드를 중지하려면 해당 폴더를 삭제하거나 이름으로 비활성화하세요. 마켓플레이스에서 아무것도 설치되지 않았으므로 `uninstall` 단계가 없습니다.

430 430

487 487

488| 필드 | 타입 | 설명 | 예시 |488| 필드 | 타입 | 설명 | 예시 |

489| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |489| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |

491 491

492이 이름은 컴포넌트 네임스페이싱에 사용됩니다. 예를 들어 UI에서 이름이 `plugin-dev`인 플러그인의 agent `agent-creator`는 `plugin-dev:agent-creator`로 나타납니다.492이 이름은 컴포넌트 네임스페이싱에 사용됩니다. 예를 들어 UI에서 이름이 `plugin-dev`인 플러그인의 agent `agent-creator`는 `plugin-dev:agent-creator`로 나타납니다.

493 493

533`defaultEnabled`는 다른 것이 플러그인의 상태를 결정하지 않았을 때의 폴백입니다. 두 가지가 이를 우선합니다:533`defaultEnabled`는 다른 것이 플러그인의 상태를 결정하지 않았을 때의 폴백입니다. 두 가지가 이를 우선합니다:

534 534

535* **사용자의 설정**: 모든 설정 범위에서 플러그인에 대한 `enabledPlugins`의 항목입니다. 작성되면 플러그인 업데이트 및 재설치 전체에서 유지되므로 나중 릴리스에서 `defaultEnabled`를 변경해도 기존 사용자를 뒤집지 않습니다.535* **사용자의 설정**: 모든 설정 범위에서 플러그인에 대한 `enabledPlugins`의 항목입니다. 작성되면 플러그인 업데이트 및 재설치 전체에서 유지되므로 나중 릴리스에서 `defaultEnabled`를 변경해도 기존 사용자를 뒤집지 않습니다.

536* **종속성 요구 사항**: 플러그인이 활성화된 다른 플러그인에 의해 필요할 때 Claude Code는 설치 또는 활성화 시 `true`를 작성합니다. 이는 명시적 설정을 제공하므로 자체 기본값이 더 이상 적용되지 않습니다. [종속성이 있는 플러그인 활성화 또는 비활성화](/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)를 참조하세요.536* **종속성 요구 사항**: 플러그인이 활성화된 다른 플러그인에 의해 필요할 때 Claude Code는 설치 또는 활성화 시 `true`를 작성합니다. 이는 명시적 설정을 제공하므로 자체 기본값이 더 이상 적용되지 않습니다. [종속성이 있는 플러그인 활성화 또는 비활성화](/docs/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)를 참조하세요.

537 537

538동일한 필드가 플러그인의 마켓플레이스 항목에 나타날 수 있으며, 여기서 `plugin.json`의 값보다 우선합니다. [선택사항 플러그인 필드](/ko/plugin-marketplaces#optional-plugin-fields)를 참조하세요.538동일한 필드가 플러그인의 마켓플레이스 항목에 나타날 수 있으며, 여기서 `plugin.json`의 값보다 우선합니다. [선택사항 플러그인 필드](/docs/ko/plugin-marketplaces#optional-plugin-fields)를 참조하세요.

539 539

540<h3 id="component-path-fields">540<h3 id="component-path-fields">

541 컴포넌트 경로 필드541 컴포넌트 경로 필드

557| `dependencies` | array | 이 플러그인이 필요로 하는 다른 플러그인, 선택적으로 semver 버전 제약 포함. [플러그인 종속성 버전 제약](/ko/plugin-dependencies) 참조 | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |557| `dependencies` | array | 이 플러그인이 필요로 하는 다른 플러그인, 선택적으로 semver 버전 제약 포함. [플러그인 종속성 버전 제약](/docs/ko/plugin-dependencies) 참조 | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

558 558

559<h3 id="experimental-components">559<h3 id="experimental-components">

560 실험적 컴포넌트560 실험적 컴포넌트

601 601

602각 값은 MCP 및 LSP 서버 구성과 hook 명령어에서 `${user_config.KEY}`로 대체할 수 있습니다. 민감하지 않은 값은 skill 및 agent 콘텐츠에서도 대체할 수 있습니다. 모든 값은 hook 프로세스에 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수로 내보내집니다. 여기서 `<KEY>`는 옵션 키를 대문자로 표기한 것입니다.602각 값은 MCP 및 LSP 서버 구성과 hook 명령어에서 `${user_config.KEY}`로 대체할 수 있습니다. 민감하지 않은 값은 skill 및 agent 콘텐츠에서도 대체할 수 있습니다. 모든 값은 hook 프로세스에 `CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수로 내보내집니다. 여기서 `<KEY>`는 옵션 키를 대문자로 표기한 것입니다.

603 603

604셸에서 실행되는 필드는 `${user_config.*}`를 거부합니다. 구성된 값을 셸 명령어에 대체하면 셸이 해당 값이 포함하는 모든 것을 실행할 수 있으므로 컴포넌트는 [오류](/ko/errors#plugin-command-references-user-config)로 실패합니다. 거부된 각 필드에는 값을 전달하는 대체 방법이 있습니다:604셸에서 실행되는 필드는 `${user_config.*}`를 거부합니다. 구성된 값을 셸 명령어에 대체하면 셸이 해당 값이 포함하는 모든 것을 실행할 수 있으므로 컴포넌트는 [오류](/docs/ko/errors#plugin-command-references-user-config)로 실패합니다. 거부된 각 필드에는 값을 전달하는 대체 방법이 있습니다:

605 605

606| 거부된 필드 | 값을 전달하는 방법 |606| 거부된 필드 | 값을 전달하는 방법 |

607| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |607| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |

608| Shell-form hook 명령어 | [exec form](/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하거나 hook의 환경에서 `CLAUDE_PLUGIN_OPTION_<KEY>`를 읽습니다. |608| Shell-form hook 명령어 | [exec form](/docs/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하거나 hook의 환경에서 `CLAUDE_PLUGIN_OPTION_<KEY>`를 읽습니다. |

609| [Monitor](#monitors) 명령어 | 스크립트의 구성 파일에서 값을 읽습니다. |609| [Monitor](#monitors) 명령어 | 스크립트의 구성 파일에서 값을 읽습니다. |

611 611

612v2.1.207 이전에는 이러한 필드가 `${user_config.KEY}` 값을 대체했습니다. 이에 의존하는 플러그인을 업데이트하세요.612v2.1.207 이전에는 이러한 필드가 `${user_config.KEY}` 값을 대체했습니다. 이에 의존하는 플러그인을 업데이트하세요.

613 613

653사용자 정의 경로가 플러그인의 기본 디렉토리를 대체하는지 확장하는지는 필드에 따라 다릅니다:653사용자 정의 경로가 플러그인의 기본 디렉토리를 대체하는지 확장하는지는 필드에 따라 다릅니다:

654 654

655* **기본값 대체**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. 예를 들어 매니페스트가 `commands`를 지정하면 기본 `commands/` 디렉토리는 스캔되지 않습니다. 기본값을 유지하고 더 많은 것을 추가하려면 명시적으로 나열하세요: `"commands": ["./commands/", "./extras/"]`655* **기본값 대체**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. 예를 들어 매니페스트가 `commands`를 지정하면 기본 `commands/` 디렉토리는 스캔되지 않습니다. 기본값을 유지하고 더 많은 것을 추가하려면 명시적으로 나열하세요: `"commands": ["./commands/", "./extras/"]`

656* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 서브디렉토리를 선언하면 기본 `skills/` 스캔을 대체합니다.656* **기본값에 추가**: `skills`. 기본 `skills/` 디렉토리는 항상 스캔되며, `skills`에 나열된 디렉토리는 함께 로드됩니다. 예외: [소스가 마켓플레이스 루트로 확인되는 마켓플레이스 항목](/docs/ko/plugin-marketplaces#advanced-plugin-entries)의 경우 특정 서브디렉토리를 선언하면 기본 `skills/` 스캔을 대체합니다.

657* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.657* **자체 병합 규칙**: [hooks](#hooks), [MCP servers](#mcp-servers) 및 [LSP servers](#lsp-servers). 각 섹션에서 여러 소스가 어떻게 결합되는지 참조하세요.

658 658

659플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있으면 Claude Code v2.1.140 이상은 `claude plugin list` 및 `/plugin` 상세 보기에서 무시된 폴더에 플래그를 지정합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. 매니페스트 키가 기본 폴더를 가리킬 때는 경고가 표시되지 않습니다 (예: `"commands": ["./commands/deploy.md"]`). 이 경우 폴더가 명시적으로 처리되기 때문입니다.659플러그인에 기본 폴더와 일치하는 매니페스트 키가 모두 있으면 Claude Code v2.1.140 이상은 `claude plugin list` 및 `/plugin` 상세 보기에서 무시된 폴더에 플래그를 지정합니다. 플러그인은 여전히 매니페스트 경로를 사용하여 로드됩니다. 매니페스트 키가 기본 폴더를 가리킬 때는 경고가 표시되지 않습니다 (예: `"commands": ["./commands/deploy.md"]`). 이 경우 폴더가 명시적으로 처리되기 때문입니다.

706 706

707hook 명령어에서 [exec form](/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하여 각 경로가 따옴표 없이 하나의 인수로 전달되도록 하세요. shell-form hook 및 monitor 명령어에서 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`와 같이 큰따옴표로 변수를 감싸세요. 이 shell-form hook은 플러그인과 함께 번들된 스크립트를 실행합니다:707hook 명령어에서 [exec form](/docs/ko/hooks#exec-form-and-shell-form)을 `args`와 함께 사용하여 각 경로가 따옴표 없이 하나의 인수로 전달되도록 하세요. shell-form hook 및 monitor 명령어에서 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`와 같이 큰따옴표로 변수를 감싸세요. 이 shell-form hook은 플러그인과 함께 번들된 스크립트를 실행합니다:

708 708

709```json theme={null}709```json theme={null}

710{710{

727 727

728플러그인이 세션 중에 업데이트될 때 hook 명령어, monitors, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. `/reload-plugins`를 실행하여 hook, MCP 서버 및 LSP 서버를 새 경로로 전환하세요. monitors는 세션 재시작이 필요합니다.728플러그인이 세션 중에 업데이트될 때 hook 명령어, monitors, MCP 서버 및 LSP 서버는 이전 버전의 경로를 계속 사용합니다. `/reload-plugins`를 실행하여 hook, MCP 서버 및 LSP 서버를 새 경로로 전환하세요. monitors는 세션 재시작이 필요합니다.

729 729

730MCP 서버는 또한 `roots/list` 요청을 호출하여 런타임에 세션의 작업 디렉토리를 읽을 수 있습니다. [`roots/list`가 반환하는 것과 Claude Code가 서버에 변경을 알리는 시기](/ko/mcp#option-3-add-a-local-stdio-server)를 참조하세요.730MCP 서버는 또한 `roots/list` 요청을 호출하여 런타임에 세션의 작업 디렉토리를 읽을 수 있습니다. [`roots/list`가 반환하는 것과 Claude Code가 서버에 변경을 알리는 시기](/docs/ko/mcp#option-3-add-a-local-stdio-server)를 참조하세요.

731 731

732<h4 id="persistent-data-directory">732<h4 id="persistent-data-directory">

733 영구 데이터 디렉토리733 영구 데이터 디렉토리

895| **Executables** | `bin/` | Bash tool의 `PATH`에 추가된 실행 파일. 여기의 파일은 플러그인이 활성화된 동안 모든 Bash tool 호출에서 bare 명령어로 호출 가능 |895| **Executables** | `bin/` | Bash tool의 `PATH`에 추가된 실행 파일. 여기의 파일은 플러그인이 활성화된 동안 모든 Bash tool 호출에서 bare 명령어로 호출 가능 |

896| **Settings** | `settings.json` | 플러그인이 활성화될 때 적용되는 기본 구성. 현재 [`agent`](/ko/sub-agents) 및 [`subagentStatusLine`](/ko/statusline#subagent-status-lines) 키만 지원됩니다 |896| **Settings** | `settings.json` | 플러그인이 활성화될 때 적용되는 기본 구성. 현재 [`agent`](/docs/ko/sub-agents) 및 [`subagentStatusLine`](/docs/ko/statusline#subagent-status-lines) 키만 지원됩니다 |

897 897

898***898***

899 899

942| `mcp` | HTTP 및 stdio 서버 예시가 있는 `.mcp.json` |942| `mcp` | HTTP 및 stdio 서버 예시가 있는 `.mcp.json` |

943| `lsp` | 언어 서버 예시가 있는 `.lsp.json` |943| `lsp` | 언어 서버 예시가 있는 `.lsp.json` |

946 946

947스캐폴드된 플러그인은 마켓플레이스가 아닌 `@skills-dir` 소스를 사용합니다. 관리자는 [관리되는 설정](/ko/plugin-marketplaces#managed-marketplace-restrictions)에서 `strictKnownMarketplaces`로 이 소스를 차단하거나 `blockedMarketplaces`에 `{"source": "skills-dir"}`을 추가할 수 있습니다. 차단되면 `plugin init`은 작성하기 전에 실패합니다.947스캐폴드된 플러그인은 마켓플레이스가 아닌 `@skills-dir` 소스를 사용합니다. 관리자는 [관리되는 설정](/docs/ko/plugin-marketplaces#managed-marketplace-restrictions)에서 `strictKnownMarketplaces`로 이 소스를 차단하거나 `blockedMarketplaces`에 `{"source": "skills-dir"}`을 추가할 수 있습니다. 차단되면 `plugin init`은 작성하기 전에 실패합니다.

948 948

949**예시:**949**예시:**

950 950

1027 plugin prune1027 plugin prune

1028</h3>1028</h3>

1029 1029

1030더 이상 설치된 플러그인에서 필요로 하지 않는 자동 설치된 플러그인 종속성을 제거합니다. Claude Code가 다른 플러그인의 [`dependencies`](/ko/plugin-dependencies) 필드를 만족하기 위해 가져온 종속성은 제거되며, 직접 설치한 플러그인은 절대 건드리지 않습니다.1030더 이상 설치된 플러그인에서 필요로 하지 않는 자동 설치된 플러그인 종속성을 제거합니다. Claude Code가 다른 플러그인의 [`dependencies`](/docs/ko/plugin-dependencies) 필드를 만족하기 위해 가져온 종속성은 제거되며, 직접 설치한 플러그인은 절대 건드리지 않습니다.

1031 1031

1032```bash theme={null}1032```bash theme={null}

1033claude plugin prune [options]1033claude plugin prune [options]

1054 plugin enable1054 plugin enable

1055</h3>1055</h3>

1056 1056

1057비활성화된 플러그인을 활성화합니다. 플러그인이 [종속성](/ko/plugin-dependencies)을 선언하면 Claude Code는 동일한 범위에서 이들을 전이적으로 활성화하며, 종속성이 설치되지 않으면 명령어가 실패합니다.1057비활성화된 플러그인을 활성화합니다. 플러그인이 [종속성](/docs/ko/plugin-dependencies)을 선언하면 Claude Code는 동일한 범위에서 이들을 전이적으로 활성화하며, 종속성이 설치되지 않으면 명령어가 실패합니다.

1058 1058

1059```bash theme={null}1059```bash theme={null}

1060claude plugin enable <plugin> [options]1060claude plugin enable <plugin> [options]

1075 plugin disable1075 plugin disable

1076</h3>1076</h3>

1077 1077

1078플러그인을 제거하지 않고 비활성화합니다. 다른 활성화된 플러그인이 대상에 [종속되어](/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 있으면 실패합니다. 오류 메시지에는 먼저 모든 종속 플러그인을 비활성화하는 연쇄 명령어가 포함됩니다.1078플러그인을 제거하지 않고 비활성화합니다. 다른 활성화된 플러그인이 대상에 [종속되어](/docs/ko/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 있으면 실패합니다. 오류 메시지에는 먼저 모든 종속 플러그인을 비활성화하는 연쇄 명령어가 포함됩니다.

1079 1079

1080```bash theme={null}1080```bash theme={null}

1081claude plugin disable <plugin> [options]1081claude plugin disable <plugin> [options]

1192 plugin tag1192 plugin tag

1193</h3>1193</h3>

1194 1194

1195현재 디렉토리의 플러그인에 대한 릴리스 git 태그를 생성합니다. 플러그인의 폴더 내에서 실행하세요. [플러그인 릴리스 태그 지정](/ko/plugin-dependencies#tag-plugin-releases-for-version-resolution)을 참조하세요.1195현재 디렉토리의 플러그인에 대한 릴리스 git 태그를 생성합니다. 플러그인의 폴더 내에서 실행하세요. [플러그인 릴리스 태그 지정](/docs/ko/plugin-dependencies#tag-plugin-releases-for-version-resolution)을 참조하세요.

1196 1196

1197```bash theme={null}1197```bash theme={null}

1198claude plugin tag [options]1198claude plugin tag [options]

1352 참고 항목1352 참고 항목

1353</h2>1353</h2>

1354 1354

1355* [플러그인](/ko/plugins) - 튜토리얼 및 실제 사용1355* [플러그인](/docs/ko/plugins) - 튜토리얼 및 실제 사용

1356* [플러그인 마켓플레이스](/ko/plugin-marketplaces) - 마켓플레이스 생성 및 관리1356* [플러그인 마켓플레이스](/docs/ko/plugin-marketplaces) - 마켓플레이스 생성 및 관리

1357* [Skills](/ko/skills) - Skill 개발 세부 정보1357* [Skills](/docs/ko/skills) - Skill 개발 세부 정보

1358* [Subagents](/ko/sub-agents) - Agent 구성 및 기능1358* [Subagents](/docs/ko/sub-agents) - Agent 구성 및 기능

1359* [Hooks](/ko/hooks) - 이벤트 처리 및 자동화1359* [Hooks](/docs/ko/hooks) - 이벤트 처리 및 자동화

1360* [MCP](/ko/mcp) - 외부 도구 통합1360* [MCP](/docs/ko/mcp) - 외부 도구 통합

1361* [설정](/ko/settings) - 플러그인의 구성 옵션1361* [설정](/docs/ko/settings) - 플러그인의 구성 옵션

troubleshooting.md +18 −14

Details

10 10

11| 증상 | 이동 |11| 증상 | 이동 |

12| :---------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |12| :---------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

14| `The connection dropped while downloading the update` 또는 `aborted`로 업데이트 또는 설치 다운로드 실패 | [오류 참조](/ko/errors#the-connection-dropped-while-downloading-the-update) |14| `The connection dropped while downloading the update` 또는 `aborted`로 업데이트 또는 설치 다운로드 실패 | [오류 참조](/docs/ko/errors#the-connection-dropped-while-downloading-the-update) |

15| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명 | [설치 및 로그인 문제 해결](/ko/troubleshoot-install#login-and-authentication) |15| 로그인 루프, OAuth 오류, `403 Forbidden`, "organization disabled", Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry 자격 증명 | [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install#login-and-authentication) |

16| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/ko/debug-your-config) |16| 설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음 | [구성 디버깅](/docs/ko/debug-your-config) |

19| VS Code 확장이 Claude에 연결되지 않거나 감지하지 못함 | [VS Code 통합](/ko/vs-code#fix-common-issues) |19| VS Code 확장이 Claude에 연결되지 않거나 감지하지 못함 | [VS Code 통합](/docs/ko/vs-code#fix-common-issues) |

20| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/ko/jetbrains#troubleshooting) |20| JetBrains 플러그인 또는 IDE가 감지되지 않음 | [JetBrains 통합](/docs/ko/jetbrains#troubleshooting) |

21| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |21| 높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함 | [성능 및 안정성](#performance-and-stability) 아래 |

22 22

23어떤 것이 적용되는지 확실하지 않으면 Claude Code 내에서 `/doctor`를 실행하여 설치, 설정, 확장 및 컨텍스트 사용을 자동으로 확인하세요. 이 도구는 확인 후 적용할 수 있는 수정 사항을 제안합니다. `claude`가 전혀 시작되지 않으면 셸에서 `claude doctor`를 대신 실행하세요. `/mcp`를 실행하여 MCP 서버 상태를 확인하세요.23어떤 것이 적용되는지 확실하지 않으면 Claude Code 내에서 `/doctor`를 실행하여 설치, 설정, 확장 및 컨텍스트 사용을 자동으로 확인하세요. 이 도구는 확인 후 적용할 수 있는 수정 사항을 제안합니다. `claude`가 전혀 시작되지 않으면 셸에서 `claude doctor`를 대신 실행하세요. `/mcp`를 실행하여 MCP 서버 상태를 확인하세요.

371. `/compact`를 정기적으로 사용하여 컨텍스트 크기 감소371. `/compact`를 정기적으로 사용하여 컨텍스트 크기 감소

382. 주요 작업 사이에 Claude Code 닫기 및 다시 시작382. 주요 작업 사이에 Claude Code 닫기 및 다시 시작

393. 큰 빌드 디렉토리를 `.gitignore` 파일에 추가하는 것을 고려하세요393. 큰 빌드 디렉토리를 `.gitignore` 파일에 추가하는 것을 고려하세요

404. [`claude --safe-mode`](/ko/cli-reference#cli-flags)로 다시 시작하여 플러그인, MCP 서버 또는 hook이 원인인지 확인하세요. 이는 세션의 모든 사용자 정의를 비활성화합니다. 사용량이 감소하면 [구성 디버깅](/ko/debug-your-config#test-against-a-clean-configuration)을 참조하여 어느 것이 원인인지 찾으세요404. [`claude --safe-mode`](/docs/ko/cli-reference#cli-flags)로 다시 시작하여 플러그인, MCP 서버 또는 hook이 원인인지 확인하세요. 이는 세션의 모든 사용자 정의를 비활성화합니다. 사용량이 감소하면 [구성 디버깅](/docs/ko/debug-your-config#test-against-a-clean-configuration)을 참조하여 어느 것이 원인인지 찾으세요

41 41

42메모리 사용량이 이 단계 후에도 높게 유지되면 `/heapdump`를 실행하여 JavaScript 힙 스냅샷과 메모리 분석을 `~/Desktop`에 작성하세요. Linux에 Desktop 폴더가 없으면 파일이 홈 디렉토리에 작성됩니다.42메모리 사용량이 이 단계 후에도 높게 유지되면 `/heapdump`를 실행하여 JavaScript 힙 스냅샷과 메모리 분석을 `~/Desktop`에 작성하세요. Linux에 Desktop 폴더가 없으면 파일이 홈 디렉토리에 작성됩니다.

43 43

44분석은 상주 집합 크기, JS 힙, 배열 버퍼 및 설명되지 않은 네이티브 메모리를 표시하며, 이는 증가가 JavaScript 객체인지 네이티브 코드인지 식별하는 데 도움이 됩니다. Chrome DevTools의 메모리 → 로드에서 `.heapsnapshot` 파일을 열어 보유자를 검사하세요. [GitHub](https://github.com/anthropics/claude-code/issues)에서 메모리 문제를 보고할 때 두 파일을 모두 첨부하세요.44분석은 상주 집합 크기, JS 힙, 배열 버퍼 및 설명되지 않은 네이티브 메모리를 표시하므로, 증가가 JavaScript 객체에 있는지 네이티브 코드에 있는지 식별하는 데 도움이 됩니다. 보유자를 검사하려면 Chrome DevTools의 Memory → Load에서 `.heapsnapshot` 파일을 열면 됩니다. 분석은 `-diagnostics.json`으로 끝나는 파일입니다.

46<Warning>

47 `.heapsnapshot` 파일에는 프로세스의 모든 문자열이 포함됩니다. 공개 이슈에 첨부하거나 공유하지 마십시오. 메모리 문제를 [GitHub](https://github.com/anthropics/claude-code/issues)에 보고할 때는 `-diagnostics.json` 파일만 첨부하십시오. 이 파일에는 메모리 통계가 포함되어 있으며 대화 내용이나 자격 증명은 포함되지 않습니다.

48</Warning>

45 49

46<h3 id="large-tables-are-cut-off-in-the-terminal">50<h3 id="large-tables-are-cut-off-in-the-terminal">

47 터미널에서 큰 테이블이 잘림51 터미널에서 큰 테이블이 잘림

48</h3>52</h3>

49 53

50200개 이상의 행이 있는 Markdown 테이블은 처음 200개 행을 렌더링한 후 `… N more rows not shown` 줄을 표시합니다. 표시만 제한됩니다. 전체 테이블은 대화에 남아 있으며 [`/copy`](/ko/commands)는 모든 행을 복사합니다. 터미널에서 읽기에 너무 큰 테이블의 경우 Claude에게 대신 파일에 작성하도록 요청하세요. v2.1.208 이전에는 Claude Code가 모든 행을 렌더링했으므로 매우 큰 테이블이 포함된 세션을 다시 시작하면 다시 렌더링하는 동안 중단될 수 있었습니다.54200개 이상의 행이 있는 Markdown 테이블은 처음 200개 행을 렌더링한 후 `… N more rows not shown` 줄을 표시합니다. 표시만 제한됩니다. 전체 테이블은 대화에 남아 있으며 [`/copy`](/docs/ko/commands)는 모든 행을 복사합니다. 터미널에서 읽기에 너무 큰 테이블의 경우 Claude에게 대신 파일에 작성하도록 요청하세요. v2.1.208 이전에는 Claude Code가 모든 행을 렌더링했으므로 매우 큰 테이블이 포함된 세션을 다시 시작하면 다시 렌더링하는 동안 중단될 수 있었습니다.

51 55

52<h3 id="auto-compaction-stops-with-a-thrashing-error">56<h3 id="auto-compaction-stops-with-a-thrashing-error">

53 자동 압축이 스래싱 오류로 중단됨57 자동 압축이 스래싱 오류로 중단됨

59 63

601. Claude에게 전체 파일 대신 특정 줄 범위 또는 함수와 같은 더 작은 청크로 큰 파일을 읽도록 요청하세요641. Claude에게 전체 파일 대신 특정 줄 범위 또는 함수와 같은 더 작은 청크로 큰 파일을 읽도록 요청하세요

612. 큰 출력을 삭제하는 포커스로 `/compact`를 실행하세요. 예: `/compact keep only the plan and the diff`652. 큰 출력을 삭제하는 포커스로 `/compact`를 실행하세요. 예: `/compact keep only the plan and the diff`

~~623. 큰 파일 작업을 [서브에이전트](/ko/sub-agents)로 이동하여 별도의 컨텍스트 창에서 실행하세요~~663. 큰 파일 작업을 [서브에이전트](/docs/ko/sub-agents)로 이동하여 별도의 컨텍스트 창에서 실행하세요

634. 이전 대화가 더 이상 필요하지 않으면 `/clear`를 실행하세요674. 이전 대화가 더 이상 필요하지 않으면 `/clear`를 실행하세요

64 68

65<h3 id="command-hangs-or-freezes">69<h3 id="command-hangs-or-freezes">

77 편집기의 통합 터미널에서 손상되거나 깨진 텍스트81 편집기의 통합 터미널에서 손상되거나 깨진 텍스트

78</h3>82</h3>

79 83

80VS Code, Cursor 또는 Devin Desktop 통합 터미널에서 Claude Code를 실행할 때 문자가 상자, 얼룩 또는 잘못된 글리프로 렌더링되면 터미널의 GPU 렌더러가 원인일 가능성이 높습니다. Claude Code 내에서 `/terminal-setup`을 실행하여 `terminal.integrated.gpuAcceleration`을 `"off"`로 설정하거나 편집기 설정에서 수동으로 설정하고 창을 다시 로드하세요. `/terminal-setup`이 작성하는 다른 설정에 대해서는 [터미널 구성](/ko/terminal-config)을 참조하세요.84VS Code, Cursor 또는 Devin Desktop 통합 터미널에서 Claude Code를 실행할 때 문자가 상자, 얼룩 또는 잘못된 글리프로 렌더링되면 터미널의 GPU 렌더러가 원인일 가능성이 높습니다. Claude Code 내에서 `/terminal-setup`을 실행하여 `terminal.integrated.gpuAcceleration`을 `"off"`로 설정하거나 편집기 설정에서 수동으로 설정하고 창을 다시 로드하세요. `/terminal-setup`이 작성하는 다른 설정에 대해서는 [터미널 구성](/docs/ko/terminal-config)을 참조하세요.

81 85

82<h3 id="search-and-discovery-issues">86<h3 id="search-and-discovery-issues">

83 검색 및 발견 문제87 검색 및 발견 문제

117 </Tab>121 </Tab>

118</Tabs>122</Tabs>

119 123

120그런 다음 [환경](/ko/env-vars)에서 `USE_BUILTIN_RIPGREP=0`을 설정하세요.124그런 다음 [환경](/docs/ko/env-vars)에서 `USE_BUILTIN_RIPGREP=0`을 설정하세요.

121 125

122<h3 id="slow-or-incomplete-search-results-on-wsl">126<h3 id="slow-or-incomplete-search-results-on-wsl">

123 WSL에서 느리거나 불완전한 검색 결과127 WSL에서 느리거나 불완전한 검색 결과

Documentation 2026-07-20 23:01 UTC to 2026-07-21 23:00 UTC