03-실전

03. 실전 — 10가지 흔한 증상 + 응급 처치

1) “도구를 사용할 수 없다” 메시지

• 원인 90%: allowedTools 누락 또는 매처 문법 오류.
• 응급: claude --debug 재시작, 어떤 매처가 거부했는지 로그 확인.

2) 모델이 같은 실수를 반복

• 원인: 컨텍스트가 너무 길어 직전 교정이 윈도우 밖.
• 응급: 핸드오프 작성 → /clear → 새 세션에서 핵심만 멘션.

3) PreToolUse hook이 모든 명령을 차단

• 원인: hook 스크립트의 정규식 오버매칭.
• 응급: hook을 일시 비활성 (.claude/settings.local.json), stdin 시뮬레이션으로 디버깅.

4) /compact 후 디테일 사라짐

• 원인: 자동 요약 손실.
• 응급: git stash/이전 작업 마크다운에서 핵심을 다시 멘션. 다음부터는 /compact 대신 핸드오프.

5) --resume이 깨진 트랜스크립트로 복구

• 원인: 2026-04 이전 버전의 알려진 버그 (v2.1.91에서 수정).
• 응급: claude --version이 v2.1.91+ 인지 확인, 아니면 업그레이드.

6) Plan 모드 종료 후 plan 파일이 사라짐

• 원인: 컨테이너 재시작. 동일 릴리스에서 수정.
• 응급: 플랜을 git 추적 위치(./plan.md)에 떨어뜨리도록 프롬프트.

7) MCP 응답이 잘림

• 원인: 기본 응답 크기 한도.
• 응급: 해당 MCP 도구 호출에 _meta["anthropic/maxResultSizeChars"] 오버라이드 (최대 500K).

8) 서브에이전트가 spawn 실패

• 원인: tmux 윈도우 종료/번호 변경 (v2.1.92에서 수정).
• 응급: 업그레이드. 미업그레이드 환경에서는 tmux 사용 금지.

9) 헤드리스 작업이 무한 대기

• 원인: 사람 승인 필요한 도구가 화이트리스트 밖.
• 응급: --max-turns 강제 + 별도 settings 프로파일.

10) 어제와 동작이 다름

• 원인: 모델 변경, CLAUDE.md 변경, 또는 새 릴리스.
• 응급: git log -p CLAUDE.md, claude --version, changelog.

응급 도구 한 줄

# 디버그 시작
claude --debug

# 세션 중 토글
> /debug 이 명령이 왜 안 돌아가는지 봐줘

# 권한 머지 결과 확인
cat ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

# hook 직접 호출
echo '{"tool":"Bash","input":{"command":"echo hi"}}' | .claude/hooks/block-dangerous.sh

# 버전·changelog
claude --version
gh release view --repo anthropics/claude-code