AI Forge Eval은(는) 무엇을 하나요?
스킬과 에이전트의 행동 검증. 루브릭 점수 평가(ai-forge-judge)는 아티팩트가 잘 작성되었는지 알려줍니다. Eval은 실제로 작동하는지 알려줍니다.
SKILL.md(스킬) 및 .agent.md(에이전트)에서 작동합니다. 동일한 5단계 흐름; 2단계 설정은 아티팩트 유형에 따라 다릅니다.
0단계 — 스위트 불러오기 또는 작성하기
필수 — references/eval-suite.md 읽기 — 디스크 저장 형식, 트리거 프로토콜, 단언문 판별 테이블을 확인하세요.
아티팩트 옆에 evals/evals.json이 있는지 확인하세요.
- 있음 — 불러와서 2단계로 건너뜁니다. 커버리지가 부족하면 케이스를 추가하되, 기존 케이스를 조용히 교체하지 마세요. 그렇지 않으면 추세가 깨집니다.
- 없음 — 1단계에서 작성하고 아티팩트를 생성하기 전에
evals/evals.json에 저장합니다.
이 대화 내에서만 존재하는 스위트는 다음 달에 회귀를 감지할 수 없습니다. 지속적으로 저장하는 것이 의견과 테스트를 구분하는 핵심입니다.
1단계 — 평가 케이스 작성
2-3개의 평가 케이스를 작성합니다. 각 평가는 현실적인 프롬프트와 3-5개의 단언문으로 구성됩니다.
아티팩트 자체에 명시된 트리거보다는 기준선 프로브(ai-forge-create 1b단계)에서 가져온 프롬프트를 선호하세요. 아티팩트로부터 작성된 단언문은 아티팩트가 주장하는 대로 동작하는지만 확인할 수 있습니다. 각 캡처는 시나리오의 baseline_failure 필드에 기록하세요.
스킬의 경우: 스킬을 자연스럽게 활성화해야 하는 프롬프트입니다. 단언문은 스킬별 동작을 확인합니다 (예: "출력에 1단계 요약이 포함됨", "NEVER 규칙 형식에 WHY와 INSTEAD가 있음").
에이전트의 경우: 에이전트의 명시된 범위를 다루는 프롬프트입니다. 단언문은 관찰 가능한 동작(생성된 파일, 호출된 도구, 어조 제약, 범위 제한 등)을 확인합니다 (예: "src/lib/ 외부의 파일을 수정하지 않음", "PR을 열었음", "커밋 메시지가 'refactor:'로 시작함").
단언문 규칙:
- 확인 가능: 평가자가 출력만으로 확인 가능해야 함
- 구체적: "출력이 잘 구조화됨"보다 "출력에 'Phase 1' 헤더가 포함됨"이 더 나음
- 반증 가능: 실패할 가능성이 있어야 함
평가 케이스 기록:
Eval 1: <프롬프트>
기대 사항:
- <단언문 1>
- <단언문 2>
- <단언문 3>
2단계 — 병렬 실행
각 평가 케이스에 대해 같은 메시지 내에서 아티팩트 실행과 기준선 실행을 동시에 시작합니다(절대 순차적으로 하지 마세요). 벤치마크 모드에서는 평가당 N개의 시행-쌍이 됩니다 — 아래 벤치마크 모드 참조.
아티팩트 실행: 평가 프롬프트를 제공합니다. 스킬의 경우: "이 작업에는 <skill-name> 스킬을 사용하세요."를 추가합니다. 에이전트의 경우: 에이전트의 전체 지침을 시스템 컨텍스트로 붙여넣습니다.
기준선 실행: 측정 대상에 따라 다릅니다.
- 새 아티팩트 — 동일한 평가 프롬프트, 스킬 지침 없음, 에이전트 컨텍스트 없음. 일반 어시스턴트 응답.
- 기존 아티팩트 개선 — 먼저 현재 버전을 스냅샷으로 복사(
cp -r <path> <scratch>/snapshot/)한 다음 기준선을 스냅샷으로 설정합니다. "아티팩트 없음"은 변경이 도움이 되었는지 묻는 질문에 대한 잘못된 대조군입니다. 이는 아티팩트의 존재를 측정할 뿐, 편집 자체를 측정하지 않습니다.
완료 즉시 캡처: 각 작업 알림이 도착하면 어떤 실행인지(그리고 벤치마크 모드에서는 시행 인덱스) 기록하고 <usage> 블록에서 duration_ms와 subagent_tokens를 읽습니다 — 정확히, 추정하지 마세요. <usage> 블록이 없으면 null을 기록하고, 절대 벽시계 추정으로 대체하지 마세요. 이 데이터는 알림 시점에만 존재하며 이후에는 재구성할 수 없습니다.
평가당 저장: with_artifact 및 baseline 출력 텍스트, 각 실행의 duration_ms 및 tokens.
3단계 — 채점
필수 읽기: agents/assayer.md
각 평가에 대해 assayer를 호출하여 두 출력을 모두 평가합니다. 전달:
Output: <출력 텍스트>
Expectations:
- <단언문 1>
- <단언문 2>
Assayer가 기대 사항별로 반환:
{ "text": "...", "passed": true, "evidence": "..." }
pass_rate = passed / total (실행별) 계산.
delta = with_artifact.pass_rate - baseline.pass_rate 계산.
그런 다음 각 단언문을 두 실행에서의 동작에 따라 분류합니다 — 둘 다 통과(모델을 측정, 아티팩트 아님), 둘 다 실패(깨졌거나 도달 불가능), 아티팩트로 통과하고 기준선으로 실패(실제 신호), 아티팩트로 실패하고 기준선으로 통과(아티팩트가 해를 끼침), 또는 높은 변동성(불안정). references/eval-suite.md의 테이블을 참조하세요. 모든 단언문이 두 실행에서 통과하는 스위트는 건강한 통과율을 보고하지만 아무것도 알려주지 않습니다.
또한 출력뿐만 아니라 대화 기록을 읽으세요: 실행이 실제로 아티팩트를 따랐습니까, 아니면 아티팩트에도 불구하고 올바른 답에 도달했습니까? 아티팩트가 유발한 작업이 결과물을 내지 못한 것은 삭제 대상입니다.
3b단계 — 인간 검토
스스로 분석하기 전에 사용자에게 원시 출력을 제시하세요.
assets/eval-review.html을 채우세요 — __ARTIFACT_NAME__과 __EVAL_DATA__( {id, name, prompt, with_artifact, baseline, assertions} 의 JSON 배열)를 대체하고 평가 스위트 옆에 작성하세요. 가능한 경우 파일 전달 도구를 사용하여 표시하고, 그렇지 않으면 사용자에게 경로를 알려주세요. 사용자가 완료하면 내보낸 feedback.json을 읽으세요.
모델이 자신의 아티팩트 출력을 채점하는 것은 여기서 가장 약한 신호입니다 — 인간의 시선은 어떤 단언문도 작성하지 않은 결함을 잡아냅니다. 사용자가 거절하는 경우에만 건너뛰세요.
4단계 — 비교 (선택 사항)
필수 읽기: agents/arbiter.md — 4단계가 실행될 때만 불러오세요.
4단계 실행 조건: 델타가 0.1 이상이거나 평가 간 통과율이 충돌하는 경우.
건너뛰기 조건: 통과율이 동일하거나 사용자가 채점만 요청한 경우.
Arbiter 입력: 출력 A(레이블 없음), 출력 B(레이블 없음), 기대 사항 목록. 5단계를 위해 어느 것이 어느 것인지 기록하세요.
Arbiter 반환: 콘텐츠 점수(1-5), 구조 점수(1-5), 승자(A/B/무승부), 근거, 각 측의 강점/약점.
두 버전 비교 시 출시 게이트: 새 버전이 모든 시나리오에서 이기거나 비기고, 적어도 하나는 이겨야 출시합니다. 한 케이스에서 크게 이기고 다른 케이스에서 지는 버전은 하나의 실패를 다른 실패로 바꾼 것일 뿐, 개선이 아닙니다 — 집계 델타는 이를 숨깁니다.
5단계 — 분석 및 보고
필수 읽기: agents/refiner.md — 4단계가 실행된 경우에만 불러오세요.
4단계를 건너뛴 경우: 바로 벤치마크 테이블로 이동하세요.
Refiner 입력: arbiter 출력 + 레이블 매핑 { "A": "with_artifact", "B": "baseline" }(또는 반대). Refiner는 승자가 패자를 이긴 이유를 설명하고 1-3개의 우선순위 개선 사항을 제시합니다.
벤치마크 테이블 렌더링 — 평가당 한 행 + Avg 행, 열 Eval | with_artifact | baseline | delta | duration_ms (with / base), 각 실행의 통과 횟수 및 백분율. 3단계에서 플래그된 비판별 또는 유해 단언문을 추가한 다음, 실행된 경우 refiner의 개선 제안을 추가합니다.
델타가 음수인 평가가 있으면 플래그: "아티팩트가 성능을 저하시킬 수 있음 — 트리거 문구 또는 범위 제약 조건을 검토하세요."
6단계 — 트리거 확인
행동 평가는 "호출되었을 때 작동하는가"에 답합니다. 이 단계는 "호출되는가"에 답합니다 — 더 흔한 실패이며 위의 모든 단계에서 보이지 않습니다.
스위트에 triggers 블록이 있을 때 실행하거나, 5단계 이후에 제안하세요. 필수 — references/eval-suite.md 읽기 — 프로토콜, 60/40 홀드아웃 분할, 쿼리 품질 기준을 확인하세요. 행동 전용 실행에서는 불러오지 마세요.
분할(훈련 및 홀드아웃)별 재현율과 정밀도, 그리고 특정 누락 및 오탐지를 보고합니다. 낮은 재현율에 높은 정밀도는 설명이 너무 좁다는 의미 — 확장하세요. 반대는 인접 작업을 침범한다는 의미 — 부정 트리거를 추가하세요.
벤치마크 모드
사용자가 벤치마크, 회귀 추적 또는 추세 게이트를 요청할 때 실행합니다. 벤치마크 모드는 반복 시행과 지속적인 추세 저장소로 5단계를 확장합니다.
필수 읽기: references/benchmarking.md 실행 전 — 시행 프로토콜, 집계 공식, 게이트 임계값, 시행 결과 + benchmark.json 스키마가 여기에 있습니다. 단일 실행 평가에서는 불러오지 마세요.
- 시행 — 각 평가는 N회 실행됩니다(기본값 3). 평가당 모든 N개의 시행-쌍(2N 하위 에이전트)을 하나의 메시지에서 실행하고, 2단계당
<usage>를 캡처하면서 해당 평가의 알림을 소비한 후 다음 평가로 이동합니다. 모든 평가의 시행을 한 번에 실행하지 마세요. - 집계 —
node scripts/aggregate-benchmark.cjs --trials <scratch.json> --prior benchmarks/<artifact-name>.json --artifact <path>는 평가당 평균/표준편차, 불안정 및 판별 플래그, 이전 실행 대비 델타, 게이트 판정을 반환합니다. 실행할 수 없는 경우(node없음, 스크립트 누락, 사용법 오류)⚠ 집계 불가 — 검증기 사용 불가: <이유>와 함께 원시 시행별 결과를 보고하고 게이트 판정을 직접 계산하지 마세요. 게이트 판정은 통계적 유의성에 대한 주장이므로 추정해서는 안 됩니다. FAIL 판정은 항상 차단합니다. - 저장 — 반환된 페이로드를
benchmarks/<artifact-name>.json(커밋됨)에 저장하여 새로운 추세 기준선으로 삼습니다. - 보고 — 5단계 테이블에 평균±표준편차 열과 게이트 판정을 포함합니다. 게이트 실패 시 판정은 "회귀 — 준비되지 않음".
NEVER (절대 하지 말아야 할 것)
-
절대 시행의 아티팩트 실행과 기준선 실행을 순차적으로 실행하지 마세요 대신: 각 시행의 두 실행을 같은 메시지에서 실행하세요. 벤치마크 모드에서는 한 평가의 모든 N개 시행-쌍을 하나의 메시지에 넣고, 다른 평가는 순차적으로 배치할 수 있습니다. 이유: 순차적 실행은 피드백을 직렬화합니다; 그러나 모든 평가의 시행을 한 번에 실행하면 알림이 넘쳐 도착 시점의
<usage>캡처가 신뢰할 수 없게 됩니다. -
절대 다른 실행이 완료될 때까지 usage 캡처를 미루지 마세요 대신: 각 알림의
<usage>블록(duration_ms,subagent_tokens)을 도착하는 즉시 읽으세요. 이유:<usage>데이터는 알림 시점에만 존재하며 이후에는 재구성할 수 없습니다. -
절대 단일 시행을 벤치마크로 보고하지 마세요 대신: 평균과 표준편차가 의미 있도록 최소 N=3회 시행하세요. 이유: 단일 통과율은 정밀해 보이지만 불안정성을 숨깁니다 — 실제로 1/3 확률로 통과하는 스킬이 한 번의 시행에서 100% 또는 0%로 읽힐 수 있습니다.
-
절대 아티팩트 실행이 실패한 시나리오를 약화시키지 마세요 대신: 본문을 강화하여 실행이 작성된 시나리오를 통과할 때까지 개선하세요. 이유: 시나리오는 실제 실패의 기록입니다. 이를 약화시키면 평가는 초록불이 되지만, 이를 잡기 위해 만들어진 실패는 그대로 남습니다.
-
절대 홀드아웃 트리거 쿼리에 맞춰 설명을 조정하지 마세요 대신: 훈련 분할에서 반복하고, 최종 버전을 선택할 때만 홀드아웃을 확인하세요. 이유: 자체 테스트 세트에 맞춰 조정된 설명은 점수는 좋지만 일반화 성능이 떨어집니다 — 유일한 불편 추정치를 잃게 됩니다.
-
절대 주관적인 단언문을 작성하지 마세요 ("출력이 명확함", "잘 형식화됨", "철저함") 대신: 텍스트에서 검증 가능한 것: "출력에 'Phase 1' 제목이 포함됨", "WHY 절이 누락된 NEVER 규칙 없음" 이유: 주관적인 단언문은 assayer에게 근거 진리를 제공하지 않습니다; 통과/실패가 임의적이고 반복 불가능해집니다.
-
절대 아티팩트 실행과 기준선 실행에 다른 프롬프트를 사용하지 마세요 대신: 동일한 프롬프트 — 아티팩트 지침만 다릅니다. 이유: 프롬프트 변동은 델타를 혼란시킵니다; 프롬프트 품질을 측정할 뿐 아티팩트 효과를 측정하지 않습니다.
-
절대 비표준 필드 이름을 가진 assayer 출력을 수락하지 마세요 대신: 정확히
text,passed,evidence를 요구하세요 —name,met,details등을 거부하세요. 이유: 5단계 집계는 정확한 필드 이름에 의존합니다; 조용히 잘못된 이름은 잘못된 통과율을 생성합니다.