Claude Code 상세 사용법 54: 느려짐과 멈춤을 운영 이슈로 다루기 | DAKER 커뮤니티

Claude Code 상세 사용법 54: 느려짐과 멈춤을 운영 이슈로 다루기

Claude Code가 느려지거나 멈출 때 “프롬프트를 더 잘 써야 하나?”부터 고민하면 원인이 흐려집니다. 공식 troubleshooting 문서는 high CPU와 memory, auto-compact thrashing, hang, terminal rendering, search 문제를 각각 다른 복구 루프로 나눕니다. 클로드 코드 성능 문제는 모델 품질 문제가 아니라 context, 파일 시스템, extension, 검색 표면의 운영 이슈일 때가 많습니다.

Mermaid 흐름으로 보는 성능 진단

아래 Mermaid source처럼 먼저 context를 줄이고, 그 다음 custom surface를 격리하고, 마지막에 검색과 OS 환경을 봅니다.

Mermaid source:
flowchart TD
  A[Slow or unstable session] --> B[/compact and restart]
  B --> C[Check safe mode]
  C --> D[Inspect search and ripgrep]
  D --> E[Resume or report with evidence]

CPU와 메모리가 높을 때

큰 코드베이스를 오래 다루면 context와 tool output이 커집니다. 먼저 /compact로 핵심 계획과 diff만 남기고, 큰 작업 단위가 끝났으면 Claude Code를 재시작하세요. build output, generated file, dependency cache가 검색에 계속 걸리면 .gitignore에 넣어 작업 표면을 줄입니다.

/compact keep only the current plan, modified files, and failing test output

그래도 메모리가 계속 증가하면 /heapdump를 실행해 heap snapshot과 memory breakdown을 남깁니다. 이 파일은 사람에게 읽히는 보고서가 아니라 문제 재현을 위한 증거입니다.

auto-compact thrashing

Autocompact is thrashing은 자동 압축 자체가 실패했다는 뜻이 아닙니다. 압축 직후 큰 파일이나 긴 tool output이 context를 다시 채워서 루프가 된 상태입니다. 복구 순서는 작게 읽기, focused compact, subagent 분리, /clear입니다.

이 파일 전체를 읽지 말고 120-220라인의 함수만 분석해줘.
/compact keep only the bug hypothesis and the edited diff

agentic coding에서 중요한 습관은 “더 많이 읽기”가 아니라 “지금 필요한 범위만 읽기”입니다.

멈춤과 터미널 깨짐

명령이 멈추면 먼저 Ctrl+C로 현재 작업을 취소합니다. 반응이 없으면 터미널을 닫고 같은 directory에서 claude --resume으로 이어갑니다. 대화 기록은 로컬에 남아 있어 재시작이 곧 손실은 아닙니다.

claude --resume

VS Code, Cursor, Devin Desktop 통합 터미널에서 글자가 깨지면 /terminal-setup을 실행하거나 editor의 GPU acceleration을 끕니다. 이 문제는 프롬프트나 모델이 아니라 렌더러 문제입니다.

검색이 파일을 못 찾을 때

Search, @file, custom agent, skill이 파일을 못 찾으면 bundled ripgrep이 시스템에서 실행되지 않는 경우가 있습니다. platform ripgrep을 설치하고 내장 ripgrep을 끕니다.

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

WSL에서는 /mnt/c 같은 Windows filesystem 위에서 검색 성능이 떨어져 결과가 적게 나올 수 있습니다. 가능하면 repo를 /home 아래로 옮기고, 검색어도 package나 파일 타입으로 좁히세요.

실패 모드

느린 세션에서 MCP, hook, plugin을 동시에 의심하면 오래 걸립니다. 먼저 claude --safe-mode로 custom surface를 모두 끄고 비교하세요. 문제가 사라지면 설정 디버깅 루프로 넘어가고, 사라지지 않으면 filesystem, 터미널, provider 상태를 봅니다.

시니어 엔지니어의 결론

Claude Code 성능 문제의 해법은 “더 강한 모델”이 아닐 때가 많습니다. context를 줄이고, 큰 출력은 잘라 읽고, custom extension을 safe mode로 격리하고, 검색 도구와 filesystem을 점검하세요. 이 루프가 있어야 바이브코딩이 개인 감각이 아니라 팀이 운영 가능한 LLM 개발 워크플로우가 됩니다.

참고: Anthropic Claude Code troubleshooting, context window, llms.txt 문서를 2026-06-12 Asia/Seoul 기준으로 확인했습니다.