> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 구성 디버깅하기 > CLAUDE.md, 설정, 훅, MCP 서버 또는 스킬이 적용되지 않는 이유를 진단합니다. /context, /doctor, /hooks, /mcp를 사용하여 실제로 로드된 항목을 확인합니다. Claude가 명령을 무시하거나 구성한 기능이 나타나지 않을 때, 원인은 보통 파일이 로드되지 않았거나, 예상과 다른 위치에서 로드되었거나, 다른 파일이 이를 재정의했기 때문입니다. 이 가이드는 Claude Code가 실제로 로드한 항목을 검사하여 어느 경우에 해당하는지 좁혀나가는 방법을 보여줍니다. 설치, 인증 및 연결 문제의 경우 대신 [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)을 참조하십시오.

컨텍스트에 로드된 항목 확인

`/context` 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, 사용자 정의 서브에이전트(로드된 소스 포함), MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 `CLAUDE.md`, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다. 특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다: | 명령 | 표시 내용 | | :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `/memory` | 로드된 `CLAUDE.md` 및 규칙 파일, 자동 메모리 항목 | | `/skills` | 프로젝트, 사용자 및 플러그인 소스의 사용 가능한 스킬 | | `/hooks` | 활성 훅 구성 | | `/mcp` | 연결된 MCP 서버 및 해당 상태 | | `/permissions` | 현재 적용 중인 허용 및 거부 규칙 | | `/doctor` | 설정 점검: 설치 상태, 잘못된 설정 파일, 사용하지 않는 확장 프로그램, 동일한 디렉토리의 중복 [서브에이전트](/docs/ko/sub-agents) 이름 및 Claude가 코드베이스에서 파생할 수 있는 체크인된 `CLAUDE.md` 콘텐츠(제안된 수정 사항 포함) | | `/debug [issue]` | 세션에 대해 디버그 로깅을 활성화하고 Claude가 로그 출력 및 설정 경로를 사용하여 진단하도록 프롬프트합니다 | | `/status` | 활성 설정 소스, 관리 설정이 적용 중인지 여부 포함 | 메모리 파일이 `/memory`에서 누락된 경우, [CLAUDE.md 파일이 로드되는 방식](/docs/ko/memory#how-claude-md-files-load)에 대해 해당 위치를 확인합니다. 하위 디렉토리 `CLAUDE.md` 파일은 Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 요청 시 로드되며, 세션 시작 시가 아닙니다. `/memory`가 파일이 로드되었음을 확인했지만 Claude가 여전히 특정 명령을 따르지 않는 경우, 문제는 파일이 로드되었는지 여부가 아니라 명령이 작성된 방식일 가능성이 높습니다. CLAUDE.md는 새로운 팀원에게 제공할 지침(예: 프로젝트 규칙, 빌드 명령 및 파일 위치)에 적합합니다. 명령이 여러 방식으로 해석될 수 있을 정도로 모호할 때, 두 파일이 상충하는 지시를 제공할 때, 또는 파일이 충분히 길어서 개별 규칙이 덜 주목받을 때 준수가 감소합니다. [효과적인 명령 작성](/docs/ko/memory#write-effective-instructions)은 준수를 높게 유지하는 특이성, 크기 및 구조 패턴을 다룹니다. CLAUDE.md와 권한은 서로 다른 문제를 해결합니다. CLAUDE.md는 Claude에게 프로젝트가 어떻게 작동하는지 알려주어 좋은 결정을 내리도록 합니다. [권한](/docs/ko/permissions) 및 [훅](/docs/ko/hooks)은 Claude가 무엇을 결정하든 제한을 강제합니다. CLAUDE.md는 "우리는 여기서 이렇게 합니다"에 사용합니다. 권한 또는 훅은 보안 경계 및 절대 발생해서는 안 되는 모든 것에 사용하며, 지침 대신 보장이 필요합니다.

해결된 설정 확인

설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 [환경 변수](/docs/ko/env-vars)로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다. `/doctor`를 실행하여 구성 및 설치를 확인합니다. 이는 잘못된 설정 파일, 중복 설치 및 사용하지 않는 확장 프로그램을 포함하여 발견한 내용을 보고한 다음, {/* min-version: 2.1.206 */}체크인된 `CLAUDE.md` 콘텐츠 Claude가 코드베이스에서 파생할 수 있는 내용을 확인하고, 사용자가 확인한 후에만 적용하는 수정 사항을 제안합니다. `CLAUDE.md` 트림 확인은 Claude Code v2.1.206 이상이 필요합니다. v2.1.205 이전에는 `/doctor`가 읽기 전용 진단 화면을 열었고 `f`를 누르면 보고서를 Claude에게 보내 수정하도록 했습니다. 터미널에서 `claude doctor`는 세션을 시작하지 않고 읽기 전용 설치 및 설정 진단을 출력합니다. `/status`를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 어느 범위가 우선하는지 이해하려면 [범위가 상호작용하는 방식](/docs/ko/settings#how-scopes-interact)을 참조합니다.

MCP 서버 확인

`/mcp`를 실행하여 모든 구성된 서버, 해당 연결 상태 및 현재 프로젝트에 대해 승인했는지 여부를 확인합니다. 서버가 올바르게 정의되었지만 여전히 몇 가지 일반적인 이유로 도구를 제공하지 않을 수 있습니다: * `.mcp.json`의 프로젝트 범위 서버는 일회성 승인이 필요합니다. 프롬프트가 해제된 경우, 서버는 `/mcp`에서 승인할 때까지 비활성화된 상태로 유지됩니다. * 시작에 실패한 서버는 `/mcp`에서 실패로 표시됩니다. `command` 또는 `args`의 상대 파일 경로는 `.mcp.json`의 위치가 아니라 Claude Code를 시작한 디렉토리에 대해 해석되므로 빈번한 원인입니다. * 연결된 것으로 표시되지만 도구가 0개인 서버는 성공적으로 시작되었지만 도구 목록을 반환하지 않습니다. `/mcp`에서 **다시 연결**을 선택합니다. 개수가 0으로 유지되면 `claude --debug mcp`를 실행하여 서버의 stderr 출력을 확인합니다. 구성 위치 및 범위 규칙은 [MCP](/docs/ko/mcp)를 참조합니다.

훅 확인

`/hooks`를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 읽혀지지 않는 것입니다: 훅은 독립 실행형 파일이 아니라 설정 파일의 `"hooks"` 키 아래에 있습니다. 훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오: * `matcher` 필드는 여러 도구 이름을 일치시키기 위해 `|`를 사용하는 단일 문자열입니다(예: `"Edit|Write"`). {/* min-version: 2.1.191 */}`,` 구분 기호는 동등하므로 `"Edit,Write"`는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 `|`를 사용하십시오. * 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다. * 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고 전체 사용자, 프로젝트 또는 로컬 설정 파일을 거부하며, `claude doctor`는 검증 실패를 보고하고, 해당 파일의 훅이 `/hooks`에 나타나지 않습니다. [관리되는 설정](/docs/ko/settings#settings-files)에서는 유효하지 않은 항목만 제거되고 파일의 다른 훅은 계속 적용됩니다. `settings.json`에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 `/hooks`가 여전히 이전 정의를 표시하면 `/hooks`를 다시 실행하여 보기를 새로 고칩니다. `/hooks`가 훅을 표시하지만 여전히 실행되지 않으면, 다음 단계는 훅 평가를 실시간으로 감시하는 것입니다. `claude --debug hooks`로 세션을 시작하고 도구 호출을 트리거합니다. 디버그 로그는 각 이벤트, 확인된 매처 및 훅의 종료 코드와 출력을 기록합니다. 로그 형식은 [훅 디버깅](/docs/ko/hooks#debug-hooks)을 참조하고 일반적인 실패 패턴은 [훅 문제 해결](/docs/ko/hooks-guide#limitations-and-troubleshooting)을 참조합니다.

깨끗한 구성에 대해 테스트

{/* min-version: 2.1.169 */}[`claude --safe-mode`](/docs/ko/cli-reference#cli-flags)로 시작합니다. 이는 `CLAUDE.md`, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 안전 모드는 여전히 조직에서 배포한 관리 훅 및 설정 정책을 적용합니다. 관리 플러그인, 스킬, `CLAUDE.md` 및 MCP 서버는 꺼집니다. 안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 빈 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다. ```bash theme={null} cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude ``` 깨끗한 세션에는 사용자 또는 프로젝트 설정, 훅, MCP 서버, 플러그인 또는 메모리가 없습니다. * 조직이 배포하는 경우 관리 설정은 여전히 적용됩니다. 이들은 `~/.claude` 외부의 시스템 경로에 있기 때문입니다. * Linux 및 Windows에서는 자격 증명이 구성 디렉토리 아래에 저장되므로 다시 로그인하라는 메시지가 표시됩니다. * macOS에서는 자격 증명이 Keychain에 있으며 깨끗한 세션으로 이월됩니다. 문제가 여기서 사라지면, 원인은 실제 `~/.claude` 또는 프로젝트 `.claude` 파일 어딘가에 있습니다. 임시 디렉토리에 파일을 복사하거나 프로젝트에서 시작하여 한 번에 하나씩 다시 도입하여 어느 것인지 찾습니다. 깨끗한 세션에서 지속되면, 원인은 사용자 및 프로젝트 구성 외부에 있습니다. `/status`를 실행하여 관리 설정이 적용 중인지 확인하고, Claude Code에 영향을 미치는 [환경 변수](/docs/ko/env-vars)를 찾은 다음, [문제 해결](/docs/ko/troubleshooting)을 참조합니다.

일반적인 원인 확인

대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다: | 증상 | 원인 | 해결 | | :--------------------------------------------------------- | :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 훅이 절대 실행되지 않음 | `matcher`가 문자열 대신 JSON 배열입니다 | 여러 도구를 일치시키기 위해 `\|`를 사용하는 단일 문자열을 사용합니다(예: `"Edit\|Write"`). [매처 패턴](/docs/ko/hooks#matcher-patterns)을 참조합니다. | | 훅이 절대 실행되지 않음 | `matcher`가 v2.1.191 이전 버전에서 구분 기호로 `,`를 사용합니다 | {/* min-version: 2.1.191 */}Claude Code v2.1.191 이상은 `,`를 `\|`와 같은 목록 구분 기호로 처리합니다. 이전 버전은 쉼표를 리터럴 문자로 평가하므로 `"Edit,Write"`는 아무것도 일치하지 않습니다. 대신 `\|`를 사용하거나 Claude Code를 업그레이드합니다. | | 훅이 절대 실행되지 않음 | `matcher` 값이 소문자입니다(예: `"bash"`) | 일치는 대소문자를 구분합니다. 도구 이름은 대문자입니다: `Bash`, `Edit`, `Write`, `Read`. | | 훅이 절대 실행되지 않음 | 훅이 `settings.json` 대신 독립 실행형 파일에 정의되어 있습니다 | 프로젝트 또는 사용자 구성에 대한 독립 실행형 훅 파일이 없습니다. `settings.json`의 `"hooks"` 키 아래에 훅을 정의합니다. [플러그인](/docs/ko/plugins-reference#hooks)만 별도의 `hooks/hooks.json`을 로드합니다. [훅 구성](/docs/ko/hooks)을 참조합니다. | | 전역으로 설정된 권한, 훅 또는 env가 무시됩니다 | 구성이 `~/.claude.json`에 추가되었습니다 | `~/.claude.json`은 앱 상태 및 UI 토글을 보유합니다. `permissions`, `hooks` 및 `env`는 `~/.claude/settings.json`에 속합니다. 이는 두 개의 다른 파일입니다. | | `settings.json` 값이 무시되는 것처럼 보입니다 | 동일한 키가 `settings.local.json`에 설정되어 있습니다 | `settings.local.json`은 `settings.json`을 재정의하고, 둘 다 `~/.claude/settings.json`을 재정의합니다. [설정 우선순위](/docs/ko/settings#how-scopes-interact)를 참조합니다. | | 스킬이 `/skills`에 나타나지 않습니다 | 스킬 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 내부에 `SKILL.md`가 있는 폴더를 사용합니다: `.claude/skills/name/SKILL.md`. | | 스킬이 `/skills`에 나타나지만 Claude가 절대 호출하지 않습니다 | 스킬의 프론트매터에 `disable-model-invocation: true`가 있거나, 해당 설명이 요청을 표현하는 방식과 일치하지 않습니다 | `/skills`의 배지를 확인합니다: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. [스킬 호출](/docs/ko/skills)을 참조합니다. | | 하위 디렉토리 `CLAUDE.md` 명령이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 요청 시 로드됩니다 | Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 로드되며, 시작 시가 아니고 파일을 작성하거나 생성할 때도 아닙니다. [CLAUDE.md 파일이 로드되는 방식](/docs/ko/memory#how-claude-md-files-load)을 참조합니다. | | 서브에이전트가 `CLAUDE.md` 명령을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 `CLAUDE.md`를 건너뜁니다. 사용자 정의 서브에이전트는 주 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우, 위임 프롬프트에서 명령을 다시 명시합니다. 사용자 정의 서브에이전트의 경우, 중요한 명령을 에이전트 파일 본문에 넣습니다. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/docs/ko/sub-agents#what-loads-at-startup)을 참조합니다. | | 정리 로직이 세션 종료 시 절대 실행되지 않습니다 | `SessionEnd` 훅이 구성되지 않았습니다 | `settings.json`에 `SessionEnd` 훅을 추가합니다. [훅 이벤트 목록](/docs/ko/hooks#hook-events)을 참조합니다. | | `.mcp.json`의 MCP 서버가 절대 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나 Claude Desktop의 구성 형식을 사용합니다 | 프로젝트 MCP 구성은 `.claude/` 내부가 아니라 저장소 루트에 `.mcp.json`으로 이동합니다. [MCP 구성](/docs/ko/mcp)을 참조합니다. | | `settings.json`의 `mcpServers` 아래에 추가된 MCP 서버가 절대 나타나지 않습니다 | `settings.json`은 `mcpServers` 키를 읽지 않습니다 | 저장소 루트의 `.mcp.json`에서 프로젝트 서버를 정의하거나, 사용자 범위 서버의 경우 `claude mcp add --scope user`를 실행합니다. [MCP 구성](/docs/ko/mcp)을 참조합니다. | | 프로젝트 MCP 서버가 추가되었지만 나타나지 않습니다 | 일회성 승인 프롬프트가 해제되었습니다 | 프로젝트 범위 서버는 승인이 필요합니다. `/mcp`를 실행하여 상태를 확인하고 승인합니다. | | MCP 서버가 일부 디렉토리에서 시작하지 못합니다 | `command` 또는 `args`가 상대 파일 경로를 사용합니다 | 로컬 스크립트에 절대 경로를 사용합니다. `npx` 또는 `uvx`와 같은 `PATH`의 실행 파일은 그대로 작동합니다. | | MCP 서버가 예상 환경 변수 없이 시작됩니다 | 변수가 `settings.json` `env`에 있으며, MCP 자식 프로세스로 전파되지 않습니다 | 대신 `.mcp.json` 내부에 서버별 `env`를 설정합니다. | | `Bash(rm *)` 거부 규칙이 `/bin/rm` 또는 `find -delete`를 차단하지 않습니다 | 접두사 규칙은 기본 실행 파일이 아니라 리터럴 명령 문자열과 일치합니다 | 각 변형에 대해 명시적 패턴을 추가하거나, [PreToolUse 훅](/docs/ko/hooks-guide) 또는 [샌드박스](/docs/ko/sandboxing)를 사용하여 하드 보장을 얻습니다. | 각 구성 표면에 대한 전체 참조는 전용 페이지를 참조합니다: * **[`.claude` 디렉토리 참조](/docs/ko/claude-directory)**: 모든 구성 파일 위치 및 읽는 항목 * **[설정](/docs/ko/settings)**: 우선순위 순서 및 전체 키 목록 * **[훅 참조](/docs/ko/hooks)**: 이벤트 이름, 페이로드 및 `--debug hooks` 출력 형식 * **[MCP](/docs/ko/mcp)**: 서버 구성, 승인 및 `/mcp` 출력 * **[설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)**: `command not found`, PATH 및 인증 문제 * **[문제 해결](/docs/ko/troubleshooting)**: 성능, 응답 중단 및 검색 문제