스킬도 플러그인도 MCP 서버도, 써보고 괜찮다 싶으면 추가하는 과정을 반복하다 보면 점점 늘어납니다. 곤란한 점은 삭제할 때인데, "최근에 사용하지 않은 것 같다" 이상의 판단 근거가 없습니다. 삭제했을 때 문제가 생길지 여부는 실제로 얼마나 사용해 왔는지를 확인하지 않으면 알 수 없습니다.

그 판단 근거를 /doctor가 제공해 줍니다. 사용 실적과 컨텍스트 비용(상주 토큰)을 대조하여, 남길지 삭제할지를 이유와 함께 나열해 주는 명령어입니다.

/doctor가 무엇을 보고 있는지, 그리고 자신의 환경에서 실행한 결과를 정리합니다.

/doctor가 검진용 명령어가 되기까지

/doctor의 담당 범위가 넓어진 것은 v2.1.205 버전부터입니다.

/doctor is now a full setup checkup that can diagnose and fix issues; /checkup is its alias

설정 파일의 구문 체크부터 진단 및 수정까지 가능한 셋업 검진(setup checkup)이 되었으며, /checkup이라는 에일리어스(alias)가 붙었습니다. 명령어 이름은 바뀌지 않았기 때문에, 업데이트를 인지하지 못한 채 기존 용도로 계속 사용하더라도 이상할 것이 없습니다.

이어지는 v2.1.206 버전에서는 CLAUDE.md를 대상으로 한 체크가 추가되었습니다.

Added a /doctor check that proposes trimming checked-in CLAUDE.md files by cutting content Claude could derive from the codebase

리포지토리에 커밋되어 있는 CLAUDE.md 중, 코드베이스를 읽으면 유추할 수 있는 내용을 삭제하도록 제안하는 기능입니다. 디렉토리 구성이나 아키텍처 개요와 같이, ls 명령어로 파일 하나만 읽어도 알 수 있는 정보가 대상이 됩니다.

무엇을 확인해 주는가

업데이트 이력으로는 차이점(diff)만 볼 수 있으므로, 현재의 전체 모습은 공식 문서를 통해 확인합니다. 체크 대상은 5가지 영역입니다.

찾아낸 문제는 진단에서 끝나지 않고 수정까지 제안됩니다. '정리'에 해당하는 것이 다음 두 가지입니다.

• 설치 또는 설정 파일을 자동으로 복구
• 상시 로드되는 규약을 스킬이나 하위 디렉토리의 CLAUDE.md로 이동

'권한'과 관련된 것이 나머지 두 가지입니다.

• 권한 모드를 auto로 설정
• 반복해서 거부되고 있는 읽기 전용 명령어를 허용 규칙으로 설정

권한 측면의 두 가지는 권한을 완화하는 방향의 변경이므로, 정리 작업에 대한 동의와 함께 하나의 "예"로 처리되지 않고 별도의 질문으로 물어봅니다.

이 중 '재고 조사(inventory)'에 해당하는 것이 두 번째 줄의 설정 최적화입니다. 이 부분을 자신의 환경에서 실행해 보았습니다.

실제로 정리를 시켜보았다

실행은 세션 중에 입력하기만 하면 됩니다.

/doctor

체크는 읽기 전용으로 실행되며, 결과를 보고 나서 수정할지 여부를 선택할 수 있습니다.

제 환경에서의 결과는 다음과 같았습니다.

스캔 대상은 스킬 251건, 플러그인 7건, MCP 서버 2건입니다. 판정에 사용된 것은 최근 50세션 분량, 약 18시간 분량의 로그였습니다(이후 이 기간을 '윈도우(window)'라고 부릅니다). 설정 파일을 읽어서 "등록된 것"을 세는 것이 아니라, 실행 이력에서 "실제로 호출되었는지"를 계산합니다.

판정 근거는 4가지

컴포넌트 단위로 다음 항목들이 나열됩니다.

• 설치 후 몇 번 호출되었는가
• 최근 윈도우에서도 호출되었는가 (로그 및 최종 사용 일시)
• 상주 시 토큰을 얼마나 소비하는가 (개략적 수치)
• 남길 것인가 삭제할 것인가, 그 이유

MCP 서버는 지연 로딩(lazy load) 방식이라면 상주 토큰 0으로 취급됩니다.

판정은 사용 횟수와 상주 토큰의 상관관계에 따라 결정됩니다. 판단이 갈리는 부분은 사용 빈도가 낮은 항목들이므로, 그 부분을 보면 기준이 명확해집니다.

Component: frontend-design@claude-code-plugins
Uses (total since install): 8
Used in window?: no (last used Jul 21)
...

평생 8회 사용, 최근에는 사용하지 않음. 그럼에도 판정은 keep이며, 이유는 "빈도는 낮지만 실제로 사용되었고, 또한 저렴함"입니다. 빈도가 낮다는 이유만으로 기계적으로 삭제되지는 않습니다. 반대로 codex...

의 5122회나 ralph-wiggum의 2997회처럼, 일상적으로 사용하고 있는 것은 당연히 keep(유지)으로 판정됩니다.

삭제 제안은 2건

삭제가 제안된 것은 다음과 같습니다.

• example-skills (플러그인): 평생 사용 1회, 최근에도 미사용
• chrome-devtools (MCP): 호출 0건, 우선적으로 사용하기로 결정한 다른 서버와 중복

251건의 스킬은 모두 사용 실적이 있는 것으로 판정되었습니다. 플러그인 7건의 내역은 삭제 제안이 1건, 후술할 경고가 1건, 나머지 5건은 문제없음입니다. MCP 서버도 남은 1건은 문제없습니다. 앞서 언급한 기준으로 걸러진 결과이므로, 이유를 들어 설명할 수 있는 것들만 남았습니다.

적용 대상도 한정되어 있습니다. 쓰는 것은 유저 스코프(User Scope)·로컬 스코프(Local Scope) 설정 파일뿐이며, 리포지토리에 커밋되는 CLAUDE.md나 공유 설정인 .claude/settings.json에는 손대지 않습니다.

작동하지 않는 훅(Hook)에 대한 경고

삭제 제안과는 별개로, 경고가 하나 나왔습니다.

security-guidance 플러그인이 매 턴 발화(fire)해야 하는 훅을 가지고 있음에도 사용 카운터가 0건이라는 지적입니다. 삭제 제안은 되지 않았고, 플러그인 관리 화면에서 활성화 상태를 확인해 달라는 안내에 그쳤습니다.

사용하지 않는 것을 찾는 것뿐이라면 설정 파일을 살펴보면 짐작할 수 있습니다. 반면, 작동하고 있다고 생각하지만 실제로는 작동하지 않는 것은 설정을 봐도 알 수 없습니다. 설정상으로는 활성화되어 있고, 실행 이력만 제로인 상태이기 때문입니다. 사용 실적을 세는 메커니즘이 있으면, 이런 것들이 부수적인 결과물로 나타납니다.

어디까지 조사하고 있는가

판정의 정밀함이 궁금해서, 세션에 /doctor의 내용을 설명하게 해보았습니다.

10개의 읽기 전용 체크와 제안·확인·적용의 3단계 플로우를 가진 지침서(procedure)로서 전달되고 있다는 설명이었습니다. 내용은 설치 상태 진단부터 권한 모드 확인까지, 앞서 언급한 5개 영역과 겹치는 내용이었습니다.

실수로 권한이나 공유 파일을 건드리지 않기 위한 제약도 지시되어 있었습니다. 앞서 언급한 "권한 제안을 청소와 섞지 않는다", "쓰기는 유저 스코프·로컬 스코프에 한정한다"에 더해 다음 2가지입니다.

• 설정 파일의 env나 헤더 값은 읽지 않는다, 인용하지 않는다
• 수집한 플러그인 이름·스킬 이름은 신뢰할 수 없는 입력(untrusted input)으로 취급하여 쉘 커맨드(shell command)에 직접 삽입하지 않는다

마지막 항목이 개인적으로는 의외였습니다. 자신의 설정 파일에서 읽은 문자열조차 인젝션(injection) 방지 대상으로서 취급되고 있습니다. 이 정도까지 수행한 뒤에 제안을 내놓는 것이라면, 믿고 맡겨도 좋겠다는 재료가 되었습니다.

삭제하고 나서 어떻게 되었나

제안대로 2건을 적용했습니다.

example-skills를 제외한 덕분에, 매 세션 로드되는 스킬 목록이 추정치로 약 250 토큰 정도 가벼워졌습니다. chrome-devtools는 원래 지연 로딩(lazy load) 방식이었기에 토큰 절감 효과는 없었지만, 사용하지 않기로 결정한 연결을 하나 정리할 수 있었다는 효과가 있었습니다.

수치상으로는 작습니다. 다만, 둘 다 커밋 대상 파일에는 손대지 않았습니다. 개인 설정에 국한된 변경이므로 부담 없이 실행할 수 있습니다.

CLAUDE.md에 대해서는, 전날 별도로 /doctor의 축소 제안을 적용하여 4개 파일에서 141행을 줄였기 때문에, 이번에는 건전 판정으로 변경 사항이 없었습니다.

요약

/doctor는 사용 횟수와 최근 사용 여부, 상주 토큰, 그리고 남겨야 할 이유를 나열하여 스킬이나 플러그인을 판정해 줍니다. 제 환경에서는 251건의 스킬에 대해 2건의 삭제 제안이 있었고, 절감량은 추정치로 약 250 토큰 정도였습니다. 수치는 작지만, 삭제 시점을 감에 의존해 결정하지 않아도 된다는 점이 실제 가치라고 느낍니다.

X를 팔로우해 주시면 감사하겠습니다!

AI 주도 개발(특히 Claude Code)의 노하우나 팁(Tips)을 자주 발신하고 있습니다!

Discussion