SpyBara
Go Premium

debug-your-config.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 21 additions and 22 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

구성 디버깅하기

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

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

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

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

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

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

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

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

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

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

해결된 설정 확인

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

잘못된 설정 파일을 찾으려면 터미널에서 claude doctor를 실행합니다. 이는 세션을 시작하지 않고 읽기 전용 설치 및 설정 진단을 출력합니다. 수정 사항을 제안하고 적용하기 전에 확인하는 전체 점검을 위해 세션 내에서 /doctor를 실행합니다.

/status를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 Claude Code가 사용하는 범위를 이해하려면 설정 우선순위를 참조합니다.

MCP 서버 확인

/mcp를 실행하여 모든 구성된 서버, 해당 연결 상태 및 현재 프로젝트에 대해 승인했는지 여부를 확인합니다. 서버가 올바르게 정의되었지만 여전히 몇 가지 일반적인 이유로 도구를 제공하지 않을 수 있습니다:

  • .mcp.json의 프로젝트 범위 서버는 일회성 승인이 필요합니다. 프롬프트가 해제된 경우, 서버는 /mcp에서 승인할 때까지 비활성화된 상태로 유지됩니다.
  • 시작에 실패한 서버는 /mcp에서 실패로 표시됩니다. command 또는 args의 상대 파일 경로는 .mcp.json의 위치가 아니라 Claude Code를 시작한 디렉토리에 대해 해석되므로 빈번한 원인입니다.
  • 연결된 것으로 표시되지만 도구가 0개인 서버는 성공적으로 시작되었지만 도구 목록을 반환하지 않습니다. /mcp에서 다시 연결을 선택합니다. 개수가 0으로 유지되면 claude --debug=mcp를 실행하고 ~/.claude/debug/<session-id>.txt의 디버그 로그에서 서버의 stderr을 읽습니다.

구성 위치 및 범위 규칙은 MCP를 참조합니다.

훅 확인

/hooks를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 읽혀지지 않는 것입니다: 훅은 독립 실행형 파일이 아니라 설정 파일의 "hooks" 키 아래에 있습니다.

훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:

  • matcher 필드는 여러 도구 이름을 일치시키기 위해 |를 사용하는 단일 문자열입니다(예: "Edit|Write"). , 구분 기호는 동등하므로 "Edit,Write"는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 |를 사용하십시오.
  • 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.
  • 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고 전체 사용자, 프로젝트 또는 로컬 설정 파일을 거부하며, claude doctor는 검증 실패를 보고하고, 해당 파일의 훅이 /hooks에 나타나지 않습니다. 관리되는 설정에서는 Claude Code가 파일을 포함하는 전체 hooks 키를 삭제하므로 해당 파일의 훅이 적용되지 않습니다. 파일의 다른 설정은 계속 적용되며, claude doctor는 삭제된 키를 나열합니다.

settings.json을 편집하면 파일 안정성 지연 후 실행 중인 세션에서 변경 사항이 적용됩니다. 세션이 시작된 후 파일이나 프로젝트의 .claude/ 폴더를 생성한 경우에도 다시 시작할 필요가 없습니다. v2.1.257 이전에는 Claude Code가 세션이 시작된 후 생성된 .claude/ 폴더의 편집을 감지하지 못했습니다.

저장 후 몇 초가 지났는데도 /hooks가 여전히 이전 정의를 표시하면 /hooks를 다시 실행하여 보기를 새로 고칩니다.

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

깨끗한 구성에 대해 테스트

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 Code가 온보딩 상태를 저장하기 때문에 이 화면들을 건너뜁니다.

  • 조직이 관리 설정을 배포하는 경우 여전히 적용됩니다. Claude Code는 구성 디렉토리 외부의 위치에서 MDM 프로필, 레지스트리 정책 및 managed-settings.json을 읽으며, 깨끗한 세션이 자격 증명을 가지면 서버 관리 설정을 다시 가져옵니다
  • 다시 로그인하라는 메시지가 표시됩니다

문제가 여기서 사라지면, 원인은 실제 ~/.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/ 아래에 있거나 서버가 VS Code의 mcp.json처럼 최상위 servers 키 아래에 있으며, mcpServers 대신 있습니다 프로젝트 MCP 구성은 .claude/ 내부가 아니라 저장소 루트에 .mcp.json으로 이동하며, mcpServers 키 아래에 서버가 있습니다. 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 서버가 예상 환경 변수 없이 시작됩니다 서버의 구성 항목이 설정하지 않으며, Claude Code가 stdio 서버에 전달하는 환경에 없습니다: 자체 환경에서 서브프로세스에서 제거하는 변수 제외 서버의 .mcp.json 항목 내에 서버별 env를 설정합니다. 이는 시작 환경이나 작업 공간 신뢰에 따라 달라지지 않습니다.
Bash(rm *) 거부 규칙이 /bin/rm 또는 find -delete를 차단하지 않습니다 접두사 규칙은 기본 실행 파일이 아니라 리터럴 명령 문자열과 일치합니다 각 변형에 대해 명시적 패턴을 추가하거나, PreToolUse 훅 또는 샌드박스를 사용하여 하드 보장을 얻습니다.

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