Claude Code가 설치되고 로그인도 됐는데, 쓰다 보면 느려지거나 멈추거나 글자가 깨지거나 검색이 파일을 못 찾는 경우가 있습니다. 이 글은 그렇게 실행 중에 생기는 성능·안정성 문제를 Claude Code 공식 문서 기준으로 다룹니다. 설치·로그인·연결 자체가 안 된다면 설치·인증·연결 문제 해결 가이드를 먼저 보세요.
증상별로 어디를 봐야 하나
문제 유형에 따라 봐야 할 곳이 다릅니다. 어디인지 헷갈리면 Claude Code 안에서 /doctor를 실행하세요. 설치·설정·MCP 서버·컨텍스트 사용량을 한 번에 자동 점검해 줍니다. claude가 아예 켜지지 않으면 셸에서 claude doctor를 실행합니다.
느리거나 메모리를 많이 쓸 때
Claude Code는 대규모 코드베이스를 다룰 때 리소스를 많이 쓸 수 있습니다. 다음 순서로 시도하세요.
/compact를 정기적으로 써서 컨텍스트 크기를 줄입니다.- 큰 작업과 작업 사이에 Claude Code를 닫았다 다시 엽니다.
- 큰 빌드 디렉토리를
.gitignore에 추가합니다. claude --safe-mode로 재시작해 플러그인·MCP 서버·hook이 원인인지 확인합니다(모든 커스터마이징을 끈 채 실행). 사용량이 줄면 그중 하나가 원인입니다.
그래도 메모리가 높으면 /heapdump를 실행하세요. 힙 스냅샷과 메모리 분석이 ~/Desktop(데스크톱 폴더가 없는 Linux는 홈 디렉토리)에 저장되며, GitHub 이슈로 보고할 때 함께 첨부하면 됩니다.
"Autocompact is thrashing" 오류가 날 때
Autocompact is thrashing... 메시지는 자동 압축은 성공했지만, 파일이나 도구 출력이 컨텍스트 창을 곧바로 다시 가득 채우는 일이 연달아 일어났다는 뜻입니다. Claude Code는 진전 없는 반복에 API 호출을 낭비하지 않으려고 재시도를 멈춥니다. 이렇게 복구하세요.
- 큰 파일은 전체 대신 특정 줄 범위나 함수 단위로 나눠 읽게 요청합니다.
- 큰 출력을 버리도록 초점을 줘서
/compact를 실행합니다(예: "계획과 diff만 남겨줘"). - 큰 파일 작업은 별도 컨텍스트 창에서 도는 서브에이전트로 옮깁니다.
- 앞선 대화가 더 필요 없으면
/clear로 비웁니다.
명령이 멈추거나 응답이 없을 때
Claude Code가 응답하지 않으면 먼저 Ctrl+C로 현재 작업 취소를 시도합니다. 그래도 반응이 없으면 터미널을 닫고 다시 시작해야 할 수 있습니다. 재시작해도 대화는 사라지지 않습니다 — 같은 디렉토리에서 claude --resume을 실행하면 세션을 이어서 쓸 수 있습니다.
편집기 터미널에서 글자가 깨질 때
VS Code·Cursor·Devin Desktop의 통합 터미널에서 글자가 네모·뭉개짐·이상한 모양으로 보이면 터미널의 GPU 렌더러가 원인일 가능성이 큽니다. Claude Code 안에서 /terminal-setup을 실행하면 terminal.integrated.gpuAcceleration을 "off"로 설정해 줍니다(또는 편집기 설정에서 직접 끄고 창을 새로고침).
검색이 파일을 못 찾을 때
Search 도구, @file 멘션, 커스텀 에이전트·스킬이 파일을 못 찾는다면, 번들된 ripgrep 바이너리가 시스템에서 실행되지 않는 것일 수 있습니다. 플랫폼용 ripgrep을 설치한 뒤 그것을 쓰도록 알려주세요.
brew install ripgrep # macOS
sudo apt install ripgrep # Ubuntu/Debian
winget install BurntSushi.ripgrep.MSVC # Windows그런 다음 환경변수에 USE_BUILTIN_RIPGREP=0을 설정합니다.
WSL에서 검색이 느리거나 결과가 적을 때
WSL에서 파일시스템을 넘나들면 디스크 읽기 성능 저하로 예상보다 적은 검색 결과가 나올 수 있습니다(검색은 동작하지만 매치가 줄어듦). 이때 /doctor는 검색을 정상으로 표시합니다. 해결책: ① 디렉토리나 파일 유형을 지정해 더 구체적으로 검색, ② 프로젝트를 Windows 경로(/mnt/c/)가 아닌 Linux 파일시스템(/home/)에 두기, ③ WSL 대신 Windows 네이티브로 실행.
자주 쓰는 복구 명령
그래도 안 되면
위에서 해결되지 않으면 ① /doctor로 설치 상태·설정·MCP·컨텍스트를 한 번에 점검하고, ② Claude Code 안에서 /feedback 명령으로 Anthropic에 문제를 직접 보고하고, ③ GitHub 저장소에서 알려진 이슈를 확인하세요. Claude에게 기능·사용법을 직접 물어볼 수도 있습니다.
마무리
요약하면, 실행 중 문제는 /doctor 진단 → /compact로 컨텍스트 정리 → --safe-mode로 원인 격리 순서로 접근하면 대부분 좁혀집니다. 설치·로그인 단계에서 막혔다면 설치·인증·연결 문제 해결 가이드를 참고하세요. 이 내용은 Claude Code 공식 문서(Troubleshooting) 기준입니다.