Claude Code의 /doctor 명령어는 무엇을 하나요? CLAUDE.md의 변경 사항, prompt-audit 플래그 항목, 컨텍스트 비용이 높은 스킬 찾는 법 (2026)

이름이 거의 같은 두 가지 명령어가 있습니다:

• claude doctor: 터미널에서 실행하며 진단 전용입니다. Anthropic은 다음과 같이 설명합니다: "세션을 시작하지 않고 읽기 전용 설치 진단을 수행하려면 터미널에서 claude doctor를 대신 실행하세요."
• /doctor: 세션 내부에서 실행하며 전체 점검을 수행합니다. 명령어 레퍼런스에서는 이를 "설치, 설정, 확장 프로그램 및 CLAUDE.md 문제를 진단하고 사용자가 확인한 후 Claude가 적용할 수 있는 수정 사항을 제안하는 실행"으로 정의합니다.

Claude Code 변경 로그에는 세션 내 버전이 변경된 시점이 기록되어 있습니다: "/doctor는 이제 문제를 진단하고 수정할 수 있는 전체 설정 점검 기능입니다. /checkup은 이 명령어의 별칭(alias)입니다." 따라서 /checkup과 /doctor는 동일한 기능을 실행합니다.

Anthropic의 스킬 문서는 다섯 가지 영역을 나열합니다.

설치 상태(Installation health). 중복되거나 남겨진 설치 파일, PATH 문제, 파싱할 수 없는 설정 파일, 릴리스 채널에 최신 버전이 있는지 여부를 확인합니다.

확장 프로그램(Extensions). 점검을 통해 "사용되지 않는 스킬, MCP 서버 및 플러그인"을 "컨텍스트 비용"과 비교하고, 속도가 느린 훅(hook)을 찾습니다.

CLAUDE.md 파일. 체크인된 파일과 중복되는 로컬 CLAUDE.md 파일, Claude가 코드베이스에서 유도해낼 수 있는 체크인된 내용, 그리고 항상 로드되는 가이드 중 남은 내용을 확인합니다. Claude는 이를 스킬이나 필요할 때 로드되는 중첩된 CLAUDE.md 파일로 마이그레이션할 것을 제안합니다.

권한(Permissions). auto 모드를 기본 권한 모드로 설정하거나, 자주 거부하는 읽기 전용 명령어를 사전 승인하도록 제안합니다.

사용량(Usage). Pro, Max, Ultra, Team 및 Enterprise 플랜에서 지난 7일간의 측정치를 바탕으로 플랜 사용량을 낮추기 위해 /usage가 권장하는 변경 사항을 확인합니다. Anthropic은 "Claude는 스스로 수행할 수 있는 변경 사항을 제안하고, 나머지는 사용자가 실행할 명령어와 같은 조언으로 보고합니다"라고 말합니다. 사용량 확인에는 Claude Code v2.1.305 이상이 필요하며, Remote Control이 연결된 동안에는 점검에서 제외됩니다.

점검의 CLAUDE.md 부분은 매우 중요합니다. 체크인된 CLAUDE.md 지침은 항상 로드되기 때문입니다.

Anthropic의 메모리 문서는 무엇을 잘라내고 무엇을 유지하는지 설명합니다. 점검은 "체크인된 CLAUDE.md의 정리를 제안합니다. 디렉토리 레이아웃, 종속성 목록, 아키텍처 개요와 같이 Claude가 코드베이스에서 유도할 수 있는 내용은 삭제하고, 도구의 기본값과 다른 함정(pitfalls), 근거(rationale), 컨벤션(conventions)은 유지합니다."

이 구분이 핵심입니다. 디렉토리 트리나 종속성 목록은 Claude가 필요할 때마다 저장소에서 읽을 수 있는 것입니다. 반면, 왜 특정 마이그레이션을 먼저 실행해야 하는지에 대한 메모나 팀이 따르는 특수한 컨벤션은 코드에서 유도해낼 수 없습니다. 점검은 전자를 비용으로, 후자를 가치로 취급합니다.

크기가 중요한 이유

CLAUDE.md에 대한 Anthropic의 가이드는 명확합니다: "CLAUDE.md 파일당 200줄 미만을 목표로 하세요. 파일이 길어질수록 더 많은 컨텍스트를 소비하고 지침 준수 능력이 저하됩니다."

동일한 문서에 언급된 몇 가지 관련 제한 사항은 다음과 같습니다:

• 경고. "지침 파일 중 하나가 권장 길이를 초과하면 시작 시점과 /status 실행 시 경고가 표시됩니다."
• 합계 크기. 개별 파일이 길이 제한 내에 있더라도 세션 시작 시 합계 제한을 초과하면 경고가 표시됩니다.
• 최대 한도. "Claude Code는 4 MiB를 초과하는 파일을 건너뜁니다."
• 임포트는 크기 문제에 도움이 되지 않음. @path 임포트로 분할하는 것은 "조직화에는 도움이 되지만 컨텍스트를 줄여주지는 않습니다. 임포트된 파일은 이를 불러오는 CLAUDE.md와 함께 로드되기 때문입니다."

만약 중첩된 CLAUDE.md의 뒷부분을 Claude가 무시하는 것이 문제라면, 이는 별도의 파일당 제한 문제입니다. Claude가 하위 디렉토리 CLAUDE.md의 끝부분을 무시하는 이유에 대한 가이드에서 이를 다룹니다.

정리된 지침이 이동하는 곳

점검은 단순히 삭제만 하지 않습니다. 가끔씩만 필요한 항상 로드되는 지침의 경우, 이를 스킬이나 "필요할 때 로드되는" 중첩된 CLAUDE.md 파일로 이동할 것을 제안합니다. 경로 범위 규칙(Path-scoped rules)은 문서화된 또 다른 옵션으로, "Claude가 일치하는 파일로 작업할 때만" 로드됩니다.

점검(checkup)이 설정을 검토한다면, prompt-audit은 작성된 내용을 검토합니다. Anthropic은 다음과 같이 말합니다: "설정이 아니라 지침을 감사하려면 Claude Code 프롬프트에서 /doctor prompt-audit을 실행하세요."

메모리 문서에서는 감사 대상을 다음과 같이 설명합니다: "Claude는 이전 모델을 위해 작성된 지침, 존재하지 않는 파일이나 명령어에 대한 참조, 서로 모순되는 파일 등의 문제를 찾습니다."

각각은 실제 오류 모드입니다:

• 이전 모델을 위해 작성된 지침. 이를 도입한 변경 로그 항목에서는 감사를 "이전 모델을 위해 작성된 프롬프팅 패턴"을 확인하는 것으로 설명합니다.
• 오래된 참조. 이동된 파일 경로 나 이름이 변경된 스크립트는 Claude가 존재하지 않는 것을 찾게 만들 수 있습니다.
• 모순. Anthropic은 "두 지침이 서로 충돌하면 Claude가 임의로 하나를 선택할 수 있습니다"라고 주의를 줍니다.

이후 릴리스에서 보고서 순서가 변경되었습니다: "오래된 경로, 오래된 명령어, 충돌하는 지침 파일이 보고서 상단에 위치하며, Claude Code가 문서화한 사고(thinking) 키워드는 유지됩니다."

감사 범위

"기본적으로 감사는 CLAUDE.md, CLAUDE.local.md, AGENTS.md 파일과 .claude/ 및 ~/.claude/ 아래의 rules, skills, commands, subagents, output styles를 포함합니다."

특정 파일이나 폴더만 감사하려면 경로를 전달하세요. Anthropic의 예시는 /doctor prompt-audit .claude/skills/deploy입니다.

변경 사항

요청하기 전까지는 아무것도 변경되지 않습니다. "수정 제안이 포함된 결과 보고서를 받게 되며, Claude에게 적용을 요청하기 전까지는 파일의 어떤 것도 변경되지 않습니다."

요구 사항

감사는 "내장된 /claude-api 스킬을 통해 실행됩니다." skillOverrides나 disableBundledSkills에서 해당 스킬이 꺼져 있으면 사용할 수 없으며, Claude Code v2.1.283 이상이 필요합니다.

스킬은 그 자체로 컨텍스트 비용을 가집니다. Anthropic의 스킬 문서는 다음과 같이 명시합니다: "스킬 목록에 있는 모든 스킬은 Claude가 실제로 사용하든 안 하든 매 턴마다 컨텍스트에 추가됩니다."

/skill-doctor는 이에 대한 보고서입니다. Anthropic은 이것이 "각 스킬의 비용과 사용 빈도를 보여주어 어떤 스킬을 끌지 결정할 수 있게 해준다"고 설명합니다.

보고서 포함 내용:

• 번들 스킬 및 엔터프라이즈 스킬을 제외한 세션 내 스킬.
• "한 번도 호출되지 않은" 스킬에 대한 플래그와 끄는 방법 안내.
• 최근에 사용하지 않은 플러그인.

Anthropic의 시작 조언: "끌 수 있는 위치를 알려주는 스킬 중에서 컨텍스트 비용이 가장 높은 것부터 시작하세요."

대화형 세션에서 보고서는 /plugin 관리자의 Stats 탭에서 열립니다. -p 옵션을 사용하면 Claude Code가 이를 텍스트로 출력합니다. v2.1.252 이상 및 기능 플래그 페칭이 필요합니다. 휴대폰이나 브라우저를 통한 Remote Control 환경에서는 사용할 수 없습니다. 세션이 실행 중인 머신의 터미널에서 실행하세요.

• 무언가 고장 났거나 시작이 느릴 때: 터미널에서 claude doctor를 실행하여 읽기 전용 설치 진단을 수행합니다.
• 세션이 빨리 차거나 지침이 무시될 때: CLAUDE.md 정리를 포함한 전체 점검을 위해 /doctor를 실행합니다.
• 지침이 오래되었거나 모순될 가능성이 있을 때: 작성된 내용에 대한 보고서를 위해 /doctor prompt-audit을 실행합니다.
• 스킬을 많이 설치했을 때: 각 스킬의 컨텍스트 비용과 사용량을 확인하기 위해 /skill-doctor를 실행합니다.

점검의 자체 규칙이 가장 좋은 가이드입니다: Claude가 코드베이스에서 유도할 수 있는 것은 삭제하고, "도구의 기본값과 다른 함정, 근거, 컨벤션"은 유지하세요.

유지되는 부분은 코드가 Claude에게 알려줄 수 없는 것들입니다: 테스트가 불안정한 이유, 두 스크립트가 실행되어야 하는 순서, 리뷰어가 항상 요구하는 컨벤션 등입니다. 이러한 부분은 단일 저장소의 CLAUDE.md를 넘어서, 비슷한 규칙을 가진 새 프로젝트를 시작하거나 다른 도구에서 작업할 때도 중요합니다.

Claude 자체가 노트를 저장하는 경우, 이는 자체 인덱스와 제한을 가진 auto memory에 저장됩니다. Claude Code의 auto memory란 무엇인가에 대한 가이드에서 이것이 CLAUDE.md와 어떻게 다른지 설명합니다.

claude doctor만 실행하고 멈추는 것. 이는 설치 상태만 확인합니다. CLAUDE.md 및 확장 프로그램 확인은 /doctor에 있습니다.

컨텍스트를 아끼려고 CLAUDE.md를 임포트로 분할하는 것. 임포트된 파일은 호출하는 파일과 함께 로드됩니다.

200줄 미만으로 맞추기 위해 근거(rationale)를 삭제하는 것. 점검이 근거와 함정을 유지하는 데는 이유가 있습니다.

제안된 모든 수정을 한꺼번에 수락하는 것. 요청하기 전까지는 아무것도 변경되지 않으므로 각 항목을 검토하세요.

모든 스킬을 설치된 상태로 두는 것. 목록에 있는 각 스킬은 매 턴마다 컨텍스트를 추가합니다.

1단계: 점검 실행

세션에서 /doctor를 입력하고 무엇이든 승인하기 전에 각 영역의 발견 사항을 읽어보세요.

2단계: 작성된 내용 감사

/doctor prompt-audit을 실행하고 오래된 경로, 오래된 명령어, 모순되는 사항을 먼저 수정하세요.

3단계: 사용하지 않는 스킬 끄기

/skill-doctor를 실행하고 사용하지 않으면서 컨텍스트 비용이 가장 높은 스킬부터 시작하세요.

4단계: 유지한 근거 저장하기

유지하기로 한 함정, 이유, 컨벤션을 이 저장소 외부에서도 재사용할 수 있는 곳에 복사해 두세요.

점검은 Claude가 코드에서 읽을 수 있는 것과 사용자만 아는 것을 분리하는 데 유용합니다. 함정, 이유, 팀 컨벤션과 같은 두 번째 그룹은 여러 프로젝트와 도구에서 사용할 수 있도록 보관할 가치가 있습니다.

MemoryLake는 컨벤션, 결정 사항 및 그 배경 이유와 같은 프로젝트 지식을 위한 메모리 레이어입니다. 사용자가 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트에서 사용할 수 있습니다.

항목은 사용자가 직접 자신의 언어로 작성합니다. CLAUDE.md 파일, rules, skills, auto memory, ~/.claude 폴더 또는 어떤 벤더의 저장소에서도 내용을 읽거나 쓰거나 삭제하지 않습니다. 점검과 prompt-audit은 Anthropic이 설명한 대로 작동하며, 사용자는 여전히 어떤 수정을 적용할지 결정합니다.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하세요.

2단계: 첫 번째 메모리 업로드

해결책의 4단계에서 저장한 내용, 즉 점검에서 유지하라고 한 함정, 이유, 컨벤션부터 시작하세요. 항목당 하나의 내용을 입력합니다.

3단계: AI 및 에이전트 연결

Claude Code 및 사용하는 다른 어시스턴트를 연결합니다. 동일한 항목을 연결된 모든 프로젝트와 도구에서 사용할 수 있습니다.

첫 번째 차이점은 걱정할 필요 없는 가벼운 CLAUDE.md입니다. 항상 로드되는 컨텍스트에서 정리된 이유들은 여전히 기록되어 있습니다.

두 번째는 프로젝트 간 재사용입니다. 어디서나 따르는 컨벤션을 각 저장소마다 복사할 필요가 없습니다.

세 번째는 다른 도구에서의 동일한 지식 활용입니다. Codex나 ChatGPT도 해당 항목들을 활용할 수 있습니다.

claude doctor뿐만 아니라 /doctor를 사용하세요. CLAUDE.md 및 확장 프로그램 점검은 세션 내에서 이루어집니다.

CLAUDE.md를 200줄 미만으로 유지하세요. 파일이 길어지면 컨텍스트를 더 많이 소비하고 지침 준수율이 떨어집니다.

근거는 유지하고, 유도 가능한 것은 삭제하세요. 이것이 점검의 자체 규칙입니다.

모델 변경 후에는 prompt-audit을 실행하세요. 이전 모델을 위해 작성된 지침을 찾아냅니다.

모순되는 사항을 먼저 수정하세요. Claude는 충돌하는 두 지침 중 하나를 임의로 선택할 수 있습니다.

비용에 따라 스킬을 정리하세요. 컨텍스트 비용이 가장 많이 드는 사용하지 않는 스킬부터 시작하세요.

적용하기 전에 검토하세요. 요청하기 전까지는 아무것도 변경되지 않습니다.

Claude Code의 /doctor는 전체 설정 점검 기능입니다. 설치 상태, 확장 프로그램, CLAUDE.md 파일, 권한 및 사용량을 확인하고 사용자가 확인한 후에만 수정을 적용합니다. CLAUDE.md의 경우, 코드베이스에서 유도할 수 있는 내용은 삭제하고 함정, 근거, 컨벤션은 유지합니다. 터미널의 claude doctor는 읽기 전용 설치 확인 기능입니다.

/doctor prompt-audit은 지침 파일의 오래된 가이드, 잘못된 참조, 모순을 검토하며, /skill-doctor는 각 스킬의 컨텍스트 비용과 사용 빈도를 보여줍니다. 이들을 함께 사용하여 매 세션마다 로드되는 내용을 가볍게 유지하고, 유지하기로 결정한 추론 내용은 재사용 가능한 곳에 보관하세요.