15 KiB
15 KiB
SDD: [bench-01] Agent 비교 벤치마크 파이프라인 준비
위치
- Milestone: Agent 비교 벤치마크 파이프라인 준비
- Phase: PHASE.md
상태
[승인됨]
SDD 잠금
- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
- [D01] benchmark 준비는
[route-02]와 병렬로 진행하며 direct route live connectivity와 generic preset runner fixture까지만 완료 조건으로 둔다. 실제 Gemini/GPT hybrid preset live readiness와 scored 비교는[route-02]정식 smoke 뒤의 별도[bench-02]가 소유한다. - [D02] 모든 scored model 호출은 IOP를 경유하며 Claude Code, agy, Codex 차이는 runner adapter가 흡수한다.
- [D03] pipeline lifecycle은 고정하고 agent/model/preset/effort/prompt/assets/repetitions는 manifest로 바꾼다.
- [D04] 원샷은 사용자 작업 제출 1회부터 finish/complete 후 idle까지이며 내부 model/tool 호출 횟수는 제한하지 않고 측정한다.
- [D05] dev runtime 테스트베드는
../iop-s2이고 결과물은 run별 격리 workspace에 생성해 테스트베드 source를 수정하지 않는다. - [D06] 초기 반복 횟수는 1이지만 pipeline은 양수
repetitions를 지원한다. - [D07] credential/model/effort 누락은 등록·지원 요청으로, agy/Codex endpoint/auth/protocol/stream gap은 별도 구현 Plan 후보로 분류한다.
- [D08] 실제 CLI/IOP entrypoint를 직접 호출하며 Agent-Ops task dispatcher를 제품 runtime이나 benchmark harness로 사용하지 않는다.
- [D09] provider가 보고하지 않은 token은
unavailable로 기록하고 추정값을 exact source와 섞지 않는다. - [D10] 각 cell은 fresh caller session과 clean workspace를 사용하고 공통 setup/cache 정책을 기록하며, timing은 관측 clock/source를 보존하고 중첩 구간을 임의 합산하지 않는다.
- [D01] benchmark 준비는
문제 / 비목표
- 문제: 모델, caller agent, prompt와 반복 횟수를 바꿀 때마다 수동 명령과 임시 측정 방식을 다시 만들면 시간·token·품질 비교가 재현되지 않고, 연결 실패나 scored failure가 선택적으로 누락될 수 있다. 고정 lifecycle, adapter 경계, 공통 evidence schema와 secret-safe report가 필요하다.
- 비목표:
[route-02]제품 구현 또는 필수 smoke 대체- 9개 비교군의 실제 scored 실행과 우열 결론
- 범용 CI/CD scheduler나 장기 agent orchestration 제품
- raw credential, private endpoint, prompt/tool 원문을 tracked evidence에 저장하는 기능
Source of Truth
| 영역 | 기준 | 메모 |
|---|---|---|
| Roadmap | Milestone 문서 | pipeline 기능 Task와 완료 상태 원장 |
| Skill | agent-ops/skills/project/iop-agent-comparison-benchmark/ |
사용자 요청 해석, preflight와 실행·보고 진입점 |
| Pipeline | project-owned benchmark runner와 manifest schema | lifecycle, adapter, attempt/evidence 생성 구현 원본; exact 경로는 Plan에서 기존 testing 구조에 맞춰 확정 |
| Test Evidence | agent-test/runs/<run-id>/, agent-test/dev/ |
raw run evidence와 날짜별 Markdown report |
| Dev Testbed | ../iop-s2 |
IOP dev runtime; scored 결과 workspace의 source가 아님 |
| API Contract | Anthropic-Compatible Messages API, OpenAI-Compatible API | Claude Code/agy/Codex의 IOP ingress와 terminal/usage 기준 |
| Config Contract | Edge Config And Runtime Refresh | model route, execution preset, protocol profile, credential 경계 |
| User Decision | D01-D10 | 2026-08-06 확정 방향과 공정성 보강, 추가 사용자 결정 없음 |
State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|---|---|---|---|
defined |
manifest schema와 pipeline version을 load | preflighting, rejected |
validated manifest, fixture checksum |
preflighting |
caller binary/config와 IOP dev route를 secret-safe로 점검 | ready, blocked, rejected |
CLI version, auth/model/endpoint/effort/stream result |
ready |
모든 선택 cell의 preflight와 isolated workspace 준비 완료 | running, cancelled |
immutable run manifest와 workspace locator |
running |
caller에 사용자 작업을 한 번 제출 | validating, failed, timed_out, cancelled |
normalized event timeline, process exit와 idle marker |
validating |
finish/complete 후 idle 또는 terminal failure 확정 | scoring, reported, failed |
workspace checksum, build/render/test evidence |
scoring |
익명화된 결과와 screenshot 준비 | reported, failed |
rubric version과 evaluator record |
reported |
raw evidence와 Markdown summary 원자적 생성 | 종료 | report path, manifest/evidence digest |
blocked |
credential/model 누락 또는 client↔IOP 호환 gap | preflighting, 종료 |
redacted blocker classification과 후속 Plan 후보 |
rejected |
manifest, fixture, path, repetitions 또는 secret policy 위반 | 종료 | validation error |
failed |
scored 실행·검증·보고 실패 | 종료 | 보존된 attempt와 failure class |
timed_out |
run 전체 timeout 초과 | 종료 | timeout/cancel/cleanup evidence |
cancelled |
사용자 또는 process cancellation | 종료 | child process cleanup evidence |
State invariant:
- 하나의 attempt는 immutable manifest cell, repetition index, fixture checksum, clean workspace generation과 fresh caller session identity를 가진다. 이전 conversation/resume state를 재사용하지 않는다.
- preflight는 scored attempt가 아니며 setup time/usage를 별도 evidence로 둔다.
- scored attempt가 시작된 뒤의 실패는 삭제하거나 같은 attempt id로 재실행하지 않는다.
- finish/complete event만으로 성공 판정하지 않고 caller adapter가 idle과 process/output quiescence를 함께 확정한다.
- raw credential과 private endpoint는 manifest, event, log, metric, screenshot, report에 기록하지 않는다.
Interface Contract
- 계약 원문: Anthropic-Compatible Messages API, OpenAI-Compatible API, Edge Config And Runtime Refresh
- manifest 입력:
pipeline_version,environment=dev,testbed=../iop-s2: 실행 contract와 테스트베드 선택이다.fixture: prompt, asset와 initial workspace checksum/version이다.matrix[]: stable cell id, caller(claude|agy|codex), IOP route/preset, expected model/stage binding과 effort다.repetitions: 1 이상의 실행 횟수이며 초기 비교 manifest는 1이다.session_policy=fresh,setup_cache_policy,timeout,viewports,rubric_version,output_root: 격리, 공통 setup/cache와 bounded 실행·검증·보고 옵션이다.
- runner adapter 출력:
- 공통 timeline은
submitted,first_output,first_file_write, model call start/end, tool start/end, finish/complete, idle와 terminal outcome을 monotonic timestamp와 observation source로 표현한다. 구간이 겹치거나 source가 없으면 별도overlap|unavailable로 남기고total-model-tool을 authoritative overhead로 단정하지 않는다. - usage는 model/stage, input/output/reasoning/cached/total, source(
provider_reported|client_reported|iop_ledger|estimated|unavailable)와 호출 횟수를 보존한다. - caller 고유 event는 raw evidence에 bounded/redacted 형태로 남기되 공통 field를 추정해 성공으로 만들지 않는다.
- 공통 timeline은
- pipeline 출력:
- attempt manifest, normalized timeline/usage, verification JSON, screenshot, score worksheet와 Markdown report를 run id 아래 연결한다.
- 금지:
- caller가 IOP를 우회한 provider 호출을 scored IOP cell로 인정한다.
- unsupported model alias나 effort를 다른 값으로 조용히 대체한다.
- preflight 성공을 실제 scored 결과로 재사용한다.
- raw secret이나 prompt/tool 원문을 tracked artifact에 포함한다.
Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|---|---|---|---|---|
| S01 | benchmark-manifest |
새로운 model/agent/prompt/repetition 조합 | manifest validate | schema에 맞는 조합만 canonical ordering으로 확정되고 code 변경 없이 matrix가 늘어난다. |
| S02 | benchmark-skill |
사용자가 benchmark 준비·실행·보고를 요청 | skill 진입 | required context와 preflight를 확인하고 deterministic pipeline 명령으로 연결한다. |
| S03 | isolated-workspace |
같은 fixture를 쓰는 여러 cell/attempt | workspace 준비 | 동일 checksum의 clean workspace와 fresh caller session이 생성되고 ../iop-s2 source, 이전 history/resume state와 다른 attempt가 변경·재사용되지 않는다. |
| S04 | run-lifecycle |
caller별 서로 다른 event/exit 형태 | 사용자 작업 1회 제출 | finish/complete와 idle까지 bounded 대기하고 terminal outcome을 공통 timeline으로 만든다. |
| S05 | repeat-attempt |
repetitions=1 또는 더 큰 값과 중간 failure |
matrix 실행 | cell별 repetition/attempt id가 안정적으로 생성되고 failure와 재실행이 덮어써지지 않는다. |
| S06 | claude-iop |
IOP dev direct route와 Claude Code | Sonnet/Gemini/GPT direct preflight와 generic preset fixture 검증 | direct auth/model/stream/terminal과 arbitrary preset route adapter 계약이 확인된다. |
| S07 | agy-iop |
IOP dev Gemini direct route와 agy | direct preflight와 generic preset fixture 검증 | 지원이면 IOP 경유가 입증되고 아니면 정확한 호환 gap이 기록된다. |
| S08 | codex-iop |
IOP dev GPT direct route와 Codex | direct preflight와 generic preset fixture 검증 | 지원이면 IOP 경유가 입증되고 아니면 정확한 호환 gap이 기록된다. |
| S09 | effort-route |
Sonnet 최고/Gemini high/GPT xhigh 요청 | 각 route preflight | requested/effective model·effort가 확인되며 unsupported 값은 fail-closed다. |
| S10 | connection-gap |
credential/model 또는 endpoint/auth/protocol/stream 실패 | blocker 분류 | 안전한 등록 요청 또는 별도 구현 Plan 후보가 만들어지고 우회 PASS가 없다. |
| S11 | timing-usage |
caller/model별 event와 provider usage 편차 | evidence normalize | 첫 output·첫 write·model/tool/queue/total 시간의 clock/source와 overlap, 호출 횟수와 token source/미제공이 보존된다. |
| S12 | web-validation |
생성된 vanilla web page | build/serve/render 검증 | 두 이미지, desktop/mobile, asset/console, 반응형·접근성 evidence와 screenshot이 생성된다. |
| S13 | blind-score |
identity가 제거된 결과물과 screenshot | Codex 평가 | 동일 rubric version의 항목별 점수와 근거가 자동 gate와 분리되어 기록된다. |
| S14 | report-output |
성공·실패·blocked attempt evidence | 보고 생성 | 조건·버전·시간·token·품질·한계와 raw evidence 포인터가 있는 Markdown이 생성된다. |
Evidence Map
| Scenario | Required Evidence | agent-task 연결 |
완료 Evidence 기대 |
|---|---|---|---|
| S01 | manifest schema/fixture validation과 matrix extension test | agent-task/m-agent-comparison-benchmark-pipeline/benchmark-manifest/ |
benchmark-manifest config-driven matrix evidence |
| S02 | project skill validation과 dry command transcript | agent-task/m-agent-comparison-benchmark-pipeline/benchmark-skill/ |
benchmark-skill deterministic entrypoint evidence |
| S03 | workspace checksum, containment와 non-mutation test | agent-task/m-agent-comparison-benchmark-pipeline/isolated-workspace/ |
isolated-workspace clean isolation evidence |
| S04 | fake/fixture event streams와 real CLI lifecycle probe | agent-task/m-agent-comparison-benchmark-pipeline/run-lifecycle/ |
run-lifecycle finish+idle/timeout/cancel evidence |
| S05 | repetition ordering, failure preservation과 resume test | agent-task/m-agent-comparison-benchmark-pipeline/repeat-attempt/ |
repeat-attempt immutable attempt evidence |
| S06 | redacted Claude Code→IOP preflight | agent-task/m-agent-comparison-benchmark-pipeline/claude-iop/ |
claude-iop route/auth/stream evidence |
| S07 | redacted agy→IOP preflight 또는 exact blocker | agent-task/m-agent-comparison-benchmark-pipeline/agy-iop/ |
agy-iop supported/gap evidence |
| S08 | redacted Codex→IOP preflight 또는 exact blocker | agent-task/m-agent-comparison-benchmark-pipeline/codex-iop/ |
codex-iop supported/gap evidence |
| S09 | requested/effective route/model/effort matrix | agent-task/m-agent-comparison-benchmark-pipeline/effort-route/ |
effort-route no-substitution evidence |
| S10 | blocker classifier와 follow-up routing test | agent-task/m-agent-comparison-benchmark-pipeline/connection-gap/ |
connection-gap registration/Plan routing evidence |
| S11 | normalized timeline/usage fixtures와 unavailable handling | agent-task/m-agent-comparison-benchmark-pipeline/timing-usage/ |
timing-usage source-aware metric evidence |
| S12 | deterministic web fixture, viewport screenshots와 gate result | agent-task/m-agent-comparison-benchmark-pipeline/web-validation/ |
web-validation render/console/accessibility evidence |
| S13 | anonymization mapping 분리와 rubric worksheet | agent-task/m-agent-comparison-benchmark-pipeline/blind-score/ |
blind-score unbiased score evidence |
| S14 | success/failure/blocked report golden test | agent-task/m-agent-comparison-benchmark-pipeline/report-output/ |
report-output Markdown/raw-link evidence |
공통 완료 검증은 pipeline unit/integration test에서 실제 provider를 호출하지 않는 fake runner guard, manifest/schema validation, workspace containment·cleanup, secret redaction, report golden test와 git diff --check를 포함한다. 실제 외부 CLI 호출은 S06-S10의 명시적인 redacted dev preflight로만 분리한다.
Cross-repo Dependencies
- 없음.
../iop-s2는 같은 IOP 프로젝트의 dev 테스트베드 workspace이며 별도 프로젝트 Milestone 의존성으로 취급하지 않는다.
Drift Check
- Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- Evidence Map이 code-review/complete.log에서 검증 가능하다.
- agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- 사용자 리뷰가 필요한 항목은 없고 확정된 D01-D10을 반영했다.
사용자 리뷰 이력
- 2026-08-06: 사용자가 모든 비교군의 IOP 경유, Claude Code와 agy/Codex caller 조합, finish/idle 기준 원샷, 초기 1회·가변 반복 pipeline, dev
../iop-s2테스트베드와 post-smoke 실제 비교를 확정했다.
작업 컨텍스트
- 표준선: project-local skill은 orchestration을, deterministic pipeline은 실제 CLI/IOP 호출과 evidence lifecycle을 소유한다. Agent-Ops dispatcher와 IOP 제품 runtime 책임을 섞지 않는다.
- 후속 SDD: IOP 원샷 Agent 모델 비교 벤치마크