Claude Code 설정 디버깅

Claude Code 설정 디버깅

CLAUDE.md·설정·훅·MCP 서버·스킬이 반영되지 않을 때, 실제로 어떤 값이 로드됐는지 들여다보는 방법을 다루는 페이지입니다. 대부분 원인은 '파일이 로드되지 않았거나, 예상과 다른 위치에서 로드됐거나, 다른 파일이 덮어썼다' 셋 중 하나입니다. /context, /doctor, /hooks, /mcp로 실제 로드 상태를 확인해 어느 쪽인지 좁힙니다. 설치·인증·연결 문제는 Troubleshoot installation and login을 보세요.

출처: 공식문서

본문

컨텍스트에 로드된 것 확인

/context는 현재 세션의 컨텍스트 창을 차지하는 모든 것(시스템 프롬프트, 시스템 도구, MCP 도구, 소스 포함 커스텀 서브에이전트, 메모리 파일, 스킬, 대화 메시지)을 범주별로 보여줍니다. 먼저 실행해 CLAUDE.md·규칙·스킬 설명이 존재하는지 확인하세요. /context의 스킬 섹션은 /skills가 나열하지 않는 번들 스킬도 포함합니다.

특정 범주는 전용 명령으로:

명령 보여주는 것
/memory 유저·프로젝트 범위 메모리 파일 위치, 자동 메모리 폴더·토글
/skills 프로젝트·유저·플러그인 소스의 스킬
/hooks 활성 훅 설정
/mcp 연결된 MCP 서버와 상태
/permissions 적용 중인 allow·deny 규칙
/doctor 설치 건강, 무효 설정 파일, 미사용 확장, 중복 서브에이전트 이름, 코드베이스에서 유도 가능한 CLAUDE.md, 제안 수정
/debug [issue] 세션 디버그 로깅 활성화 + 로그로 진단
/status 활성 설정 소스(관리 설정 포함)

메모리 파일이 /context에 없으면 CLAUDE.md 로드 방식을 확인하세요. 하위 디렉터리의 CLAUDE.md는 세션 시작이 아니라 Claude가 그 디렉터리 파일을 Read 도구로 읽을 때 온디맨드로 로드됩니다.

/context가 로드는 확인했는데도 지시를 안 따르면 로드 여부보다 지시 작성 방식 문제일 수 있습니다. 모호하거나 두 파일이 충돌하거나 파일이 너무 길면 준수율이 떨어집니다. 효과적인 지시 작성을 참조하세요.

참고: CLAUDE.md와 권한은 다른 문제를 풉니다. CLAUDE.md는 "우리는 여기서 이렇게 한다"는 지침이고, 권한·훅은 보안 경계·절대 금지 사항처럼 지침이 아닌 보장이 필요한 곳에 쓰세요.

해석된 설정 확인

설정은 관리·유저·프로젝트·로컬 범위로 병합됩니다. 관리 설정이 있으면 최우선이고, 나머지는 가까운 범위가 먼저: local → project → user. 일부는 CLI 플래그·환경변수로도 설정됩니다. 설정이 안 먹히면 다른 범위·환경변수가 덮어썼을 가능성이 높습니다.

claude doctor로 무효 설정 파일을 찾으세요(세션 없이 읽기 전용 진단). 세션 안의 /doctor는 수정 제안·적용 전 승인 포함 전체 점검입니다. /status로 활성 설정 소스, 설정 우선순위로 특정 키의 사용 값 판정 기준을 확인하세요.

MCP 서버 확인

/mcp로 각 서버의 상태·프로젝트 승인 여부를 봅니다. 서버가 올바르게 정의됐는데 도구가 안 보이는 일반적 이유:

  • .mcp.json의 프로젝트 범위 서버는 1회 승인이 필요합니다. 프롬프트를 닫았으면 /mcp에서 승인할 때까지 비활성화 유지.
  • 시작 실패는 /mcp에서 failed로 표시. command/args의 상대 경로가 흔한 원인(.mcp.json 위치가 아니라 실행한 디렉터리 기준으로 해석).
  • connected인데 도구 0개면 시작은 됐지만 목록을 반환 안 함 — /mcp에서 Reconnect. 계속 0이면 claude --debug=mcp로 ~/.claude/debug/<session-id>.txt 확인.

훅 확인

/hooks로 이벤트별 등록 훅을 봅니다. 정의한 훅이 안 보이면 읽히지 않는 것 — 훅은 독립 파일이 아니라 settings 파일의 "hooks" 키 아래 있어야 합니다. 훅은 보이는데 발동 안 하면 matcher가 흔한 원인:

  • matcher는 |로 여러 도구를 매칭하는 단일 문자열(예: "Edit|Write"). v2.1.191 이전에선 , 구분자는 regex로 넘어가 매칭 실패.
  • 오타난 도구 이름은 매칭 안 됨(조용히 실패).
  • 배열 값은 스키마 오류 — 해당 settings 파일 전체가 거부되고 claude doctor가 보고합니다.

settings.json을 수정하면 약간의 안정화 지연 후 실행 중인 세션에 반영됩니다. 저장 몇 초 후에도 옛 정의가 보이면 /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·프로젝트 .claude 파일 중 하나가 원인 — 하나씩 다시 도입해 찾으세요. 깨끗한 세션에서도 지속되면 유저/프로젝트 설정 밖 원인. /status로 관리 설정, 환경변수를 확인 후 Troubleshooting으로.

흔한 원인 체크

증상 원인 해결
훅 발동 안 함 matcher가 JSON 배열 `
훅 발동 안 함 v2.1.191 이전에서 , 구분자 `
훅 발동 안 함 matcher 소문자("bash") 대소문자 구분 — Bash, Edit, Write, Read
훅 발동 안 함 독립 파일에 정의 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 단일 파일 .claude/skills/name/SKILL.md 폴더
하위 디렉터리 CLAUDE.md 무시 온디맨드 로드 해당 디렉터리 파일을 Read 도구로 읽을 때 로드(시작·쓰기 시 아님)
서브에이전트가 CLAUDE.md 무시 내장 Explore·Plan은 CLAUDE.md 건너뜀 Explore·Plan은 위임 프롬프트에 재진술, 커스텀 서브에이전트는 에이전트 파일 본문에
.mcp.json 서버 로드 안 됨 .claude/ 아래이거나 servers 키 저장소 루트의 .mcp.json, mcpServers 키
MCP 서버 실패 command/args 상대 경로 로컬 스크립트는 절대 경로, npx·uvx는 PATH로
Bash(rm *) deny가 /bin/rm 차단 안 함 Bash 규칙은 명령 문자열 그대로 매칭 PreToolUse 훅 또는 샌드박스

더 알아보기