홈 / 학습 코스 / Claude Code 안내서

24. 트러블슈팅

🎯 이 장의 목표
  • 설치·인증 문제를 진단하고 해결한다
  • "규칙을 안 따른다", "멍청해졌다" 같은 동작 문제의 원인을 짚는다
  • 한도·비용 관련 증상을 이해한다
  • 막혔을 때의 표준 진단 순서를 익힌다

만능 첫 단계: claude doctor

무엇이든 "고장난 느낌"이 들면 손으로 디버깅하기 전에 이것부터.

BASH
claude doctor   # 설치 유형·인증·설정·MCP 서버 자동 진단

설치 방식·인증 상태·PATH·설정·프롬프트 캐싱 활성 여부 등을 점검하고 해결책을 제안합니다. 대부분의 설정 문제를 여기서 잡습니다.

설치·인증 문제

증상원인·해결
command not foundPATH 문제. 네이티브는 ~/.local/bin, npm은 prefix 확인. claude doctor
irm ... is not recognized (Windows)PowerShell이 아니라 CMD. 프롬프트가 PS C:\인지 확인 (2장)
EACCES 권한 오류 (npm)sudo 쓰지 말 것. npm prefix를 사용자 디렉터리로 (2장)
무료 플랜 거부Pro 이상 필요. 올바른 계정으로 로그인됐는지 확인
인증 꼬임claude logout 후 다시 claude. 브라우저가 올바른 계정인지
musl 배포판(Alpine) 오류libgcc·libstdc++·ripgrep 설치 후 USE_BUILTIN_RIPGREP=0

"규칙을 안 따른다"

CLAUDE.md나 메모리 규칙이 안 먹히는 것 같을 때:

flowchart TB
    A[규칙 무시?]:::danger --> B[/memory 로 로드된 파일 확인]:::tool
    B --> C{규칙이 보이나?}:::agent
    C -->|안 보임| D[하위 디렉터리 lazy-load 파일?<br/>그 디렉터리 파일을 아직 안 읽음]:::tool
    C -->|보임| E{여러 CLAUDE.md 상충?}:::agent
    E -->|예| F[모순 제거·명확화]:::result
    E -->|아니오| G{강제가 필요한 규칙?}:::agent
    G -->|예| H[CLAUDE.md→Hook/deny로 격상]:::result

    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000
  1. /memory로 어떤 파일이 로드됐는지 확인 (10장)
  2. 규칙이 아직 안 읽힌 하위 디렉터리의 path-scoped 파일에 있진 않은지
  3. 여러 CLAUDE.md 간 상충 지침이 없는지 — 있으면 임의로 하나를 고름 (9장)
  4. CLAUDE.md는 안내(약 70% 준수)일 뿐 — 반드시 지킬 규칙은 Hook·deny 규칙으로 (15장, 8장)
  5. 파일이 너무 길지 않은지(200줄 초과면 일부를 못 붙잡음, 9장)
📌 핵심
어떤 지침 파일이 언제·왜 로드됐는지 정밀 추적은 InstructionsLoaded 훅으로 로깅.

"갑자기 멍청해졌다 / 방금 한 말을 잊는다"

대개 컨텍스트 문제입니다(4장, 21장).

증상대응
긴 세션에서 품질 저하context rot. /clear 후 더 나은 프롬프트로 재시작
제약을 잊음컴팩션이 그 메시지를 날렸을 수 있음. CLAUDE.md에 적거나 /compact에 초점 지정
잡동사니 세션"주방 싱크대" 문제. 무관한 작업 사이 /clear
반복 교정 실패두 번 고쳐도 안 되면 /clear 후 재시작

"탈선했다 / 계획에 없는 걸 함"

  • 계획 승인 후: "계획대로만 구현해, 추가 금지"를 명시 (7장)
  • Ctrl+G로 계획을 미리 명확히
  • 너무 모호한 계획이 원인 — 계획을 더 구체적으로

한도·비용 증상

증상원인·대응
갑자기 한도 빨리 소진긴 세션·병렬 서브에이전트·MCP 과다 (22장). /usage·/stats로 확인
오전에 한도 부족5시간+주간 이중 한도, 채팅·Cowork와 공유. 오전 세션이 과했을 수 있음
예상 못 한 output 비용컴팩션 폭주·thinking 남용 의심. /cost(API)로 확인
특정 버전 후 급증릴리스 회귀일 수 있음. 버전 확인·업데이트, 공식 채널 점검
⚠️ 흔한 실수
과거 특정 버전에서 토큰 인플레이션·캐싱 버그가 보고된 적 있습니다. 이상하면 claude doctor로 캐싱 활성 여부를 보고, 버전을 확인하세요. 한도·과금 수치는 공식 문서로 재확인.

도구 선택이 이상하다

Claude가 엉뚱한 도구로 헤매면(예: Glob을 여러 번 실패 후 Grep으로 답 찾음), 보통 프롬프트가 불명확했던 것입니다(6장). 경로를 직접 짚어주면(src/auth/) 빨라집니다. Glob=파일명, Grep=내용 구분을 기억하세요.

스킬·플러그인이 반영 안 됨

  • SKILL.md 텍스트 변경은 보통 세션 중 자동 반영 (12장)
  • 세션 시작 시 없던 최상위 skills 디렉터리를 새로 만들면 재시작 필요
  • 플러그인의 hooks/·.mcp.json·agents/ 변경은 /reload-plugins 필요
  • 스킬이 자동 호출 안 되면 description이 모호하지 않은지 확인 (12장)

표준 진단 순서

flowchart TB
    A[막혔다]:::danger --> B[claude doctor]:::tool
    B --> C[/memory 로 로드 상태 확인]:::tool
    C --> D[/context · /usage 로 컨텍스트·한도 확인]:::tool
    D --> E{여전히?}:::agent
    E -->|예| F[/clear 후 더 나은 프롬프트로 재시작]:::result
    E -->|예| G[공식 문서·릴리스 노트 확인]:::result

    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

이 장에서 배운 것

  • 막히면 claude doctor 부터 — 설치·인증·설정·캐싱을 자동 진단한다.
  • "규칙 무시"는 /memory·상충 점검·강제 격상(Hook/deny)·분량 점검 순으로 푼다.
  • "멍청해짐/망각"은 대개 컨텍스트 문제 → /clear·CLAUDE.md 보존·초점 컴팩션.
  • 한도·비용 급증은 긴 세션·서브에이전트·MCP·thinking이 원인. /usage·/cost·/stats로 확인.
  • 스킬·플러그인 미반영은 재시작·/reload-plugins·description 점검으로.

✍️ 확인 문제

  1. 무엇이든 고장난 느낌일 때 가장 먼저 실행할 명령은 무엇인가요?
  2. CLAUDE.md 규칙이 무시되는 것 같을 때의 진단 순서를 말해 보세요.
  3. "긴 세션에서 Claude가 멍청해졌다"의 가장 흔한 원인과 대응은 무엇인가요?
🎉 본문 6부 완료! 이제 부록으로 넘어갑니다.
다음: 부록 A. 슬래시 명령·단축키 치트시트