하네스

하네스(Harness)는 모델이나 프로그램을 정해진 조건으로 실행하고, 그 과정과 결과를 관리하기 위해 붙이는 주변 소프트웨어와 실행 구성을 통틀어 부르는 말입니다. AI에서는 평가 문제를 모델에 전달하고 점수를 계산하는 평가 하네스, 도구 실행과 작업 상태를 관리하는 에이전트 하네스처럼 목적에 따라 여러 형태로 쓰입니다.

하네스라는 말이 쓰이는 자리

모델의 응답 하나를 얻는 일에도 입력을 준비하고 요청을 보내며 결과를 받는 과정이 필요합니다. 여러 모델을 같은 문제로 비교하려면 질문 형식과 정답 처리 방법도 맞춰야 합니다. 이런 공통 작업을 매번 따로 작성하는 대신 소프트웨어로 구성하면, 실행 조건을 반복해서 적용하고 결과를 비교하기 쉬워집니다. 하네스라는 말은 이처럼 중심이 되는 모델이나 프로그램을 실행하고 다루는 주변 구성을 가리킵니다.

평가 하네스의 한 예로 EleutherAI의 Language Model Evaluation Harness가 있습니다. 이 프로젝트는 평가 데이터, 프롬프트 구성, 모델 호출, 응답 처리와 점수 계산을 연결합니다. 같은 실행 틀에서 여러 모델과 평가 과제를 다룰 수 있도록 만든 것입니다. 벤치마크는 무엇을 측정할지에 관한 문제와 기준이고, 평가 하네스는 그 평가를 실행하는 소프트웨어입니다. 같은 하네스를 사용하더라도 선택한 과제와 설정이 다르면 점수의 의미가 달라집니다.

예를 들어 두 언어 모델이 고객 문의를 얼마나 정확히 분류하는지 비교한다고 가정해 보겠습니다. 같은 문의를 같은 형식으로 전달하고, 모델이 반환한 분류명을 꺼내 정답과 대조합니다. 한 모델에만 정답 예시를 더 보여 주거나 다른 분류명을 허용하면 공정한 비교가 어려워집니다. 하네스는 이런 입력과 채점 절차를 일정하게 적용하도록 도울 수 있습니다. 어떤 문의가 실제 업무를 대표하는지, 어느 답을 정답으로 인정할지는 사람이 별도로 정해야 합니다.

에이전트 하네스는 모델이 도구를 사용하며 작업을 이어가는 데 초점을 둡니다. 모델의 도구 호출을 받아 실행하고 결과를 다시 전달하며, 세션이나 중단 조건을 관리하는 구성이 여기에 들어갑니다. Anthropic의 장기 실행 에이전트 연구는 초기 환경을 준비하고 진행 기록을 남겨 여러 세션에 걸친 작업을 이어가는 예를 설명합니다. 하네스 전체를 에이전트와 같은 뜻으로 보기는 어렵고, 에이전트 하네스는 이 용어가 쓰이는 한 가지 구체적인 맥락입니다.

규칙 파일과 실행 소프트웨어의 차이

하네스는 실행 코드와 설정, 모델에 전달할 지침을 함께 사용할 수 있습니다. 하지만 규칙을 적은 문서와 그 규칙을 읽고 작업을 실행하는 프로그램은 역할이 다릅니다. 예를 들어 파일에 “작업 뒤 변경 내용을 기록한다”고 적어도, 그 파일 자체가 도구를 호출하거나 기록을 저장하지는 않습니다. 파일을 읽는 프로그램과 실제 저장 기능이 있어야 작업으로 이어집니다.

Claude Code의 CLAUDE.md는 이런 구분이 필요한 사례입니다. 공식 메모리 문서는 이 파일을 모델에 지속적인 문맥과 지시를 제공하는 마크다운 파일로 설명합니다. 파일에 프로젝트의 문체, 코드 규칙, 작업 절차를 적을 수 있지만, 파일 자체를 완성된 하네스라고 부르면 실행을 맡는 소프트웨어가 빠집니다. 문서를 수정하는 일은 하네스가 읽는 지침을 바꾸는 일로 이해하는 편이 정확합니다.

지시를 전달하는 것과 행동을 강제로 제한하는 것도 구분해야 합니다. 같은 공식 문서는 CLAUDE.md를 강제되는 설정이 아닌 문맥으로 다룬다고 설명합니다. 특정 도구 실행을 차단하려면 실제 권한 설정이나 실행 전 검사 같은 제어가 필요합니다. Claude Code의 훅 문서는 도구를 실행하기 전에 호출을 허용하거나 거부하는 PreToolUse의 동작을 설명합니다. 이런 실행 제어와 자연어 지침이 함께 있어도 둘의 보장 범위가 같아지는 것은 아닙니다.

이 차이는 결과를 검토할 때도 중요합니다. 모델에 정해진 형식으로 답하라고 요청하는 것은 지시이고, 반환된 응답이 그 형식에 맞는지 프로그램이 검사하는 것은 실행 후 처리입니다. 검사에 실패했을 때 다시 요청할지, 사용자에게 오류를 알릴지, 해당 작업을 끝낼지도 구현해야 합니다. 하네스에 이런 처리가 있다는 사실과 모델의 답변 내용이 사실이라는 판단은 별개의 문제입니다.

비교와 재개에 필요한 기록

하네스가 같다고 실행 결과까지 언제나 같아지는 것은 아닙니다. 모델 버전, 입력 데이터, 프롬프트, 생성 설정이 바뀌면 결과가 달라질 수 있습니다. 평가 목적이라면 사용한 과제와 정답 추출 방식까지 함께 남겨야 차이를 해석할 수 있습니다. 모델 평가 하네스가 공개된 프롬프트와 설정을 다루는 이유도 실행 조건을 확인하고 비교할 수 있게 하기 위해서입니다.

오래 걸리는 에이전트 작업에서는 이전에 무엇을 마쳤고 무엇이 남았는지 기록하는 기능이 도움이 됩니다. 앞의 Anthropic 연구도 진행 파일과 변경 이력을 다음 세션에서 읽는 구성을 사용합니다. 다만 기록에 완료라고 적혀 있다는 사실만으로 실제 작업이 끝났다고 판단해서는 안 됩니다. 생성한 파일이나 실행 결과처럼 완료를 뒷받침하는 상태를 함께 확인해야, 잘못된 기록을 이어받아 같은 실수를 반복하는 일을 줄일 수 있습니다.

모든 하네스가 로그, 재시도, 접근 제어를 자동으로 제공하는 것은 아닙니다. 필요한 기능을 직접 구현하거나 제공되는 기능을 설정해야 합니다. 요청과 응답을 기록한다면 어떤 항목을 남길지, 민감한 내용을 가릴지, 얼마나 보관할지도 정해야 합니다. 하네스를 비교할 때는 이름보다 실제로 관리하는 입력, 실행, 결과와 그 한계를 살펴보는 편이 유용합니다.