설정 디버깅
Claude가 지시를 무시하거나 설정한 기능이 안 보일 때, 거의 항상 원인 셋 중 하나입니다:
- 파일이 로드 안 됐다
- 의도한 위치가 아닌 다른 위치에서 로드됐다
- 다른 파일이 우선순위로 덮어썼다
이 챕터는 Claude Code가 실제 로드한 것을 확인하는 진단 명령과 자주 마주치는 함정을 정리합니다.
설치·로그인 단계 문제는 레벨 1 설치 챕터를, 런타임 에러 메시지는 레벨 2 에러 카탈로그를 먼저 참고. 본 챕터는 "설정이 안 먹는다"는 케이스 전용입니다.
첫 명령은 /context
/context는 현재 세션의 컨텍스트 윈도우를 카테고리별로 보여줍니다 — 시스템 프롬프트·메모리·skill·MCP 도구·메시지. CLAUDE.md·rule·skill 설명이 로드 자체가 됐는지 가장 먼저 확인할 곳입니다.
(Velog 일지 #38에서 /context 활용 패턴 정리)
카테고리별 진단 명령
| 명령 | 보여주는 것 |
|---|---|
/memory | 로드된 CLAUDE.md·rule 파일 + auto-memory 항목 |
/skills | 프로젝트·사용자·플러그인 출처별 사용 가능 skill |
/agents | 설정된 subagent와 그 설정 |
/hooks | 활성 hook 설정 |
/mcp | 연결된 MCP 서버와 상태 |
/permissions | 현재 적용 중인 allow·deny 룰 |
/doctor | 설정 진단 — 잘못된 키·스키마 오류·설치 상태 |
/debug [issue] | 세션에 디버그 로깅 활성화 + Claude가 로그 보며 진단 |
/status | 활성 설정 source — managed settings 적용 여부 포함 |
순서: /context → 해당 카테고리 명령 → /doctor (전체 진단)
CLAUDE.md가 로드 안 된다
/memory에 파일이 안 보이면 위치 문제:
- 서브디렉토리
CLAUDE.md는 세션 시작 시 자동 로드 X. Claude가 Read 도구로 해당 디렉토리 파일을 읽을 때 on-demand 로드. 따라서 처음엔 안 보이는 게 정상 /memory엔 보이는데 Claude가 따르지 않으면 = 로드 문제 아닌 지시 작성 방식 문제. 모호하거나, 두 파일이 충돌하거나, 파일이 너무 길어 개별 룰 주의가 떨어짐
(Velog 일지 #47에서 compact vs 새 세션 결정 기준 정리)
설정 우선순위
설정은 4개 scope로 병합: managed·user·project·local.
- managed가 있으면 항상 이김
- 나머지는 local → project → user 순으로 우선 (가까운 scope가 이김)
- 명령줄 플래그·환경변수가 또 다른 오버라이드 layer
/status로 어느 source가 활성인지 확인. 어느 scope가 이기는지 판단은 공식 settings 문서 참고.
MCP 서버가 안 연결된다
/mcp 출력에서 상태 확인:
- 프로젝트 scope
.mcp.json서버는 1회 승인 필요 — 첫 진입 프롬프트 닫으면 비활성./mcp에서 다시 승인 - 시작 실패하면 failed 표시.
command·args에 상대 경로 쓰면.mcp.json위치가 아니라 Claude Code 시작 디렉토리 기준이라 자주 깨짐. 절대 경로 권장 - 연결됐는데 도구 0개면 서버는 떴지만 도구 목록 반환 안 함.
/mcp에서 Reconnect. 그래도 0이면claude --debug mcp로 서버 stderr 확인
Hook이 안 발사된다
/hooks에 등록 안 보이면 = 읽히지 않은 것. Hook은 settings.json "hooks" 키 아래에 둬야 — 별도 파일 아닙니다.
/hooks에 보이는데도 안 발사되면 거의 matcher 문제:
| 함정 | 해결 |
|---|---|
matcher가 JSON 배열 | 단일 문자열로. 여러 도구 매치는 | 사용 — 예: "Edit|Write" |
matcher가 소문자 — "bash" | 대소문자 구분. 도구명은 대문자 — Bash·Edit·Write·Read |
| 도구명 오타 | 조용히 매치 실패 |
settings.json 편집 후 약간의 file-stability 지연 뒤 자동 반영. 재시작 불필요. 몇 초 후 /hooks 다시 실행.
진짜 안 잡히면 claude --debug hooks로 hook 평가 라이브 관찰 — 각 event·matcher 체크·exit code·output 다 로그됨.
Clean 세션과 비교
타겟 진단으로 원인 못 잡거나 설정 상태를 모르겠으면, 본인 평소 설정을 하나도 안 로드한 세션과 비교. CLAUDE_CONFIG_DIR을 빈 디렉토리로 가리키고 .claude·.mcp.json·CLAUDE.md 없는 디렉토리에서 시작:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
Clean 세션은 user·project 설정·hook·MCP·플러그인·메모리 전무.
- managed 설정만은 시스템 경로라 적용됨
- Linux·Windows는 로그인 다시 요청 (자격 증명이 config 디렉토리 안에 저장)
- macOS는 Keychain이라 자격 증명 그대로 유지
Clean에서 문제 사라지면 → 원인은 본인 ~/.claude 또는 프로젝트 .claude 안. 하나씩 다시 추가하며 범인 찾기.
Clean에서도 재현되면 → 본인 user·project 설정 밖. /status로 managed 설정 영향 확인, 환경변수 점검.
자주 마주치는 함정 12선
| 증상 | 원인 | 해결 |
|---|---|---|
| Hook 안 발사 | matcher가 배열 또는 소문자 | 단일 문자열 + 대문자 — "Edit|Write"·"Bash" |
| Hook 안 발사 | hook이 standalone 파일 | settings.json "hooks" 키 아래로 (플러그인만 별도 hooks/hooks.json) |
permissions·hooks·env가 전역 무시 | ~/.claude.json에 추가 | ~/.claude.json은 app state 전용. 위 키는 ~/.claude/settings.json에 |
settings.json 값 무시 | 같은 키가 settings.local.json에 | settings.local.json > settings.json > ~/.claude/settings.json |
Skill /skills에 안 보임 | .claude/skills/name.md에 둠 | 폴더 구조 — .claude/skills/name/SKILL.md |
| Skill 보이는데 Claude가 호출 X | disable-model-invocation: true 또는 description이 본인 요청 표현과 안 맞음 | /skills에서 "user-only" 뱃지 확인 |
서브디렉토리 CLAUDE.md 무시 | on-demand 로드 — Claude가 Read 도구로 그 디렉토리 파일 읽을 때만 로드 | 정상. 시작 시 자동 X |
Subagent가 CLAUDE.md 무시 | 내장 Explore·Plan은 CLAUDE.md skip | Explore·Plan은 위임 프롬프트에 재진술. 커스텀 subagent는 agent 파일 body에 |
| 세션 종료 시 cleanup 안 됨 | SessionEnd hook 미설정 | settings.json에 추가 |
| 프로젝트 MCP 서버 안 떰 | .claude/ 안에 두거나 Claude Desktop 형식 사용 | 저장소 루트에 .mcp.json |
settings.json에 mcpServers 추가 | settings.json은 mcpServers 키 안 읽음 | .mcp.json (프로젝트) 또는 claude mcp add --scope user |
| MCP 서버 시작 시 환경변수 누락 | settings.json env는 MCP 자식 프로세스로 전파 X | .mcp.json 안 서버별 env로 |
정리
| 첫 의심 | 명령 |
|---|---|
| 뭐가 로드됐는지 모름 | /context → /memory·/skills·/hooks·/mcp 순 |
| 설정 source 다중 충돌 | /status (활성 source 확인) + /doctor (검증) |
| Hook 안 발사 | /hooks로 등록 확인 → matcher 대소문자·배열·키 위치 점검 → claude --debug hooks |
| MCP 안 잡힘 | /mcp → 승인 상태·시작 실패·도구 0개 확인 → 절대 경로로 교체 → claude --debug mcp |
| 원인 못 잡음 | CLAUDE_CONFIG_DIR=/tmp/claude-clean claude로 비교 |
본 챕터는 공식 debug 페이지를 베이스로 한국어 시청자가 자주 만나는 케이스로 정리. 최신 함정 목록은 공식 문서가 정답.
다음 챕터: Hooks 자동화 →