13장. 평가와 관측 가능성

다음은 여러 현장에서 반복된 패턴을 합친 합성 사례로, 등장하는 숫자는 설명을 위한 예시 수치다.

공장이 실패했다. 대시보드에는 모델 요청 200, 평균 지연 8초, 오류율 2%가 보였다. 하지만 왜 주문 총액 작업이 세 번 재시도됐는지, 첫 오류가 명세인지 도구인지, 사람은 어디서 개입했는지 알 수 없었다. 인프라는 관측했지만 작업의 의미와 결과는 관측하지 않은 것이다.

테스트는 한 변경이 기준을 만족하는지 판정한다. 평가는 공장과 에이전트가 대표 업무군에서 얼마나 잘 수행하는지 비교한다. 관측 가능성은 실제 실행에서 무엇이 일어났는지 증거로 재구성하게 한다. 세 가지가 연결될 때 공장은 실패를 학습으로 바꾼다.

이번 장의 약속

제품 테스트와 에이전트 평가의 역할을 구분한다.
대표 작업·채점 기준·반복 실행으로 평가 세트를 만든다.
요청에서 배포까지 연결되는 이벤트·메트릭·트레이스를 설계한다.
실패를 모델, 명세, 도구, 하니스, 통합 문제로 좁힌다.

테스트, 평가, 운영 관측

구분	핵심 질문	실행 시점	예
제품 테스트	이 변경이 제품 규칙을 만족하는가?	작업·통합마다	AC-02 취소 품목 제외
에이전트 평가	이 시스템이 대표 작업을 안정적으로 수행하는가?	변경 전후·정기	30개 작업 성공/정책 위반/비용
운영 관측	실제 실행에서 무슨 일이 일어났는가?	항상	task→run→gate→change trace

제품 테스트만으로는 에이전트가 불필요한 파일을 넓게 고쳤는지, 사람의 개입이 얼마나 필요했는지, 같은 결과를 몇 번 만에 얻었는지 알 수 없다. 평가는 결과 품질과 실행 행동을 함께 본다.

평가 단위는 실제 작업을 닮아야 한다

평가 사례는 자연어 질문 하나가 아니라 다음 묶음이다.


고정 기준 저장소
작업 계약과 승인 명세
허용 도구·권한·예산
예상 제품 동작
금지 행동
채점기와 수동 루브릭
재현용 환경 버전

예시:

설계 예(실행용 아님) — 원본: 이 장의 평가 사례 설명; 명령: 없음.


id: EVAL-ORDER-004
task: 주문 조회에 total을 추가한다
base_fixture: order-app-v3
spec: SPEC-ORDER-007@3
must_pass:
  - AC-01
  - AC-02
  - AC-03
  - ARCH-DOMAIN-001
must_not:
  - modify: factory/**
  - expose_fields: [paymentToken, internalCost]
budget:
  actions: 20
  wall_seconds: 120
manual_rubric:
  maintainability: 0..2
  explanation: 0..2

평가용 기준 저장소는 매 실행 전에 같은 상태로 복원한다. 평가 작업과 정답을 실제 에이전트의 기본 문맥에 섞지 않는다.

대표성을 층화한다

성공하기 쉬운 예제만 모으면 실제 현장을 예측하지 못한다. 업무군과 위험을 나눈다.

축	범주 예
작업 유형	버그 수정, API 확장, 리팩터링, 테스트, 문서, 마이그레이션
난이도	지역 변경, 다중 모듈, 외부 계약, 모호함 포함
저장소 준비도	좋은 문서, 오래된 문서, 테스트 공백
위험	낮음, 데이터/권한, 공급망, 외부 효과
실패 주입	도구 일시 오류, 테스트 불안정, 명세 변경, 작업자 중단

처음에는 가장 자주 자동화할 업무군 20~30개로 시작해도 된다. 숫자보다 분포와 실제성, 변경 이력 관리가 중요하다. 운영에서 반복되는 실패를 개인정보와 비밀을 제거한 뒤 평가 사례로 승격한다.

결과, 과정, 효율, 복구를 함께 채점한다

결과 채점

필수 제품 테스트 통과
명세의 모든 수용 기준 증거
구조·보안·호환성 게이트
숨은 경계 사례

과정 채점

허용 경로와 도구 준수
테스트·정책 우회 없음
위험 행동 전 승인
입력과 산출물 출처 보존

효율 채점

실행 시간과 도구 호출
재시도 횟수
변경 파일·diff 규모
사람 개입 시간
성공 작업당 자원

복구 채점

도구 오류 분류
체크포인트와 인계 품질
중단 뒤 중복 부작용 없는 재개
명세 변경 뒤 오래된 결과 거부

하나의 가중 점수로만 줄이지 않는다. 필수 안전 규칙 위반은 높은 기능 점수로 상쇄할 수 없는 하드 실패다.


최종 판정:
  policy violation? → FAIL
  required outcome missing? → FAIL
  otherwise → 품질·효율·복구 프로필 비교

변동성을 평가한다

결정론적 하니스 테스트는 한 번으로 충분할 수 있지만 실제 모델 평가에는 반복이 필요하다. 같은 작업을 여러 번 실행해 다음을 본다.

성공 비율과 신뢰 구간
첫 시도 성공과 제한된 재시도 성공의 차이
결과의 구조적 다양성
실패 코드 분포
비용·지연의 중앙값과 긴 꼬리
정책 위반이 한 번이라도 발생했는지

반복 수가 적으면 작은 차이를 승리라고 선언하지 않는다. 모델·프롬프트·하니스 변경을 비교할 때 같은 기준 저장소, 도구, 예산을 사용한다.

평가 오염을 막는다

에이전트가 평가 ID나 정답 patch를 검색할 수 있으면 실제 능력이 아니라 정답 찾기를 측정한다.

평가 기준과 채점기는 작업 공간 밖에 둔다.
공개 명세와 숨은 채점을 구분한다.
정답 코드보다 동작과 정책을 채점한다.
평가 케이스의 고유 문자열을 운영 프롬프트에 넣지 않는다.
사례가 널리 알려지면 새 변형과 실제 운영 사례로 갱신한다.

숨은 기준은 공개 요구를 넘어선 비밀 요구가 되어서는 안 된다. 명세의 규칙을 다른 데이터와 경로로 검증한다.

관측의 세 신호

이벤트와 로그

구체적 사건과 진단 정보를 담는다. task.ready, run.started, tool.denied, gate.failed, review.completed, change.integrated처럼 상태 언어를 통일한다.

메트릭

기간과 집단을 비교하는 수치다. 처리량, 리드 타임, 첫 시도 통과율, WIP, 사람 개입 시간, 오류 코드 빈도를 집계한다. runId처럼 값 종류가 무한한 식별자를 메트릭 라벨에 넣으면 저장 비용이 폭증하므로 trace/log에서 찾는다.

트레이스

하나의 요구가 작업, 실행, 도구, 게이트, 리뷰, 통합을 통과하는 인과 흐름이다.


trace: request REQ-77
└─ plan
   ├─ task ORDER-11 / run-1
   │  ├─ tool.read
   │  ├─ tool.write
   │  └─ gates
   └─ task ORDER-12 / run-2
      ├─ tool.read
      ├─ gate.contract (failed)
      ├─ checkpoint
      └─ gate.contract (passed)
└─ review
└─ merge-preview
└─ integrate

이 그림은 운영용 목표 trace 모델입니다. 현재 교육용 JSONL은 factory, batch, task, workspace, agent, review, gate 사건과 증가하는 sequence를 저장하지만 request/change/deploy 계층과 모델/tool span을 모두 구현하지는 않습니다. 트레이스는 모델 호출만 감싸지 않고 의미 있는 작업 단계와 산출물 연결을 보여 줘야 합니다.

공통 필드

도구가 달라도 다음 필드를 일관되게 사용하는 것이 운영 확장 목표입니다.


request.id, task.id, run.id, run.attempt
spec.id, spec.version, base.revision
agent.adapter, harness.version, policy.version
workspace.id, tool.name, gate.id
status, reason.code, duration.ms
change.id, patch.hash, artifact.uri
human.intervention.type, human.minutes

모델 이름·버전, 사용량 같은 공급자별 정보는 어댑터 필드로 추가한다. 원문 프롬프트, 비밀, 개인 데이터는 기본 속성으로 넣지 않는다.

이벤트에서 지표를 계산한다

별도 수기 보고보다 상태 이벤트를 원천으로 사용한다.


리드 타임 = change.integrated.time - task.ready.time
실행 시간 = run.finished.time - run.started.time
검증 대기 = gate.started.time - run.work_finished.time
첫 시도 통과 = task의 attempt=1 실행이 SUCCEEDED
사람 개입 = human.intervention.finished - started

이벤트가 중복 전달될 수 있으므로 eventId로 멱등 집계한다. 시계가 다른 호스트에 있다면 순서 번호와 서버 수신 시각을 함께 보존한다.

실습 1: 평가 세트를 실행한다


npm run eval

현재 명령은 외부 모델 없이 캡스톤 한 사례를 다시 실행해 결과 게이트와 과정 지표를 요약합니다. 실제 출력은 다음과 같습니다.


평가 대상: order-capstone
결과 게이트: 3/3 PASS
과정 지표: 작업 5, 시도 5, 재시도 0, 인계 0
판정: GREEN

이것은 다중 trial 평가 스위트가 아니라 평가 보고의 최소 단면입니다. 성공·정책 위반·의도된 차단·복구를 기대 상태별로 비교하려면 specs/retry.json, specs/handoff.json, tasks/missing-acceptance.json, 보안 테스트를 평가 manifest에 추가하고 각 기대 종료 코드를 채점해야 합니다. 현재 명령이 8개 사례를 평가한다고 과장하지 않습니다.

실습 2: 한 실패를 트레이스로 읽는다


npm run report -- --latest --trace

다음 순서로 진단한다.

최초의 비정상 상태는 어디인가?
그 직전 입력·도구·정책 버전은 무엇인가?
후속 실패는 첫 원인의 파급인가 별도 원인인가?
같은 실패 코드가 다른 작업에도 있는가?
재현할 최소 입력과 명령은 무엇인가?

마지막 오류 줄부터 무작정 수정하지 않는다. 첫 원인에 가까운 이벤트를 찾는다.

캡스톤 성공 trace에서는 001 factory.started부터 060 factory.completed까지 보입니다. 실패 trace를 읽으려면 먼저 의도된 실패 fixture를 실행한 뒤 같은 report 명령을 사용합니다. --latest는 수정 시각이 가장 최근인 run을 고르므로 어떤 fixture를 방금 실행했는지 확인합니다.

실습 3: 지표 착시 찾기

제공된 두 실행 보고서를 비교한다.


Factory A: 평균 실행 30초, 성공 40%, 사람 복구 20분/작업
Factory B: 평균 실행 55초, 성공 90%, 사람 복구 3분/작업

실행 지연만 보면 A가 빠르다. 성공 작업당 실행 시간과 사람의 주의, 유출 결함을 함께 계산한다. 이 예시는 단일 결론을 강제하기보다 필요한 분모를 찾는 연습이다.

관측 자체의 품질

관측 파이프라인이 실패해도 제품 작업의 안전 판정이 사라지면 안 된다.

필수 감사 이벤트를 기록하지 못하면 고위험 행동을 중단한다.
메트릭 전송 실패는 로컬 버퍼와 한도로 처리한다.
이벤트 스키마 버전과 호환성을 검사한다.
민감 필드 마스킹 테스트를 실행한다.
샘플링하더라도 오류·정책 위반·승인 이벤트는 보존한다.
보존 기간과 접근 권한을 데이터 분류에 맞춘다.

왜 실패하는가

성공/실패 한 숫자로 모델을 평가한다

정책을 어겨 얻은 성공과 안전하게 차단한 사례를 구분하지 못한다. 기대 종료 상태와 결과·과정·효율·복구 프로필을 본다.

평가 세트가 데모만 담는다

명세 모호함, 도구 오류, 중단, 권한, 통합 충돌 같은 실제 비용을 빠뜨린다. 운영 실패에서 새 사례를 승격한다.

모든 원문을 로그에 넣는다

비용과 유출 위험이 커진다. 구조화된 메타데이터와 산출물 참조를 우선하고 원문은 최소 권한으로 제한한다.

지표 변화에 바로 원인을 붙인다

성공률 하락이 모델 변경, 더 어려운 업무 구성, 느린 CI, 명세 품질 중 무엇인지 층화와 trace 없이는 알 수 없다.

운영 판단: 변경을 배포할 평가 게이트

하니스, 모델, 도구, 정책 변경마다 다음을 비교한다.

필수 정책 위반이 증가하지 않는다.
대표 업무군의 결과 프로필이 기준선을 충족한다.
긴 꼬리 지연과 성공 작업당 자원이 허용 범위다.
차단과 복구 사례의 기대 상태가 유지된다.
특정 쉬운 범주 개선이 다른 고위험 범주 악화를 가리지 않는다.
평가 환경과 실제 운영의 차이를 문서화한다.

작은 트래픽이나 낮은 위험 작업군에 먼저 적용하고 운영 관측으로 확인한다.

연습문제

제품 테스트는 통과하지만 에이전트 평가에서 실패해야 할 사례를 세 개 설계하라.
현재 업무를 유형·난이도·준비도·위험으로 층화한 20개 평가 목록을 만들라.
trace에서 첫 원인과 후속 오류를 구분하는 규칙을 적어라.
메트릭 라벨로 쓰면 안 되는 고유 식별자와 trace 속성으로 남길 필드를 구분하라.

체크포인트

대표 업무와 실패 주입을 포함한 버전 관리 평가 세트가 있다.
기능 성공이 정책 위반을 상쇄하지 않는다.
요청부터 통합까지 공통 식별자로 연결된 이벤트와 trace가 있다.
성공 작업당 자원, 사람의 주의, 실패 분포를 함께 본다.

다음 장에서는 몇 시간이나 며칠 걸리는 작업이 중단되어도 같은 외부 효과를 반복하지 않고 이어지는 내구성 있는 실행을 만든다.

Codex로 구축하는 AI 개발팀: 13장. 평가와 관측 가능성