클로드 코드가 말을 계속 안 듣는다? 원인부터 순서대로 짚어보는 가이드
클로드 코드가 말을 안 듣는 건지, 내가 너무 많은 걸 한 세션에 쌓았는지 처음엔 구분하기 어렵습니다. 답이 느려지고, 지시를 놓치고, 예전엔 잘 따라오던 규칙을 갑자기 안 지키기 시작하면 보통 설정을 하나씩 건드려 보게 되는데, 그러다 보면 뭘 고쳐서 나아졌는지도 같이 잊어버립니다.
아래 순서대로 보면 5분 안에 어디부터 손봐야 할지 정할 수 있어요.
0. 시작 전에 - 느린 순간부터 구분해요
| 이럴 때 | 먼저 볼 곳 |
|---|---|
| 클로드가 답을 시작하기 전부터 오래 걸림 | 컨텍스트, 모델, 네트워크 |
| 특정 도구나 명령을 쓸 때만 늦음 | MCP, Hook, 그 명령 자체의 실행 시간 |
| 테스트나 빌드가 오래 걸림 | 클로드가 아니라 프로젝트 명령, 디스크, 백그라운드 작업 |
새 대화를 켠 뒤 /context부터 쳐보세요.
아직 대화를 안 했는데도 컨텍스트가 비어 있지 않은 건 자연스러운 일입니다.
어떤 항목이 자리를 차지하는지만 보면 다음에 볼 곳이 정해집니다.바로 쓰는 5분 점검 프롬프트
내 Claude Code가 느려진 원인을 먼저 점검해줘. 아직 파일과 설정은 바꾸지 마.
1. 지금 세션의 /context를 보고, 큰 항목이 무엇인지 설명해줘.
2. 현재 프로젝트에 적용되는 CLAUDE.md와 주요 지침 파일이 너무 크거나 중복되는지 확인해줘.
3. MCP는 실제 컨텍스트 비용, 연결 오류, 항상 미리 불러오는 설정이 있는지만 확인해줘.
4. 특정 동작만 느리다면 Hook이나 그 명령 자체가 원인인지 구분해줘.
5. ~/.claude/projects 에 세션 기록이 얼마나 쌓였는지도 가볍게 확인해줘.
6. 모델, 네트워크, 백그라운드 빌드처럼 클로드 밖의 원인도 짧게 점검해줘.
결과는 아래 형식으로 보여줘.
- 가장 가능성 큰 원인 1~2개
- 그렇게 판단한 근거
- 내가 다음으로 직접 확인할 명령이나 화면
- 바꾸기 전에 내 확인이 필요한 항목이 프롬프트를 한 번 돌린 뒤, 아래에서 해당하는 부분만 이어서 보면 됩니다. 진단 결과가 한 곳을 뚜렷하게 가리키면 그 섹션만 읽고 끝내도 되고, 애매하면 순서대로 하나씩 지워가면서 확인하면 됩니다.
1. 세션의 컨텍스트 관리하기
| 신호 | 먼저 해볼 일 |
|---|---|
| 새 세션인데도 예상보다 많이 차 있음 | /context에서 시스템 규칙, 문서, 도구 이름 중 무엇이 큰지 확인 |
| 대화가 길어지고 큰 결과가 계속 쌓임 | 같은 작업을 이어 갈 거면 /compact로 정리 |
| 압축 뒤에도 금방 다시 차오름 | 긴 명령 출력이나 큰 파일 내용을 계속 넣고 있지 않은지 확인 |
| 완전히 다른 작업으로 넘어감 | handoff 문서를 만들어 새 세션에 넘기거나 /clear로 새로 시작 |
복사해서 쓰기 - 새 세션으로 넘길 요약 만들기
지금까지 진행한 일을 새 세션에서 바로 이어 갈 수 있게 정리해줘.
- 처음 목표와 지금까지 끝낸 일
- 중요한 결정과 그 이유
- 바뀐 파일이나 확인한 경로
- 실행했지만 아직 끝나지 않은 명령이나 작업
- 다음에 할 일 3개와 주의할 점
이미 끝난 이야기나 장황한 설명은 빼고, 다음 세션에 붙여넣기 좋은 짧은 인계문으로 써줘.2. CLAUDE.md는 공통 규칙만 남겨요
CLAUDE.md에는 클로드 코드가 작업할 때 따라야 할 규칙이 들어갑니다. 클로드 코드의 성능을 결정짓는 가장 큰 요인 중 하나는 메모리인 CLAUDE.md 입니다. 잘못되거나 옛날 지침들이 들어가 있으면 클로드 코드는 이를 따라 동작하게 됩니다.
공통 규칙은 세션을 시작할 때부터 함께 읽히고, 특정 폴더에서만 필요한 문서는 그 폴더 파일을 다룰 때 읽힐 수 있어요.
문제는 이 파일이 한 번에 이렇게 커지지 않는다는 데 있습니다. 프로젝트를 진행하면서 그때그때 겪은 예외 상황, 한 번 실수했던 걸 막으려고 추가한 규칙, 특정 기능에서만 필요했던 지침이 조금씩 쌓입니다. 하나하나는 다 이유가 있어서 넣은 규칙인데, 몇 달 지나 다시 보면 지금은 안 맞는 지침과 여전히 지켜야 하는 지침이 섞여 있고, 어느 게 어느 건지 구분하기가 쉽지 않습니다.
CLAUDE.md가 200줄을 넘는다면 꼭 필요한 공통 규칙만 남길 후보입니다.- 배포 절차나 문서 작성 규칙처럼 특정 상황에만 필요한 지침은 해당 작업의 스킬이나 가까운 폴더 문서로 옮깁니다.
- 같은 지침을 여러 파일에 복사해 두었다면 한곳만 고쳐도 되도록 정리합니다.
CLAUDE.md를 정리하기 전, 먼저 이렇게 시켜보세요
이 프로젝트에서 지금 적용되는 CLAUDE.md와 지침 파일을 읽어줘. 아직 수정하지 마.
각 규칙을 아래 셋으로 나눠줘.
- 모든 작업에 필요한 공통 규칙
- 특정 폴더나 특정 작업에만 필요한 규칙
- 중복되었거나 지금은 지키지 않는 규칙
그다음 공통 규칙은 짧게 남기고, 나머지는 어디로 옮기면 좋을지 제안해줘.
파일을 바꾸기 전에는 변경안과 이유를 먼저 보여줘.문서를 짧게 만드는 목적은 무조건 줄이기가 아닙니다.
작업할 때 필요한 규칙을 더 빨리 찾게 만드는 데 있어요.
3. 특정 동작만 느리다면 Hook을 봐요
Hook은 세션 시작이나 도구 실행 전후처럼 정해진 순간에 자동으로 끼어드는 도구입니다. 일반적으로 오픈소스 도구들을 막 설치하다 보면 Hook이 쌓이게 되고 이는 성능 저하를 유발합니다.
플러그인이나 하네스를 하나 설치할 때마다 Hook도 한두 개씩 따라 붙는데, 각각은 편의를 위해 넣은 거라 지울 이유가 딱히 없어 보입니다. 근데 이게 쌓이면 도구를 하나 쓸 때마다 여러 Hook이 순서대로 돌면서 컨텍스트를 계속 주입하게 되고, 그중엔 지금 작업과 상관없는 내용도 섞여 들어갑니다. 설치한 기억도 잘 안 나는 Hook이 매번 조용히 실행되고 있는 경우가 생각보다 많습니다.
파일을 읽거나 명령을 실행할 때만 유난히 늦다면, 해당 순간에 돌아가는 Hook이 있는지 확인해 보세요.
/hooks를 치면 목록을 직접 볼 수 있습니다.
Hook을 지우기 전에 먼저 쓰는 점검 프롬프트
내 Claude Code에 설정된 Hook을 점검해줘. 아직 삭제하거나 수정하지 마.
Hook마다 아래를 알려줘.
- 언제 실행되는지
- 어떤 명령이나 스크립트를 돌리는지
- 매번 기다려야 하는 동기 작업인지
- 다른 Hook과 겹치거나 지금 쓰지 않는지
- 지웠을 때 어떤 기능이 사라지는지
느려짐과 관련 있을 가능성이 큰 순서로 정리하고, 변경이 필요하면 안전한 변경안을 먼저 보여줘.4. 오래된 세션 기록도 정리해요
Claude Code가 나눈 대화는 전부 ~/.claude/projects 안에 파일로 남습니다. 지운 적이 없다면 지금도 계속 쌓이고 있는 상태예요.
여기서 헷갈리기 쉬운 게 하나 있는데, 세션 기록이 쌓인다고 해서 그게 매 요청의 응답 속도를 직접 늦추는 건 아닙니다. 지금 쓰는 세션이 열어보는 건 그 세션 자체의 컨텍스트지, ~/.claude/projects 전체를 뒤지는 게 아니거든요. 그래서 CLAUDE.md나 Hook처럼 "요청 하나하나가 느려지는" 원인은 아닙니다.
오래된 기록부터 정리하는 점검 프롬프트
Claude Code 세션 기록이 얼마나 쌓였는지 보여줘.
~/.claude/projects 를 기준으로 오래됐거나 용량이 큰 것부터 순서대로 정리해주고,
지워도 괜찮은 것부터 후보로 알려줘. 아직 삭제하지 마.
지울 파일이 정해지면
1. 먼저 백업할 위치를 제안하고
2. 백업이 끝난 뒤에만 삭제해줘.지운 세션은 복구할 수 없습니다. 백업 없이 바로 지우라고 시키지 마세요.
5. 토큰을 절약하는 오픈소스 사용해보기
컨텍스트와 CLAUDE.md, Hook까지 다 정리했는데도 도구 결과나 로그가 유난히 크다면, 클로드에게 전달되기 전에 그 내용 자체를 줄여주는 도구를 써볼 수 있습니다.
headroom은 도구 출력, 로그, 파일 내용처럼 에이전트가 읽는 데이터를 LLM에 보내기 전에 로컬에서 압축하는 오픈소스입니다.
# CLI 설치
pip install "headroom-ai[all]"
# Claude Code를 감싸서 바로 적용 (되돌리려면 headroom unwrap claude)
headroom wrap claude- wrap - 기존 사용법 그대로, 클로드에게 전달되기 직전 데이터만 압축
- proxy - 코드 변경 없이 프록시로 붙이는 방식
- MCP 서버 -
headroom_compress,headroom_retrieve같은 도구로 직접 제어
이 프로젝트는 클로드 코드 공식 기능이 아닌 서드파티 오픈소스입니다.
컨텍스트나 응답 속도가 실제로 문제일 때 시도해 보는 선택지 중 하나로 보면 되고, 먼저 붙이기 전에 결과가 바뀌지 않는지 원래 하던 작업으로 비교해 보는 걸 권합니다.
6. 모델과 작업 환경도 같이 봐요
오타 수정에 가장 무거운 모델을 쓰는 건 편의점 갈 때 택시를 부르는 것과 비슷해요.
반대로 설계나 까다로운 버그처럼 판단이 중요한 일은 더 강한 모델이 시간을 아껴줄 수 있습니다. 작업마다 모델을 매번 바꾸기 번거로우면, 지금 하고 있는 작업이 어느 쪽에 가까운지만 가끔 점검해도 충분합니다.
| 작업 유형 | 추천 모델 급 |
|---|---|
| 오타·포맷 정리, 짧은 질문 | 가벼운 모델 |
| 일반적인 기능 구현, 리뷰 | 중간 모델 |
| 복잡한 설계, 까다로운 버그 | 상위 모델 |
컨텍스트와 설정이 모두 괜찮다면 클로드 밖도 확인합니다.
- 네트워크 - VPN·프록시를 거치고 있는가, 지연이 큰 회선인가
- 디스크 I/O - 프로젝트 폴더가 네트워크 드라이브나 동기화 폴더(iCloud, Dropbox 등) 안에 있는가 (→ 생각보다 여기서 클로드 코드가 많이 느려질 수 있어요!)
- 도구 실행 시간 - 테스트·빌드 명령이 원래 오래 걸리는 것과 클로드 응답 지연을 구분했는가
MCP는 많다고 바로 느려지지 않아요 (참고)
MCP는 클로드 코드에 외부 도구를 연결하는 방식입니다.
기본 설정에서는 연결된 도구의 설명 전체를 처음부터 읽지 않고, 도구 이름만 먼저 봅니다. 실제 도구 설명은 필요할 때 가져와요 (Dynamic Loaded)
그래서 MCP가 여러 개라고 바로 느려지는 건 아닙니다. CLAUDE.md나 Hook과 자주 같이 의심받지만 성격이 다른 원인이라, 정리 순서에서는 뒤로 미뤄도 됩니다.
특정 MCP를 처음 쓸 때만 잠깐 늦거나, 연결 오류가 반복되는 경우에는 그 서버를 점검해 볼 만합니다.
한 번 쓴 도구의 설명과 큰 결과는 이후 대화에 남을 수 있으니, 오래 이어지는 세션에서는 /context로 확인하세요.
MCP가 의심될 때만 펼쳐 보는 점검 프롬프트
현재 연결된 MCP를 점검해줘. 아직 활성화 상태나 설정은 바꾸지 마.
서버마다 아래를 표로 정리해줘.
- 어떤 일을 하는 연결인지
- 지금 세션의 컨텍스트에 실제로 부담이 보이는지
- 연결 오류나 재연결이 반복되는지
- 항상 미리 불러오도록 설정돼 있는지
- 처음 사용할 때만 늦는지, 매번 늦는지
마지막에는 끄거나 설정을 바꿔 볼 후보가 있다면 이유와 예상 영향을 알려줘.
확실한 근거가 없으면 "그대로 두기"라고 말해줘.마지막 체크리스트
예시로 한 번 해보면 이런 흐름이에요.
- /context를 쳐보니 시스템 프롬프트 항목이 유독 크게 나온다.
- Hook 점검 프롬프트를 돌려보니, 예전에 설치만 하고 안 쓰는 Hook 하나가 나온다.
- 그 Hook 하나만 지운다. CLAUDE.md는 아직 건드리지 않는다.
- 같은 작업(예: 파일 몇 개 읽고 수정하는 요청)을 다시 시켜보고 체감 속도를 비교한다.
- 차이가 없으면 되돌리고 다음 후보(CLAUDE.md, 세션 기록)로 넘어간다.
/context로 현재 사용량과 큰 항목을 확인했다./compact, 다른 작업은 /clear로 구분했다.