본문으로 건너뛰기

Claude Code 문제 해결

중급
What you'll learn
  • 증상 표를 이용해 어떤 Claude Code 문제든 한 단계 만에 해당 해결책으로 연결하기
  • 직접 손으로 디버깅하기 전에 대부분의 설정 문제를 해결하는 두 가지 진단 명령 실행하기
  • 플러그인, MCP 서버, 훅 중 무엇이 실제 원인인지 격리하기
  • 네 가지 고전적 런타임 실패 해결하기: 높은 메모리, 멈춤, 압축 반복, 아무것도 찾지 못하는 검색
  • 버그 리포트를 제출하기 전에 올바른 증거 수집하기

핵심 개념​

거의 모든 Claude Code 문제는 두 종류 중 하나이며, 그 해결책은 완전히 다릅니다:

  • 설정이 잘못됨 — 플러그인, MCP 서버, 훅, 설정 파일, 누락된 바이너리. 해결책은 구성입니다.
  • 세션이 부하를 받음 — 컨텍스트 창이 가득 찼거나, 거대한 파일이 메모리를 폭발시켰거나, 터미널이 렌더링하지 못함. 해결책은 위생 관리입니다.

어느 쪽인지 추측하는 데서 사람들은 오후 하나를 날립니다. 아래 표는 그 추측을 건너뜁니다.

:::tip 다른 종류의 "이상함"인가요? 이 페이지는 도구의 오작동에 관한 것입니다 — 시작되지 않거나, 멈추거나, 검색이 아무것도 못 찾는 경우죠. 모델이 오작동하는 경우라면 — 사실을 지어내거나, 지시를 잊거나, 합리적인 요청을 거절하는 경우 — 그건 다른 페이지입니다: Claude가 왜 그랬을까? :::

여기서 시작: 증상 → 이동할 곳​

당신의 증상을 찾으세요. 페이지의 나머지는 읽지 마세요.

증상이동할 곳
command not found, 설치 실패, EACCES, PATH 또는 TLS 오류공식: 설치 및 로그인
로그인 반복, OAuth 오류, 403 Forbidden, "organization disabled"공식: 로그인 및 인증
설정이 적용되지 않음, 훅이 실행되지 않음, MCP 서버가 로드되지 않음아래 설정 격리하기
API Error: 5xx, 529 Overloaded, 429, 검증 오류오류 및 속도 제한
model not found / "you may not have access to it"현재 모델 및 가격
VS Code 또는 JetBrains가 Claude를 감지하지 못함IDE 통합
높은 CPU 또는 메모리아래 메모리와 CPU
멈춤, 정지, 무응답아래 멈춤과 정지
Autocompact is thrashing아래 압축 반복
검색, @file, 에이전트, 스킬이 파일을 찾지 못함아래 검색이 아무것도 못 찾음
IDE 터미널에서 상자, 번짐, 잘못된 글리프아래 깨진 터미널 텍스트

먼저 실행할 두 가지 명령​

직접 손으로 디버깅하기 전에, 내장 점검을 실행하세요. 설치, 설정, 확장, 컨텍스트 사용량을 진단하고 — 확인 후 적용할 수 있는 해결책을 제안합니다.

Guided walkthrough1 of 3
  1. /doctor(별칭 /checkup)는 설치, 설정, 확장, 컨텍스트 사용량을 검사한 다음, 적용할 수 있는 해결책을 제안합니다. 이것만으로 대부분의 설정 관련 불만이 해결됩니다.

망가진 설정 진단하기

# inside a session
/doctor

# if the session won't start at all
claude doctor

# check MCP server status
/mcp

설정 격리하기​

설정이 적용되지 않거나, 훅이 실행되지 않거나, 무언가가 그냥 이상하다면, 질문은 결코 "무엇이 망가졌는가"가 아니라 — 당신의 커스터마이징 중 무엇이 망가졌는가입니다. 그것들을 한꺼번에 제거해서 답하세요.

--safe-mode는 모든 커스터마이징을 비활성화한 채로 Claude Code를 시작합니다: 플러그인 없음, MCP 서버 없음, 훅 없음.

깨끗한 구성에 대해 테스트하기

claude --safe-mode

이것은 깨끗한 이분법적 결과를 제공합니다:

커스터마이징이 원인임을 알게 되면, 이분 탐색을 하세요: 문제가 돌아올 때까지 그룹 단위로 다시 활성화하세요. 원인일 확률이 높은 순서대로 대략 나열하면 MCP 서버, 훅, 플러그인, 설정입니다.

Pro tip
  • --safe-mode는 완전한 고장뿐 아니라 원인 모를 느려짐에도 올바른 첫 수순입니다. 수다스러운 MCP 서버는 둘 다의 매우 흔한 원인입니다.

메모리와 CPU​

Claude Code는 대부분의 환경에서 동작하지만 큰 코드베이스에서는 실제 자원을 소비할 수 있습니다. 다음을 순서대로 진행하세요 — 비용이 가장 적은 것부터 정렬되어 있습니다.

Guided walkthrough1 of 5
  1. /compact를 실행해 컨텍스트를 줄이세요. 부풀어 오른 컨텍스트 창은 무거운 세션의 가장 흔한 단일 원인입니다. /docs/claude-code/context-management를 참고하세요.

/heapdump 분석은 상주 세트 크기(resident set size), JS 힙, 배열 버퍼(array buffers), 그리고 집계되지 않은 네이티브 메모리를 보고합니다. 그 분할이 유용한 부분입니다: 증가가 JavaScript 객체에 있는지 아니면 네이티브 코드 저편에 있는지 알려줍니다. 무엇이 메모리를 살아있게 붙잡고 있는지 살펴보려면, Chrome DevTools의 Memory → Load에서 .heapsnapshot 파일을 여세요.

멈춤과 정지​

Claude Code가 응답을 멈추면:

Guided walkthrough1 of 3
  1. Ctrl+C를 누르세요. 세션을 죽이지 않고 실행 중인 것을 중단합니다.
Pro tip
  • 긴 대화를 잃을까 봐 두려운 것이 사람들이 멈춤을 죽이는 대신 기다리는 이유입니다. 그러지 마세요 — 같은 디렉터리에서 claude --resume를 하면 세션이 돌아옵니다.

압축 반복​

이 오류는 경보처럼 보이지만 실제로는 보호 장치입니다:

Autocompact is thrashing: the context refilled to the limit...

이것은 자동 압축이 성공했음을 의미합니다 — 그런 다음 파일이나 도구 출력이 즉시 전체 컨텍스트 창을 다시 채우는 일이 연속으로 여러 번 일어난 것입니다. Claude Code는 진전이 없는 루프에 API 호출을 태우기보다 재시도를 멈춥니다.

원인은 거의 항상 지나치게 큰 무언가를 통째로 읽는 것입니다. 당신의 상황에 맞는 해결책을 고르세요:

상황해결책
하나의 거대한 파일이 문제파일 전체 대신 라인 범위나 단일 함수를 읽도록 Claude에게 요청하세요
컨텍스트에 더 이상 필요 없는 큰 출력물이 있음그것을 버리는 초점을 주며 /compact
큰 읽기가 정말로 필요함그것을 서브에이전트로 옮겨 별도의 컨텍스트 창을 소비하게 하세요
이전 대화가 더 이상 중요하지 않음/clear

군더더기를 버리는 초점으로 압축하기

/compact keep only the plan and the diff

서브에이전트 옵션은 사람들이 잊는 것이며, 종종 최선입니다: 서브에이전트가 자신의 컨텍스트에서 거대한 파일을 읽고 결론만 당신에게 반환합니다. 컨텍스트 관리와 서브에이전트를 참고하세요.

검색이 아무것도 못 찾음​

검색 도구, @file 멘션, 커스텀 에이전트, 또는 커스텀 스킬이 존재한다고 확신하는 파일을 찾지 못한다면, 번들된 ripgrep 바이너리가 당신의 시스템에서 실행되지 못하는 것일 가능성이 높습니다. 해결책은 당신 플랫폼의 자체 ripgrep을 설치하고 Claude Code에게 그것을 쓰라고 알려주는 것입니다.

Guided walkthrough1 of 3
  1. macOS: brew install ripgrep — Ubuntu/Debian: sudo apt install ripgrep — Alpine: apk add ripgrep — Arch: pacman -S ripgrep — Windows: winget install BurntSushi.ripgrep.MSVC

macOS에서 검색 고치기

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

WSL 예외​

WSL에서는 불완전한 검색 결과가 대개 망가진 바이너리 때문이 아닙니다. Windows/Linux 파일 시스템 경계를 넘나들며 읽는 것은 디스크 성능 페널티를 수반하므로, 검색은 예상보다 적은 매치를 반환합니다. 검색은 여전히 작동합니다 — 그저 덜 내어줄 뿐입니다.

Watch out
  • WSL에서는 결과가 불완전해도 claude doctor가 Search를 OK로 보고합니다. 녹색 점검이 이것을 배제하지 못합니다 — 바로 그 점이 진단을 어렵게 만듭니다.

빠져나가는 세 가지 방법, 좋은 순서대로: 프로젝트를 /mnt/c/가 아니라 Linux 파일 시스템(/home/)으로 옮기기; WSL을 통하지 말고 Windows에서 Claude Code를 네이티브로 실행하기; 또는 검색을 좁혀 더 적은 파일을 스캔하기 — "auth-service 패키지에서 JWT 검증 로직을 검색해줘"가 "인증 코드 찾아줘"보다 낫습니다.

깨진 터미널 텍스트​

VS Code, Cursor, 또는 Devin Desktop 통합 터미널 안에서 문자가 상자, 번짐, 또는 잘못된 글리프로 렌더링되는 것은 폰트나 인코딩 문제가 아니라 GPU 렌더러 문제입니다.

IDE 터미널의 깨진 글리프 고치기

/terminal-setup

그것은 terminal.integrated.gpuAcceleration을 "off"로 설정합니다. 대신 에디터 설정에서 직접 설정하고 창을 다시 로드해도 됩니다 — 같은 결과입니다.

큰 표가 잘림​

200행이 넘는 마크다운 표는 처음 200행을 렌더링한 뒤 … N more rows not shown 줄을 표시합니다. 이것은 표시 제한일 뿐입니다 — 전체 표는 여전히 대화에 있으며, /copy는 모든 행을 복사합니다. 터미널에서 도저히 읽을 수 없을 만큼 큰 표라면, Claude에게 파일로 써 달라고 요청하세요.

좋은 버그 리포트 작성하기​

여기 있는 어떤 것도 맞지 않으면 보고하세요 — 단, 증거를 가져오세요. "느려요"라고 하는 리포트는 아무 데도 가지 못하고, 힙 스냅샷과 --safe-mode 결과를 담은 리포트는 고쳐집니다.

Guided walkthrough1 of 4
  1. 점검이 뭐라고 하는지, 그리고 실제로 어떤 MCP 서버가 로드되었는지 기록하세요. 보고되는 버그의 절반은 여기서 답이 나옵니다.
Key takeaways
  • /doctor(별칭 /checkup)를 먼저 실행하세요 — 세션이 시작되지 않으면 셸에서 claude doctor로. 설치, 설정, 확장, 컨텍스트 사용량을 진단하고 해결책을 적용할 수 있습니다.
  • claude --safe-mode는 모든 커스터마이징을 한꺼번에 비활성화합니다. 문제가 그것을 견디고 살아남는지가 당신이 모을 수 있는 가장 유익한 단일 사실입니다.
  • 높은 메모리: /compact, 작업 사이 재시작, 빌드 디렉터리 .gitignore, 그다음 --safe-mode, 그다음 증거를 위한 /heapdump.
  • 멈춤은 대화를 잃은 것이 아닙니다 — Ctrl+C, 그다음 터미널 재시작, 그다음 같은 디렉터리에서 claude --resume.
  • Autocompact 반복은 지나치게 큰 읽기 하나가 창을 다시 채운다는 뜻입니다. 청크 단위로 읽거나, 초점을 주며 /compact 하거나, 읽기를 서브에이전트에 위임하세요.
  • 검색이 아무것도 못 찾으면 대개 번들된 ripgrep이 실행되지 못하는 것입니다: 당신 플랫폼의 ripgrep을 설치하고 USE_BUILTIN_RIPGREP=0도 설정하세요. WSL에서는 대신 파일 시스템 경계 페널티이며 — claude doctor는 여전히 Search를 OK로 보고합니다.

스스로 점검하기

0/5
  1. 훅이 실행되지 않고 설정이 무시되는 것 같습니다. 시도해볼 가장 유익한 한 가지는 무엇인가요?
  2. Claude Code가 작업 도중 멈추고 Ctrl+C가 도움이 안 됩니다. 터미널을 닫습니다. 당신의 대화는 어떻게 되나요?
  3. 'Autocompact is thrashing: the context refilled to the limit...'가 보입니다. 실제로 무슨 일이 일어난 건가요?
  4. @file 멘션이 아무것도 못 찾아서 brew로 ripgrep을 설치했는데, 검색이 여전히 안 됩니다. 무엇을 놓쳤나요?
  5. WSL에서 검색이 예상보다 적은 매치를 반환하는데 claude doctor는 Search를 OK로 보고합니다. 무슨 일인가요?

다음​