Claude Code 상세 사용법 39: 설정이 안 먹힐 때 진단 루프 | DAKER 커뮤니티

Claude Code 상세 사용법 39: 설정이 안 먹힐 때 진단 루프

Claude Code에서 CLAUDE.md, hooks, MCP, skills, permissions가 “안 먹히는” 문제는 대부분 기능 버그가 아니라 로드 위치, 설정 우선순위, schema 오류다. 공식 troubleshooting 문서는 /context, /doctor, /hooks, /mcp처럼 실제 로드 상태를 보는 명령부터 쓰라고 안내한다.

위 SVG는 Mermaid 구조를 DAKER 편집기용 튜토리얼 이미지로 옮긴 것이다.

1. 먼저 현재 세션에 무엇이 들어왔는지 본다

/context는 system prompt, memory, skills, MCP tools, conversation이 context window를 어떻게 쓰는지 보여 준다. 여기서 안 보이면 Claude가 무시한 것이 아니라 애초에 로드되지 않은 것이다.

/context
/memory
/skills
/agents
/permissions

subdirectory CLAUDE.md는 세션 시작 때 전부 로드되지 않는다. Claude가 해당 디렉터리 파일을 읽을 때 on-demand로 들어온다.

2. 설정 충돌은 /doctor와 /status로 본다

settings는 managed, user, project, local scope가 병합된다. local이 project와 user를 덮고, managed settings는 조직 정책으로 우선한다. 값이 안 먹히면 “잘못 썼나”보다 “다른 scope가 덮었나”를 먼저 확인한다.

/doctor
/status

/doctor가 schema 오류를 말하면 설정 파일을 고친 뒤 같은 명령을 다시 실행한다. AI 코딩 세션에서는 고친 사실보다 재확인 출력이 더 중요하다.

3. MCP는 승인과 경로 문제를 먼저 본다

/mcp에서 server가 보이지만 tool이 없거나 disabled라면 세 가지를 본다. project .mcp.json은 one-time approval이 필요하다. 상대 경로는 Claude Code를 실행한 위치 기준으로 풀릴 수 있다. server stderr가 필요하면 claude --debug mcp로 시작한다.

4. hooks는 matcher가 자주 틀린다

hooks는 standalone file이 아니라 settings의 "hooks" key 아래에 둔다. matcher는 배열이 아니라 문자열이고, 여러 tool은 "Edit|Write"처럼 |로 묶는다. tool name은 Bash, Edit, Write처럼 대소문자를 맞춘다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint -- --fix" }]
      }
    ]
  }
}

5. 마지막은 clean config session

원인이 안 잡히면 빈 config dir로 시작해 사용자 설정을 우회한다.

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

macOS는 credentials가 Keychain에 있어 clean session에도 남을 수 있다. 문제가 사라지면 ~/.claude나 project .claude 파일을 하나씩 되돌려 원인을 찾는다.

Senior takeaway: Claude Code 설정 디버깅은 추측 싸움이 아니다. /context로 로드 여부, /doctor로 schema, /mcp와 /hooks로 연결 상태를 확인하면 MCP, CLI 자동화, 테스트 자동화 흐름의 장애를 재현 가능한 개발 생산성 문제로 바꿀 수 있다.

참고: Claude Code debug configuration

Redirecting to Claude Code 상세 사용법 39: 설정이 안 먹힐 때 진단 루프 | DAKER 커뮤니티...