하네스는 프롬프트가 아니라 네 요소의 배포 단위
하네스는 시스템 프롬프트만 가리키는 말이 아닙니다. 프롬프트 텍스트, 도구 스키마, 권한·샌드박스 정책, 모델 버전 핀 네 가지가 한 덩어리로 묶여 에이전트의 행동을 결정합니다. 이 중 하나만 바뀌어도 도구를 고르는 순서, 인자를 채우는 방식, 실패 시 대응 경로가 통째로 달라질 수 있습니다.
그런데도 애플리케이션 코드는 PR 리뷰와 CI를 거치는 팀에서조차 하네스 정의 파일은 승인 절차 없이 바로 배포되는 경우가 많습니다. 프롬프트 몇 줄, 스키마 필드 하나의 수정이 회귀를 일으켜도 잡아낼 장치가 없다는 뜻입니다.
회귀는 출력이 아니라 궤적에서 먼저 드러난다
Anthropic의 에이전트 평가 가이드는 최종 답변(outcome)과 도구 호출 순서·인자·중간 결과를 담은 트랜스크립트(trajectory)를 분리해서 봐야 한다고 설명합니다. 두 실행이 같은 답에 도달해도 서로 다른 도구 호출 경로를 거쳤을 수 있기 때문입니다.
하네스 회귀도 마찬가지입니다. 출력 텍스트만 비교하면 통과로 보이지만, 실제로는 이전에 쓰지 않던 도구를 새로 호출하거나 인자 순서가 바뀌어 다운스트림 시스템이 깨지는 경우가 흔합니다. 궤적을 diff하지 않으면 이런 회귀는 배포 후에야 발견됩니다.
설계에서 운영까지: 하네스 회귀 게이트 구축 로드맵
기획 단계에서는 골든 트레젝토리 세트부터 만듭니다. 실제 프로덕션 트레이스에서 대표 시나리오 40건 이상을 뽑아 도구 호출 순서·인자·최종 상태를 스냅샷으로 고정합니다. 세트가 40건 미만이면 회귀율 수치 자체가 통계적으로 불안정해 배포 게이트 기준으로 쓰기 어렵습니다.
배포 차단 기준도 숫자로 못박아야 실무에서 흔들리지 않습니다. 골든셋 대비 도구 호출 시퀀스 일치율이 95% 아래로 떨어지거나 신규 실패 케이스가 3건을 넘으면 자동 배포를 막고 사람 승인 단계로 넘깁니다.
흔한 실패 패턴은 세 가지입니다. 첫째, 시스템 프롬프트에 지시문 한 줄을 추가했더니 이전에는 후순위였던 도구를 먼저 호출하는 순서 역전이 생깁니다. 둘째, 도구 스키마에 enum 값을 하나 추가했는데 파서가 구버전 스키마를 캐싱해 신규 값에서 파싱 오류가 발생합니다. 셋째, 모델 버전 핀을 풀고 최신 버전으로 자동 승격했더니 같은 프롬프트에서도 도구 인자를 채우는 방식이 달라집니다.
복구 분기는 실패 유형별로 다르게 둡니다. 시퀀스 역전은 즉시 이전 하네스 버전으로 롤백하고, 스키마 파싱 오류는 캐시를 무효화한 뒤 재검증하며, 모델 승격 회귀는 핀을 이전 버전으로 되돌리고 승격 자체를 다음 배포 주기로 미룹니다.
운영 체크리스트로는 하네스 변경을 애플리케이션 코드와 동일하게 PR 리뷰 대상에 올리고, diff에 프롬프트·도구 스키마·권한·모델 핀 네 항목을 표준 필드로 표시합니다. 트레이스 로그에는 하네스 버전 필드를 남겨 회귀가 어느 배포부터 시작됐는지 추적하고, 트레이스에 담긴 사용자 발화와 개인정보는 골든셋으로 저장하기 전에 마스킹합니다.
배포 전 검증에는 리허설 단계도 넣습니다. 스테이징에서 골든셋 전체를 재생해 일치율·신규 실패 수를 확인한 뒤에만 실제 배포 파이프라인을 통과시키고, 리허설을 건너뛴 배포는 별도 태그로 남겨 사후 감사 대상으로 분리합니다.
개선 루프는 배포마다 회귀율과 신규 실패 케이스를 changelog로 따로 기록하는 데서 시작합니다. 어떤 유형의 변경이 회귀를 자주 유발하는지 누적해서 보면 취약한 지점이 드러납니다. OpenAI의 회귀 탐지 가이드도 프롬프트·모델·파라미터를 바꿀 때마다 같은 평가 기준을 재실행해 비교하도록 권고하는데, 이 반복 실행 자체가 골든셋을 최신 상태로 유지하는 근거가 됩니다.
한눈에 보는 적용 포인트
하네스를 프롬프트 텍스트가 아니라 프롬프트·도구 스키마·권한·모델 핀 네 요소의 배포 단위로 다루고, 골든 트레젝토리 40건 이상과 시퀀스 일치율 95% 하한을 코드로 못박아 배포 게이트에 넣으면 결과만 비교할 때 놓치던 궤적 회귀를 배포 전에 잡을 수 있습니다.
참고 링크
Demystifying evals for AI agents — Anthropic
Evals API use-case: Detecting prompt regressions — OpenAI Cookbook