구성 디버깅하기
CLAUDE.md, 설정, 훅, MCP 서버 또는 스킬이 적용되지 않는 이유를 진단합니다. /context, /doctor, /hooks, /mcp를 사용하여 실제로 로드된 항목을 확인합니다.
Claude가 명령을 무시하거나 구성한 기능이 나타나지 않을 때, 원인은 보통 파일이 로드되지 않았거나, 예상과 다른 위치에서 로드되었거나, 다른 파일이 이를 재정의했기 때문입니다. 이 가이드는 Claude Code가 실제로 로드한 항목을 검사하여 어느 경우에 해당하는지 좁혀나가는 방법을 보여줍니다.
설치, 인증 및 연결 문제의 경우 대신 문제 해결을 참조하십시오.
컨텍스트에 로드된 항목 확인
/context 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 CLAUDE.md, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다.
특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:
| 명령 | 표시 내용 |
|---|---|
/memory |
로드된 CLAUDE.md 및 규칙 파일, 자동 메모리 항목 |
/skills |
프로젝트, 사용자 및 플러그인 소스의 사용 가능한 스킬 |
/agents |
구성된 서브에이전트 및 해당 설정 |
/hooks |
활성 훅 구성 |
/mcp |
연결된 MCP 서버 및 해당 상태 |
/permissions |
현재 적용 중인 허용 및 거부 규칙 |
/doctor |
구성 진단: 잘못된 키, 스키마 오류, 설치 상태 |
/status |
활성 설정 소스, 관리 설정이 적용 중인지 여부 포함 |
메모리 파일이 /memory에서 누락된 경우, CLAUDE.md 파일이 로드되는 방식에 대해 해당 위치를 확인합니다. 하위 디렉토리 CLAUDE.md 파일은 Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 요청 시 로드되며, 세션 시작 시가 아닙니다.
/memory가 파일이 로드되었음을 확인했지만 Claude가 여전히 특정 명령을 따르지 않는 경우, 문제는 파일이 로드되었는지 여부가 아니라 명령이 작성된 방식일 가능성이 높습니다. CLAUDE.md는 새로운 팀원에게 제공할 지침(예: 프로젝트 규칙, 빌드 명령 및 파일 위치)에 적합합니다.
명령이 여러 방식으로 해석될 수 있을 정도로 모호할 때, 두 파일이 상충하는 지시를 제공할 때, 또는 파일이 충분히 길어서 개별 규칙이 덜 주목받을 때 준수가 감소합니다. 효과적인 명령 작성은 준수를 높게 유지하는 특이성, 크기 및 구조 패턴을 다룹니다.
해결된 설정 확인
설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 환경 변수로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다.
/doctor를 실행하여 구성 파일을 검증하고 잘못된 키 또는 스키마 오류를 표시합니다. /status를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 어느 범위가 우선하는지 이해하려면 범위가 상호작용하는 방식을 참조합니다.
MCP 서버 확인
/mcp를 실행하여 모든 구성된 서버, 해당 연결 상태 및 현재 프로젝트에 대해 승인했는지 여부를 확인합니다. 서버가 올바르게 정의되었지만 여전히 몇 가지 일반적인 이유로 도구를 제공하지 않을 수 있습니다:
.mcp.json의 프로젝트 범위 서버는 일회성 승인이 필요합니다. 프롬프트가 해제된 경우, 서버는/mcp에서 승인할 때까지 비활성화된 상태로 유지됩니다.- 시작에 실패한 서버는
/mcp에서 실패로 표시됩니다.command또는args의 상대 파일 경로는.mcp.json의 위치가 아니라 Claude Code를 시작한 디렉토리에 대해 해석되므로 빈번한 원인입니다. - 연결된 것으로 표시되지만 도구가 0개인 서버는 성공적으로 시작되었지만 도구 목록을 반환하지 않습니다.
/mcp에서 다시 연결을 선택합니다. 개수가 0으로 유지되면claude --debug mcp를 실행하여 서버의 stderr 출력을 확인합니다.
구성 위치 및 범위 규칙은 MCP를 참조합니다.
훅 확인
/hooks를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 읽혀지지 않는 것입니다: 훅은 독립 실행형 파일이 아니라 설정 파일의 "hooks" 키 아래에 있습니다.
훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. matcher 필드는 여러 도구 이름을 일치시키기 위해 |를 사용하는 단일 문자열입니다(예: "Edit|Write"). 잘못된 도구 이름은 매처가 일치하지 않기 때문에 자동으로 실패합니다. 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고, /doctor는 검증 실패를 보고하며, 훅 항목은 /hooks에 나타나지 않도록 삭제됩니다.
settings.json에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 /hooks가 여전히 이전 정의를 표시하면 /hooks를 다시 실행하여 보기를 새로 고칩니다.
/hooks가 훅을 표시하지만 여전히 실행되지 않으면, 다음 단계는 훅 평가를 실시간으로 감시하는 것입니다. claude --debug hooks로 세션을 시작하고 도구 호출을 트리거합니다. 디버그 로그는 각 이벤트, 확인된 매처 및 훅의 종료 코드와 출력을 기록합니다. 로그 형식은 훅 디버깅을 참조하고 일반적인 실패 패턴은 훅 문제 해결을 참조합니다.
일반적인 원인
대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다:
| 증상 | 원인 | 해결 |
|---|---|---|
| 훅이 절대 실행되지 않음 | matcher가 문자열 대신 JSON 배열입니다 |
여러 도구를 일치시키기 위해 |를 사용하는 단일 문자열을 사용합니다(예: "Edit|Write"). 매처 패턴을 참조합니다. |
| 훅이 절대 실행되지 않음 | matcher 값이 소문자입니다(예: "bash") |
일치는 대소문자를 구분합니다. 도구 이름은 대문자입니다: Bash, Edit, Write, Read. |
| 훅이 절대 실행되지 않음 | 훅이 독립 실행형 .claude/hooks.json 파일에 있습니다 |
독립 실행형 훅 파일이 없습니다. settings.json의 "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을 재정의합니다. 설정 우선순위를 참조합니다. |
스킬이 /skills에 나타나지 않습니다 |
스킬 파일이 폴더 대신 .claude/skills/name.md에 있습니다 |
내부에 SKILL.md가 있는 폴더를 사용합니다: .claude/skills/name/SKILL.md. |
스킬이 /skills에 나타나지만 Claude가 절대 호출하지 않습니다 |
스킬의 프론트매터에 disable-model-invocation: true가 있거나, 해당 설명이 요청을 표현하는 방식과 일치하지 않습니다 |
/skills의 배지를 확인합니다: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. 스킬 호출을 참조합니다. |
하위 디렉토리 CLAUDE.md 명령이 무시되는 것처럼 보입니다 |
하위 디렉토리 파일은 세션 시작 시가 아니라 요청 시 로드됩니다 | Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 로드되며, 시작 시가 아니고 파일을 작성하거나 생성할 때도 아닙니다. CLAUDE.md 파일이 로드되는 방식을 참조합니다. |
서브에이전트가 CLAUDE.md 명령을 무시합니다 |
서브에이전트는 항상 프로젝트 메모리를 상속하지 않습니다 | 중요한 규칙을 에이전트 파일 본문에 넣습니다. 이는 서브에이전트의 시스템 프롬프트가 됩니다. 서브에이전트 구성을 참조합니다. |
| 정리 로직이 세션 종료 시 절대 실행되지 않습니다 | SessionEnd 훅이 구성되지 않았습니다 |
settings.json에 SessionEnd 훅을 추가합니다. 훅 이벤트 목록을 참조합니다. |
.mcp.json의 MCP 서버가 절대 로드되지 않습니다 |
파일이 .claude/ 아래에 있거나 Claude Desktop의 구성 형식을 사용합니다 |
프로젝트 MCP 구성은 .claude/ 내부가 아니라 저장소 루트에 .mcp.json으로 이동합니다. MCP 구성을 참조합니다. |
| 프로젝트 MCP 서버가 추가되었지만 나타나지 않습니다 | 일회성 승인 프롬프트가 해제되었습니다 | 프로젝트 범위 서버는 승인이 필요합니다. /mcp를 실행하여 상태를 확인하고 승인합니다. |
| MCP 서버가 일부 디렉토리에서 시작하지 못합니다 | command 또는 args가 상대 파일 경로를 사용합니다 |
로컬 스크립트에 절대 경로를 사용합니다. npx 또는 uvx와 같은 PATH의 실행 파일은 그대로 작동합니다. |
| MCP 서버가 예상 환경 변수 없이 시작됩니다 | 변수가 settings.json env에 있으며, MCP 자식 프로세스로 전파되지 않습니다 |
대신 .mcp.json 내부에 서버별 env를 설정합니다. |
Bash(rm *) 거부 규칙이 /bin/rm 또는 find -delete를 차단하지 않습니다 |
접두사 규칙은 기본 실행 파일이 아니라 리터럴 명령 문자열과 일치합니다 | 각 변형에 대해 명시적 패턴을 추가하거나, PreToolUse 훅 또는 샌드박스를 사용하여 하드 보장을 얻습니다. |
관련 리소스
각 구성 표면에 대한 전체 참조는 전용 페이지를 참조합니다:
.claude디렉토리 참조: 모든 구성 파일 위치 및 읽는 항목- 설정: 우선순위 순서 및 전체 키 목록
- 훅 참조: 이벤트 이름, 페이로드 및
--debug hooks출력 형식 - MCP: 서버 구성, 승인 및
/mcp출력 - 설치 및 로그인 문제 해결:
command not found, PATH 및 인증 문제 - 문제 해결: 성능, 응답 중단 및 검색 문제