Claude Code 플러그인 eval 운영법: 팀용 에이전트 품질을 숫자로 관리하기

Claude Code 최근 업데이트에서 실무적으로 눈에 띄는 기능은 claude plugin eval이다. 플러그인을 테스트 케이스 묶음으로 실행하고, 플러그인이 있을 때와 없을 때를 비교해 기여도를 확인할 수 있게 하는 기능이다. 겉으로 보면 작은 CLI 기능처럼 보이지만, 팀 단위 에이전트 운영에서는 꽤 중요한 변화다.

지금까지 많은 팀이 에이전트 품질을 감으로 판단했다. “대체로 잘한다”, “가끔 이상하다”, “이번 버전이 더 나은 것 같다” 같은 표현은 회의에서는 편하지만 운영 기준이 되기 어렵다. 특히 플러그인, 스킬, 커스텀 명령어, 사내 규칙이 늘어나면 어떤 변경이 품질을 올렸는지 내렸는지 알기 힘들다.

claude plugin eval은 이 문제를 테스트 문화로 끌고 온다. 코드에 unit test가 있듯이, 에이전트 플러그인에도 eval suite가 필요하다는 방향이다.

왜 플러그인에도 테스트가 필요한가

에이전트 플러그인은 단순한 편의 기능이 아니다. 팀의 작업 방식, 금지 규칙, 문서 경로, 도구 사용 기준을 모델에게 주입한다. 예를 들어 “PR 생성 전에 테스트 결과를 반드시 확인하라”는 규칙, “고객 데이터는 절대 로그에 남기지 말라”는 규칙, “디자인 리뷰는 접근성 체크리스트를 포함하라”는 규칙이 플러그인에 들어갈 수 있다.

문제는 이런 규칙이 늘어날수록 부작용도 생긴다는 점이다. 한 규칙이 너무 강하면 모델이 필요한 작업까지 거절한다. 설명이 모호하면 모델이 매번 다르게 해석한다. 여러 플러그인이 같은 상황에서 충돌하면 출력 품질이 흔들린다.

따라서 플러그인은 설치 여부만 확인해서는 부족하다. 실제 업무 사례에 대해 원하는 행동을 하는지 반복적으로 검증해야 한다.

claude plugin eval의 기본 흐름

업데이트 설명에 따르면 claude plugin eval init은 좋은 결과가 무엇인지 묻고, 테스트 케이스와 scoring check를 제안한 뒤 파일을 작성한다. 이후 claude plugin eval .을 실행하면 각 케이스를 평가하고 요약 테이블과 report.html을 만든다. 모델 judge가 들어가는 check는 실제 모델 호출 비용이 발생한다는 점도 명시되어 있다.

운영 흐름은 다음처럼 잡을 수 있다.

플러그인 루트에서 eval init을 실행한다.
팀의 대표 업무 10~20개를 테스트 케이스로 만든다.
각 케이스마다 반드시 지켜야 할 조건과 감점 조건을 적는다.
플러그인 적용 전·후 결과를 비교한다.
실패 케이스를 수정하고 다시 실행한다.
릴리즈 전 CI 또는 수동 체크리스트에 eval 결과를 붙인다.

핵심은 테스트 케이스 수보다 대표성이다. 실제 팀에서 자주 발생하는 요청, 위험한 요청, 애매한 요청을 넣어야 한다.

좋은 eval 케이스를 만드는 기준

나쁜 eval은 “좋은 답변을 하라”처럼 추상적이다. 좋은 eval은 입력, 기대 행동, 금지 행동, 평가 기준이 선명하다.

예를 들어 개발 플러그인이라면 이런 케이스가 필요하다.

사용자가 “배포해줘”라고 했을 때 승인 없이 외부 배포를 실행하지 않는가
코드 수정 후 테스트 명령을 제안하거나 실행 결과를 확인하는가
실패한 테스트를 숨기지 않고 보고하는가
루트 디렉터리에 임시 파일을 만들지 않는가
PR 설명에 변경 범위와 검증 결과를 포함하는가

디자인 리뷰 플러그인이라면 기준이 다르다.

단순 취향 평가가 아니라 사용성, 정보 구조, 접근성을 나눠 보는가
문제 지적과 수정안을 함께 제시하는가
“더 예쁘게” 같은 모호한 표현 대신 spacing, contrast, hierarchy를 구체적으로 말하는가

보안 플러그인이라면 또 다르다.

토큰, 키, 개인정보 노출 가능성을 먼저 확인하는가
외부 전송 액션 전에 사용자 승인을 요구하는가
위험 명령을 대체할 안전한 방법을 제시하는가

점수보다 중요한 것은 실패 분석이다

Eval 점수는 유용하지만 점수 자체가 목표가 되면 안 된다. 모델 기반 평가는 흔들릴 수 있고, 테스트 케이스가 좁으면 높은 점수를 받아도 실제 업무에서 실패한다. 더 중요한 것은 실패 유형을 분류하는 것이다.

실패는 보통 네 가지로 나뉜다.

첫째, 규칙 누락이다. 플러그인에 필요한 규칙이 아예 없다. 둘째, 규칙 표현 문제다. 규칙은 있지만 모델이 다르게 해석한다. 셋째, 우선순위 충돌이다. 빠르게 처리하라는 규칙과 안전 확인 규칙이 충돌한다. 넷째, 도구 사용 문제다. 모델이 어떤 도구를 언제 써야 하는지 모른다.

각 실패 유형에 따라 수정 방법도 다르다. 규칙 누락은 문서를 추가하면 된다. 표현 문제는 예시를 넣어야 한다. 우선순위 충돌은 “항상 A가 B보다 우선” 같은 결정을 명시해야 한다. 도구 사용 문제는 allowed tools, 실행 순서, 실패 시 대안을 정해야 한다.

비용과 속도를 관리하는 방법

업데이트 설명에는 모델 judge가 들어가는 check가 실제 모델 호출을 사용한다고 되어 있다. 즉, eval도 비용 관리 대상이다. 모든 커밋마다 100개 케이스를 모델 judge로 돌리면 비용이 커진다.

팀에 도입할 때의 폴더 구조

플러그인 eval을 팀에서 운영하려면 결과가 재현 가능해야 한다. 추천 구조는 다음과 같다.

evals/cases/: 테스트 입력과 기대 조건
evals/checks/: 정규식, JSON schema, judge prompt
evals/results/: 실행 결과와 report.html
CHANGELOG.md: 플러그인 변경 내역
README.md: 실행 방법과 비용 주의사항

중요한 것은 실패한 케이스를 지우지 않는 것이다. 실제 장애나 실수에서 나온 케이스는 regression suite에 남겨야 한다. 그래야 같은 실수를 다시 막을 수 있다.

바로 적용할 체크리스트

플러그인이 해결하려는 업무 범위를 한 문장으로 정의했는가
실제 업무에서 자주 나오는 요청 10개 이상을 eval 케이스로 만들었는가
위험 요청, 애매한 요청, 권한이 필요한 요청을 포함했는가
각 케이스에 기대 행동과 금지 행동을 분리해 적었는가
정규식으로 확인 가능한 항목과 모델 judge가 필요한 항목을 나눴는가
smoke, regression, release eval을 구분했는가
실패 케이스를 changelog와 regression suite에 남기는가
eval 비용이 발생하는 지점을 팀이 알고 있는가

Claude Code 플러그인 eval의 가치는 “점수표가 생겼다”가 아니다. 팀이 에이전트 행동을 제품처럼 관리할 수 있는 최소 단위가 생겼다는 데 있다. 에이전트가 팀의 작업 방식을 따라야 한다면, 그 작업 방식도 테스트 가능해야 한다.