claude doctor 돌렸는데 왜 안 고쳐질까요? 진짜 청소는 /doctor (2026 기준)

claude doctor 돌렸는데 왜 안 고쳐질까요? 진짜 청소는 /doctor (2026 기준)

claude doctor는 읽기 전용 진단이고, 안 쓰는 확장과 비대해진 CLAUDE.md를 실제로 정리하는 기능은 세션 안 /doctor에만 있습니다.

결론부터 말씀드리면, claude doctor는 문제를 찾아줄 뿐 고쳐주지는 않아요. "우리 팀 CLAUDE.md가 너무 길어진 것 같은데, 이거 claude doctor 치면 정리되나요?" 같은 질문을 종종 받는데 답은 아니요입니다. 헷갈릴 만해요. 이름이 비슷한 명령어가 터미널과 세션 안에 따로 있고, 하는 일도 다르거든요. 이 글은 Claude Code 설정 점검을 처음 해보시는 분들을 위해 썼습니다. 두 명령어가 실제로 뭘 하는지, 조용히 사라지는 설정을 어떻게 확인하는지 순서대로 정리해 드릴게요.

claude doctor와 /doctor, 뭐가 다른가요

claude doctor란?: 세션을 열지 않고 터미널에서 설치 상태와 설정 파일 오류를 읽기 전용으로 출력하는 진단 명령입니다. 실제로 무엇을 바꿀지 제안하는 전체 점검은 세션 안에서 실행하는 /doctor(별칭 /checkup)의 몫입니다.

2026-09-14에 로컬에서 claude doctor --help를 실행해 봤어요. 옵션은 -h/--help 하나뿐이었고, 설명 문구도 분명했습니다. "현재 디렉터리의 설정 파일을 신뢰 프롬프트 없이 읽는다. 고칠 수도 있는 전체 점검은 세션에서 /doctor를 실행하라." 공식 CLI 레퍼런스(2026-09-11 갱신, 2026-09-14 기준 3일 전)도 같은 내용을 명시하고 있어요.

이 구분이 왜 중요할까요. 두 상황에서 갈립니다. 세션이 아예 안 뜨는 상태라면 세션을 열 수 없으니 터미널 진단이 유일한 진입로예요. 그리고 -p 헤드리스 실행은 대화형 창을 띄우지 않아서, 잘못된 설정을 조용히 건너뛰고 그냥 진행해 버립니다. 공식 설정 문서는 "-p 실행이 어떤 설정을 무시했는지 보려면 claude doctor를 실행하라"고 안내해요. 자동화 파이프라인을 돌리는 쪽이라면 이 한 줄이 꽤 쓸모 있습니다.

/doctor는 CLI 서브커맨드가 아니라 번들 스킬로 분류돼요. 이 슬래시 커맨드 doctor는 매번 완전히 같은 결과를 내놓지 않고, 상황을 읽어 제안을 구성하는 방식이거든요.

언제 어떤 명령을 써야 하나요

claude mcp list가 보여주는 기호도 구분이 필요해요. ✔ Connected, ! Needs authentication, ✘ Failed to connect는 실제 연결 시도 결과지만, ⏸ Pending approval이나 ✘ Rejected, ⊘ Disabled for this project는 연결을 시도하지도 않고 설정 판단만 보여준 것입니다.

/doctor가 실제로 손보는 것들

공식 커맨드 문서(2026-09-11 갱신, 2026-09-14 기준 3일 전)가 정리한 /doctor의 작업 범위는 여섯 가지예요.

여기서 짚어둘 게 두 가지 있어요. 첫째, 바꾸기 전에 항상 확인을 받습니다. 문서 표현으로는 "발견 사항을 먼저 보고하고 무엇이든 바꾸기 전에 확인을 요청한다"는 것인데, 항목별로 묻기 때문에 CLAUDE.md 정리만 받고 권한 완화 제안은 거절하는 선택도 가능해요. 둘째, 버전 조건이 있습니다. CLAUDE.md 축약 검사는 v2.1.206 이상이 필요하고, v2.1.205 이전의 /doctor는 읽기 전용 리포트 화면을 열고 f 키로 그 리포트를 Claude에게 보내는 정도였어요. 이 명령의 성격이 지금 모습으로 바뀐 시점이 v2.1.205 릴리스(2026-07-08, 2026-09-14 기준 68일 전)입니다.

조용히 사라지는 설정이 가장 무섭습니다

요란한 에러는 오히려 안전해요. 눈에 보이니까요. 진짜 위험한 고장은 아무 알림 없이 값만 빠지는 경우입니다. 공식 설정 문서는 고장을 세 단계로 나눠요.

• Settings Error: 파일 전체가 깨진 JSON이거나 스키마가 거부하는 값. 세션 시작 시 대화형 창이 뜹니다.
• Settings Warning: 개별 항목만 실패하는 경우. 잘못된 권한 규칙, 오타 난 훅 이벤트 이름 같은 것이고, Claude Code는 그 값만 건너뛰고 나머지 파일은 그대로 적용해요.
• Configuration error: ~/.claude.json 자체를 못 읽는 상태. 깨진 파일을 백업 폴더로 옮기고 손으로 고칠지 기본값으로 초기화할지 물어봅니다.

두 번째 유형이 "설정에 있는데 훅이 안 도는" 전형적인 시나리오예요. 에러가 안 보이니 고장 자체를 모르고 넘어가기 쉽습니다.

이런 사고는 실제로도 반복 보고됐어요. GitHub 이슈 #74023(2026-07-03 생성, 2026-09-13 갱신, 상태 closed)은 .claude/settings.json이 git 루트가 아니라 실행한 디렉터리 그대로 해석돼서, 하위 폴더에서 실행하면 훅·권한·플러그인 설정이 에러 없이 통째로 빠지던 문제였습니다. 이슈 #79480(2026-07-20 생성, 2026-09-04 갱신, 2026-09-14 기준 10일 전, 상태 closed)은 같은 파일의 permissions는 정상 로드되는데 hooks 키만 등록이 안 되던 사례고요. 두 건 다 닫힌 상태지만 "설정 파일이 있다"와 "설정이 실제로 적용됐다"는 여전히 다른 문제입니다. 공식 안내는 /status로 영향받은 파일을, claude doctor로 각 오류의 상세를 확인하라고 말해요.

대화를 시작하기도 전에 쓰는 컨텍스트

Anthropic 엔지니어링 블로그(2025-11-24 발표, 2026-09-14 기준 294일 경과)가 제시한 실측치예요. 이 수치는 상당히 오래된 자료라 지금 그대로 적용하면 안 되고, 현행 동작은 2026-09-11과 2026-09-12에 갱신된 공식 문서로 다시 확인했습니다.

같은 글은 Jira 서버 하나만 더해도 약 17,000 토큰이 붙는다고 적었고, Anthropic 내부에서는 최적화 전 툴 정의가 134,000 토큰을 차지한 사례도 있었다고 밝혔어요. 다만 이 55,000 토큰은 완화 장치가 없을 때의 구조입니다. 지금 Claude Code는 툴 정의를 기본으로 지연 로딩하고, 임계 모드 auto에서는 정의 총량이 컨텍스트의 10% 미만이면 미리 싣고 10%에 도달하면 전부 지연시켜요. MCP 컨텍스트 비용을 줄이는 첫 번째 방법은 결국 최신 버전을 쓰는 것 자체입니다. 그래도 CLI 쪽이 더 저렴해요. gh, aws, gcloud 같은 도구는 툴 목록을 아예 컨텍스트에 추가하지 않거든요.

CLAUDE.md는 작을수록 말을 잘 듣습니다

공식 메모리 문서(2026-09-10 갱신, 2026-09-14 기준 4일 전)는 크기 기준을 숫자로 못 박아요. "CLAUDE.md 파일당 200줄 미만을 목표로 하라. 파일이 길수록 컨텍스트를 더 쓰고 준수율이 떨어진다." 같은 문서는 CLAUDE.md가 강제 설정이 아니라 컨텍스트일 뿐이라고 선을 긋습니다. 무조건 막아야 하는 동작은 글로 더 적을 게 아니라 PreToolUse 훅으로 처리하라는 뜻이에요.

CLAUDE.md 정리를 위해 문서가 제시하는 방법은 세 가지입니다. 경로 범위 규칙으로 특정 파일을 만질 때만 로드시키는 방법, 특정 워크플로 지침은 스킬로 옮겨 호출 시점에만 싣는 방법, 그리고 <!-- --> 블록 주석을 쓰는 방법이에요. 마지막은 덜 알려져 있는데, 블록 주석은 컨텍스트 주입 전에 제거되기 때문에 사람용 메모를 토큰 비용 없이 남길 수 있습니다. 참고로 auto memory는 CLAUDE.md와 별개 시스템이고, 매 세션 앞 200줄 또는 25KB까지만 로드돼요.

이 지점에서 커뮤니티 온도 차도 갈렸습니다. Claude Code 제작자 Boris Cherny는 2026-07-08(2026-09-14 기준 68일 전) /checkup 기능을 직접 발표했고 좋아요 11,636건을 받았어요. 안 쓰는 스킬·MCP·플러그인 정리, 로컬 CLAUDE.md 중복 제거, 느린 훅 끄기가 요지였습니다. 반대편에는 CLAUDE.md 관리 자체에 대한 피로감도 있어요. Hacker News 게시글 "I am morally opposed to updating my Claude.md"(2026-08-20, 2026-09-14 기준 25일 전, 29점)는 "더 이상 존재하지 않는 모델을 위해 쓰인 지시가 더 똑똑해진 모델이 알아서 잘했을 일을 오히려 방해한다"고 적었어요. Google의 Addy Osmani는 2026-08-10(2026-09-14 기준 35일 전) 정기적으로 /doctor를 돌려 안 쓰는 확장과 컨텍스트 사용을 감사하라고 권했는데, 같은 결의 조언이죠.

로컬에서 확인해본 숫자

2026-09-14 기준으로 이 머신에서 직접 측정한 값이에요. 문서가 경고한 그대로 쌓여 있었습니다.

버전이 16개나 쌓인 이유는 실행기 방식에 있었어요. ~/.local/bin/claude가 네이티브 설치기가 만든 심볼릭 링크가 아니라 직접 작성한 zsh 래퍼였는데, 설정 문서는 이 경우 "Claude Code가 런처에 어떤 버전이 필요한지 알 수 없어 설치된 모든 버전을 디스크에 남긴다"고 설명합니다. claude doctor가 이런 런처를 그대로 지적하는 항목이니, 진작 돌려봤다면 3.0GB가 쌓이기 전에 알았을 일이네요.

마무리

핵심은 두 가지예요. claude doctor는 진단, /doctor는 실제 정리를 맡습니다. 그리고 가장 위험한 고장은 에러 화면이 아니라 조용히 빠지는 설정 항목이었어요. 우리 팀 하네스가 지금 어느 상태인지부터 확인해 보세요. 판단에 필요한 명령어는 위에 정리해 뒀습니다.

자주 묻는 질문 (FAQ)

Q: claude doctor를 쳤는데 왜 아무것도 안 바뀌나요?

claude doctor는 읽기 전용 진단이라 처음부터 아무것도 고치지 않아요. 정리와 수정을 원하면 세션 안에서 /doctor를 실행해야 하고, CLAUDE.md 축약 기능은 v2.1.206 이상에서만 동작합니다.

Q: CLAUDE.md 업데이트가 귀찮은데 그냥 둬도 되지 않나요?

이 피로감은 Hacker News에서도 많이 공유된 정서예요. 다만 낡은 지시가 최신 모델의 판단을 오히려 방해하는 경우가 있어서, /doctor의 중복 제거·축약 제안을 먼저 받아보고 골라서 반영하는 편이 통째로 방치하는 것보다 안전합니다.

Q: MCP 서버를 여러 개 연결해도 괜찮나요?

지금은 툴 정의가 기본으로 지연 로딩되고 컨텍스트의 10%를 넘으면 자동으로 미뤄지기 때문에 예전만큼 위험하지 않아요. 다만 CLI로 대체 가능한 서버(gh, aws, gcloud 등)는 애초에 툴 목록을 추가하지 않으니 그쪽이 더 저렴합니다.

참고 자료

• Claude Code 커맨드 공식 문서
• Claude Code CLI 레퍼런스
• Claude Code 설정 문서
• Claude Code 메모리 문서
• Claude Code 비용 문서
• Claude Code MCP 문서
• Anthropic 엔지니어링 블로그: Advanced tool use
• GitHub 이슈 #74023
• GitHub 이슈 #79480
• Boris Cherny의 /checkup 발표 트윗
• Addy Osmani의 정기 점검 권장 트윗