[Claude Code 스킬] /doctor — 설치·환경을 한 번에 건강검진 | DAKER 커뮤니티

무엇

/doctor는 Claude Code의 환경 종합검진 명령이다. 사람이 건강검진 한 번으로 여러 장기를 한 자리에서 보듯, /doctor는 설치 방식·설정 유효성·MCP 서버 상태·훅 문법·API 연결·컨텍스트 사용량을 한 패스로 점검한다. 결과는 통과(초록)·경고(노랑)·오류(빨강)로 색칠되고, 무엇이 문제인지와 고치는 법까지 함께 알려 준다.

언제 쓰나

증상이 나타나는 세 순간에 가장 효과적이다. (1) 설치 직후 — 제대로 깔렸는지 한 번에 확인. (2) 업그레이드 후 — 자동 업데이트가 실제로 적용됐는지 확인. (3) Claude Code가 이상하게 굴 때 — MCP 도구가 안 보이거나, 설정이 안 먹히거나, 자동 업데이트 실패 알림이 떴을 때. 앱 안에서 막혔으면 /doctor, 아예 claude가 켜지지도 않으면 셸에서 claude doctor로 간다.

사용법

# Claude Code 세션 안에서 — 종합검진 한 번
/doctor

# claude가 아예 시작되지 않을 때 — 셸에서 직접
claude doctor

# npm 전역 설치 → 네이티브로 이관(자동 업데이트 복구)
claude install

/doctor 리포트가 보여 주는 핵심 항목: 설치 유형(npm 전역 / npm 로컬 / 네이티브), Updates(자동 업데이트 채널과 사용 가능한 npm 버전 stable/latest), 설정 schema 유효성, MCP 서버 헬스, 훅 문법, API·셸 연동. 같은 네이티브 바이너리라도 '어떻게 깔았나'가 자동 업데이트 가능 여부를 가른다.

팁

① 자동 업데이트 실패 알림이 뜨면 대개 npm 전역 디렉터리에 쓰기 권한이 없는 경우다. claude doctor가 해결책 목록을 직접 보여 주며, claude install로 네이티브 설치로 옮기면 백그라운드 자동 업데이트가 켜져 이 문제 자체가 사라진다. ② 고친 뒤엔 같은 /doctor를 한 번 더 돌려 '재확인 출력'을 남겨라. AI 코딩 세션에서는 고쳤다는 기억보다, 초록으로 바뀐 리포트가 증거다.

출처

· Claude Code Docs — Troubleshooting
· Claude Code Docs — Advanced setup (native vs npm, claude install)
· Claude Code /doctor: Fix Setup Issues in 30 Seconds