메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

이 페이지는 Claude Code가 실행 중일 때의 성능, 안정성 및 검색 문제를 다룹니다. 다른 문제의 경우 문제가 있는 위치와 일치하는 페이지부터 시작하세요:
증상이동
command not found, 설치 실패, PATH 문제, EACCES, TLS 오류설치 및 로그인 문제 해결
로그인 루프, OAuth 오류, 403 Forbidden, “organization disabled”, Bedrock/Vertex/Foundry 자격 증명설치 및 로그인 문제 해결
설정이 적용되지 않음, hooks가 실행되지 않음, MCP 서버가 로드되지 않음구성 디버깅
API Error: 5xx, 529 Overloaded, 429, 요청 검증 오류오류 참조
model not found 또는 you may not have access to it오류 참조
VS Code 확장이 Claude에 연결되지 않거나 감지하지 못함VS Code 통합
JetBrains 플러그인 또는 IDE가 감지되지 않음JetBrains 통합
높은 CPU 또는 메모리, 느린 응답, 중단, 검색이 파일을 찾지 못함성능 및 안정성 아래
어떤 것이 적용되는지 확실하지 않으면 Claude Code 내에서 /doctor를 실행하여 설치, 설정, MCP 서버 및 컨텍스트 사용을 자동으로 확인하세요. claude가 전혀 시작되지 않으면 셸에서 claude doctor를 대신 실행하세요.

​
성능 및 안정성

이 섹션에서는 리소스 사용, 응답성 및 검색 동작과 관련된 문제를 다룹니다.

​
높은 CPU 또는 메모리 사용량

Claude Code는 대부분의 개발 환경에서 작동하도록 설계되었지만 대규모 코드베이스를 처리할 때 상당한 리소스를 소비할 수 있습니다. 성능 문제가 발생하는 경우:
  1. /compact를 정기적으로 사용하여 컨텍스트 크기 감소
  2. 주요 작업 사이에 Claude Code 닫기 및 다시 시작
  3. 큰 빌드 디렉토리를 .gitignore 파일에 추가하는 것을 고려하세요
메모리 사용량이 이 단계 후에도 높게 유지되면 /heapdump를 실행하여 JavaScript 힙 스냅샷과 메모리 분석을 ~/Desktop에 작성하세요. Linux에 Desktop 폴더가 없으면 파일이 홈 디렉토리에 작성됩니다. 분석은 상주 집합 크기, JS 힙, 배열 버퍼 및 설명되지 않은 네이티브 메모리를 표시하며, 이는 증가가 JavaScript 객체인지 네이티브 코드인지 식별하는 데 도움이 됩니다. Chrome DevTools의 메모리 → 로드에서 .heapsnapshot 파일을 열어 보유자를 검사하세요. GitHub에서 메모리 문제를 보고할 때 두 파일을 모두 첨부하세요.

​
자동 압축이 스래싱 오류로 중단됨

Autocompact is thrashing: the context refilled to the limit...이 표시되면 자동 압축이 성공했지만 파일 또는 도구 출력이 즉시 컨텍스트 창을 여러 번 연속으로 다시 채웠습니다. Claude Code는 진행되지 않는 루프에서 API 호출을 낭비하지 않기 위해 재시도를 중단합니다. 복구하려면:
  1. Claude에게 전체 파일 대신 특정 줄 범위 또는 함수와 같은 더 작은 청크로 큰 파일을 읽도록 요청하세요
  2. 큰 출력을 삭제하는 포커스로 /compact를 실행하세요. 예: /compact keep only the plan and the diff
  3. 큰 파일 작업을 서브에이전트로 이동하여 별도의 컨텍스트 창에서 실행하세요
  4. 이전 대화가 더 이상 필요하지 않으면 /clear를 실행하세요

​
명령 중단 또는 정지

Claude Code가 응답하지 않는 것처럼 보이면:
  1. Ctrl+C를 눌러 현재 작업을 취소하세요
  2. 응답하지 않으면 터미널을 닫고 다시 시작해야 할 수 있습니다
다시 시작해도 대화가 손실되지 않습니다. 같은 디렉토리에서 claude --resume을 실행하여 세션을 다시 시작하세요.

​
검색 및 발견 문제

Search 도구, @file 언급, 사용자 정의 에이전트 또는 사용자 정의 skills가 파일을 찾지 못하면 번들된 ripgrep 바이너리가 시스템에서 실행되지 않을 수 있습니다. 플랫폼의 ripgrep 패키지를 설치하고 Claude Code에 대신 사용하도록 지시하세요: 
brew install ripgrep
그런 다음 환경에서 USE_BUILTIN_RIPGREP=0을 설정하세요.

​
WSL에서 느리거나 불완전한 검색 결과

WSL에서 파일 시스템 간 작업할 때 디스크 읽기 성능 저하로 인해 WSL에서 Claude Code를 사용할 때 예상보다 적은 일치 항목이 발생할 수 있습니다. 검색은 여전히 작동하지만 네이티브 파일 시스템보다 적은 결과를 반환합니다.
이 경우 /doctor는 검색을 OK로 표시합니다.
해결책:
  1. 더 구체적인 검색 제출: 디렉토리 또는 파일 유형을 지정하여 검색되는 파일 수를 줄이세요: “auth-service 패키지에서 JWT 검증 로직 검색” 또는 “JS 파일에서 md5 해시 사용 찾기”.
  2. 프로젝트를 Linux 파일 시스템으로 이동: 가능하면 프로젝트가 Windows 파일 시스템(/mnt/c/) 대신 Linux 파일 시스템(/home/)에 있는지 확인하세요.
  3. Windows 기본 사용: 더 나은 파일 시스템 성능을 위해 WSL 대신 Windows에서 기본적으로 Claude Code를 실행하는 것을 고려하세요.

​
추가 도움 받기

여기에 다루지 않은 문제가 발생하는 경우:
  1. /doctor를 실행하여 설치 상태, 설정 유효성, MCP 구성 및 컨텍스트 사용을 한 번에 확인하세요
  2. Claude Code 내에서 /feedback 명령을 사용하여 Anthropic에 문제를 직접 보고하세요
  3. GitHub 저장소에서 알려진 문제를 확인하세요
  4. Claude에게 직접 기능 및 특징에 대해 물어보세요. Claude는 문서에 대한 기본 제공 액세스 권한이 있습니다.