컨텍스트에 로드된 항목 확인
/context 명령은 현재 세션의 컨텍스트 윈도우를 차지하는 모든 항목을 시스템 프롬프트, 메모리 파일, 스킬, 사용자 정의 서브에이전트(로드된 소스 포함), MCP 도구 및 대화 메시지로 분류하여 표시합니다. 먼저 이를 실행하여 CLAUDE.md, 규칙 또는 스킬 설명이 실제로 존재하는지 확인합니다.
특정 카테고리에 대한 세부 정보는 전용 명령으로 팔로우업합니다:
메모리 파일이
/memory에서 누락된 경우, CLAUDE.md 파일이 로드되는 방식에 대해 해당 위치를 확인합니다. 하위 디렉토리 CLAUDE.md 파일은 Claude가 Read 도구로 해당 디렉토리의 파일을 읽을 때 요청 시 로드되며, 세션 시작 시가 아닙니다.
/memory가 파일이 로드되었음을 확인했지만 Claude가 여전히 특정 명령을 따르지 않는 경우, 문제는 파일이 로드되었는지 여부가 아니라 명령이 작성된 방식일 가능성이 높습니다. CLAUDE.md는 새로운 팀원에게 제공할 지침(예: 프로젝트 규칙, 빌드 명령 및 파일 위치)에 적합합니다.
명령이 여러 방식으로 해석될 수 있을 정도로 모호할 때, 두 파일이 상충하는 지시를 제공할 때, 또는 파일이 충분히 길어서 개별 규칙이 덜 주목받을 때 준수가 감소합니다. 효과적인 명령 작성은 준수를 높게 유지하는 특이성, 크기 및 구조 패턴을 다룹니다.
해결된 설정 확인
설정은 관리, 사용자, 프로젝트 및 로컬 범위에 걸쳐 병합됩니다. 관리 설정은 존재할 때 항상 우선합니다. 나머지 중에서는 더 가까운 범위가 로컬, 프로젝트, 사용자 순서로 더 넓은 범위를 재정의합니다. 일부 설정은 또한 명령줄 플래그 또는 환경 변수로 설정할 수 있으며, 이는 또 다른 재정의 계층으로 작동합니다. 설정이 적용되지 않는 것처럼 보일 때, 설정한 값은 보통 다른 범위 또는 환경 변수에 의해 재정의되고 있습니다./doctor를 실행하여 구성 및 설치를 확인합니다. 이는 잘못된 설정 파일, 중복 설치 및 사용하지 않는 확장 프로그램을 포함하여 발견한 내용을 보고한 다음, 체크인된 CLAUDE.md 콘텐츠 Claude가 코드베이스에서 파생할 수 있는 내용을 확인하고, 사용자가 확인한 후에만 적용하는 수정 사항을 제안합니다. CLAUDE.md 트림 확인은 Claude Code v2.1.206 이상이 필요합니다. v2.1.205 이전에는 /doctor가 읽기 전용 진단 화면을 열었고 f를 누르면 보고서를 Claude에게 보내 수정하도록 했습니다.
터미널에서 claude doctor는 세션을 시작하지 않고 읽기 전용 설치 및 설정 진단을 출력합니다.
/status를 실행하여 관리 설정이 적용 중인지 여부를 포함하여 활성 설정 소스를 확인합니다. 주어진 키에 대해 어느 범위가 우선하는지 이해하려면 범위가 상호작용하는 방식을 참조합니다.
MCP 서버 확인
/mcp를 실행하여 모든 구성된 서버, 해당 연결 상태 및 현재 프로젝트에 대해 승인했는지 여부를 확인합니다. 서버가 올바르게 정의되었지만 여전히 몇 가지 일반적인 이유로 도구를 제공하지 않을 수 있습니다:
.mcp.json의 프로젝트 범위 서버는 일회성 승인이 필요합니다. 프롬프트가 해제된 경우, 서버는/mcp에서 승인할 때까지 비활성화된 상태로 유지됩니다.- 시작에 실패한 서버는
/mcp에서 실패로 표시됩니다.command또는args의 상대 파일 경로는.mcp.json의 위치가 아니라 Claude Code를 시작한 디렉토리에 대해 해석되므로 빈번한 원인입니다. - 연결된 것으로 표시되지만 도구가 0개인 서버는 성공적으로 시작되었지만 도구 목록을 반환하지 않습니다.
/mcp에서 다시 연결을 선택합니다. 개수가 0으로 유지되면claude --debug mcp를 실행하여 서버의 stderr 출력을 확인합니다.
훅 확인
/hooks를 실행하여 현재 세션에 등록된 모든 훅을 이벤트별로 그룹화하여 나열합니다. 정의한 훅이 나타나지 않으면 읽혀지지 않는 것입니다: 훅은 독립 실행형 파일이 아니라 설정 파일의 "hooks" 키 아래에 있습니다.
훅이 나타나지만 실행되지 않으면, 매처가 보통 원인입니다. 다음 실수를 확인하십시오:
matcher필드는 여러 도구 이름을 일치시키기 위해|를 사용하는 단일 문자열입니다(예:"Edit|Write").,구분 기호는 동등하므로"Edit,Write"는 동일한 도구를 일치시킵니다. v2.1.191 이전에는 쉼표가 정규식 평가로 넘어가고 매처가 일치하지 않으므로, v2.1.191이 아직 아니면|를 사용하십시오.- 잘못된 도구 이름은 아무것도 일치하지 않는 매처를 생성하므로 훅이 자동으로 실패합니다.
- 배열 값은 스키마 오류입니다: Claude Code는 설정 오류 알림을 표시하고 전체 사용자, 프로젝트 또는 로컬 설정 파일을 거부하며,
claude doctor는 검증 실패를 보고하고, 해당 파일의 훅이/hooks에 나타나지 않습니다. 관리되는 설정에서는 유효하지 않은 항목만 제거되고 파일의 다른 훅은 계속 적용됩니다.
settings.json에 대한 편집은 짧은 파일 안정성 지연 후 실행 중인 세션에서 적용됩니다. 다시 시작할 필요가 없습니다. 저장 후 몇 초가 지났는데도 /hooks가 여전히 이전 정의를 표시하면 /hooks를 다시 실행하여 보기를 새로 고칩니다.
/hooks가 훅을 표시하지만 여전히 실행되지 않으면, 다음 단계는 훅 평가를 실시간으로 감시하는 것입니다. claude --debug hooks로 세션을 시작하고 도구 호출을 트리거합니다. 디버그 로그는 각 이벤트, 확인된 매처 및 훅의 종료 코드와 출력을 기록합니다. 로그 형식은 훅 디버깅을 참조하고 일반적인 실패 패턴은 훅 문제 해결을 참조합니다.
깨끗한 구성에 대해 테스트
claude --safe-mode로 시작합니다. 이는 CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령 및 에이전트를 포함한 모든 사용자 정의가 비활성화된 세션을 시작합니다. 인증, 모델 선택, 기본 제공 도구 및 권한은 정상적으로 작동합니다. 안전 모드에서 문제가 사라지면, 이러한 표면 중 하나가 원인입니다. 위의 대상 확인을 사용하여 어느 것인지 찾습니다. 안전 모드는 여전히 조직에서 배포한 관리 훅 및 설정 정책을 적용합니다. 관리 플러그인, 스킬, CLAUDE.md 및 MCP 서버는 꺼집니다.
안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. CLAUDE_CONFIG_DIR을 빈 디렉토리로 지정하여 ~/.claude 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 .claude 폴더, .mcp.json 또는 CLAUDE.md가 없는 디렉토리에서 시작합니다.
- 조직이 배포하는 경우 관리 설정은 여전히 적용됩니다. 이들은
~/.claude외부의 시스템 경로에 있기 때문입니다. - Linux 및 Windows에서는 자격 증명이 구성 디렉토리 아래에 저장되므로 다시 로그인하라는 메시지가 표시됩니다.
- macOS에서는 자격 증명이 Keychain에 있으며 깨끗한 세션으로 이월됩니다.
~/.claude 또는 프로젝트 .claude 파일 어딘가에 있습니다. 임시 디렉토리에 파일을 복사하거나 프로젝트에서 시작하여 한 번에 하나씩 다시 도입하여 어느 것인지 찾습니다. 깨끗한 세션에서 지속되면, 원인은 사용자 및 프로젝트 구성 외부에 있습니다. /status를 실행하여 관리 설정이 적용 중인지 확인하고, Claude Code에 영향을 미치는 환경 변수를 찾은 다음, 문제 해결을 참조합니다.
일반적인 원인 확인
대부분의 구성 놀라움은 작은 위치 및 구문 규칙 집합으로 추적됩니다. 버그라고 가정하기 전에 다음을 확인합니다:관련 리소스
각 구성 표면에 대한 전체 참조는 전용 페이지를 참조합니다:.claude디렉토리 참조: 모든 구성 파일 위치 및 읽는 항목- 설정: 우선순위 순서 및 전체 키 목록
- 훅 참조: 이벤트 이름, 페이로드 및
--debug hooks출력 형식 - MCP: 서버 구성, 승인 및
/mcp출력 - 설치 및 로그인 문제 해결:
command not found, PATH 및 인증 문제 - 문제 해결: 성능, 응답 중단 및 검색 문제