SpyBara
Go Premium

debug-your-config.md 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

33 added, 33 removed.

2026
Wed 5 19:57 Tue 4 22:59 Mon 3 20:02 Sun 2 19:00

구성 디버깅하기

CLAUDE.md, 설정, 훅, MCP 서버 또는 스킬이 적용되지 않는 이유를 진단합니다. /context, /doctor, /hooks, /mcp를 사용하여 실제로 로드된 항목을 확인합니다.

Claude가 명령을 무시하거나 구성한 기능이 나타나지 않을 때, 원인은 보통 파일이 로드되지 않았거나, 예상과 다른 위치에서 로드되었거나, 다른 파일이 이를 재정의했기 때문입니다. 이 가이드는 Claude Code가 실제로 로드한 항목을 검사하여 어느 경우에 해당하는지 좁혀나가는 방법을 보여줍니다.

설치, 인증 및 연결 문제의 경우 대신 설치 및 로그인 문제 해결을 참조하십시오.

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

/context 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, 사용자 정의 서브에이전트(로드된 소스 포함), MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 CLAUDE.md, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다.

특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:

명령 표시 내용
/memory 로드된 CLAUDE.md 및 규칙 파일, 자동 메모리 항목
/skills 프로젝트, 사용자 및 플러그인 소스의 사용 가능한 스킬
/hooks 활성 훅 구성
/mcp 연결된 MCP 서버 및 해당 상태
/permissions 현재 적용 중인 허용 및 거부 규칙
/doctor 설정 점검: 설치 상태, 잘못된 설정 파일, 사용하지 않는 확장 프로그램, 동일한 디렉토리의 중복 서브에이전트 이름 및 Claude가 코드베이스에서 파생할 수 있는 체크인된 CLAUDE.md 콘텐츠(제안된 수정 사항 포함)
/debug [issue] 세션에 대해 디버그 로깅을 활성화하고 Claude가 로그 출력 및 설정 경로를 사용하여 진단하도록 프롬프트합니다
/status 활성 설정 소스, 관리 설정이 적용 중인지 여부 포함

메모리 파일이 /memory에서 누락된 경우, CLAUDE.md 파일이 로드되는 방식에 대해 해당 위치를 확인합니다. 하위 디렉토리 CLAUDE.md 파일은 Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 요청 시 로드되며, 세션 시작 시가 아닙니다.

/memory가 파일이 로드되었음을 확인했지만 Claude가 여전히 특정 명령을 따르지 않는 경우, 문제는 파일이 로드되었는지 여부가 아니라 명령이 작성된 방식일 가능성이 높습니다. CLAUDE.md는 새로운 팀원에게 제공할 지침(예: 프로젝트 규칙, 빌드 명령 및 파일 위치)에 적합합니다.

명령이 여러 방식으로 해석될 수 있을 정도로 모호할 때, 두 파일이 상충하는 지시를 제공할 때, 또는 파일이 충분히 길어서 개별 규칙이 덜 주목받을 때 준수가 감소합니다. 효과적인 명령 작성은 준수를 높게 유지하는 특이성, 크기 및 구조 패턴을 다룹니다.

해결된 설정 확인

설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 환경 변수로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다.

/doctor를 실행하여 구성 및 설치를 확인합니다. 이는 잘못된 설정 파일, 중복 설치 및 사용하지 않는 확장 프로그램을 포함하여 발견한 내용을 보고한 다음, 체크인된 CLAUDE.md 콘텐츠 Claude가 코드베이스에서 파생할 수 있는 내용을 확인하고, 사용자가 확인한 후에만 적용하는 수정 사항을 제안합니다. CLAUDE.md 트림 확인은 Claude Code v2.1.206 이상이 필요합니다. v2.1.205 이전에는 /doctor가 읽기 전용 진단 화면을 열었고 f를 누르면 보고서를 Claude에게 보내 수정하도록 했습니다.

터미널에서 claude 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"). , 구분 기호는 동등하므로 "Edit,Write"는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 |를 사용하십시오.
  • 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.
  • 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고 전체 사용자, 프로젝트 또는 로컬 설정 파일을 거부하며, claude doctor는 검증 실패를 보고하고, 해당 파일의 훅이 /hooks에 나타나지 않습니다. 관리되는 설정에서는 유효하지 않은 항목만 제거되고 파일의 다른 훅은 계속 적용됩니다.

settings.json에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 /hooks가 여전히 이전 정의를 표시하면 /hooks를 다시 실행하여 보기를 새로 고칩니다.

/hooks가 훅을 표시하지만 여전히 실행되지 않으면, 다음 단계는 훅 평가를 실시간으로 감시하는 것입니다. claude --debug hooks로 세션을 시작하고 도구 호출을 트리거합니다. 디버그 로그는 각 이벤트, 확인된 매처 및 훅의 종료 코드와 출력을 기록합니다. 로그 형식은 훅 디버깅을 참조하고 일반적인 실패 패턴은 훅 문제 해결을 참조합니다.

깨끗한 구성에 대해 테스트

claude --safe-mode로 시작합니다. 이는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 안전 모드는 여전히 조직에서 배포한 관리 훅 및 설정 정책을 적용합니다. 관리 플러그인, 스킬, CLAUDE.md 및 MCP 서버는 꺼집니다.

안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. CLAUDE_CONFIG_DIR을 빈 디렉토리로 지정하여 ~/.claude 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 .claude 폴더, .mcp.json 또는 CLAUDE.md가 없는 디렉토리에서 시작합니다.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

깨끗한 세션에는 사용자 또는 프로젝트 설정, 훅, MCP 서버, 플러그인 또는 메모리가 없습니다.

  • 조직이 배포하는 경우 관리 설정은 여전히 적용됩니다. 이들은 ~/.claude 외부의 시스템 경로에 있기 때문입니다.
  • Linux 및 Windows에서는 자격 증명이 구성 디렉토리 아래에 저장되므로 다시 로그인하라는 메시지가 표시됩니다.
  • macOS에서는 자격 증명이 Keychain에 있으며 깨끗한 세션으로 이월됩니다.

문제가 여기서 사라지면, 원인은 실제 ~/.claude 또는 프로젝트 .claude 파일 어딘가에 있습니다. 임시 디렉토리에 파일을 복사하거나 프로젝트에서 시작하여 한 번에 하나씩 다시 도입하여 어느 것인지 찾습니다. 깨끗한 세션에서 지속되면, 원인은 사용자 및 프로젝트 구성 외부에 있습니다. /status를 실행하여 관리 설정이 적용 중인지 확인하고, Claude Code에 영향을 미치는 환경 변수를 찾은 다음, 문제 해결을 참조합니다.

일반적인 원인 확인

대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다:

증상 원인 해결
훅이 절대 실행되지 않음 matcher가 문자열 대신 JSON 배열입니다 여러 도구를 일치시키기 위해 |를 사용하는 단일 문자열을 사용합니다(예: "Edit|Write"). 매처 패턴을 참조합니다.
훅이 절대 실행되지 않음 matcher가 v2.1.191 이전 버전에서 구분 기호로 ,를 사용합니다 Claude Code v2.1.191 이상은 ,를 |와 같은 목록 구분 기호로 처리합니다. 이전 버전은 쉼표를 리터럴 문자로 평가하므로 "Edit,Write"는 아무것도 일치하지 않습니다. 대신 |를 사용하거나 Claude Code를 업그레이드합니다.
훅이 절대 실행되지 않음 matcher 값이 소문자입니다(예: "bash") 일치는 대소문자를 구분합니다. 도구 이름은 대문자입니다: Bash, Edit, Write, Read.
훅이 절대 실행되지 않음 훅이 settings.json 대신 독립 실행형 파일에 정의되어 있습니다 프로젝트 또는 사용자 구성에 대한 독립 실행형 훅 파일이 없습니다. settings.json의 "hooks" 키 아래에 훅을 정의합니다. 플러그인만 별도의 hooks/hooks.json을 로드합니다. 훅 구성을 참조합니다.
전역으로 설정된 권한, 훅 또는 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 명령을 무시합니다 기본 제공 Explore 및 Plan 에이전트는 CLAUDE.md를 건너뜁니다. 사용자 정의 서브에이전트는 주 대화와 동일한 방식으로 로드합니다 Explore 또는 Plan의 경우, 위임 프롬프트에서 명령을 다시 명시합니다. 사용자 정의 서브에이전트의 경우, 중요한 명령을 에이전트 파일 본문에 넣습니다. 이는 에이전트의 시스템 프롬프트가 됩니다. 시작 시 로드되는 항목을 참조합니다.
정리 로직이 세션 종료 시 절대 실행되지 않습니다 SessionEnd 훅이 구성되지 않았습니다 settings.json에 SessionEnd 훅을 추가합니다. 훅 이벤트 목록을 참조합니다.
.mcp.json의 MCP 서버가 절대 로드되지 않습니다 파일이 .claude/ 아래에 있거나 Claude Desktop의 구성 형식을 사용합니다 프로젝트 MCP 구성은 .claude/ 내부가 아니라 저장소 루트에 .mcp.json으로 이동합니다. MCP 구성을 참조합니다.
settings.json의 mcpServers 아래에 추가된 MCP 서버가 절대 나타나지 않습니다 settings.json은 mcpServers 키를 읽지 않습니다 저장소 루트의 .mcp.json에서 프로젝트 서버를 정의하거나, 사용자 범위 서버의 경우 claude mcp add --scope user를 실행합니다. MCP 구성을 참조합니다.
프로젝트 MCP 서버가 추가되었지만 나타나지 않습니다 일회성 승인 프롬프트가 해제되었습니다 프로젝트 범위 서버는 승인이 필요합니다. /mcp를 실행하여 상태를 확인하고 승인합니다.
MCP 서버가 일부 디렉토리에서 시작하지 못합니다 command 또는 args가 상대 파일 경로를 사용합니다 로컬 스크립트에 절대 경로를 사용합니다. npx 또는 uvx와 같은 PATH의 실행 파일은 그대로 작동합니다.
MCP 서버가 예상 환경 변수 없이 시작됩니다 변수가 settings.json env에 있으며, MCP 자식 프로세스로 전파되지 않습니다 대신 .mcp.json 내부에 서버별 env를 설정합니다.
Bash(rm *) 거부 규칙이 /bin/rm 또는 find -delete를 차단하지 않습니다 접두사 규칙은 기본 실행 파일이 아니라 리터럴 명령 문자열과 일치합니다 각 변형에 대해 명시적 패턴을 추가하거나, PreToolUse 훅 또는 샌드박스를 사용하여 하드 보장을 얻습니다.

각 구성 표면에 대한 전체 참조는 전용 페이지를 참조합니다: