eval-harness

eval-harness 스킬 개요

eval-harness가 하는 일

eval-harness 스킬은 Claude Code 세션과 eval 기반 개발을 위한 공식 평가 프레임워크입니다. 배포하기 전에 무엇이 “좋은 결과”인지 먼저 정의하고, 에이전트·프롬프트·워크플로가 실제로 그 기준을 충족하는지 측정할 수 있게 도와줍니다.

누가 사용하면 좋은가

AI 보조 코딩, 프롬프트 변경, 에이전트 동작에 대해 반복 가능한 검증이 필요하다면 eval-harness 스킬을 사용하세요. 모델 버전을 비교하는 팀, 회귀(regression)를 추적하는 팀, 모호한 작업 기대치를 합격/불합격 기준으로 바꾸려는 팀에 특히 유용합니다.

왜 중요한가

Model Evaluation을 위한 eval-harness의 핵심 가치는 신뢰성입니다. 결과를 느낌으로 판단하는 대신, 동작이 언제 어떻게 바뀌는지 드러내는 eval을 작성할 수 있기 때문입니다. 덕분에 에이전트 성능을 더 쉽게 디버깅하고, 실행 결과를 비교하고, 품질을 조용히 떨어뜨리는 프롬프트 업데이트를 배포하는 일을 막을 수 있습니다.

언제 적합한가

이 스킬은 작업을 관찰 가능한 성공 기준, 출력 구조, 체크포인트가 있는 동작으로 표현할 수 있을 때 가장 잘 맞습니다. 반대로 범위가 넓고 창의적인 작업은, 측정 가능한 합격 조건을 정의할 수 있을 때만 효과적으로 활용할 수 있습니다.

eval-harness 스킬 사용 방법

설치하고 활성화하기

eval-harness install을 하려면 Claude Code 환경에서 저장소의 스킬 설치 흐름을 사용한 뒤, 스킬 파일을 직접 열어보세요. 이 스킬은 skills/eval-harness/SKILL.md에 있으며, 프레임워크를 언제 활성화할지와 eval을 어떻게 구성할지를 정의하므로 가장 먼저 읽어야 하는 파일입니다.

스킬이 평가할 수 있는 프롬프트 만들기

eval-harness usage를 제대로 하려면 “내 에이전트를 테스트해줘”처럼 시작하지 마세요. 대신 에이전트가 완료해야 할 작업, 성공으로 볼 조건, 실패의 모습, 능력 검증인지 회귀 검증인지 같은 구체적인 목표부터 정해야 합니다. 더 나은 입력 예시는 다음과 같습니다: “검증을 깨뜨리지 않고 React 폼을 업데이트할 수 있는지 평가하고, 명시적인 성공 기준 3개를 요구해줘.” 이렇게 해야 harness가 측정 가능한 대상을 갖게 됩니다.

먼저 읽어야 할 파일 보기

자신의 워크플로에 eval-harness guide 방식을 적용하려면, 먼저 SKILL.md를 읽고 그다음 평가 스타일, 채점 로직, 출력 규칙을 설명하는 저장소 노트를 확인하세요. 이 저장소에는 보조 스크립트나 추가 지원 폴더가 없으므로, 스킬 파일 자체가 사실상의 단일 기준(source of truth)입니다.

실무 워크플로에 적용하기

좋은 워크플로는 이렇습니다: 동작을 정의하고, 정상 경로(happy path)용 eval 하나를 작성한 뒤, 이미 알려진 실패를 위한 회귀 eval 하나를 추가하고, harness를 실행한 다음 기준을 다듬습니다. 이렇게 하면 eval이 너무 커져서 디버깅하기 어려워지는 일을 막을 수 있고, 해석하기 힘들 정도로 넓은 테스트를 쓰는 것도 줄일 수 있습니다.

eval-harness 스킬 FAQ

eval-harness는 Claude Code 전용인가요?

아닙니다. 이 스킬은 Claude Code 세션을 기준으로 작성됐지만, 구조화된 에이전트 평가가 필요한 곳이라면 어디서든 유용합니다. 사용하는 스택이 다른 도구를 기반으로 하더라도, eval 형식과 채점 로직은 그대로 맞춰 쓸 수 있습니다.

eval-harness는 일반 프롬프트와 같은가요?

아닙니다. 일반 프롬프트는 답을 요청하지만, eval-harness는 그 답을 반복 가능하게 판단하는 방법을 요구합니다. 버전이 달라도 일관성이 필요할 때는 이 차이가 매우 중요합니다. 단순히 한 번 잘 나오는 응답이 필요한 게 아니라면 더더욱 그렇습니다.

초보자도 쓰기 쉬운가요?

네, 작업을 분명하게 설명할 수 있다면 가능합니다. 더 어려운 부분은 문법이 아니라 좋은 성공 기준을 쓰는 일입니다. 초보자는 전체 워크플로를 한 번에 모델링하려 하기보다, 간단한 능력 평가 하나로 시작할 때 대체로 더 잘합니다.

언제 쓰지 않는 게 좋나요?

작업이 매우 주관적이거나, 결과를 일관되게 확인할 수 없거나, 단발성 답변만 필요하다면 eval-harness는 건너뛰세요. 신뢰성, 회귀 추적, 모델 비교가 실제 목표일 때 가장 강합니다.

eval-harness 스킬 개선 방법

기준을 관찰 가능하게 만들기

가장 큰 품질 향상은 의견을 체크 가능한 조건으로 바꾸는 데서 나옵니다. “더 좋게 만들어줘” 대신 “기존 API 형태를 유지한다”, “유효한 JSON을 반환한다”, “세 개의 회귀 사례를 모두 통과한다”처럼 조건을 제시하세요. 기준이 더 관찰 가능할수록 eval-harness는 실행도, 신뢰도도 높아집니다.

능력 평가와 회귀 평가를 분리하기

새 기능 검증과 기존 동작 검증을 섞으면 실패 원인을 해석하기 어려워집니다. 능력 eval은 Claude가 새로운 일을 할 수 있는지에만 집중하고, 회귀 eval은 알려진 기준선이 여전히 유지되는지에 집중하세요.

harness에 실제 엣지 케이스를 넣기

더 강한 eval에는 정상 경로만이 아니라 실패 모드도 포함됩니다. 까다로운 입력, 불완전한 컨텍스트, 모호한 지시를 추가해 eval-harness skill이 에이전트가 강한지, 아니면 깨끗한 예시에서만 운이 좋았는지를 드러내게 하세요.

첫 실행 뒤에 반복 개선하기

첫 실행은 증명이 아니라 보정으로 보세요. 결과가 불명확하다면 성공 기준을 더 엄격하게 만들고, 기준선을 추가하고, 하나의 큰 eval을 더 작은 검사로 나누세요. 보통 이 방법이 eval-harness usage를 개선하고 실제로 행동에 옮길 수 있는 결과를 얻는 가장 빠른 길입니다.