grahama1970/agentic-evals

agentic-evals은(는) 무엇을 하나요?

일회성 스모크 테스트로는 부족하고 반복 가능하고 증거 기반의 스킬 또는 에이전트 워크플로우 평가가 필요한 작업에 이 스킬을 사용하세요.

현재 범위

이 초기 번들은 명령어 기반 케이스를 위한 결정론적 픽스처 실행기를 제공합니다. 각 케이스를 여러 번 실행하고, stdout/stderr/종료 상태 및 소요 시간을 기록하며, 명시적인 기대치를 확인하고, 머신이 읽을 수 있는 준비 요약을 생성합니다.

이는 선언된 픽스처 동작만 증명합니다. 의미론적 정확성, 실제 서비스 통합, LLM 심사 품질 또는 릴리스 준비 상태는 픽스처 명령어 자체가 해당 라이브 경로를 실행하지 않는 한 증명하지 않습니다.

사용법

./run.sh run fixtures/agentic_eval.json
./run.sh run fixtures/agentic_eval.json --output /tmp/agentic-evals-report.json
./run.sh audit-skills ../ --output /tmp/agentic-evals-baseline-gap-report.json
./run.sh scaffold-fixture ../some-skill --output ../some-skill/fixtures/agentic_eval.json
./run.sh apply-scaffolds ../ --write --output /tmp/agentic-evals-apply-scaffolds.json
# 라이브 디스커버리를 통한 요구사항-저니 계획 (#1629)
./run.sh plan-journeys --fixture fixtures/agentic_eval.json \
  --requirements requirements.json \
  --interaction-inventory discovery/discovery-inventory.json \
  --state-graph discovery/state-graph.json \
  --output journey-plan.json [--scaffold-output fragment.json] [--report-only]
# 클레임 / 증거 / 회귀 / 커버리지 (#1445-#1448)
./run.sh regressions audit ../ --output /tmp/agentic-evals-regressions.json
./run.sh regressions show . && ./run.sh regressions verify .
./run.sh coverage audit ../ --output /tmp/agentic-evals-coverage.json
./run.sh coverage show .

클레임 기반 준비 (#1445)

결정론적 테스트는 메커니즘을 증명하고, 실제 E2E는 역량을 증명합니다. 통과하는 결정론적 케이스의 더미는 실제로 실행되지 않은 라이브 역량에 대한 준비 상태처럼 보여서는 안 됩니다. 따라서 준비 상태는 선언된 각 능력 클레임별로 계산된 후 집계되며, 케이스 수에서 계산되지 않습니다.

capability_claims를 선언하세요 (증명 범위 설명과 별도로 유지하여 v2 픽스처가 유효하도록). 각 클레임을 지원하는 케이스는 자체 태그를 지정합니다:

{
  "capability_claims": [
    {"id": "ask.roundtable.mixed_provider", "description": "...",
     "criticality": "critical",
     "evidence_required": {"deterministic": true, "live_e2e": true}}
  ],
  "cases": [
    {"name": "roundtable-live", "type": "positive", "evidence_class": "live_e2e",
     "supports_claims": ["ask.roundtable.mixed_provider"],
     "command": ["bash", "run.sh", "..."],
     "expected": {"exit_code": 0, "artifacts": [{"path": "out/join.json", "json_pointer": "/settled", "equals": true}]}}
  ]
}

증거 클래스: deterministic, property_or_fuzz, fault_injected_deterministic, live_e2e, adversarial_live_e2e, human_evaluation. 클레임별 판정: PROVEN, PARTIALLY_PROVEN, BLOCKED_EXTERNAL, FAILED, NOT_ESTABLISHED. 모든 필수 중요 클레임이 자체 증거 요구사항에 따라 PROVEN인 경우에만 스킬이 READY 상태입니다. 클레임이 선언되면 run의 게이트는 케이스 기반 및 클레임 기반 준비 상태 중 더 나쁜 쪽이므로, 충족되지 않은 필수 live_e2e 슬롯이 있는 20개의 녹색 결정론적 케이스는 READY에 도달할 수 없습니다. 둘 이상의 클레임을 지원하는 라이브 케이스는 클레임당 독립적인 아티팩트를 제공해야 하며, 그렇지 않으면 어느 클레임에도 포함되지 않습니다. report["capability_readiness"]는 클레임별 분석 결과를 보유합니다.

불변성에서 파생된 클레임 (답변을 스텁(stub)하지 마세요) — 운영자 2026-09-11

oai-트라이얼은 한 가지 누락으로 실패했습니다: "PII가 출력에 도달하지 않음" 요구사항이 조용히 "PII 문자열이 출력에 도달하지 않음"으로 축소되었습니다. 모든 평가, 검증기, 자격 실행은 축소된 클레임이 녹색임을 증명했지만, 정수 유형의 전화번호는 그대로 통과했습니다. 클라이언트는 도메인 범위에서 불변성을 읽었고, 우리는 메커니즘 범위에서 증명했습니다. 규칙:

1. 클레임은 코드가 이미 수행하는 작업에서 파생되지 않고 도메인 불변성에서 파생됩니다. capability_claims를 선언하기 전에 클라이언트의 표현으로 불변성을 작성하고("X가 어떤 표현으로든 출력에 도달하지 않음"), 그대로 중요한 클레임으로 선언하세요. 현재 동작을 설명하는 클레임은 스텁입니다.
2. 값 관련 클레임에는 표현 매트릭스가 필수입니다. 데이터 값(PII, 금융 정보, 식별자, 비밀)에 대한 모든 클레임은 입력 형식이 허용하는 표현(JSON 문자열/정수/실수/과학적 표기법, CSV 인용, SQL 유형)을 열거하고, 각 표현당 하나 이상의 적대적 사례를 포함해야 하며, 각각 실패할 수 있어야 합니다. 표현 매트릭스 없이 값 관련 클레임은 PROVEN될 수 없습니다.
3. 데이터 값을 변환, 필터링 또는 마스킹하는 모든 파이프라인에는 value-representation(중요도: critical)이라는 커버리지 심(seam)이 필요합니다. 감사는 해당 심에 유능한 가드가 있음을 보여야 합니다.
4. 독립적인 검사기는 생산자의 데이터 생성기를 공유해서는 안 됩니다. 검증기의 픽스처에는 변환 자체의 픽스처에 없는 표현이 포함되어야 하며, 그렇지 않으면 독립성은 명목상에 불과합니다.
5. 표현 격차가 발생하면 fixtures/regressions.json(인시던트 → 유지된 가드)과 value-representation 심에 기록합니다. 동일한 유형의 누락은 영원히 감지 가능해야 합니다.

안티-슬롭 계약은 자기만족적인 배관을 거부합니다. 이 규칙들은 자기만족적인 가정을 거부합니다 — 정직하고, 적대적이며, 다중 시험을 수행하고, 데이터 형태에 대한 하나의 보이지 않는 전제 조건을 모든 픽스처가 공유하기 때문에 여전히 눈이 먼 스위트입니다.

실제 종단간 증거 계약 (#1446)

evidence_class는 run.sh 또는 curl을 포함하는 명령어에서 유추되지 않습니다. 라이브 클래스(live_e2e/adversarial_live_e2e)를 선언하는 케이스는 구조적으로 자격이 확인되며, 다음과 같은 경우 다운그레이드(묵인되지 않음)됩니다:

• 경계 권한으로 fixtures//스텁/mocked 입력을 자체 공급하는 경우;
• 실질적인 프로덕션 진입점에 도달하지 않는 경우;
• 독립적인 읽기 확인 오라클(expected.artifacts, readback: true, 또는 stdout_excludes)이 없는 경우 — 종료 코드와 명령어 자체의 성공 문구는 증거가 아닙니다. 또는
• --execute 및 브라우저/제공자 실행 아티팩트(예: node-receipt.json, response.md, response.meta.json, browser-tab-lifecycle.json, execution-status.json, roundtable-summary.md, 또는 compete-scorecard.json)의 읽기 확인 없이 $ask 브라우저 tau-dag/compete 핸들러에 대한 라이브 증거를 주장하는 경우. 컴파일/사전 확인 전용 $ask 케이스는 결정론적 메커니즘 증거이며, 절대 live_e2e가 아닙니다.

다운그레이드된 케이스는 fault_injected_deterministic(실제 경로의 결함) 또는 deterministic이 되며, 보고서는 evidence_disqualifiers를 기록합니다. BLOCKED_EXTERNAL 케이스에 의해서만 충족되는 필수 라이브 슬롯은 클레임을 PROVEN 상태로 만들지 않습니다.

면제는 명시적이고 만료됩니다. 클레임은 evidence_class, reason_code, justification, owner, expires를 명명하는 exemptions를 포함할 수 있습니다. 유효한 면제는 보고서에 표시되지만(exempt_evidence) 클레임을 PROVEN으로 만들지 않습니다. 만료되었거나 불완전한 면제는 무시됩니다. 실행 가능한 운영 능력을 충족시키는 포괄적인 eval_not_required는 없습니다.

인시던트 → 유지된 회귀 (#1447)

라이브 실패는 fixtures/regressions.json(agentic_evals.regressions.v1)에 영구적인 증거가 됩니다. 각 레코드는 인시던트를 그것이 위협한 클레임 및 심에 연결하고, 유지된 가드 케이스(retained_case / retained_fixture)의 이름을 지정하며, fail_before_fix.proof_command를 포함합니다.

• regressions show <skill> / regressions audit <root> 보고서: 보호되지 않은 회귀(유지된 케이스 누락/이름 변경), 입증되지 않은(잠재적으로 공허한) 회귀, 오래된 라이브 증거, 폐기된 회귀, 그리고 회귀 매핑이 없는 열린 인시던트를 보고합니다.
• regressions verify <skill>는 각 증명 명령어를 재실행하고 가드가 실제로 손상된 동작에 대해 실패하는지(0이 아닌 종료) 확인합니다 — 자체 보고 플래그가 아닌 비-공허성 증명입니다. 활성 회귀의 가드가 실패-전-수정을 입증할 수 없는 경우 0이 아닌 종료 코드를 반환합니다.

버그를 수정하기 위해 평가 기대치를 손상된 출력과 일치하도록 편집하는 것은 정확히 비-공허성 증명이 잡아내는 것입니다. 회귀를 폐기하려면 retirement 이유가 필요합니다.

위험 기반 커버리지 충분성 (#1448)

케이스 수를 세는 것은 조작 가능합니다. coverage audit/coverage show는 선언된 각 seam에 대해 묻습니다: 해당 심의 위험이 요구하는 각 증거 클래스에서, 해당 심에서 회귀를 감지할 수 있는 케이스가 하나 이상 있습니까? seam_id, seam_type, criticality, required_evidence와 함께 seams를 선언하고, seams로 케이스에 태그를 지정하세요. 케이스가 해당 심을 나열하고 그리고 실패할 수 있는 오라클을 가지고 있는 경우에만 심을 커버합니다. 맨 exit 0 긍정 케이스는 weak_only이며 계산되지 않습니다. 감사는 커버된/커버되지 않은 심, 약한 전용 커버리지, 라이브 vs 결정론적 커버리지, 매핑된 인시던트 회귀, 우선순위가 지정된 다음 평가를 보고합니다. 커버리지(유능한 가드가 선언됨)와 신선도(라이브 증거가 최신임)는 별개의 차원입니다. 실행기는 여기서 심 케이스를 실행하지 않습니다.

픽스처 계약

{
  "version": 2,
  "skill": "example-skill",
  "trials": 3,
  "proof_scope": "fixture wiring smoke",
  "claims": {
    "proves": "the declared command exits with the expected status",
    "does_not_prove": "semantic correctness, live service behavior, or full skill readiness"
  },
  "cases": [
    {
      "name": "happy-path",
      "type": "positive",
      "command": ["echo", "success"],
      "expected": {
        "exit_code": 0,
        "stdout_contains": ["success"]
      }
    }
  ]
}

각 케이스는 다음을 선언해야 합니다:

• name
• type: positive, negative, 또는 adversarial
• command: 비어 있지 않은 argv 목록
• expected.exit_code

선택적 기대치:

• expected.stdout_contains
• expected.stderr_contains
• must_exercise: 케이스의 최상위 명령어에 나타나야 하는 다운스트림 계약 명령어 하위 문자열 목록입니다. 예를 들어 래퍼가 성공을 위조할 수 있는 경우 유용합니다. 예를 들어 $ticket/$project-watchdog 라우팅 가능성을 주장하는 평가는 OK를 출력하는 도우미 스크립트만이 아닌 "skills/ticket/run.sh feature"를 포함해야 합니다.

안티-슬롭 계약 (fail-closed)

스킬 평가 픽스처는 실제 증명이 아닌 자기만족적인 결정론적 배관인 경우 로드 시점에서 거부됩니다(0이 아닌 종료 코드, 실행 없음). 통과하려면 스킬 픽스처는 다음을 반드시 충족해야 합니다:

• trials >= 2 설정 (단일 시험은 증거가 아님);
• 최소 하나의 negative 또는 adversarial 케이스 포함 (모든 긍정 픽스처는 자기만족적임);
• 최소 하나의 실제 세계 케이스 포함: "real_world": true이고 명령어가 라이브 경로(스킬의 run.sh / 스크립트 / 라이브 HTTP / 테스트 러너)를 실행하며, 자체적으로 fixtures/ 스텁 입력을 제공하지 않아야 함;
• 아무것도 증명하지 않는 사소한 echo/상수 케이스가 없어야 함.

거부 메시지는 모든 위반 사항을 명명합니다. 이는 스킬이 실제로 작동하는지에 대해 아무것도 증명하지 않으면서 통과하는 평가를 방지합니다.

규정 준수 계층 ("eval_tier": "compliance")

규정 준수 파이프라인 단계를 보호하는 픽스처는 "eval_tier": "compliance"를 선언하고, 실행기는 기본 계약 위에 강력한 계약을 의무화합니다(운영자 지시 2026-08-12, "이것은 규정 준수 파이프라인이므로 강력하게 강화되어야 함"). 이러한 픽스처는 다음을 충족하지 않으면 거부됩니다:

• 케이스의 엄격한 과반수가 adversarial/negative인 경우 (정확히 절반이 아닌 절반 이상 — 긍정 제어는 소수여야 함);
• 최소 하나의 케이스가 비-결정론적인 경우: 명령어가 --samples, --seed 또는 셸 $RANDOM을 통해 실행마다 새로운 입력을 샘플링합니다(고정 키가 있는 프로브 스크립트 이름은 계산되지 않음);
• 모든 비-결정론적 케이스가 --samples >= 50을 명명하여 각 단계의 커버리지가 실행당 수백에서 수천 개의 어설션, 모드별로 단계당 약 1000개를 목표로 합니다.

선언은 조용히 완화될 수 없습니다. 규정 준수 파이프라인 자체의 픽스처가 계층을 설정하므로 게이트를 피하기 위해 제거하는 것 자체가 회귀입니다. tests/test_compliance_tier_gate.py는 각 규칙을 약화에 고정합니다.

두 가지 정직하게 선언된 면제는 게이트를 우회합니다. 실제 스킬 평가에는 유효하지 않습니다:

• "eval_kind": "runner_selftest" — 이 러너 자체를 테스트하거나 문서 예제인 픽스처.
• "eval_kind": "scaffold" — scaffold-fixture / apply-scaffolds에 의해 생성된 기계적 첫 번째 포즈 픽스처로, 감사에서 여전히 실제 케이스가 필요함을 표시합니다.

준비 매핑

준비 상태는 필수 케이스에 대해서만 점수가 매겨집니다("required": false는 케이스를 선택 해제함). BLOCKED 필수 케이스는 READY에 도달할 수 없습니다: 충족되지 않은 전제 조건은 성공의 증거가 아니라 증거의 부재입니다.

• READY: 모든 필수 케이스가 모든 시험을 통과했습니다.
• USABLE_WITH_GAPS: 적어도 하나의 시험은 통과했고 적어도 하나는 통과하지 못했습니다.
• NOT_READY: 시험은 실행되었지만 필수 케이스가 완전히 통과되지 않았습니다.
• NOT_ESTABLISHED: 실행된 케이스가 없습니다.

Fail-closed 종료

run은 준비 상태가 READY가 아니면 0이 아닌 종료 코드로 종료됩니다. USABLE_WITH_GAPS에서 0으로 종료하는 러너는 실패한 케이스에도 외부 CI 작업을 녹색으로 통과시켜, 이 게이트가 방지하려는 실패의 전부입니다. 게이트 없이 보고서만 필요한 경우 --report-only를 전달하세요.

케이스 결과

각 케이스는 하나의 outcome을 보고합니다. 이는 게이트에 대해 각각 다른 의미를 갖기 때문입니다:

결과	의미
PASS	모든 시험이 모든 기대치를 충족했습니다
FAIL	결함, 시간 초과 또는 하위 프로세스를 남긴 시험
BLOCKED	전제 조건이 충족되지 않음; blocked_when_stdout_contains를 통해 마커 선언
NOT_TESTED	실행된 시험이 없음

아티팩트 어설션

stdout 부분 문자열 일치는 "이 두 영수증이 동일한 세션을 명명함" 또는 "실행이 아무것도 남기지 않음"을 표현할 수 없습니다. expected.artifacts를 선언하세요:

"expected": {
  "exit_code": 0,
  "artifacts": [
    {"path": "out/session.json", "json_pointer": "/sessionId",
     "equals_artifact": {"path": "out/detach.json", "json_pointer": "/sessionId"}},
    {"path": "out/attach.json", "json_pointer": "/sessionId",
     "not_present": true}
  ]
}

지원되는 어설션:

• equals: 리터럴 값과 정확히 일치
• matches: 정규식
• not_equals: 리터럴 값과 일치하지 않음
• exists: 포인터가 가리키는 키/인덱스가 존재함 (값 무시)
• not_present: 포인터가 해결되지 않아야 함
• equals_artifact: 다른 아티팩트의 JSON 포인터 값과 동일
• length_gte, length_lte, length_eq: 배열 길이 제약

실행 시간 및 위험 신호

보고서에는 각 케이스에 대해 mean_duration_ms, p95_duration_ms, trial_count가 포함됩니다. 모든 시험에서 평균 이상으로 느린 케이스는 risk_signals 아래에 duration_spike가 표시됩니다. --trial-timeout-ms로 시간 초과를 설정할 수 있습니다.

환경

픽스처는 환경 변수 없이 실행되어야 합니다. 필요한 경우 각 픽스처는 env_vars 아래에 의존성을 선언합니다:

{
  "env_vars": {
    "required": ["SKILL_API_KEY"],
    "optional": ["LOG_LEVEL"]
  }
}

required 변수가 누락된 케이스는 BLOCKED로 표시됩니다.

보고서 출력

run은 stdout에 사람이 읽을 수 있는 요약을 인쇄하고 --output에 머신이 읽을 수 있는 JSON 보고서를 작성합니다:

{
  "skill": "example-skill",
  "readiness": "NOT_READY",
  "summary": {
    "total_cases": 2,
    "passed": 1,
    "failed": 1,
    "blocked": 0,
    "not_tested": 0,
    "trials_per_case": 3,
    "total_duration_ms": 1500
  },
  "cases": [
    {
      "name": "happy-path",
      "type": "positive",
      "outcome": "PASS",
      "duration_ms": 500,
      "trials": [{"trial": 1, "exit_code": 0, "duration_ms": 450}, ...]
    }
  ],
  "risk_signals": [],
  "capability_readiness": {}
}

종속성

• jq — JSON 처리
• bash >= 4.0