Claude Code 플러그인 평가: 켠 결과와 끈 결과를 같은 테스트로 비교하기

Claude Code 플러그인은 스킬, 훅, 에이전트, MCP 서버를 한 묶음으로 배포한다. 설치가 잘 되는지는 claude plugin validate로 확인할 수 있지만, 플러그인이 같은 작업의 결과를 실제로 개선하는지는 알 수 없었다. 잘 만든 설명이나 데모 하나가 있어도, 모델이 스킬을 부르지 않거나 훅이 엉뚱한 순간에 개입하면 실제 효과는 달라진다.

Anthropic은 2026년 9월 11일 공개한 Claude Code 2.1.269 릴리스에 claude plugin eval을 추가했다. 플러그인의 테스트 묶음을 Claude Code로 실행하고 JSON과 HTML 보고서를 만든다. 평가 체계 전반은 AI 평가 가이드에 두고, 이 글은 2.1.270의 CLI 도움말을 함께 확인해 새 명령이 무엇을 비교하고 결과를 어떻게 읽어야 하는지 살펴본다. 직접 플러그인 평가를 실행해 얻은 측정 결과는 아니다.

같은 작업에서 플러그인만 뺀다

기본 비교 단위는 플러그인을 켠 실행과 끈 실행이다. 각 테스트 케이스의 프롬프트와 채점 기준은 유지하고, 플러그인 로딩 여부만 바꾼다.

같은 case
├── WITH    플러그인을 로드한 Claude Code 실행
└── W/OUT   플러그인을 제외한 기준선 실행
       ↓
     Δ = WITH - W/OUT

보고서의 열은 다음처럼 읽으면 된다.

항목	뜻	판단할 때 볼 것
WITH	플러그인을 켠 실행의 집계 점수	의도한 스킬·도구가 사용됐는지, 결과 기준을 만족했는지
W/OUT	같은 프롬프트를 플러그인 없이 실행한 기준선 점수	모델이 원래도 풀던 문제인지
Δ	WITH에서 W/OUT을 뺀 차이	플러그인이 더한 효과의 방향과 크기
RUNS	각 조건에서 반복한 실행 수	우연한 한 번의 성공을 얼마나 걸러냈는지

Δ가 양수라고 바로 좋은 플러그인이라고 결론 내릴 수는 없다. 모델 실행은 확률적이고, grader가 잘못된 대리 지표를 채점할 수 있다. WITH 점수가 높아도 W/OUT이 이미 같다면 플러그인의 추가 효과는 없다. 반대로 평균 Δ가 좋아도 한 실행이 저장소를 망가뜨리거나 금지된 도구를 쓰면 배포 기준을 통과시켜서는 안 된다.

테스트 케이스와 채점 기준을 만든다

플러그인 루트에서 평가 묶음을 만든다.

claude plugin eval init
claude plugin eval .

init의 기본 경로는 대화형 인터뷰다. Claude가 플러그인을 읽고 어떤 동작을 보호할지 물은 뒤 evals/ 아래에 케이스와 grader를 만든다. 빈 틀부터 쓰려면 claude plugin eval init --bare <name>을 사용한다. 한 케이스는 case.yaml 하나로 적거나, prompt.md와 graders/*.md로 나눌 수 있다.

좋은 케이스는 “플러그인을 사용하라”고 지시하지 않는다. 실제 사용자가 할 말을 넣고, 플러그인이 필요한 순간에 선택되는지 본다. 예를 들어 코드 리뷰 플러그인은 다음 세 종류가 필요하다.

써야 하는 요청 — 변경 파일에서 실제 결함을 찾아 수정 우선순위를 제시한다.
쓰지 않아야 하는 요청 — 단순 오탈자 수정처럼 플러그인 절차가 오히려 비용을 늘리는 작업이다.
실패하기 쉬운 요청 — 테스트가 없거나 변경 범위가 큰 저장소처럼 기존에 빠뜨리던 조건을 넣는다.

채점도 최종 답변의 말투보다 작업 계약에 붙인다. 필수 결함을 찾았는지, 허용된 도구만 썼는지, 특정 파일을 정확히 바꿨는지, 테스트가 통과했는지를 각각 확인한다. 모델 grader가 필요한 주관적 품질과 파일·도구 사용으로 판정할 수 있는 조건을 나누면 점수의 원인을 찾기 쉽다.

반복 횟수는 신뢰도와 비용을 함께 늘린다

CLI의 기본 반복값은 케이스당 3회이며 --runs <n>으로 바꾼다. 플러그인 유무를 비교하면 한 케이스에 WITH 3회와 W/OUT 3회가 필요하고, grader 호출이 추가될 수 있다. RUNS를 늘리면 결과의 흔들림은 더 잘 보이지만 사용량과 시간도 함께 늘어난다.

처음에는 실패 사례를 빠르게 고치는 데 3회를 쓰고, 배포 후보에서만 횟수를 늘리는 편이 낫다. 평균 점수만 저장하지 말고 실행별 점수와 실패 이유를 본다. 5회 중 세 번만 성공한 플러그인은 평균이 좋아도 사용자가 매번 믿고 맡기기 어렵다.

모델, 권한, 도구, fixture도 고정해야 한다. 플러그인 수정과 동시에 모델을 바꾸면 Δ가 어느 변화에서 왔는지 알 수 없다. 비교할 때는 --model, 허용 도구, 케이스 파일과 grader 버전을 함께 기록한다. MCP 서버는 기본적으로 mock을 기록해 사용하고, 실제 서버는 명시적으로 허용한 경우에만 시작한다.

claude plugin eval . \
  --runs 5 \
  --model sonnet \
  --max-cost-usd 20 \
  --no-publish \
  --report evals/results/plugin-report.html

--threshold는 케이스 하나라도 기준 아래면 종료 코드 1을 내므로 CI의 회귀 차단에 쓸 수 있다. --max-cost-usd는 다음 실행을 시작하기 전에 비용 상한을 확인한다. 병렬 실행 중인 작업만큼은 상한을 넘을 수 있으므로, 엄격한 예산에서는 --concurrency 1과 함께 쓴다.

플러그인을 고치는 순서가 달라진다

이 도구가 바꾸는 것은 플러그인의 작성 형식보다 개선 순서다. 예전에는 스킬 설명을 다듬고 잘 된 예시를 다시 실행했다. 이제는 먼저 과거 실패를 케이스로 남기고, WITH와 W/OUT의 차이를 확인한 뒤 플러그인을 고칠 수 있다.

W/OUT도 높고 Δ가 작으면 플러그인이 필요 없는 문제일 수 있다.
WITH와 W/OUT이 모두 낮으면 플러그인보다 과제·도구·grader 설계를 먼저 의심한다.
WITH만 흔들리면 스킬 선택 조건, 훅 시점, MCP 응답처럼 플러그인 경로를 추적한다.
Δ는 높지만 비용과 시간이 크게 늘면, 얻은 품질이 그 비용을 감당하는 작업에만 플러그인을 제한한다.

따라서 채택 기준에는 점수 외에도 성공률, 실행 시간, 사용 비용, 사람의 개입, 금지 행동을 넣어야 한다. 대표 과제를 고정하고 플러그인 버전마다 같은 묶음을 돌리면 모델 업데이트나 스킬 수정 뒤의 회귀도 찾을 수 있다.

실행 전에 확인할 점

평가는 로컬에서 로그인한 사용자의 권한과 사용량으로 Claude Code 자식 프로세스를 실행한다. 처음 보는 플러그인의 평가 묶음도 코드처럼 검토해야 한다. scaffold 스크립트와 실제 MCP 서버는 별도 옵션을 켰을 때 사용자 권한으로 실행된다. 테스트 통과는 보안 검사를 대신하지 않는다.

HTML 보고서는 계정과 정책이 허용하면 claude.ai에 게시될 수 있다. 저장소 내용이 보고서에 들어갈 수 있으므로 로컬에만 둘 때는 --no-publish를 명시한다. 현재 설치에서 사용할 수 있는 옵션과 접근 여부는 claude plugin eval --help로 확인한다.

플러그인 평가는 “이 플러그인이 좋아 보이는가”를 “같은 과제에서 플러그인이 결과를 얼마나 바꾸는가”로 바꾼다. 가장 유용한 시작점은 많은 합성 문제보다 실제로 다시 겪고 싶지 않은 실패 세 가지다. 그 실패를 케이스와 grader로 고정해야 Δ가 제품 설명이 아니라 개선 근거가 된다.