eval

eval skill 개요

AgentHub 세션에서 eval이 하는 일

eval은 완료된 에이전트 결과를 순위화하는 AgentHub skill입니다. 여러 에이전트가 같은 작업을 이미 수행한 뒤, 점수를 매기거나 비교하거나 최종 승자를 골라야 하는 /hub:eval 명령에 맞춰 설계되어 있습니다. eval skill은 eval 명령이 설정되어 있을 때는 지표 기반 평가를 지원하고, 사용할 수 있는 지표가 없을 때는 LLM judge 평가를 사용하며, 객관적인 점수와 코드 판단이 모두 중요할 때는 두 방식을 섞은 의사결정에도 적합합니다.

가장 잘 맞는 사용자와 작업

eval skill은 AgentHub식 멀티 에이전트 워크플로를 쓰는 개발자에게 가장 잘 맞습니다. 하나의 작업을 여러 에이전트 브랜치나 worktree에서 처리한 뒤, 마지막에 결과를 비교하는 흐름입니다. “어떤 에이전트가 가장 빠른 구현을 만들었나?”, “어떤 패치를 merge하는 것이 가장 안전한가?”, “어떤 결과가 원래 작업 요구를 가장 잘 만족하는가?” 같은 질문에 반복 가능한 답을 얻고 싶을 때 유용합니다. 반대로 독립적인 벤치마킹 프레임워크로 쓰기에는 적합도가 낮습니다. AgentHub 세션 구조, 에이전트 결과 게시물, 브랜치, diff가 있다는 전제를 두기 때문입니다.

일반 프롬프트와 eval이 다른 점

일반 프롬프트로도 LLM에게 결과 비교를 요청할 수는 있습니다. 하지만 eval은 더 구체적인 평가 경로를 제공합니다. 가능한 경우 에이전트별로 지표 명령을 실행하고, judge mode를 사용할 때는 각 에이전트의 diff와 결과 게시물을 확인합니다. 핵심 차이는 이 skill이 자유로운 의견이 아니라 완료된 AgentHub 산출물을 기준으로 assistant를 움직이게 한다는 점입니다. 그만큼 추측이 줄고, 순위 판단을 나중에 검토하기도 쉬워집니다.

도입 전에 확인할 사항

eval을 설치하거나 의존하기 전에, 현재 워크플로가 에이전트 결과를 AgentHub가 기대하는 위치에 저장하는지, 에이전트 브랜치나 worktree가 아직 접근 가능한지 확인하세요. metric mode는 정상 동작하는 평가 명령, 지표 이름, 그리고 낮을수록 좋은 latency인지 높을수록 좋은 score인지 같은 방향 설정에도 의존합니다. 이 skill의 repository 경로에는 SKILL.md만 있으므로, 대부분의 동작은 skill 디렉터리 안의 추가 helper 파일이 아니라 명령 지침에 의해 정의됩니다.

eval skill 사용 방법

eval 설치와 repository 확인

일반적인 skill installer를 사용해 GitHub skill repository에서 설치합니다. 예를 들면 다음과 같습니다.

npx skills add alirezarezvani/claude-skills --skill eval

설치 후에는 먼저 engineering/agenthub/skills/eval/SKILL.md를 읽으세요. 이 skill 디렉터리에는 로컬 rules/, resources/, references/, scripts/ 폴더가 없으므로 SKILL.md가 기준 문서입니다. 또한 skill 본문은 metric mode에서 scripts/result_ranker.py를 참조합니다. 지표 기반 ranking에 의존하기 전에, 더 넓은 AgentHub 설정 안에 해당 script 또는 동등한 평가 runner가 제공되는지 확인해야 합니다.

기본 eval 사용 명령

에이전트들이 세션을 완료한 뒤 명령을 사용합니다.

/hub:eval
/hub:eval 20260317-143022
/hub:eval --judge

/hub:eval은 최신 세션을 평가합니다. 세션 ID를 넘기면 특정 실행을 대상으로 평가합니다. --judge는 LLM judge mode를 강제로 사용합니다. metric command가 없거나, 신뢰하기 어렵거나, correctness를 판단하기에 너무 좁은 지표만 제공할 때 유용합니다.

eval이 잘 작동하도록 만드는 입력

metric mode에서는 session ID, eval command, metric label, direction을 제공하거나 설정하세요. 좋은 요청은 구체적입니다.

“Run /hub:eval 20260317-143022 using the configured benchmark. Rank by latency_ms, lower is better, and call out any agent whose result fails tests.”

LLM judge mode에서는 assistant가 base branch, agent branch, git diff, 그리고 .agenthub/board/results/agent-1-result.md 같은 결과 게시물에 접근할 수 있어야 합니다. 더 좋은 프롬프트는 작업 목표와 우선순위를 함께 제공합니다.

“Use /hub:eval --judge for the latest session. Prioritize correctness first, then minimal risk, then simplicity. Treat changed public APIs as risky unless justified in the result post.”

신뢰할 수 있는 순위를 위한 실전 워크플로

모든 에이전트가 결과를 게시했고, 각 브랜치가 diff를 확인할 수 있을 만큼 정리된 뒤에 eval을 실행하세요. 런타임, 테스트 수, 정확도, 크기, 벤치마크 출력처럼 객관적인 점수가 있는 작업이라면 metric mode부터 시작하는 것이 좋습니다. 설계, 리팩터링, 버그 수정처럼 단일 지표로 속이기 쉽거나 판단이 필요한 작업에는 LLM judge mode가 더 적합합니다. 중요한 merge라면 승자만 알려 달라고 하지 말고, 주요 위험, diff에서 확인한 근거, 동점 판단에 사용한 가정까지 함께 보고하게 하세요.

eval skill FAQ

eval은 Model Evaluation용인가요, 에이전트 결과 ranking용인가요?

이 eval skill은 범용 Model Evaluation suite가 아니라, 주로 AgentHub 에이전트 결과 ranking을 위한 도구입니다. 모델이 생성한 작업물을 평가할 수는 있지만, 비교 단위는 에이전트가 완료한 세션 결과입니다. 즉 해당 에이전트의 branch, diff, result note, 그리고 선택적으로 worktree에서 실행한 metric command가 평가 대상입니다.

metric mode와 judge mode는 언제 구분해서 써야 하나요?

성공 여부를 일관되게 측정할 수 있을 때는 metric mode를 사용하세요. 예를 들어 통과한 테스트, 벤치마크 점수, latency, memory, accuracy, bundle size 또는 다른 숫자 출력이 있는 경우입니다. 실제 질문이 패치의 정확성, 유지보수성, 안전성이라면 judge mode를 사용하세요. 지표가 목표의 일부만 반영한다면 hybrid 검토를 요청하는 것이 좋습니다. 예를 들어 지표 기준으로 순위를 매기되, diff에서 correctness나 regression 우려를 별도로 표시하게 할 수 있습니다.

초보자도 eval skill을 사용할 수 있나요?

AgentHub 세션 개념을 이미 이해하고 있다면 초보자도 eval을 사용할 수 있습니다. 명령 자체는 간단하지만, 평가 품질은 repository 상태에 크게 좌우됩니다. branch, worktree, result post, 설정된 eval command가 있어야 합니다. 이런 산출물이 없으면 초보자는 혼란스럽거나 불완전한 ranking을 보게 될 수 있습니다.

eval이 맞지 않는 경우는 언제인가요?

에이전트가 아직 작업을 끝내지 않았거나, 결과가 하나뿐이거나, assistant가 diff와 result file에 접근할 수 없다면 eval을 사용하지 마세요. 넓은 의미의 모델 벤치마킹, prompt leaderboard 생성, 오프라인 dataset 평가에도 적합하지 않습니다. 단, 주변 워크플로를 별도로 맞춰 개조한다면 사용할 수는 있습니다. 그런 경우에는 전용 evaluation harness가 더 적절합니다.

eval skill 개선 방법

더 명확한 기준으로 eval 결과 개선하기

품질을 가장 크게 끌어올리는 방법은 순위 정책을 정확히 정하는 것입니다. eval에 무엇이 가장 중요한지 알려 주세요. correctness, passing tests, performance, simplicity, security, compatibility, minimal code churn 중 무엇을 우선할지 명시해야 합니다. “pick the best”처럼 모호한 요청은 피하세요. 대신 다음처럼 요청하는 편이 좋습니다. “Rank agents by correctness first; if tied, prefer fewer changed files and no new dependencies; mention any untested assumptions.”

흔한 eval 실패 패턴 방지하기

자주 발생하는 실패에는 오해를 부르는 지표만 보고 순위를 매기는 경우, 실패하는 edge case를 놓치는 경우, 오래된 branch를 비교하는 경우, 작업을 해결하지 못한 작은 diff를 과대평가하는 경우가 있습니다. 이를 막으려면 평가 전에 base branch, session ID, metric direction, task objective를 확인하세요. judge mode에서는 특정 diff와 result post에 연결된 근거 기반 ranking을 요청하는 것이 좋습니다.

첫 ranking 이후 반복 검토하기

첫 eval 출력은 최종 판결이 아니라 의사결정 초안으로 다루세요. 승자가 의외라면 논쟁이 되는 기준에 집중해 한 번 더 검토하도록 요청할 수 있습니다. 예를 들어 “Re-evaluate only the top two agents for regression risk,” 또는 “Explain whether agent-2’s faster metric comes from skipping required behavior.”처럼 요청하세요. 이렇게 하면 전체 에이전트 세션을 다시 실행하지 않고도 eval 워크플로를 실용적으로 유지할 수 있습니다.

내 워크플로에 맞게 skill 강화하기

AgentHub 설정을 직접 관리한다면 result post 형식을 표준화하고, metric 이름을 일관되게 정하며, eval command가 결정적으로 동작하도록 만들어 eval을 개선하세요. correctness로 인정할 조건, 반드시 통과해야 하는 테스트, merge를 막는 위험 요소에 대한 프로젝트별 지침도 추가하면 좋습니다. 이 skill 자체는 작기 때문에, 세션, branch, metric에 관한 로컬 관례가 일상적인 사용에서 eval을 얼마나 신뢰할 수 있는지 결정합니다.