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

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

/context 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 시스템 도구, MCP 도구, 사용자 정의 서브에이전트(로드된 소스 포함), 메모리 파일, 스킬 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 CLAUDE.md, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다. /context의 스킬 섹션에는 /skills에서 나열하지 않는 번들 스킬도 포함됩니다. 특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다: 메모리 파일이 /context 분류에서 누락된 경우, CLAUDE.md 파일이 로드되는 방식에 대해 해당 위치를 확인합니다. 하위 디렉토리 CLAUDE.md 파일은 세션 시작 시가 아니라 필요할 때 로드되므로 해당 분류에 나타나지 않습니다. /context가 파일이 로드되었음을 확인했지만 Claude가 여전히 특정 명령을 따르지 않는 경우, 문제는 파일이 로드되었는지 여부가 아니라 명령이 작성된 방식일 가능성이 높습니다. CLAUDE.md는 새로운 팀원에게 제공할 지침(예: 프로젝트 규칙, 빌드 명령 및 파일 위치)에 적합합니다. 명령이 여러 방식으로 해석될 수 있을 정도로 모호할 때, 두 파일이 상충하는 지시를 제공할 때, 또는 파일이 충분히 길어서 개별 규칙이 덜 주목받을 때 준수가 감소합니다. 효과적인 명령 작성은 준수를 높게 유지하는 특이성, 크기 및 구조 패턴을 다룹니다.
CLAUDE.md와 권한은 서로 다른 문제를 해결합니다. CLAUDE.md는 Claude에게 프로젝트가 어떻게 작동하는지 알려주어 좋은 결정을 내리도록 합니다. 권한 및 훅은 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를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 Claude Code가 해당 훅을 로드하지 않은 것입니다. 다음 원인을 확인하십시오:
  • 훅이 독립 실행형 파일에 정의되어 있습니다. 훅은 설정 파일의 "hooks" 키 아래에 있어야 합니다.
  • matcher 값이 단일 문자열이 아닌 배열입니다. Claude Code는 대화형 세션을 시작할 때와 claude doctor에서 해당 항목을 잘못된 설정으로 나열합니다. 배열이 PreToolUse 또는 PermissionRequest 아래에 있으면 해당 파일의 다른 훅도 모두 로드되지 않습니다.
훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:
  • matcher 필드는 여러 도구 이름을 일치시키기 위해 |를 사용하는 단일 문자열입니다(예: "Edit|Write"). , 구분 기호는 동등하므로 "Edit,Write"는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면 |를 사용하십시오.
  • 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.
settings.json을 편집하면 파일 안정성 지연 후 실행 중인 세션에서 변경 사항이 적용됩니다. 세션이 시작된 후 파일이나 프로젝트의 .claude/ 폴더를 생성한 경우에도 다시 시작할 필요가 없습니다. v2.1.257 이전에는 Claude Code가 세션이 시작된 후 생성된 .claude/ 폴더의 편집을 감지하지 못했습니다. 저장 후 몇 초가 지났는데도 /hooks가 여전히 이전 정의를 표시하면 /hooks를 다시 실행하여 보기를 새로 고칩니다. /hooks가 훅을 표시하지만 여전히 실행되지 않으면, 다음 단계는 훅 평가를 실시간으로 감시하는 것입니다. claude --debug로 세션을 시작하고 도구 호출을 트리거합니다. 디버그 로그는 각 이벤트, 확인된 매처 및 훅의 종료 코드와 출력을 기록합니다. 로그 형식은 훅 디버깅을 참조하고 일반적인 실패 패턴은 훅 문제 해결을 참조합니다.

​
깨끗한 구성에 대해 테스트

claude --safe-mode로 시작합니다. 이는 다음을 포함한 사용자 정의가 비활성화된 세션을 시작합니다.
  • CLAUDE.md
  • 스킬, 플러그인 및 훅
  • MCP 서버
  • 사용자 정의 명령 및 에이전트
  • 사용자 정의 출력 스타일
  • 사용자 정의 키보드 단축키
인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 비활성화한 항목 중 하나로 원인이 좁혀진 것입니다. 어느 것인지 찾으려면 컨텍스트에 로드된 항목 확인, MCP 서버 확인 또는 훅 확인과 같이 해당 항목에 대한 확인 방법을 사용합니다. 안전 모드는 여전히 조직의 관리형 훅 및 설정 정책을 적용합니다. 관리형 플러그인, 스킬, CLAUDE.md 및 MCP 서버는 꺼집니다. 안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 사용자 자신의 구성이 전혀 없는 세션을 시작하여 문제가 계속 나타나는지 확인합니다.
1

빈 디렉토리를 만들고 해당 디렉토리로 이동

Claude Code 세션이 실행되지 않은 상태에서 셸에서 디렉토리를 만들고 해당 디렉토리로 이동합니다.
2

깨끗한 구성 디렉토리로 Claude Code 시작

같은 셸에서 CLAUDE_CONFIG_DIR을 ~/.claude 대신 새 디렉토리로 설정하고, --setting-sources user를 전달하여 .claude/settings.json, CLAUDE.md, .mcp.json과 같은 프로젝트 구성을 끕니다.
이 변수는 이번 한 번의 실행에만 적용됩니다.
첫 번째 실행 시 첫 실행 설정 화면을 다시 거치게 되며, 이는 깨끗한 구성 디렉토리가 적용 중이라는 표시입니다. 관리형 설정은 여전히 적용되며, claude.ai 계정으로 로그인하면 커넥터도 계속 로드됩니다.
3

문제 재현

깨끗한 세션에서 문제를 일으킨 작업을 반복합니다.
  • 문제가 사라진 경우: 원인은 사용자 또는 프로젝트 구성에 있습니다. ~/.claude.json과 ~/.claude의 파일을 한 번에 하나씩 ~/claude-clean/config로 복사합니다. 어느 파일로도 문제가 다시 나타나지 않으면, 같은 셸에서 프로젝트 디렉토리로 이동하여 --setting-sources user 없이 Claude Code를 시작합니다. Bash 또는 Zsh에서는 CLAUDE_CONFIG_DIR=~/claude-clean/config claude를 실행합니다. PowerShell에서는 변수가 아직 설정되어 있으므로 claude를 실행합니다.
  • 문제가 지속되는 경우: 원인은 사용자 및 프로젝트 구성 외부에 있습니다. 세션에서 /status를 실행하여 관리형 설정을 확인하고, 셸에서 환경 변수를 확인한 다음, 문제 해결을 참조합니다.

​
일반적인 원인 확인

대부분의 구성 문제는 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인하세요: 각 구성 표면에 대한 전체 참조는 전용 페이지를 참조합니다: