Claude Code plugin eval 가이드 — 내 플러그인 점수로 검증하는 법

플러그인이나 스킬을 만들어놓고 "이거 진짜 도움이 되는 거 맞나?" 하고 스스로도 확신이 안 서는 순간, 다들 한 번쯤 겪어보셨을 겁니다. Claude Code 2.1.269부터 추가된 claude plugin eval은 이 질문에 숫자로 답해주는 명령어입니다. 플러그인이 있을 때와 없을 때 결과가 얼마나 달라지는지를 자동으로 채점해서, 감이 아니라 점수로 판단할 수 있게 해줍니다. 이 글에서는 명령어 사용법부터 CI 게이팅까지 실전 순서대로 정리했습니다.

claude plugin eval 실행 후 터미널에 출력되는 WITH/W-OUT/Δ 요약 표

 

claude plugin eval, 언제 어떻게 생겼나

claude plugin eval은 2026년 9월 11일 출시된 Claude Code 2.1.269에서 정식 추가됐습니다. 해당 릴리스는 CLI 변경사항이 98건이나 됐는데, 그중 하이라이트로 꼽힌 게 바로 이 명령어였습니다. "플러그인 eval을 실행하고 재현 가능한 채점을 위해 점수화된 JSON+HTML 출력을 낸다"는 게 공식 하이라이트 문구였고요.

같은 버전에서 VS Code 확장의 Agent Map, 동시 에이전트 개수를 조절하는 환경변수 등도 함께 들어갔습니다. 근데 바로 다음 버전인 2.1.270에서 "세션이 오래 지속되면 읽기 전용 Git 명령에도 권한을 다시 물어보는" 리그레션이 발견돼 수정됐는데, 이게 2.1.269의 부작용이었다고 합니다. 새 버전 올리자마자 바로 실전 투입하기보다는 며칠 지켜보는 습관이 여기서도 도움이 됩니다.

 

뭘 평가하는 건가 — WITH vs W/OUT, 그리고 Δ

공식 문서(code.claude.com/docs/en/plugin-evals)를 보면 개념 자체는 단순합니다. 실제 사용자가 입력할 법한 프롬프트를 케이스로 만들고, 그 결과를 그레이더(채점기)가 합격/불합격으로 판정하는 구조입니다.

핵심은 2-arm 비교입니다. 케이스마다 플러그인을 넣고 3회, 빼고 3회, 총 6회를 실행합니다. 플러그인 있는 쪽 점수를 WITH, 없는 쪽을 W/OUT이라 부르고 그 차이가 Δ(델타)입니다. 이게 왜 필요하냐면, 플러그인 없이도 Claude가 원래 잘하는 작업이라면 WITH 점수가 높아 봐야 그게 플러그인 덕분인지 알 수가 없기 때문입니다. WITH와 W/OUT이 둘 다 1.0이라면, 그 플러그인은 사실상 통과에 기여한 게 없는 셈입니다.

실제로 커뮤니티(DEV Community, 2026-09-14 발행)에서도 이 점을 짚었는데, "WITH와 W/OUT이 둘 다 높은데 Δ가 0에 가깝다면 그 스킬이 원래 모델이 잘하는 작업 위에서만 동작하고 있어 실질 기여도가 낮을 수 있다"는 해석을 내놨습니다.

WITH·W-OUT·Δ 2-arm 비교 구조를 보여주는 다이어그램

 

실전 사용법 — eval init부터 결과 확인까지

가장 빠른 시작 방법은 플러그인 루트에서 아래 명령을 치는 겁니다.

claude plugin eval init

이걸 실행하면 인터랙티브 세션이 열리고, Claude가 플러그인을 직접 읽으면서 "좋은 결과가 뭔지" 물어봅니다. 트리거해야 할 프롬프트와 하지 말아야 할 프롬프트를 제안하고, 각각에 맞는 그레이더까지 설계해서 시범 실행(pilot)까지 해봅니다. 결과는 evals/ 아래 케이스별 디렉터리로 저장됩니다. 터미널 없는 CI 환경이라면 claude plugin eval init --bare first-case로 빈 템플릿만 만들어야 합니다.

스위트를 만든 뒤에는 이렇게 실행합니다.

claude plugin eval .

케이스마다 6회(3+3) 실행되고 진행률이 실시간으로 뜹니다. 다 끝나면 이런 표가 출력됩니다.

CASE        WITH  W/OUT Δ      RUNS COST    NOTES
first-case  1.00  0.33  +0.67  6    $0.41

Report: 뒤에 붙는 로컬 HTML 경로나, claude.ai 구독 계정이면 자동 게시되는 Published: URL을 열면 실행별 그레이더 판정과 판단 근거까지 확인할 수 있습니다. 문서에 따르면 가장 흔하게 마주치는 첫 실패 패턴은 Δ가 0에 가까우면서 tool_used: Skill 그레이더가 실패하는 경우인데, 이건 Claude가 자연어 문구만으로는 해당 스킬을 아예 선택하지 않는다는 뜻입니다. 이럴 땐 스킬 설명(description) 프론트매터부터 손보고 재실행하는 게 첫 번째 대응입니다.

케이스 하나만 빠르게 튜닝하고 싶을 땐 이렇게 단일 arm으로 줄여서 돌릴 수 있습니다.

claude plugin eval . --case <case-name> --runs 1 --ablation none

 

eval 케이스와 그레이더 작성법

케이스는 evals/<case명>/prompt.md와 graders/*.md로 구성됩니다. prompt.md는 프론트매터에 max_turns, allowed_tools 같은 설정을 두고, 본문에는 실제 프롬프트 문장을 씁니다. 필요하면 case.yaml로 픽스처(작업용 파일, git 저장소, 이전 대화 이어가기 등)를 세팅할 수도 있습니다.

그레이더는 6종류가 전부입니다.

타입	통과 조건	비용
regex	정규식이 대상 텍스트에 매치	없음
tool_used	특정 툴 호출 횟수가 범위 안	없음
tool_order	두 툴 호출 순서가 맞는지	없음
file_exists	생성된 파일이 glob과 매치	없음
llm	judge 모델이 3표 중 2표 이상 PASS	있음
baseline	레퍼런스 트랜스크립트 대비 판단	있음

regex·tool_used·tool_order·file_exists는 트랜스크립트나 파일을 기계적으로 검사하는 방식이라 비용이 아예 안 들고, llm·baseline은 judge 모델을 실제로 호출하니 비용이 발생합니다. 커스텀 코드 그레이더는 지원하지 않는다는 점도 기억해둘 만합니다.

prompt.md와 graders 디렉터리 구조 예시 파일 트리

 

CI 파이프라인에 eval 게이트 붙이기

--threshold, --max-cost-usd, --trust-plugin, --json 옵션 조합으로 머지 전 자동 게이트를 만들 수 있습니다. 공식 문서와 DEV Community 가이드 둘 다 아래와 같은 형태를 예시로 듭니다.

claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5 \
  --judge-model claude-haiku-4-5 \
  --no-publish \
  --max-cost-usd 20

exit code 체계도 명확합니다. 0은 전부 통과, 1은 임계값 미달이나 케이스 로드 실패, 2는 비용 상한 도달이나 자격증명 거부로 인한 부분 실행, 130은 인터럽트, 143은 타임아웃 종료입니다. DEV Community 글은 병합 전 체크리스트로 "스킬을 트리거해야 하는 케이스와 트리거하면 안 되는 케이스를 각각 최소 1개씩 포함하라", "모델을 양쪽 다 고정해서 모델 롤아웃과 플러그인 리그레션을 헷갈리지 말라"는 두 가지를 특히 강조했습니다. CI 파이프라인 보안 설정을 다룰 때는 Claude Code GitHub Action 시크릿 노출 취약점 정리에서 다룬 자격증명 관리 원칙도 같이 챙겨보면 좋습니다.

 

보안 — 실행이 어디까지 접근하나

claude plugin eval은 대상 플러그인의 스킬과 훅을 사용자 권한으로 로컬에서 실제로 로드해 실행합니다. claude --plugin-dir과 동일한 신뢰 결정이라, 공식 문서도 "신뢰하는 플러그인만 평가해야 한다"고 명시하고 있습니다. 각 실행은 일회용 홈 디렉터리와 작업 디렉터리를 받고, 개인 설정·CLAUDE.md·다른 설치된 플러그인·MCP 서버는 전혀 로드되지 않습니다. Claude Code Skills 완벽 가이드에서 다룬 스킬 description 작성 원칙을 이미 적용해뒀다면, eval 케이스에서 tool_used: Skill 그레이더 통과율을 훨씬 빠르게 끌어올릴 수 있습니다.

MCP 서버를 쓰는 플러그인이라면 evals/mocks/<server>/<tool>.md로 모킹부터 해야 합니다. 모킹하지 않으면 실제 MCP 서버가 아예 시작되지 않습니다. 예전에 MCP 서버 직접 만들기 글에서 다룬 MCP 툴 구조를 떠올리면 모킹 파일 작성이 한결 수월합니다.

 

실제로 붙여보면 점수가 얼마나 나오나

커뮤니티(explainx.ai)가 인용한 Anthropic 내부 평가 사례를 보면, announcement-draft, status-update, research-summary 등 7개 케이스를 각 6회씩 돌렸을 때 평균 개선도(Δ)는 +0.29, 총 비용은 $9.59가 나왔습니다. 그중 announcement-draft 케이스는 플러그인 사용 시 0.92, 미사용 시 0.17로 Δ가 무려 +0.75였다고 합니다. 스킬 하나가 이 정도 차이를 만든다면 굳이 채점 없이도 감으로 알 것 같지만, 반대로 Δ가 0.1도 안 되는 케이스가 섞여 있다면 그 스킬은 다시 손볼 후보라는 신호입니다.

 

자주 묻는 질문

Q. 기존에 쓰던 claude plugin validate랑 뭐가 다른가요?
validate는 매니페스트 문법·스키마 오류만 확인하는 정적 검사입니다. eval은 실제로 모델을 호출해 결과 품질을 채점하는 동적 테스트라 목적이 다릅니다.

Q. 비용이 얼마나 나올지 미리 알 수 있나요?
--max-cost-usd로 상한을 걸어두면 초과 시 exit code 2로 중단되고 그때까지의 부분 결과가 partial: true로 기록됩니다. 표시되는 COST는 정가 추정치라는 점도 참고하세요.

Q. Windows에서 Bash 툴을 쓰는 스위트를 돌릴 수 있나요?
네이티브 Windows는 샌드박스 백엔드가 없어서 Bash나 PowerShell 권한을 주는 스위트는 WSL2에서 돌려야 합니다.

---

플러그인 여러 개를 운영 중이라면 evals/ 스위트를 하나씩 늘려가면서 리그레션 게이트로 붙여보는 것부터 시작해보시길 권합니다. 매니페스트 오류 잡는 법이 궁금하다면 Claude Code Skills 완벽 가이드를 먼저 훑어보는 것도 도움이 될 겁니다.