01-개념

01. 개념 — 디버깅의 첫 질문은 “어디 층에서 깨졌나”

Claude Code는 여러 층의 합주다. 고장의 90%는 다음 6개 층 중 하나다:

층	흔한 증상
권한	”이 도구를 쓰지 못합니다” / 무한 승인 대기
컨텍스트	모델이 같은 실수 반복, 디테일 망각, 컨텍스트 70%+
CLAUDE.md	모순된 동작, 어제와 다른 결과
hook	알 수 없는 차단, 명령이 PreToolUse에서 죽음
MCP	외부 도구 응답 없음 / 큰 응답 드롭
모델/버전	어제 되던 게 안 됨, 새 릴리스 후 동작 변화

이 분류 자체가 가장 비싼 절약이다. 일단 어디 층인가를 정하면 그 다음은 짧다.

/debug와 —debug의 차이

“Debug logging is off by default unless you started with claude --debug, so running /debug mid-session starts capturing logs from that point forward.”
의역: “claude --debug로 시작하지 않은 한 디버그 로깅은 꺼져 있다. 세션 도중 /debug를 돌리면 그 시점부터 로그가 잡힌다.”
— Anthropic, bundled skills 표

요약:

• 시작 전부터 의심 → claude --debug로 시작.
• 세션 중간에 이상 → /debug 호출, 그 시점부터 캡처.

/debug 번들 스킬은 단순 로그 토글이 아니라 트러블슈팅 플레이북이기도 하다 — 직접 디버그 로그를 읽고 추정한다. 그래서 “이거 왜 안 돼?” 라고만 던져도 분석을 시도한다.

changelog는 디버깅 자료다

2026-04 릴리스 노트만 봐도 이런 항목들이 있다:

• “Fixed subagent spawning failures after tmux window kills/renumbering”
• “Fixed prompt-type Stop hooks and tool input validation issues”
• “Fixed plan mode losing track of plan file after container restart”
• “Fixed transcript chain breaks on --resume from async write failures”

즉, 자기가 겪는 이상한 동작이 이미 릴리스 노트에 있는 경우가 흔하다. 디버깅의 첫 5분에 changelog를 본다.

정직한 사용자 후기

Scott Spence의 Honest Version: Mixed Experience (sources/23-case-studies-raw/failures/scott-spence-honest-version-mixed-experience.md)가 좋은 캘리브레이션이다 — 모든 것이 마법은 아니다. 모델의 잘못, 도구의 잘못, 사용자의 잘못이 공존하고, 디버깅 능력이 곧 사용자의 숙련도다.