TL;DR
- 「Claude Code 가 느리다」의 대부분은 컨텍스트 비대입니다. 스피너 상태 줄이 매 턴의 초와 토큰 수를 보여주니, 다른 도구를 찾기 전에 먼저 읽으세요.
- 불러오는 양을 줄이세요: /init 으로 CLAUDE.md 를 만들어 200 줄 미만으로 유지, 작업 사이에 /clear, 이어야 하는 세션은 초점을 좁힌 /compact.
- 일을 맞는 엔진에 보내세요: 루틴한 수정은 /model 로 더 빠른 기본 모델을, /context 로 창을 먹는 범인을 확인, 프로젝트마다 MCP 서버는 최소로.
- 느림의 일부는 당신 탓이 아닙니다: status.claude.com 에서 장애를 확인하고, 5 시간 롤링 제한을 지켜보세요 — 터미널 모니터가 리셋 카운트다운과 번레이트를 항상 보여줍니다.
Wait.. Claude Code is MADE Slow on Purpose? Heres How to Fix It
채널:AI LABS10:35
Why Claude Code Gets Slow and Forgetful and 4 Habits That Fix It
채널:Prompt to Prod11:00
Manage costs & usage limits — official documentation
공식 문서:code.claude.com/docs
이 페이지의 모든 명령·제한·기본값은 code.claude.com/docs 와 anthropics/claude-code 변경 로그로 검증했습니다. 위의 영상들은 화면과 사실의 출처입니다(상태 줄 표시와 5 시간 창 모니터 포함). 영상과 문서가 다르면 문서를 따릅니다.
스크린샷의 저작권은 각 제작자에게 있으며 정확한 타임스탬프로 딥링크됩니다. 얼굴이 나오는 프레임은 사용하지 않았습니다.
Claude Code 를 다시 빠르게, 단계별로
파트 1 — 시간이 어디 가는지 보기
- 1
텅 빈 세션에 실제 프롬프트 하나 보내기
프로젝트에서 claude 를 실행하고 실제 요청을 입력하세요. 새 세션은 웰컴 박스만 있는 상태에서 시작하므로, Claude 는 답하기 전에 파일을 읽어야 합니다 — 「Claude Code 가 느리다」 보고의 대부분은 이 탐색에서 시작됩니다. 입력 영역의 스피너 동사가 바뀌는 걸 지켜보세요.
새 세션: 웰컴 박스의 팁이 Claude Code 가 출발할 때의 전부입니다.0:08 에 보기 - 2
일하는 동안 상태 줄 읽기
diff 아래에 「Unravelling… (16s · 351 tokens · esc to interrupt)」 같은 줄이 나타납니다. 동사는 장식이고, 초와 토큰 수가 속도계입니다. Claude 가 생각 중인지, 기다리는지, 파일을 뒤지는지를 알려줍니다. 첫 편집 전에 매번 수백 토큰이 새어나간다면 컨텍스트가 느림의 원인입니다.
상태 줄이 속도계입니다: 동사, 초, 토큰, esc to interrupt.1:08 에 보기 - 3
diff 를 열어 한 번의 수정이 뭘 끌어들였는지 보기
작은 기능도 찾는 것부터 시작합니다. 영상의 글자 수 카운터 수정은 파일 하나에 9 줄 추가뿐이지만, 스피너가 가라앉기 전에 352 토큰을 썼습니다. 더 큰 리포지토리에서는 이 탐색이 디렉터리 나열과 무관한 파일 읽기로 번집니다 — 영상은 이를 「무관한 정보에 빠지는 것」이라 부릅니다.
파일 하나에 9 줄 추가했을 뿐 — 스피너는 토큰을 세고 있습니다.0:22 에 보기
파트 2 — 컨텍스트를 가볍게
- 4
/init 으로 CLAUDE.md 생성하기
/init 을 입력하고 「Initialize a new CLAUDE.md file with codebase documentation」을 고르세요. Claude 에게 리포지토리에 대한 지속 브리프를 주는 공식 명령으로, 새 세션이 매번 프로젝트를 다시 탐색하지 않게 합니다. 「매번 전부 읽는다」 불만의 가장 큰 해결책입니다.
/init 은 CLAUDE.md 를 생성하는 공식 방법입니다.3:38 에 보기 - 5
한 번뿐인 스캔을 맡기기
Claude 는 package.json, README, router 등을 읽은 뒤 파일을 씁니다 — 영상의 실행은 약 90 토큰의 도구 호출 후에 Deciphering… 스피너를 보여줍니다. 이 비용은 한 번만 지불합니다. 다음 세션부터 Claude 가 필요로 하는 컨텍스트는 CLAUDE.md 안에 있고 디스크에서 다시 읽지 않습니다.
한 번뿐인 스캔: 읽고, 찾고, 그리고 씁니다.2:22 에 보기 - 6
CLAUDE.md 는 가볍게 — 명령과 아키텍처만
완성된 파일에는 개발 명령, 데이터베이스 계층, 짧은 아키텍처 요약이 들어갑니다. 공식 문서는 CLAUDE.md 가 세션 시작 때마다 컨텍스트에 로드되므로 200 줄 미만을 권합니다. 비대해진 CLAUDE.md 는 자신이 해결할 문제를 재현합니다 — 전용 워크플로는 필요할 때 로드되는 skills 로 옮기세요.
명령과 아키텍처 — 매 세션 로드되는 파일은 짧게 유지하세요.3:50 에 보기 - 7
컨텍스트에 채우지 말고 시맨틱 검색으로 문서 가져오기
라이브러리 질문에는 영상처럼 Context7 MCP 가 get-library-docs 를 「best practices」 토픽과 함께 호출해 Microsoft 의 TypeScript 리포지토리에서 관련된 한 섹션만 받아옵니다. 시맨틱 검색은 필요한 조각만 돌려주고, 문서 전체를 창에 끌어들이지 않습니다.
get-library-docs 는 일치한 섹션만 돌려주지, 매뉴얼 전체를 돌려주지 않습니다.2:48 에 보기 - 8
/mcp 로 MCP 서버 연결 확인하기
/mcp 를 실행하고 서버가 「connected」로 표시되는지 확인하세요 — 영상은 claude mcp add 로 시맨틱 코드 검색 서버 Serena 를 추가하고 여기서 점검합니다. 영상과 문서의 주의점 두 가지: MCP 서버는 프로젝트 단위라 쓰려는 리포지토리마다 추가해야 하고, 시작 시 멈추는 서버는 그 프로젝트의 모든 세션을 느리게 만듭니다.
/mcp 는 느린 서버의 은신처입니다: serena 가 초록 connected 를 보여줍니다.5:31 에 보기
파트 3 — 모델·제한·모니터링
- 9
루틴한 작업은 더 빠른 모델에 맡기기
/model — 또는 IDE 의 피커 — 를 열어 엔진을 일에 맞추세요. 공식 문서는 Sonnet 을 일상 기본으로, Opus 를 복잡한 추론에 권하고, 단순한 서브에이전트 작업은 Haiku 로도 돌아갑니다. 빠른 모델은 어지러진 컨텍스트를 고치지 못하지만, 작은 편집에서는 응답 시간과 토큰 단가를 함께 줄여줍니다.
같은 프롬프트, 다른 엔진: 피커는 /model 과 IDE 툴바에 있습니다.4:32 에 보기 - 10
한도에 도달하면 무엇이 일어나는지 알아두기
Anthropic 문서는 분명합니다. 「You've hit your session limit」과 주간 한도 메시지는 시트 단위라 — 모델을 바꿔도 소용없고, 메시지에 리셋 시각이 표시됩니다. 모델별 한도는 /model 로 우회할 수 있고, v2.1.234 부터는 /rate-limit-options 메뉴로 리셋 후 작업을 자동 이어가게 할 수 있습니다.
「한도에 도달하면 무엇이 되나요?」에 대한 공식 답.4:44 에 보기 - 11
터미널 모니터로 소비 추적하기
영상이 권하는 것은 오픈소스 Claude Code Usage Monitor (GitHub 의 Maciek-roboblog, MIT 라이선스, uv 나 pip 로 설치)이며, 두 번째 터미널 탭에 두고 씁니다. Claude Code 자신의 세션 로그를 읽으므로 사용량이 작업 옆에 표시되고, 별도의 웹 UI 를 띄워둘 필요가 없습니다.
영상이 권하는 모니터: Maciek-roboblog/Claude-Code-Usage-Monitor.6:22 에 보기 - 12
리셋 카운트다운과 번레이트 지켜보기
TUI 에는 비용·토큰·메시지 바, Time to Reset 카운트다운(영상에서는 2 시간 52 분), 모델 분포, 그리고 「Tokens will run out: 3:00 PM」 같은 예측이 붙은 실시간 번레이트가 있습니다. 5 시간 창이 눈앞에 있으면 갑작스러운 느려짐은 더 이상 수수께끼가 아닙니다 — 천장이 다가오는 게 보입니다.
번레이트와 리셋 카운트다운, 터미널 탭 하나로.6:50 에 보기
Claude Code vs. Cursor, Codex, 그리고 지난달의 나
「claude code slower than cursor」「than codex」 검색은 대개 엔진이 아니라 환경의 차이를 비교하는 것입니다. 실제로 다른 점:
- 1Cursor 와 비교 — Cursor 는 자체 컨텍스트 파이프라인을 가지고, 영상 시점에는 모델 창을 약 120k 토큰으로 잘랐습니다. Claude Code 는 200k 전체 창을 주는 대신 리포지토리 내용을 더 많이 싣죠. 어느 쪽이 일반적으로 「빠른」 게 아니라, 창을 가볍게 유지하는 쪽이 빠르게 느껴집니다.
- 2Codex CLI 와 비교 — 물리 법칙은 같습니다. 프롬프트가 리포지토리 통째로 끌고 다니면 어떤 코딩 에이전트도 느려집니다. /clear, 가벼운 컨텍스트 파일, 초점을 좁힌 compact 는 Codex 에도 그대로 이식됩니다. 모델 큐와 레이트 제한은 터미널이 아니라 플랜이 결정합니다.
- 3지난달 Claude Code 와 비교(「예전보다 느리다」) — 먼저 의심할 것은 릴리스가 아니라 세션 길이입니다. 긴 세션은 오토 컴팩트 임계값을 넘고, 컴팩션 자체가 큰 요청입니다. /clear 와 두 줄 재브리프면 보통 옛날 날렵함이 돌아옵니다. 그다음 변경 로그를 확인하고 claude --safe-mode 로 커스터마이징을 배제하세요.
- 4claude.ai 채팅과 비교 — 채팅이 즉각적으로 느껴지는 건 리포지토리를 읽지 않기 때문입니다. Claude Code 는 그 기동 무게와 맞바꿔 행동 능력을 얻습니다: 전체 컨텍스트 창, 로컬 도구, 디스크 위의 편집. 첫 토큰 시간이 아니라 작업 완료 시간으로 평가하세요.
- 5솔직한 결론 — 상위 에이전트들의 모델 순수 지연은 비슷합니다. 체감 차이는 컨텍스트 크기, MCP 시작, 레이트 제한 대기열 세 가지 — 모두 측정 가능하고 모두 이 페이지에서 고칠 수 있습니다.
속도 때문에 도구를 바꿨다면 같은 작업을 두 번 — 매 턴 전에 /context 를 읽으며 — 돌리고 토큰 수를 비교하세요. 「이 도구가 더 빠르다」 이야기 대부분은 사실 「이 세션이 더 작았다」입니다.
그래도 느린가요? 체크리스트를 돌아보세요
느림에는 뚜렷이 다른 원인들이 있고, 저마다 신호가 있습니다. 위의 단계로 설명되지 않으면 이 목록을 순서대로:
- 1오늘은 어디서든 빙빙 돈다 → status.claude.com 을 먼저 보세요. 프로바이더 장애는 긴 대기와 재시도로 모든 환경에 동시에 나타납니다. 로컬에서는 못 고치며, 상태 줄의 토큰 수는 이상하게 낮은 채 초만 올라갑니다.
- 2「Invalid API key · Please run /login」 같은 오류 → 속도가 아니라 인증 문제지만, 세션을 멈추게 하는 점은 같습니다. /login 으로 재인증하세요. 고집스러우면 문서 권고대로 /logout, Claude Code 종료, 재시작입니다. 남아 있는 ANTHROPIC_API_KEY도 해제하세요 — 구독 로그인을 덮어씁니다.
- 3한 시간 작업 후에만 느리다 → 컨텍스트 창이 가득 찬 겁니다. 오토 컴팩트는 임계값 근처에서 오래된 히스토리를 요약하고, 컴팩션 자체가 큰 요청입니다. 초점을 좁힌 /compact (예: 계획과 diff 만 유지)나 /clear 후 두 줄 브리프로 다시 시작하세요.
- 4connecting 이나 MCP 시작에서 멈춘다 → /mcp 를 실행해 멈춰 있는 서버를 찾아 그 프로젝트에서 제거하세요. 시작은 최근 크게 개선됐습니다. v2.1.292 는 느린 stdio 서버를 7 일간 기억하고, headless 첫 턴은 HTTP 서버 응답을 기다리지 않습니다.
- 5몇 분 멈췄다 스스로 재개된다 → 사용 한도에 도달한 겁니다. 세션 한도 메시지에는 리셋 시각이 표시되고, 시트 단위 한도는 모델 교체로 못 피합니다. /rate-limit-options (v2.1.234+) 는 리셋 후 자동 재개를, /model 은 모델별 한도에만 유효합니다.
- 6터미널 자체가 느리다 — 스크롤 지연, 고스트 텍스트, 타이핑 지연 → 추론이 아니라 렌더링 문제입니다. claude --safe-mode 를 실행하면 한 세션 동안 훅과 상태 줄 스크립트가 꺼집니다. 느림이 사라지면 statusline 스크립트나 hooks 를 다듬으세요. 같은 세션을 VS Code 패널과 터미널에서 각각 돌리면 더 좁혀집니다.
문서에서 한 가지 더: 세션 메모리가 2.5GB 를 넘으면 재시작하세요 — claude --continue 가 대화를 새 프로세스로 복귀시킵니다. 보통 두고 온 프로세스보다 빠릅니다.