하네스 엔지니어링 딥다이브 — 에이전트의 완료를 시스템이 증명하게 하라

Lukas Niessen의 글 Harness Engineering Deep Dive: Where The Term Came From, And How To Actually Build One은 하네스 엔지니어링을 유행어가 아니라 하나의 설계 규율로 다룬다. 모델 호출과 도구 연결만으로는 실제 작업을 오래 수행하는 에이전트를 만들 수 없다. 실행 환경이 상태를 보존하고, 실패를 감지하고, 권한을 제한하고, 완료를 증명해야 한다.

1. 모델은 빌리고 하네스는 소유한다

에이전트를 설명하는 가장 간단한 공식은 다음과 같다.

에이전트 = 모델 + 하네스

모델은 언어를 이해하고 다음 행동을 제안한다. 하네스는 그 제안을 실행 가능한 시스템에 연결한다. 여기에는 실행 루프, 도구, 샌드박스, 컨텍스트 조립, 권한, 테스트, 상태 저장, 추적, 비용 제한, 승인 절차가 포함된다.

모델은 몇 달마다 교체될 수 있고, 도구 호출 방식과 실패 양상도 함께 변한다. 반면 하네스는 팀의 저장소와 테스트 아래에 둔다. 따라서 운영 중 문제가 생겼을 때 선택지는 두 가지다. 더 나은 모델을 기다리거나, 같은 모델이 실패하기 어렵도록 환경을 바꾸는 것이다. 후자가 엔지니어링이다.

이 관점은 “모델이 충분히 똑똑한가”라는 질문을 “실패가 반복되지 않도록 환경을 설계했는가”라는 질문으로 바꾼다. 모델 자체를 통제할 수 없어도, 모델이 보고 만지고 실행하는 경로는 통제할 수 있다.

2. 용어의 뿌리와 세 단계의 확장

하네스라는 단어는 에이전트 분야에서 갑자기 생긴 개념이 아니다. 소프트웨어 테스트의 테스트 하네스는 테스트 대상이 격리된 상태에서 실행되도록 픽스처, 가짜 의존성, 입력, 출력 수집, 검증을 제공한다. LLM 평가 하네스는 데이터셋을 불러오고 프롬프트를 만들고 결과를 채점한다. 강화학습의 환경 래퍼는 관찰 공간, 행동 공간, 보상, 종료 조건을 정의한다.

세 개념의 공통점은 작고 불확실한 핵심 요소만으로는 실제 작업이 불가능하다는 데 있다. 주변 구조가 입력의 의미와 행동의 범위, 결과의 판정 방식을 정한다.

실무에서 자주 쓰는 발전 경로는 다음과 같다.

이 단계들은 서로 대체하지 않는다. 프롬프트는 컨텍스트 설계의 일부가 되고, 컨텍스트 설계는 하네스의 일부가 된다. 이전 단계가 사라지는 것이 아니라, 더 큰 실행 단위 안으로 들어간다.

하네스 엔지니어링이 특별한 이유는 실행 단위가 한 번의 답변이 아니라 상태를 가진 전체 실행이라는 점이다. 실행은 충돌하거나, 일부 도구만 성공하거나, 같은 요청을 반복하거나, 긴 컨텍스트 때문에 중요한 사실을 놓칠 수 있다. 따라서 분산 시스템에서 오래 다뤄 온 멱등성, 재시도, 회로 차단기, 감사 로그, 예산 제한이 다시 중요해진다. 차이는 그 한가운데에 비결정적인 언어 모델이 있다는 점이다.

3. 래퍼와 하네스를 가르는 폐쇄 루프

모델 주변의 모든 코드를 하네스라고 부르면 개념이 너무 넓어진다. 원문은 실용적인 경계로 폐쇄 루프를 제시한다.

• 래퍼: 모델의 출력 자체가 최종 산출물이다. 결과를 화면에 보여주거나 저장하거나 호출자에게 반환하면 실행이 끝난다.
• 하네스: 모델의 출력이 시스템이 실행할 결정이다. 그 결정이 외부 세계를 바꾸고, 모델이 바뀐 상태를 관찰한 뒤 다음 결정을 내린다.

예를 들어 검색 결과를 컨텍스트에 넣고 한 번 답하는 RAG 챗봇은 컨텍스트 엔지니어링에 가깝다. 반면 모델이 검색 도구를 직접 호출하고, 결과가 나쁘다고 판단해 검색어를 바꾸고, 다시 검색한 뒤 답변을 만드는 순간 폐쇄 루프가 생긴다. 검색이라는 기능은 같지만, 실행 결과가 다시 모델의 입력으로 돌아온다는 화살표 하나 때문에 하네스의 문제가 시작된다.

이 기준은 제품 규모나 코드 줄 수보다 유용하다. 단순한 API 호출도 이론적으로는 래퍼이고, 작은 스크립트라도 세계를 바꾸고 결과를 다시 읽는다면 하네스의 설계 원칙을 적용해야 한다.

4. 하네스의 세 가지 분류 축

하네스를 설계할 때는 구성 요소를 한 목록으로 늘어놓기보다, 누가 만들고 언제 작동하며 어떤 방식으로 판단하는지 나누는 편이 낫다.

4.1 내부 하네스와 외부 하네스

**내부 하네스(inner harness)**는 모델 또는 에이전트 도구 공급자가 제공한다. SDK의 기본 루프, Claude Code·Codex·Cursor 같은 제품의 실행 구조가 여기에 해당한다. 사용자는 설정할 수 있지만 전체 구현을 소유하지는 않는다.

**외부 하네스(outer harness)**는 팀이 그 위에 조립한다. 저장소 지침, 스킬, MCP 서버, 훅, 센서, CI 연결, 샌드박스 정책, 평가 세트, 도메인별 도구 스키마가 포함된다. 모델을 바꾸더라도 남는 조직의 실행 지식은 주로 이 계층에 쌓인다.

4.2 가이드와 센서

**가이드(guide)**는 행동 전에 작동한다. 모델에게 규칙과 예시를 보여 주거나, 도구 호출의 형태를 제한한다.

**센서(sensor)**는 행동 후에 작동한다. 테스트, 타입 검사, 권한 확인, diff 검사로 실행 결과를 관찰하고 다음 행동에 필요한 신호를 만든다.

4.3 계산적 요소와 추론적 요소

계산적(computational) 요소는 결정론적 프로그램이 실행한다. 스키마 검증, 린터, 테스트, 타입 검사, 범위 검사처럼 같은 입력에 같은 판정을 내린다.

추론적(inferential) 요소는 모델이 판단한다. 코드 리뷰 에이전트, LLM-as-judge, 의미적 변경 검사가 예다. 유연하지만 비용과 변동성이 있다.

이를 함께 놓으면 다음과 같은 설계 지도가 된다.

많은 팀이 먼저 지침 파일을 길게 쓰지만, 원문은 계산적 센서가 가장 강력하고 자주 빠지는 계층이라고 지적한다. 지침은 권고일 뿐이지만, 테스트와 스키마는 모델과 논쟁하지 않는다.

5. 장난감 루프에서 프로덕션 하네스로

가장 단순한 에이전트는 다음 흐름으로 시작한다.

while True:
    response = model.call(context, tools=tools)
    if not response.tool_calls:
        return response.text
    for call in response.tool_calls:
        context.append(dispatch(call))

이 코드는 작동한다. 그러나 모델 호출, 도구 실행, 종료 판단만 있고, 실패를 압축하거나 상태를 복구하거나 비용을 멈추거나 권한을 확인하는 장치가 없다. 원문이 제시하는 실전 설계 포인트는 다음 일곱 가지다.

5.1 센서는 파이프가 아니라 변환기다

테스트 명령의 표준 출력과 표준 에러를 그대로 모델에게 전달하면 수천 토큰이 쉽게 쌓인다. 실제로 다음 행동을 결정하는 정보는 실패한 테스트 한 개, 파일 위치, 핵심 오류, 권장 조치 정도일 수 있다.

좋은 센서는 원시 결과를 다음과 같은 제한된 신호로 바꾼다.

ok: false
headline: "테스트 수집 실패: import 오류"
detail: "tests/conftest.py:18에서 모듈을 찾지 못함"
next_action: "테스트 로직보다 먼저 import 오류를 수정"

센서의 목적은 로그를 많이 보여 주는 것이 아니라, 모델이 다음 행동을 선택하는 데 필요한 정보를 바로 제공하는 것이다. 테스트 센서는 첫 실패에서 멈추고, 트레이스백을 한 줄로 줄이고, 수집 오류와 테스트 실패를 구분할 수 있다. 타입 검사도 200개의 연쇄 오류를 나열하기보다 최초 원인별로 묶어야 한다.

이렇게 하면 컨텍스트 비용도 줄고, 모델이 엉뚱한 오류를 고치는 위험도 줄어든다. HTTP 도구에서 429와 500을 같은 실패로 취급하지 않는 것도 같은 원리다. 전자는 재시도 대기이고 후자는 장애 조사일 수 있다.

5.2 대화 기록은 캐시이고 원장은 진실이다

대화 기록은 시간이 지나면 커지고, 컨텍스트 압축 과정에서 일부가 사라지며, 프로세스가 종료되면 메모리와 함께 사라진다. 그러므로 다음 턴에 반드시 필요한 현재 상태를 대화 메시지에만 남겨서는 안 된다.

실행마다 하나의 구조화된 원장을 둔다. 원장에는 목표, 제약, 작업별 상태, 결정, 학습한 사실, 마지막 오류, 시도 횟수와 같은 정보가 들어간다.

{
  "objective": "공개 API에 레이트 리밋 추가",
  "constraints": ["billing 경로 수정 금지", "새 의존성 추가 금지"],
  "tasks": [
    {"id": 1, "status": "done", "evidence": "테스트 3개 통과"},
    {"id": 2, "status": "in_progress", "attempts": 2, "last_error": "resolver가 None 반환"}
  ],
  "facts_learned": ["통합 테스트는 REDIS_URL이 필요함"]
}

중요한 것은 원장을 매 턴 새로 렌더링하는 방식이다. 현재 상태를 메시지에 계속 덧붙이면 “실패했다”와 “완료했다”라는 오래된 기록이 함께 남는다. 원장의 현재 값은 이전 표현을 대체해야 한다.

반면 전체 실행의 모든 턴, 도구 호출, 센서 결과는 별도의 궤적(trajectory) 으로 보존한다. 다음 행동을 바꾸는 정보는 원장에 두고, 사람이 장애를 재현하거나 감사할 때 필요한 전체 과정은 궤적에 둔다. 압축은 대화 기록을 줄일 수 있지만 원장은 버리면 안 된다.

이 구조는 중단 후 재개도 가능하게 한다. 프로세스가 작업 중 죽어도 원장을 읽어 컨텍스트를 다시 만들 수 있다. 단, 도구 실행은 재시도해도 결과가 중복되지 않도록 멱등성을 가져야 한다.

5.3 완료를 모델의 주장으로 결정하지 않는다

에이전트는 실제로 파일을 쓰지 못했는데도 완료했다고 말할 수 있다. 테스트를 실행하지 않았는데 통과했다고 보고할 수도 있다. 이는 인간적인 의미의 거짓말이라기보다, 현재 세계 상태와 모델이 생성한 서사가 어긋나는 실행 정렬 실패다.

따라서 완료는 텍스트 응답이 아니라 도구 호출로 제안하고, 하네스가 판정해야 한다. 실행별 종료 조건을 명시하고 모두 통과했을 때만 종료 상태로 바꾼다.

종료 조건 = 테스트 통과
          + 타입 검사 통과
          + 허용된 파일 범위 안에서만 변경
          + 비밀 정보 미노출
          + 출력 계약과 스키마 일치

센서 하나라도 실패하면 “아직 끝나지 않음”이라는 신호와 다음 행동을 반환한다. 핵심 원칙은 간단하다.

에이전트가 끝났다고 말한 것은 사건이고, 시스템이 완료를 확인한 것은 상태다.

두 개를 같은 것으로 취급하면 안 된다. diff 범위 검사처럼 정확성뿐 아니라 “요청받은 범위만 수정했는가”를 확인하는 센서도 필요하다.

5.4 프롬프트보다 행동 공간을 좁힌다

에이전트가 테스트 전에 마이그레이션을 자주 빼먹는다고 하자. 지침 파일에 “항상 마이그레이션을 먼저 실행하라”고 한 줄을 추가하는 것은 권고에 머문다. 테스트 도구가 실행 전에 미적용 마이그레이션을 확인하도록 만들면 실수 경로 하나가 사라진다. 애플리케이션이 시작 시 명확한 오류를 내고 실행할 명령까지 알려 주면 사람의 경로까지 보호한다.

도구 인수도 같은 방식으로 설계한다. 자유로운 SQL 문자열 대신 테넌트 ID, 허용된 상태 열거형, 기간, 상한이 있는 limit을 받는 도구를 제공하면 교차 테넌트 조회나 무제한 결과 요청을 표현하기 어렵게 만들 수 있다.

모델에게 올바른 행동을 더 잘 설명하는 것보다, 잘못된 행동을 도구의 형태와 시스템 경계에서 제거하는 편이 강하다. 이 개선이 인간 사용자에게도 안전성을 높인다면 올바른 계층을 고친다는 신호다.

5.5 예산과 정체를 함께 감지한다

에이전트 루프는 오류를 내지 않고도 비용을 폭발시킬 수 있다. 같은 도구 호출을 반복하면서 200 OK를 반환하면 일반적인 지연·오류 알림이 울리지 않을 수 있다.

최소한 다음 예산을 실행 단위로 둔다.

• 최대 단계 수
• 최대 출력 토큰 수
• 최대 벽시계 시간
• 최대 도구 오류 횟수

단계 수만 세면 생산적인 30단계와 같은 실패를 30번 반복한 실행을 구분하지 못한다. 원문은 작업 공간과 원장의 지문을 비교해 여러 단계 동안 아무것도 바뀌지 않았는지 확인하는 정체 감지를 제안한다.

예산은 모델 호출 전에 검사해야 초과 실행을 막을 수 있다. 실제 사용량은 모델 호출과 도구 결과가 발생한 지점에서 바로 기록해야 한다. 정체 감지는 한 단계가 끝난 뒤 작업 공간과 원장이 모두 갱신된 다음 한 번만 수행해야 한다.

예산이 소진되면 모호한 실패 대신 부분 결과를 남긴다. 완료한 작업, 막힌 작업, 마지막 오류, 사용한 단계·토큰·시간, 재현 가능한 궤적 위치를 함께 기록하면 사람이 다음 결정을 내릴 수 있다.

5.6 도구를 평평한 목록으로 노출하지 않는다

읽기, 쓰기, 외부 전송, 중요한 변경은 서로 다른 위험을 가진다. 모든 도구를 하나의 TOOLS 목록에 넣으면 승인, 감사, 멱등성 요구를 구분할 수 없다.

실행 계층을 나누는 예는 다음과 같다.

권한은 도구 이름만 보고 판단해서는 안 된다. get_orders를 호출할 수 있는지보다 어느 테넌트의 어떤 범위로 호출할 수 있는지를 확인해야 한다. 도구 이름만 허용하면 서로 다른 사용자의 권한을 합친 혼동된 대리인(confused deputy)이 생길 수 있다.

사람 승인을 기다리는 분기에서는 에이전트가 재시도하거나 우회하지 않도록 명시적인 신호를 반환해야 한다. 승인은 모델의 능력 부족을 인정하는 임시 장치가 아니라, 외부 부작용이 큰 시스템에서는 올바른 아키텍처가 될 수 있다.

5.7 디버깅 단위를 궤적으로 바꾼다

일반 소프트웨어는 로그 한 줄과 스택 트레이스를 중심으로 디버깅한다. 에이전트는 한 번의 실행 전체가 중요하다. 어떤 컨텍스트를 조립했는지, 모델이 무엇을 출력했는지, 어떤 도구를 호출했는지, 센서가 무엇을 반환했는지, 원장과 작업 공간이 어떻게 바뀌었는지를 순서대로 봐야 한다.

궤적을 저장하고 재생할 수 있으면 다음 질문에 답할 수 있다.

• 어느 단계에서 모델의 서사와 실제 작업 공간이 갈라졌는가?
• 실패를 잡았어야 할 센서가 없었거나 신호를 잘못 만들었는가?
• 컨텍스트 압축으로 필요한 정보가 사라졌는가?
• 가이드가 무시된 것인가, 애초에 컨텍스트에 들어오지 않은 것인가?
• 도구 결과가 다음 행동을 오도했는가?

실패한 궤적은 하네스의 다음 작업 목록이 된다. 반복 실패마다 지침을 길게 추가하는 대신, 어떤 가이드나 센서가 빠졌는지 찾아 환경을 수정한다.

6. 사업과 아키텍처에 미치는 영향

6.1 측정 대상은 모델이 아니라 모델-하네스 조합이다

원문은 Harness-Bench를 근거로 같은 모델이라도 하네스 조합에 따라 완료율, 효율, 실패 방식이 크게 달라질 수 있다고 설명한다. 따라서 모델 A가 모델 B보다 낫다는 비교는 하네스를 고정하지 않았다면 단일 변수의 결과가 아니다.

자체 작업 세트로 비교할 때는 하네스를 먼저 고정하고 모델만 바꿔야 한다. 결과도 모델 단독 점수가 아니라 모델 + 하네스 + 작업 세트의 조합으로 기록해야 재현과 의사결정이 가능하다.

6.2 장기 자산은 외부 하네스에 쌓인다

내부 하네스는 공급자가 빠르게 개선하는 구매 자원이다. 외부 하네스에는 팀의 코딩 관례, 자주 발생하는 실패, 센서, 도구 권한, 도메인 지식, facts_learned, 평가 케이스가 축적된다.

이 지식을 공급자 웹 UI에만 두면 모델이나 실행 도구를 바꿀 때 다시 만들어야 한다. 가이드와 센서를 저장소에 두고 테스트·리뷰·버전 관리의 대상이 되게 해야 이동성과 축적 효과를 얻을 수 있다.

6.3 AI 준비도는 기본 엔지니어링에 의해 제한된다

정적 타입, 빠르고 안정적인 테스트, 스키마가 검증하는 경계, 기계적으로 시행되는 아키텍처 규칙은 값싼 계산적 센서다. 반대로 타입이 없고, 테스트가 느리고 불안정하며, 수동 QA만 남아 있으면 LLM-as-judge나 리뷰 에이전트 같은 추론적 센서에 의존하게 된다.

추론적 센서는 의미를 판단하는 데 유용하지만, 비용과 지연이 크고 판정도 흔들릴 수 있다. 에이전트 플랫폼에 투자하기 전에 기존 코드베이스가 무엇을 자동으로 감지하고 거부할 수 있는지부터 개선해야 하는 이유다.

6.4 비용은 모델 가격표보다 하네스에서 결정된다

모델의 토큰 단가만 보면 모델 선택이 비용의 중심처럼 보인다. 그러나 센서가 매번 수천 토큰의 원시 로그를 전달하거나, 원장이 계속 누적되거나, 정체 감지가 없어 같은 실패를 수십 번 반복하면 실행당 토큰 수가 훨씬 커진다.

따라서 비용 최적화의 첫 질문은 “더 싼 모델이 있는가”가 아니라 다음과 같아야 한다.

• 센서가 다음 행동에 불필요한 출력을 제거하는가?
• 현재 상태가 한 번만 최신으로 렌더링되는가?
• 같은 작업을 반복하는 정체를 빠르게 감지하는가?
• 필요하지 않은 도구와 컨텍스트를 노출하지 않는가?

6.5 플랫폼 팀과 도메인 팀의 경계를 나눈다

하네스의 공통 기반은 수평적이다. 실행 루프, 도구 게이트웨이, 권한 계층, 예산, 궤적 저장, 평가 인프라, 템플릿은 플랫폼 팀이 관리할 수 있다.

하지만 어떤 실패가 중요한지 아는 것은 도메인 팀이다. 결제 팀은 결제 코드의 위험한 상태를 알고, 도메인별 센서와 도구 스키마와 종료 조건과 평가 케이스를 설계할 수 있다. 모든 것을 중앙 플랫폼에 몰아주면 병목이 되고, 모두 분산하면 호환되지 않는 하네스가 늘어난다. 공통 실행 기반과 도메인별 판단을 분리하는 편이 현실적이다.

7. 바로 적용할 수 있는 설계 순서

원문의 원칙을 작은 팀의 첫 하네스에 적용한다면 다음 순서가 현실적이다.

1. 폐쇄 루프를 정의한다. 모델의 어떤 결정이 세계를 바꾸고, 어떤 관찰이 다음 턴으로 돌아오는지 그린다.
2. 완료 조건을 먼저 쓴다. 테스트, 타입, 범위, 보안, 출력 계약을 기계가 판정할 수 있는 형태로 만든다.
3. 센서 출력을 표준화한다. ok, 한 줄 제목, 제한된 상세 정보, 다음 행동을 공통 구조로 만든다.
4. 원장과 궤적을 분리한다. 다음 행동에 필요한 현재 상태와, 감사·재생을 위한 전체 기록을 서로 다른 저장소로 관리한다.
5. 도구 표면을 줄인다. 자유로운 범용 입력보다 스키마·열거형·범위 제한으로 잘못된 호출을 표현하기 어렵게 만든다.
6. 예산과 정체 감지를 붙인다. 단계·토큰·시간·오류 횟수와 작업 공간의 실제 변화량을 함께 측정한다.
7. 권한과 승인을 계층화한다. 도구 이름이 아니라 인수와 대상까지 확인하고, 외부 전송과 중요한 변경은 별도로 다룬다.
8. 실패 궤적을 개선 백로그로 바꾼다. 같은 문제가 재발하면 지침을 추가하기 전에 도구, 센서, 상태 모델, 경계를 고칠 위치를 찾는다.
9. 하네스를 고정한 평가를 반복한다. 모델을 바꿔도 같은 작업 세트와 센서와 종료 조건을 유지해 조합의 차이를 측정한다.

8. 자주 빠지는 설계 함정

• 같은 실패를 긴 지침 파일의 네 번째 개정판으로 해결하려 한다.
• 도구의 원시 출력을 컨텍스트에 그대로 넣는다.
• 모델의 “완료했다”는 문장을 종료 상태로 기록한다.
• 압축 때 사라져도 되는 대화 기록에 현재 상태를 맡긴다.
• 단계 수만 세고 같은 실패를 반복하는 정체를 감지하지 않는다.
• 하네스를 고정하지 않은 채 모델만 비교한다.
• 공급자 UI 안에 외부 하네스의 핵심 지식을 가둔다.
• 선택 가능한 도구를 지나치게 많이 노출한다.
• 비용 상한만 올리고, 반복을 유발한 센서의 부재는 고치지 않는다.
• 궤적을 저장하지 않아 실패 원인을 재생하지 못한다.

이 함정들의 공통 원인은 에이전트를 답변 생성기로만 보는 데 있다. 폐쇄 루프가 생긴 순간부터 에이전트는 상태를 가진 프로세스이고, 하네스는 그 프로세스를 운영하는 시스템이 된다.

관련 글

결론 및 시사점

한 줄 결론: 에이전트의 신뢰성은 모델의 말솜씨보다, 모델의 결정을 제한하고 결과를 관찰하고 완료를 검증하는 하네스의 품질에서 나온다.

하네스 엔지니어링은 모델을 감싸는 부수 작업이 아니다. 모델이 현실의 긴 작업을 수행하도록 만드는 실행 조건을 설계하는 일이다. 센서는 로그를 행동 신호로 바꾸고, 원장은 컨텍스트 압축과 프로세스 종료를 넘어 상태를 보존하며, 종료 조건은 모델의 자신감과 실제 완료를 분리한다.

실무에서는 더 긴 프롬프트보다 더 좁은 도구, 더 많은 로그보다 더 좋은 센서, 더 큰 예산보다 더 빠른 정체 감지에 먼저 투자해야 한다. 실패한 궤적을 저장하고 그것을 다음 하네스 개선으로 연결하면, 팀의 실행 지식이 모델 교체와 무관한 자산으로 축적된다.