CLAUDE.md와 플러그인을 점검하는 /doctor prompt-audit와 claude plugin eval
v2.1.283의 /doctor prompt-audit는 지시 파일을 읽어 낡은 지시를 찾고, v2.1.269의 claude plugin eval은 플러그인을 여러 번 실행해 효과를 점수로 잽니다.
CLAUDE.md와 스킬은 한번 써 두면 잘 고치지 않습니다. 모델이 바뀌어도 예전 모델에 맞춰 쓴 지시가 그대로 남습니다. 플러그인도 비슷해서, 스킬 설명을 바꿨을 때 결과가 좋아졌는지 확인할 방법이 마땅치 않았습니다. 지시 파일 쪽은 v2.1.283에서, 플러그인 쪽은 v2.1.269에서 이 문제를 다루는 도구가 들어왔습니다.
읽어서 점검하는 도구와 돌려서 재는 도구
| 항목 | /doctor prompt-audit | claude plugin eval |
|---|---|---|
| 추가 버전 | v2.1.283 | v2.1.269 |
| 실행 위치 | 세션 안 슬래시 명령 | 셸 명령 |
| 대상 | CLAUDE.md, AGENTS.md, rules, skills, commands, subagents, output styles | 플러그인 |
| 방식 | 지시문을 읽고 문제를 찾음 | 케이스를 여러 번 실행하고 채점 |
| 결과 | 발견 사항과 수정 제안 리포트 | 요약 표, report.html, aggregate-result.json |
| 파일 수정 | 요청해야만 적용 | 하지 않음 |
| 쓰기 좋은 때 | 모델이 바뀐 뒤 지시를 정리할 때 | 플러그인을 바꿨거나 새 모델이 나왔을 때 |
두 명령을 실행하는 법
/doctor prompt-audit
세션 안에서 실행합니다. /checkup prompt-audit도 같은 명령입니다.
/doctor prompt-audit기본으로 CLAUDE.md, CLAUDE.local.md, AGENTS.md와 .claude/·~/.claude/ 아래 rules, skills, commands, subagents, output styles를 모두 봅니다. 특정 파일이나 디렉터리만 보려면 경로를 넘깁니다.
/doctor prompt-audit .claude/skills/deploy공식 문서는 찾는 문제의 예로 다음 셋을 듭니다.
- 예전 모델에 맞춰 쓴 지시
- 없는 파일이나 명령을 가리키는 참조
- 서로 모순되는 파일
v2.1.283 릴리스 노트에 따르면 리포트는 오래된 경로와 명령, 서로 모순되는 지시 파일을 맨 앞에 둡니다. Claude Code 문서가 안내하는 thinking 키워드(Claude가 더 오래 생각하게 하는 단어)는 낡은 지시로 지적하지 않습니다. 리포트를 받은 뒤 적용해 달라고 해야 파일이 바뀝니다.
v2.1.292에서 지시 파일 두 개를 둔 예제 폴더에 돌려 보니 25초 만에 네 건을 찾았습니다. 경로(.)를 넘기자 ~/.claude/ 아래 파일은 건너뛰었습니다.
CLAUDE.md와 .claude/rules/style.md가 들여쓰기와 커밋 언어를 반대로 정하고, CLAUDE.md는 없는 스크립트를 부릅니다.
리포트는 모순 두 건, 없는 스크립트, 낡은 지시를 먼저 한 줄씩 요약합니다.
건마다 위치·확신도·처리 방법을 붙여 확신이 높은 것부터 보여 줍니다.
파일은 고치지 않고 diff만 내놓습니다. git 기록이 없어 어느 쪽이 최신인지 가릴 수 없는 모순 두 건은 사용자에게 남깁니다.
이 기능은 Claude Code에 기본으로 들어 있는 /claude-api 스킬을 거쳐 동작합니다. skillOverrides나 disableBundledSkills로 이 스킬을 꺼 두었다면 prompt-audit도 쓸 수 없습니다.
claude plugin eval
플러그인 루트에서 셸 명령으로 실행합니다. 처음에는 init이 플러그인에 대해 묻고, 케이스와 채점기를 제안해 파일로 만들어 줍니다.
claude plugin eval initclaude plugin eval .케이스는 evals/ 아래 디렉터리 하나입니다. prompt.md 본문이 Claude에게 보낼 요청이고, graders/ 아래 파일이 채점 기준입니다.
- my-plugin/
- .claude-plugin/plugin.json
- skills/...
- evals/
- first-case/케이스 하나
- prompt.mdClaude에게 보낼 요청
- graders/채점 기준
- criteria.md
- skill-fired.md
- results/
한 케이스는 플러그인을 실은 실행과 플러그인 없이 돌린 실행을 같은 횟수만큼 비교해 채점합니다.
새 세션이 요청을 세 번 받아 일을 끝내고, 통과한 채점기 비율의 평균이 WITH 1.00입니다.
같은 요청을 플러그인 없이 같은 횟수만큼 돌린 평균이 W/OUT 0.33입니다.
두 점수의 차이 Δ +0.67이 플러그인이 더해 준 몫입니다. 점수가 높아도 W/OUT이 같이 높으면 Δ는 작습니다.
공식 문서의 예시 요약 표는 다음과 같습니다. RUNS의 6은 두 쪽을 세 번씩 돌린 횟수입니다.
CASE WITH W/OUT Δ RUNS COST NOTESfirst-case 1.00 0.33 +0.67 6 $0.41채점기는 여섯 종류입니다. regex, tool_used, tool_order, file_exists는 실행 기록과 파일만 보고 판정하므로 추가 비용이 없습니다. llm과 baseline은 judge 모델(답을 채점하는 두 번째 모델)을 불러 비용이 더 듭니다. "스킬이 호출됐나"처럼 플러그인 없이는 통과할 수 없는 채점기는 두 쪽 점수에서 모두 빼고 표시만 합니다.
CI에서는 통과 점수(--threshold)와 비용 상한(--max-cost-usd)을 정해 두고 종료 코드로 빌드를 막습니다. --trust-plugin은 처음 실행할 때 뜨는 신뢰 확인 질문을 건너뜁니다.
claude plugin eval . --trust-plugin --json results.json --threshold 0.8 --max-cost-usd 20문서가 밝힌 이유와 비용
에이전트는 같은 요청에도 실행마다 결과가 달라서, 문서는 한 번 실행으로는 알 수 있는 게 적다고 설명합니다. 케이스마다 기본 세 번씩 돌려 평균을 내는 이유입니다. 플러그인 없이 같은 횟수를 더 돌리는 것은, 점수가 높아도 Claude 혼자 그만큼 해낼 수 있기 때문입니다.
prompt-audit는 모델이 바뀌는 속도에 지시 파일이 따라가지 못하는 문제를 다룹니다. CLAUDE.md 안내 문서는 파일 하나를 200줄 아래로 두고, 서로 모순되는 지시를 주기적으로 지우라고 권합니다. 두 지시가 부딪히면 Claude가 아무 쪽이나 고를 수 있어서입니다. prompt-audit는 그 정리를 Claude에게 맡기는 도구입니다.
plugin eval은 대략 "케이스 수 × 실행 수"의 두 배만큼 에이전트를 실행하고, llm·baseline 채점기는 실행마다 judge 호출을 세 번씩 더합니다. 이 호출은 모두 내 요금제 사용량이나 API 요금으로 잡힙니다.
채점기를 다듬는 동안에는 --ablation none으로 플러그인 없는 실행을 빼면 비용이 절반으로 줄어듭니다. 대신 Δ가 나오지 않고, 스킬 호출 여부 같은 채점기도 점수에 들어가 점수가 달라질 수 있습니다. claude.ai 구독으로 로그인했다면 HTML 리포트가 claude.ai에 비공개 페이지로 올라가니, 로컬에만 두려면 --no-publish를 붙입니다. git이 깔려 있다면 2.31 이상이어야 하고, 그보다 낮으면 케이스를 하나도 돌리지 않고 멈춥니다.