8.5 KiB
8.5 KiB
| spec_doc_type | spec_id | status | source_evidence | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| spec | testing/agent-comparison-benchmark | 구현됨 |
|
스펙: Agent 비교 벤치마크 파이프라인
목적
Claude Code, agy, Codex가 IOP를 경유해 수행하는 동일 과업을 설정만 바꿔 반복 실행하고, 연결 상태부터 실행·검증·채점·보고까지 재현 가능한 evidence로 남기는 현재 benchmark harness를 설명한다.
기능 목록
| 기능 | 설명 |
|---|---|
| manifest 검증 | caller, IOP direct/preset route, model, effort, fixture, 반복 횟수, timeout, evaluator와 agent-test/runs/<output-id> 경로를 검증하고 canonical digest를 만든다. |
| 연결 preflight | Claude Code, agy, Codex의 binary/config와 IOP endpoint·auth·model·effort·stream binding을 확인하고 ready, registration_required, implementation_gap으로 분류한다. |
| 격리 실행과 재개 | 각 cell/repetition을 동일 checksum의 clean workspace와 fresh caller session에서 실행하며, 종료·idle·timeout·cancel·cleanup을 bounded하게 처리한다. 실패한 attempt는 덮어쓰지 않고 명시적 재개 시 새 attempt로 남긴다. |
| 측정과 evidence | 제출, 첫 출력, 첫 파일 쓰기, model/tool/queue, finish/idle 시간을 관측 source와 함께 정규화한다. token은 보고 주체와 미제공 상태를 보존하며 임의 추정값을 authoritative 값과 섞지 않는다. |
| 웹 자동 검증 | 필수 HTML/CSS/JS와 로컬 이미지, 외부 asset 금지, desktop/mobile render, console/asset 오류, 반응형·접근성 gate와 screenshot을 확인한다. |
| 익명 품질 채점 | 필수 자동 gate를 통과한 결과만 identity를 가린 뒤 manifest에 고정된 fresh evaluator로 100점 rubric을 평가한다. 부적격 결과는 unscored, 평가 실패는 scoring_failed로 남기며 retry는 새 scoring attempt id를 사용한다. |
| 상태와 보고 | validate, preflight, run, resume, status, score, report CLI를 제공하고, 성공·실패·blocked·unscored·scoring_failed·동점을 raw evidence 포인터와 함께 deterministic Markdown으로 만든다. |
범위
- 포함: benchmark manifest, caller adapter binding, run/attempt 저장, 격리 workspace, source-aware timing/usage, 정적 웹 gate, 익명 채점, Markdown 보고.
- 제외: IOP runtime 자체 구현, provider credential 등록, 실제 9개 비교군 실행과 모델 우열 결론. 해당 실행과 결론은
[bench-02]가 소유한다.
주요 흐름
flowchart LR
Operator[사용자 또는 project skill] --> CLI[benchmark CLI]
CLI --> Manifest[manifest 검증]
Manifest --> Preflight[caller와 IOP preflight]
Preflight --> Store[append-only run store]
Store --> Attempt[clean workspace와 fresh session attempt]
Attempt --> Evidence[timing, usage와 web evidence]
Evidence --> Score[익명 evaluator scoring]
Score --> Report[deterministic Markdown report]
계약
- OpenAI-compatible caller ingress는 OpenAI-Compatible API를 따른다.
- Claude Code ingress는 Anthropic-Compatible Messages API를 따른다.
- model, direct/preset route와 protocol profile의 기준은 Edge Config And Runtime Refresh를 따른다.
- 사용자-facing orchestration과 안전한 실행 순서는 IOP Agent Comparison Benchmark skill이 소유하고, 제품 호출과 evidence 생성은 deterministic Python pipeline이 소유한다.
설정/데이터/이벤트
- manifest의 matrix cell은 stable id, caller, IOP route kind, requested/effective model과 effort를 가진다. unsupported alias나 effort는 다른 값으로 대체하지 않고 fail-closed한다.
- run state는
agent-test/runs/<output-id>/<run-id>/아래에 격리되며 manifest digest가 다른 상태를 재개하지 않는다. - preflight는 scored attempt가 아니며, 실행 중 실패·timeout·cancel과 scoring 실패는 기존 attempt를 수정하지 않고 보존한다.
- raw credential과 private endpoint는 tracked manifest, event, log, screenshot과 report에 기록하지 않는다.
- report는 run state의 canonical evidence에서 생성되며 성공하지 않은 결과를 0점으로 변환하거나 동점에 임의 순위를 부여하지 않는다.
검증
python3 -m unittest discover -s scripts/agent_benchmark -p '*_test.py'- 전체 benchmark unit/integration 계약이 통과한다.python3 -m unittest scripts.agent_benchmark.reporting_test scripts.agent_benchmark.skill_contract_test- 공개 보고 CLI와 project-local skill 계약이 통과한다.python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-manifest.example.json- 표준 manifest가 유효하다.python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-supported-direct.example.json- 지원 direct route fixture가 유효하다.python3 scripts/agent_comparison_benchmark.py validate --manifest scripts/fixtures/agent-comparison-benchmark-direct-preflight.example.json- direct preflight fixture가 유효하다.
한계와 주의사항
- example manifest와 fake adapter 테스트 통과는 실제 provider credential, endpoint 또는 preset의 live readiness를 의미하지 않는다. 실제 실행 전 redacted preflight가 필요하다.
- 현재 living spec은 비교 파이프라인의 구현 상태만 다룬다. 9개 scored cell 실행, 비교 결과와 결론은 후속
[bench-02]evidence로 관리한다. - caller나 IOP가 제공하지 않은 usage는
unavailable로 남으며, 서로 다른 clock/source의 중첩 구간을 임의로 합산하지 않는다. - benchmark 결과는 허용된
agent-test/runs/경계 안에만 생성한다.
변경 기록
- 2026-08-12:
[bench-01]종료 감사에서 확인한 421개 benchmark test, manifest/CLI 계약과 구현 evidence를 기준으로 생성했다.