Claude Code 플러그인 테스트: 네이티브 eval로 회귀 잡기

지금 이 기능을 알아둘 이유도 분명합니다. Claude Code 2.1.269에는 2026년 9월 11일 플러그인 eval이 추가됐습니다. 이 검색 주제에서 날짜를 명시한 기존 주요 튜토리얼은 여전히 맞춤형 Python 러너를 설명합니다. 현재 로컬 플러그인을 관리하고 있다면 이제 가장 짧은 길은 네이티브 방식입니다. 동작 사례 하나를 초기화하고, 대조군과 비교해 실행하고, 보고서를 살핀 다음, 의도적으로 일으킨 회귀를 CI에서도 거부하도록 만들면 됩니다.

Claude Code 플러그인 테스트가 실제로 측정하는 것

플러그인 eval은 에이전트 동작을 대상으로 하는 A/B 테스트입니다. 같은 작업 지시서를 받은 두 개의 동일한 작업장을 떠올리면 이해하기 쉽습니다. 한쪽에는 플러그인이 설치돼 있고 다른 쪽에는 없습니다. Claude Code는 양쪽에서 작업을 반복하고 결과를 채점한 뒤 WITH, W/OUT, Δ를 보고합니다. 여기서 델타는 플러그인 적용 점수에서 미적용 점수를 뺀 값입니다.

실제로 봐야 할 수치는 바로 이 델타입니다. 양쪽 점수가 모두 1.0이면 훌륭해 보일 수 있지만, 이는 플러그인 없이도 Claude가 이미 작업을 끝낼 수 있었다는 뜻입니다. 양의 델타는 플러그인의 기여가 측정됐음을 보여줍니다. 음의 델타라면 테스트한 동작이 플러그인 때문에 오히려 나빠진 것입니다.

기본 설정에서 사례 하나는 플러그인을 적용한 새 세션 세 개와 적용하지 않은 새 세션 세 개로 실행됩니다. 각 세션에는 격리된 홈 디렉터리, 작업 디렉터리, Claude Code 설정이 주어집니다. 개인 설정, 프로젝트의 CLAUDE.md, 다른 플러그인, 메모리, 개인 MCP 서버는 따라오지 않습니다. 이런 격리는 비교를 더 깨끗하게 만들지만, 노트북의 설정에 몰래 의존하던 플러그인은 마땅한 이유로 실패하게 됩니다. 전체 격리 및 보안 규약은 Anthropic의 플러그인 eval 문서에서 확인할 수 있습니다.

먼저 로컬 플러그인을 정상 상태로 만드세요

동작 eval은 첫 번째가 아니라 두 번째 검사입니다. 플러그인 디렉터리에는 plugin.json, .claude-plugin/plugin.json 또는 유효한 스킬 디렉터리 구조가 있어야 합니다. 파일과 스키마 문제는 claude plugin validate로 확인합니다. “자연스러운 요청에서 스킬이 실행됐는가, 그리고 팀이 정한 형식으로 결과를 만들었는가?” 같은 질문에는 claude plugin eval을 사용합니다.

Claude Code v2.1.269 이상과 일반 세션에서 쓰는 것과 같은 인증도 필요합니다. eval 세션, judge 채점기, 대화형 초기화 도구는 모두 플랜 사용량이나 API 과금을 소모합니다. 아직 전반적인 Claude Code 설정부터 익혀야 한다면 출시 게이트를 더하기 전에 기본 로컬 워크플로부터 시작하세요.

신뢰할 수 있는 플러그인의 루트에서 버전을 확인하고 빈 사례를 만듭니다.

claude --version
claude plugin eval init --bare release-note

대화형 대안은 claude plugin eval init입니다. 이 명령은 플러그인을 읽고, 좋은 결과의 조건을 질문한 뒤, 사례와 채점기를 제안하고, 한 차례 시험 실행한 다음 스위트를 작성합니다. 계약 구조를 익힐 때는 아무것도 실행하지 않고 파일만 만드는 --bare 방식이 더 낫습니다.

이해할 수 있는 동작 사례 하나부터 만드세요

정상 작동 중인 플러그인에 release-notes라는 스킬이 있다고 가정해 보겠습니다. 이 스킬의 가치는 단순히 글을 쓰는 데 있지 않습니다. 자연스럽게 표현된 제품 변경 요청을 알아보고, 팀이 정한 세 부분의 릴리스 노트 형식인 Summary, Impact, Risk로 답해야 합니다.

사용자의 현실적인 요청은 prompt.md에 넣습니다. 그다음 결과를 검사하는 결정론적 채점기 하나와 작동 메커니즘을 검사하는 채점기 하나를 추가합니다. 결정론적이라는 말은 CLI가 추적 기록이나 텍스트를 직접 확인하므로 judge 모델을 호출하지 않는다는 뜻입니다.

# evals/release-note/prompt.md
---
name: release-note
tags: [smoke]
runs: 3
max_turns: 8
timeout_seconds: 180
allowed_tools: [Skill]
---

Turn this change into a customer-facing release note: checkout now retries a failed payment once before showing an error.

# evals/release-note/graders/format.md
---
type: regex
target: last_message
pattern: 'Summary[\s\S]*Impact[\s\S]*Risk'
flags: i
---

# evals/release-note/graders/skill-fired.md
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?release-notes"'
---

release-notes는 해당 스킬의 SKILL.md에 있는 실제 name으로 바꾸세요. 프롬프트에는 의도적으로 스킬 이름이나 세 개의 제목을 넣지 않았습니다. 그래야 플러그인이 작업을 스스로 인식하고 고유한 형식을 제공하는지 시험할 수 있습니다. 프롬프트에 답을 전부 써 두면 플러그인이 없는 대조군도 통과할 수 있고, 델타는 플러그인이 거의 보탠 것이 없다고 말하게 됩니다.

이 frontmatter가 현재 네이티브 스키마입니다. prompt.md에서는 runs, max_turns, timeout_seconds, model, tags, allowed_tools 같은 필드를 최상위에 둡니다. fixture, 대화 기록, 디렉터리가 필요하면 case.yaml을 추가하세요. 이 파일에는 schema_version: "1.1"과 name이 필수이며, 실행 관련 필드는 execution: 아래로 옮깁니다.

실행한 뒤 보고서를 읽는 순서

플러그인 루트에서 claude plugin eval .을 실행합니다. 지금 만든 단일 사례라면 플러그인 적용 세션 세 개와 기준선 세션 세 개가 시작됩니다. 각 세션이 끝날 때마다 진행 줄에 채점 결과가 나타나며, 요약에는 WITH, W/OUT, Δ, RUNS, COST, NOTES가 표시됩니다.

다음 순서로 읽으세요.

1. WITH는 플러그인을 적용한 세션이 채점 기준을 충족했는지 답합니다.
2. W/OUT은 Claude가 같은 결과를 혼자서 얼마나 자주 냈는지 답합니다.
3. Δ는 플러그인의 기여도를 측정합니다. 양수면 유용하고, 영에 가까우면 조사가 필요하며, 음수면 회귀입니다.
4. COST는 정가 기준 추정치이며, 구독에서 실제로 청구되는 금액과는 다를 수 있습니다.
5. NOTES는 플러그인 적용군에서 가중치가 가장 큰 실패나 실행 오류를 가리킵니다.

사례가 하나 이상인 모든 스위트는 타임스탬프가 붙은 결과 디렉터리에 aggregate-result.json과 자체 완결형 report.html을 씁니다. HTML 보고서에서는 각 실행을 열고, 채점기별 판정과 설명을 확인하며, 프롬프트 및 채점기 정의와 Claude의 실제 작업을 비교할 수 있습니다. JSON에는 전체 점수, 통과한 사례 수, 평균 델타, 부분 완료 상태, 비용 추정치, 소요 시간, Claude Code 버전 등 CI에서 안정적으로 쓸 수 있는 필드가 담깁니다.

테스트를 믿기 전에 회귀를 한 번 일으키세요

이제 테스트가 정말 실패할 수 있는지 입증할 차례입니다. release-notes 스킬의 설명을 잠시 모호한 문구로 바꿔, 스킬이 알아봐야 할 작업을 더는 언급하지 않게 만드세요. eval 사례는 건드리지 않습니다. 같은 명령을 다시 실행해 새 보고서를 확인한 뒤 실제 설명을 복원합니다.

찾아야 할 것은 동작상의 실패입니다. Skill 채점기가 통과하지 못하거나, 기대한 형식의 신뢰도가 낮아지거나, 플러그인 적용군의 우위가 줄어야 합니다. 정확한 점수를 미리 단정해서는 안 됩니다. 에이전트 실행 결과는 달라질 수 있습니다. 의도적으로 망가뜨렸는데도 기본 실행 세 번 모두에서 보고서가 사실상 달라지지 않는다면, 해당 사례는 아직 플러그인을 보호하지 못합니다. 요청을 더 대표적인 형태로 다듬고, 결과 채점 기준을 강화하거나, 스킬이 실행돼서는 안 되는 사례를 추가하세요.

의도적인 이 고장은 연기 감지기의 테스트 버튼을 누르는 것과 같습니다. 관련 결함이 대시보드를 빨간색으로 바꿀 수 있다는 사실을 확인하기 전까지 초록색 대시보드는 아무 가치가 없습니다.

사례를 늘리기 전에 반복 실행 예산부터 계산하세요

기본 사례 하나만으로도 에이전트 세션 여섯 개가 만들어집니다. 같은 사례에 LLM 채점기 하나를 추가하면 judge 투표가 열여덟 번 더 실행됩니다. 세션 여섯 개 각각에 세 표가 붙기 때문입니다. 세션 자체도 여러 턴에 걸칠 수 있습니다. 그래서 작은 스위트도 사례 수만 보고 예상한 것보다 많은 사용량을 소모할 수 있습니다.

서로 다른 세 가지 결정을 위해 세 종류의 예산을 사용합니다.

한 번만 실행하는 반복 과정에는 의도적으로 잡음이 있습니다. 뚜렷한 실수를 잡는 데 사용한 다음, 변경을 받아들이기 전 기본 실행 세 번으로 확인하세요. 자주 수행하는 검사에는 judge 호출을 추가하지 않는 regex, tool_used, tool_order, file_exists를 우선 사용합니다. 안정적인 규칙으로 표현할 수 없는 짧은 결과에만 LLM 채점기를 쓰세요.

비용 플래그에는 주의점이 있습니다. --max-cost-usd는 각 실행이 시작되기 전에 CLI가 계산한 정가 기준 추정치를 제한합니다. 이미 진행 중인 실행은 끝까지 계속되므로 보고된 추정치가 상한선을 넘을 수 있습니다. 상한선에 도달하면 부분 결과가 남고 종료 코드는 2가 됩니다. 선불 지갑이 아니라 안전장치입니다.

회귀 검사를 CI에 넘기세요

의도한 회귀가 눈에 보이고 복원한 플러그인이 통과했다면, 정확히 그 스위트를 버전 관리에 넣습니다. Anthropic의 CI 예시는 에이전트 및 judge 모델을 고정하고, results.json을 작성하며, 0.8 임계값을 적용하고, 보고서는 로컬에 보관하면서 추정 비용 상한을 $20로 설정합니다. 또한 --trust-plugin을 전달하는데, 이는 체크아웃한 플러그인과 스위트를 직접 실행해도 좋다고 판단할 때만 적절합니다.

그대로 넘겨 쓸 명령은 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입니다. Claude Code 설치와 인증을 마친 뒤 작업에 이 명령을 넣고, 결과 파일 두 개를 보관하세요.

명령의 종료 상태만으로도 빌드를 차단할 수 있습니다. 종료 코드 0은 모든 사례를 불러와 임계값을 충족했다는 뜻입니다. 종료 코드 1은 임계값 미달과 여러 설정 오류를 포함합니다. 종료 코드 2는 비용 상한 또는 최초 자격 증명 거부로 인해 부분 실행만 이뤄졌다는 뜻입니다. 실패했을 때도 results.json과 report.html을 보관해야 작성자가 플러그인 회귀, 실행 시간 초과, 예산 중단 가운데 원인을 구분할 수 있습니다.

모델 고정은 중요합니다. 고정하지 않으면 모델 출시가 플러그인 회귀처럼 보일 수 있습니다. 추론 사용량에도 같은 원칙을 적용하세요. 비용 변화가 동작 점수에 섞이지 않도록 품질과 effort를 별도 축으로 테스트하세요.

먼저 테스트할 만한 플러그인 동작 일곱 가지

가장 큰 효과를 보는 팀은 다른 사람에게 플러그인을 배포하는 팀입니다. 개인용 도우미라면 수동 검사도 감수할 수 있습니다. 하지만 마켓플레이스나 조직용 플러그인의 설명, 툴 권한, 출력 중 하나라도 허술하면 사용자 전체에 반복적인 지원 업무가 생깁니다.

사라졌을 때 사용자가 가장 먼저 알아챌 동작 두 가지부터 시작하세요. 모호한 사례 열 개보다 재현 가능한 결함을 드러내는 호출 테스트 하나와 결과 테스트 하나가 더 유용합니다.

네이티브 플러그인 eval을 중심으로 만들 만한 제품 두 가지

1. 가장 유력한 기회는 PR 델타 게이트입니다

네이티브 명령을 실행하고 aggregate-result.json을 읽은 다음, 점수 변화, 델타, 비용, 실패한 채점기, 보관된 보고서 링크를 리뷰 하나로 게시하는 가벼운 CI 제품을 만들 수 있습니다. 플러그인 팀과 마켓플레이스 관리자는 또 다른 평가기가 아니라 판단 계층에 비용을 지불합니다.

수요는 아직 초기 단계지만 상업적 신호는 뚜렷합니다. claude code evals는 미국에서 월간 검색량 약 50회를 기록하며, 전년 대비 600% 성장했고 CPC는 $17.61입니다. 더 넓은 평가 플랫폼에서도 품질 예산의 존재를 확인할 수 있습니다. Braintrust는 월 $249의 Pro 플랜을 제시합니다. 이는 해당 카테고리의 기준점일 뿐, 플러그인 래퍼의 가격 제안은 아닙니다.

판매 가능한 최소 버전은 GitHub Action과 PR 댓글의 조합입니다. 플러그인 경로, 임계값, 모델 고정값, 추정 비용 상한을 입력받고 네이티브 JSON과 HTML을 업로드하며, 종료 코드 1과 부분 종료 코드 2를 구분합니다. 다만 플랫폼 위험은 분명합니다. Anthropic이 자체 PR 보고 기능을 추가할 수 있습니다. 방어력을 만드는 계층은 네이티브 보고서를 예쁘게 복제하는 화면이 아니라 여러 저장소에 적용되는 정책, 이력 비교, 승인 규칙입니다.

2. 엄선한 eval 팩은 스킬 작성자에게 유용합니다

코드 리뷰, 변경 로그 작성, 인시던트 분류, 안전한 툴 선택처럼 흔한 플러그인 작업을 위한 유지관리형 사례 팩을 판매할 수 있습니다. 팩은 현실적인 실행·비실행 프롬프트와 결정론적 채점기가 담긴 일반 evals/ 디렉터리입니다. 팀은 품질 기준을 처음부터 발명하는 대신 이 팩을 상황에 맞게 조정할 수 있습니다.

직접 키워드인 claude code skill evals의 미국 월간 검색량은 약 10회입니다. 규모가 매우 작으므로 독립적인 벤처 시장보다는 집중형 부가 상품에 가깝습니다. MVP는 가치가 높은 플러그인 카테고리 하나를 위한 뛰어난 팩 하나입니다. Claude Code 릴리스에 맞춰 버전을 관리하고 짧은 보정 가이드를 함께 제공합니다. 한계도 분명합니다. claude plugin eval init이 이미 사례를 제안하고 시험 실행합니다. 팩이 경쟁력을 가지려면 도메인 시나리오와 실패 기준이 일반 생성 결과보다 뛰어나야 합니다.

이 명령만으로 해결되지 않는 것

네이티브 eval은 플러그인이 어떤 상황에서도 좋다는 사실을 증명하지 않습니다. 선택한 프롬프트, 환경, 모델, 툴 권한, 채점기 조건에서 어떻게 동작했는지만 입증합니다. 약한 프롬프트는 실제보다 좋은 점수를 만듭니다. regex는 내용이 틀려도 제목만 맞으면 보상할 수 있습니다. LLM judge는 결과가 달라질 수 있고, 실행마다 채점기 하나당 투표 세 번을 추가합니다.

격리에도 분명한 제약이 있습니다. 실행할 때마다 깨끗한 상태에서 시작하므로 프로젝트 파일, 사용자 설정, hook, 개인 서버가 없습니다. 재현성에는 훌륭하지만 fixture를 선언하지 않은 사례에는 불리합니다. 읽기 전용 세트를 벗어난 툴에는 명시적인 명령줄 권한이 필요합니다. 실제 플러그인 MCP 서버에는 별도의 opt-in과 권한이 필요하며, hook과 실제 서버는 에이전트 샌드박스 밖에서 작동할 수 있으므로 격리된 러너에서 실행해야 합니다.

마지막으로 정상적인 작업이 상한에 부딪힐 만큼 max_turns나 timeout_seconds를 줄이지 마세요. 시간 초과나 턴 제한에 도달한 실행은 오류로 기록되며 대개 점수를 낮춥니다. 의도한 작업을 끝낼 만큼 여유를 준 뒤, 추정 비용 상한으로 스위트 전체를 통제하세요.

월요일에는 플러그인 관리자 한 명이 호출 사례 하나를 추가하고, 의도적으로 실패시킨 뒤, 플러그인을 복원하고, 바로 그 검사를 CI에서 제한해야 합니다. 팀의 플러그인 전반에 이 출시 시스템을 구축하고 싶다면 프로덕션 게이트 설계를 도와드릴 수 있습니다.