설정이 안 먹을 때 디버그하기

기준일: 2026-07-26
공식 기준: Debug your configuration

개요

Claude가 지시를 무시하거나 설정한 기능이 안 보이면, 대개 파일이 로드되지 않았거나, 기대한 위치가 아니거나, 다른 파일이 덮어쓴 경우입니다. 이 가이드는 Claude Code가 실제로 로드한 것을 검사해 원인을 좁힙니다.

설치·인증·연결 문제는 Troubleshoot installation and login.

핵심 개념

명령	용도
`/context`	컨텍스트 창 점유 전체 (system prompt, tools, MCP, subagents, memory, skills, 메시지)
`/memory`	사용자·프로젝트 memory 위치, auto memory
`/skills`	프로젝트·사용자·플러그인 스킬
`/hooks`	활성 hook 설정
`/mcp`	연결 MCP 서버 상태
`/permissions`	적용 중인 allow/deny
`/doctor`	설치·잘못된 settings·미사용 확장·중복 subagent·파생 가능 CLAUDE.md 점검 + 확인 후 수정 제안
`/debug [issue]`	세션 debug 로깅 + 로그·settings 경로 기반 진단 유도
`/status`	활성 settings 소스, managed settings 여부

상세

컨텍스트에 로드된 것 확인

먼저 /context로 CLAUDE.md·rules·skill 설명이 있는지 확인합니다. 카테고리별 상세는 위 전용 명령.

서브디렉터리 CLAUDE.md는 세션 시작이 아니라 Read 도구로 그 디렉터리 파일을 읽을 때 온디맨드 로드됩니다. how CLAUDE.md files load.

로드는 됐는데 특정 지시만 안 따르면 작성 방식 문제일 수 있습니다. 새 팀원에게 줄 수준의 컨벤션·빌드 명령·파일 위치는 잘 지켜집니다. 모호·충돌·파일이 너무 길면 준수가 떨어집니다. Write effective instructions.

CLAUDE.md vs permissions/hooks: CLAUDE.md는 프로젝트 방식 안내. Permissions·hooks는 Claude 판단과 무관하게 한계를 강제. 보안 경계·절대 금지에는 permissions/hooks.

해석된 settings 확인

Settings는 managed → (local > project > user) 순으로 병합. managed가 있으면 항상 이김. CLI 플래그·환경 변수도 오버라이드 층. 안 먹으면 다른 scope 또는 env가 덮은 경우가 많습니다.

/doctor: 잘못된 settings, 중복 설치, 미사용 확장, v2.1.206+ 코드베이스에서 파생 가능한 체크인 CLAUDE.md 내용 등 보고 후 확인 시에만 수정 적용. v2.1.205 이전은 읽기 전용 진단, f로 Claude에 수정 위임.

터미널 claude doctor는 세션 없이 읽기 전용 설치·settings 진단.

/status로 managed 포함 활성 소스 확인. scope 승자: How scopes interact.

MCP 서버 확인

/mcp에서 서버·연결 상태·프로젝트 승인 여부.

프로젝트 스코프 .mcp.json은 1회 승인 필요. 프롬프트 무시 시 비활성 → /mcp에서 승인
시작 실패: 자주 command/args 상대 경로 — .mcp.json 위치가 아니라 Claude Code 실행 cwd 기준 해석
connected인데 tools 0: Reconnect. 유지되면 claude --debug mcp로 stderr

위치·스코프: MCP.

hooks 확인

/hooks에 세션 등록 hook이 이벤트별 목록. 안 보이면 읽히지 않음: hooks는 settings의 "hooks" 키 아래 (단독 파일 아님; 플러그인만 hooks/hooks.json).

목록에 있는데 안 뜨면 matcher:

단일 문자열, 다중 도구는 | 예 "Edit|Write". v2.1.191+ 에서 ,도 동등. 이전 버전 쉼표는 regex로 떨어져 매치 실패
도구명 오타는 silent fail
배열 값은 스키마 오류: 해당 user/project/local settings 파일 전체 거부, claude doctor 보고. managed settings는 잘못된 항목만 strip

settings.json 편집은 짧은 안정 지연 후 세션에 반영, 재시작 불필요. 수 초 뒤에도 옛 정의면 /hooks 재실행.

여전히 안 뜨면 claude --debug hooks로 이벤트·matcher·exit code 로그. Debug hooks, hooks troubleshooting.

깨끗한 설정으로 테스트

v2.1.169+: claude --safe-mode — CLAUDE.md, skills, plugins, hooks, MCP, custom commands/agents 비활성. 인증·모델·내장 도구·permissions는 정상. 문제가 사라지면 그 표면 중 하나. managed hooks·settings policy는 유지. managed plugins/skills/CLAUDE.md/MCP는 off.

또는:

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

~/.claude와 프로젝트 .claude/.mcp.json/CLAUDE.md 우회. 첫 실행에 테마 등 온보딩 화면이 보이면 clean dir 적용 중.

managed settings는 시스템 경로라 여전히 적용 가능
Linux/Windows: 자격 증명이 config dir 아래라 재로그인
macOS: Keychain이라 로그인 유지

여기서 사라지면 실제 ~/.claude/프로젝트 파일. 하나씩 재도입. 남으면 managed·env·Troubleshooting.

흔한 원인 표

증상	원인	조치
Hook 미발화	matcher가 JSON 배열	`"Edit\|Write"` 단일 문자열
Hook 미발화	v2.1.191 미만에서 `,` 구분	`\|` 사용 또는 업그레이드
Hook 미발화	matcher 소문자 `"bash"`	대소문자 구분: `Bash`, `Edit`…
Hook 미발화	단독 hooks 파일	`settings.json`의 `"hooks"` 키 (플러그인만 별도 파일)
전역 permissions/hooks/env 무시	`~/.claude.json`에 넣음	앱 상태용. 설정은 `~/.claude/settings.json`
settings 값 무시	`settings.local.json` 동일 키	local > project > user
스킬이 `/skills`에 없음	`.claude/skills/name.md`	`.claude/skills/name/SKILL.md` 폴더
스킬 목록에 있으나 미호출	`disable-model-invocation: true` 또는 description 불일치	`/skills` user-only 배지 확인
서브디렉터리 CLAUDE.md 무시	온디맨드 로드	Read 시 로드, write/create만으로는 안 됨
Subagent가 CLAUDE.md 무시	Explore/Plan 내장 에이전트는 스킵	위임 프롬프트에 재기술. 커스텀은 agent body에 핵심 지시
세션 종료 cleanup 없음	SessionEnd hook 없음	settings에 SessionEnd
`.mcp.json` 미로드	`.claude/` 아래 또는 Desktop 포맷	저장소 루트 `.mcp.json`
settings.json `mcpServers` 미동작	settings는 해당 키 미사용	`.mcp.json` 또는 `claude mcp add --scope user`
프로젝트 MCP 안 보임	승인 프롬프트 무시	`/mcp` 승인
일부 디렉터리에서 MCP 시작 실패	상대 경로	로컬 스크립트는 절대 경로. `npx`/`uvx`는 PATH OK
MCP에 env 미전달	settings `env`는 MCP 자식에 전파 안 됨	`.mcp.json` 서버별 `env`
`Bash(rm *)` deny가 `/bin/rm` 미차단	prefix 규칙은 리터럴 명령 문자열	변형별 패턴, PreToolUse hook, sandbox

체크리스트

/context로 파일이 로드됐는지 확인했다
/doctor·/status로 scope·managed·잘못된 settings를 확인했다
MCP·hooks는 /mcp·/hooks·필요 시 --debug로 검증했다
--safe-mode 또는 CLAUDE_CONFIG_DIR clean 세션으로 격리했다
흔한 원인 표의 위치·문법 실수를 점검했다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/debug-your-config

설정이 안 먹을 때 디버그하기

기준일: 2026-07-26
공식 기준: Debug your configuration

개요

설치·인증·연결 문제는 Troubleshoot installation and login.

핵심 개념

명령	용도
`/context`	컨텍스트 창 점유 전체 (system prompt, tools, MCP, subagents, memory, skills, 메시지)
`/memory`	사용자·프로젝트 memory 위치, auto memory
`/skills`	프로젝트·사용자·플러그인 스킬
`/hooks`	활성 hook 설정
`/mcp`	연결 MCP 서버 상태
`/permissions`	적용 중인 allow/deny
`/doctor`	설치·잘못된 settings·미사용 확장·중복 subagent·파생 가능 CLAUDE.md 점검 + 확인 후 수정 제안
`/debug [issue]`	세션 debug 로깅 + 로그·settings 경로 기반 진단 유도
`/status`	활성 settings 소스, managed settings 여부

상세

컨텍스트에 로드된 것 확인

먼저 /context로 CLAUDE.md·rules·skill 설명이 있는지 확인합니다. 카테고리별 상세는 위 전용 명령.

서브디렉터리 CLAUDE.md는 세션 시작이 아니라 Read 도구로 그 디렉터리 파일을 읽을 때 온디맨드 로드됩니다. how CLAUDE.md files load.

해석된 settings 확인

터미널 claude doctor는 세션 없이 읽기 전용 설치·settings 진단.

/status로 managed 포함 활성 소스 확인. scope 승자: How scopes interact.

MCP 서버 확인

/mcp에서 서버·연결 상태·프로젝트 승인 여부.

프로젝트 스코프 .mcp.json은 1회 승인 필요. 프롬프트 무시 시 비활성 → /mcp에서 승인
시작 실패: 자주 command/args 상대 경로 — .mcp.json 위치가 아니라 Claude Code 실행 cwd 기준 해석
connected인데 tools 0: Reconnect. 유지되면 claude --debug mcp로 stderr

위치·스코프: MCP.

hooks 확인

/hooks에 세션 등록 hook이 이벤트별 목록. 안 보이면 읽히지 않음: hooks는 settings의 "hooks" 키 아래 (단독 파일 아님; 플러그인만 hooks/hooks.json).

목록에 있는데 안 뜨면 matcher:

단일 문자열, 다중 도구는 | 예 "Edit|Write". v2.1.191+ 에서 ,도 동등. 이전 버전 쉼표는 regex로 떨어져 매치 실패
도구명 오타는 silent fail
배열 값은 스키마 오류: 해당 user/project/local settings 파일 전체 거부, claude doctor 보고. managed settings는 잘못된 항목만 strip

settings.json 편집은 짧은 안정 지연 후 세션에 반영, 재시작 불필요. 수 초 뒤에도 옛 정의면 /hooks 재실행.

여전히 안 뜨면 claude --debug hooks로 이벤트·matcher·exit code 로그. Debug hooks, hooks troubleshooting.

깨끗한 설정으로 테스트

또는:

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

~/.claude와 프로젝트 .claude/.mcp.json/CLAUDE.md 우회. 첫 실행에 테마 등 온보딩 화면이 보이면 clean dir 적용 중.

managed settings는 시스템 경로라 여전히 적용 가능
Linux/Windows: 자격 증명이 config dir 아래라 재로그인
macOS: Keychain이라 로그인 유지

여기서 사라지면 실제 ~/.claude/프로젝트 파일. 하나씩 재도입. 남으면 managed·env·Troubleshooting.

흔한 원인 표

증상	원인	조치
Hook 미발화	matcher가 JSON 배열	`"Edit\|Write"` 단일 문자열
Hook 미발화	v2.1.191 미만에서 `,` 구분	`\|` 사용 또는 업그레이드
Hook 미발화	matcher 소문자 `"bash"`	대소문자 구분: `Bash`, `Edit`…
Hook 미발화	단독 hooks 파일	`settings.json`의 `"hooks"` 키 (플러그인만 별도 파일)
전역 permissions/hooks/env 무시	`~/.claude.json`에 넣음	앱 상태용. 설정은 `~/.claude/settings.json`
settings 값 무시	`settings.local.json` 동일 키	local > project > user
스킬이 `/skills`에 없음	`.claude/skills/name.md`	`.claude/skills/name/SKILL.md` 폴더
스킬 목록에 있으나 미호출	`disable-model-invocation: true` 또는 description 불일치	`/skills` user-only 배지 확인
서브디렉터리 CLAUDE.md 무시	온디맨드 로드	Read 시 로드, write/create만으로는 안 됨
Subagent가 CLAUDE.md 무시	Explore/Plan 내장 에이전트는 스킵	위임 프롬프트에 재기술. 커스텀은 agent body에 핵심 지시
세션 종료 cleanup 없음	SessionEnd hook 없음	settings에 SessionEnd
`.mcp.json` 미로드	`.claude/` 아래 또는 Desktop 포맷	저장소 루트 `.mcp.json`
settings.json `mcpServers` 미동작	settings는 해당 키 미사용	`.mcp.json` 또는 `claude mcp add --scope user`
프로젝트 MCP 안 보임	승인 프롬프트 무시	`/mcp` 승인
일부 디렉터리에서 MCP 시작 실패	상대 경로	로컬 스크립트는 절대 경로. `npx`/`uvx`는 PATH OK
MCP에 env 미전달	settings `env`는 MCP 자식에 전파 안 됨	`.mcp.json` 서버별 `env`
`Bash(rm *)` deny가 `/bin/rm` 미차단	prefix 규칙은 리터럴 명령 문자열	변형별 패턴, PreToolUse hook, sandbox

체크리스트

/context로 파일이 로드됐는지 확인했다
/doctor·/status로 scope·managed·잘못된 settings를 확인했다
MCP·hooks는 /mcp·/hooks·필요 시 --debug로 검증했다
--safe-mode 또는 CLAUDE_CONFIG_DIR clean 세션으로 격리했다
흔한 원인 표의 위치·문법 실수를 점검했다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/debug-your-config

설정이 안 먹을 때 디버그하기

개요

핵심 개념

상세

컨텍스트에 로드된 것 확인

해석된 settings 확인

MCP 서버 확인

hooks 확인

깨끗한 설정으로 테스트

흔한 원인 표

체크리스트

다음 단계

기준일

관련 가이드

설정이 안 먹을 때 디버그하기

개요

핵심 개념

상세

컨텍스트에 로드된 것 확인

해석된 settings 확인

MCP 서버 확인

hooks 확인

깨끗한 설정으로 테스트

흔한 원인 표

체크리스트

다음 단계

기준일

관련 가이드