갑자기 연동이 안 될 때, /doctor로 자가진단하고 f로 바로 고치기

업데이트하고 나니 갑자기 IDE 연동이 안 되거나, 멀쩡하던 게 이상하게 동작한 적 있나요? 원인을 모르면 설정 파일을 뒤지며 한참 헤매게 되죠. 그럴 때 헤매지 말고 먼저 돌려볼 명령이 /doctor입니다. 설치와 설정 상태를 알아서 점검해주고, 문제가 있으면 그 자리에서 고쳐줍니다.

정의

/doctor는 Claude Code의 설치·설정 상태를 진단하는 명령입니다. 이름 그대로 '의사'예요. 어디가 정상이고 어디가 문제인지 한눈에 보여주고, 발견된 문제는 f 키 하나로 자동 수정합니다.

뭔가 이상한데 원인을 모를 때, 추측으로 설정을 만지는 대신 일단 진단부터 받는 도구라고 보면 됩니다.

사용법 (난이도별)

기초 — 진단하기

대화창에 이렇게만 입력합니다.

/doctor

입력하면 화면에 점검 결과가 항목별로 뜹니다. 정상인 항목과 문제가 있는 항목이 아이콘(체크·경고 등)으로 표시돼서, 어디가 잘못됐는지 한눈에 보여요.

응용 — 자동 수정하기

/doctor 실행 → 결과 화면에서 f 키

진단 결과에 문제가 보이면, 그 화면에서 f 키를 누릅니다. 그러면 Claude가 발견된 문제를 알아서 고쳐요. 설정 파일을 직접 열어 손볼 필요 없이, 진단과 수정이 한 흐름으로 끝납니다.

심화 — 로그까지 함께 추적

/doctor → /debug

/doctor로도 원인이 안 잡히는 까다로운 문제라면, /debug(디버그 — 동작 기록인 로그를 자세히 보여주는 기능)로 넘어가 깊게 추적합니다. 진단으로 표면을 보고, 그래도 안 풀리면 로그로 속을 들여다보는 순서예요.

실전 사례

Claude Code를 업데이트한 뒤 IDE 연동이 갑자기 안 됐어요. 뭐가 문제인지 몰라 막막했는데, 일단 이걸 돌렸습니다.

/doctor

진단 결과에 연동 관련 항목이 경고로 떠 있었고, 화면에서 f를 누르니 바로 고쳐졌습니다. 설정을 직접 뒤지며 한 시간 헤맬 뻔한 일을, 진단 한 번과 키 하나로 끝낸 거죠.

이렇게 더 씁니다

• 이상하면 일단 진단부터: 동작이 수상할 때 추측으로 설정을 건드리지 말고 /doctor부터 돌립니다.
• f로 자동 수정: 문제가 잡히면 결과 화면에서 f 키로 바로 고칩니다.
• 업데이트 직후 점검: 버전을 올린 뒤 연동이 깨지는 경우가 많으니, 업데이트하고 한 번 돌려보면 안심됩니다.
• 안 풀리면 debug 연계: 진단으로 안 잡히는 문제는 /debug로 로그까지 추적합니다.

팁: "원인 모를 오류가 났다" 싶을 때 가장 먼저 떠올릴 명령으로 /doctor를 기억해두세요. 검색창에 에러 메시지를 붙여넣고 헤매기 전에, 진단 한 번이면 절반은 해결되는 경우가 많습니다.

정리

핵심은 한 문장입니다. 뭔가 이상할 때 헤매지 말고 /doctor부터 돌려라. 설치·설정을 알아서 진단하고, 문제는 f 키로 그 자리에서 고쳐줍니다. 그래도 안 풀리는 까다로운 문제는 /debug로 로그까지 추적하세요.

기준: Claude Code v2.1.154 (2026.05)