AI 에이전트 하네스란 무엇인가 — 모델과 하네스를 분리해서 봐야 하는 이유

블로그에 Ultra Harness 구축기도 쓰고 실전 투입기도 썼는데, 정작 하네스가 뭔지를 정의한 적이 없다. “하네스를 만들었다”, “하네스가 에이전트를 막았다” 같은 문장을 계속 썼으니, 이번 글에서 이 단어를 한 번 제대로 풀어둔다.

원래 뜻 — 말의 힘을 방향으로 바꾸는 장치

harness는 원래 마구(馬具)다. 말에 채우는 가슴걸이와 끈 묶음. 말은 그 자체로 강력한 동력원이지만, 마구 없이는 그 힘을 마차를 끄는 데 쓸 수 없다. 마구가 하는 일은 말을 더 강하게 만드는 게 아니다. 이미 있는 힘을 원하는 방향으로 전달되게 묶는 것이다.

영어 표현 “harness the power of ~”(~의 힘을 활용하다)가 여기서 나왔다. 이 어감이 중요하다. 하네스는 동력 그 자체가 아니라, 동력과 일 사이의 연결 구조다.

소프트웨어로 넘어오다 — 테스트 하네스

이 단어가 소프트웨어에 처음 정착한 곳은 test harness다. 테스트 하네스는 테스트 대상 코드를 실행하기 위한 주변 장치 일체를 말한다. 테스트 러너, 목(mock) 객체, 픽스처, 입력 데이터 주입, 결과 수집과 리포트까지.

여기서도 구조는 같다. 테스트 하네스는 코드를 더 좋게 만들지 않는다. 코드가 통제된 환경에서, 반복 가능하게, 관찰 가능한 형태로 실행되도록 둘러쌀 뿐이다. 동력(코드)과 목적(검증) 사이의 연결 구조라는 점에서 마구와 정확히 같은 은유다.

그리고 AI 에이전트 하네스

LLM이 등장하면서 이 단어가 세 번째 삶을 얻었다. 에이전트 하네스는 모델 주변을 감싸는 모든 것이다. 구체적으로는:

• 시스템 프롬프트와 컨텍스트 주입 (CLAUDE.md, 메모리, 규칙 파일)
• 모델이 쓸 수 있는 도구(tool)와 그 권한 체계
• 행동을 제약하는 가드레일 (훅, 권한 모드, 승인 플로우)
• 여러 에이전트를 엮는 오케스트레이션 (서브에이전트, 워크플로)
• 결과를 검증하는 피드백 루프 (테스트, 린트, 리뷰 에이전트)

말 — 마차 — 마구의 구도를 그대로 옮기면, 모델이 말이고, 내 작업이 마차고, 하네스가 마구다. Claude Code 같은 코딩 에이전트 도구 자체가 하나의 거대한 하네스다. 같은 모델 API를 쓰더라도 raw API 호출과 Claude Code 안에서의 동작이 완전히 다른 이유가 이것이다. 파일을 읽는 도구, 권한 시스템, 컨텍스트 관리가 전부 하네스 레이어에서 제공되기 때문이다.

모델과 하네스를 분리해서 봐야 하는 이유

이 구분이 단순한 용어 정리 이상으로 중요한 이유가 있다.

1. 벤치마크는 사실 “모델 + 하네스” 점수다

SWE-bench 같은 에이전트형 벤치마크에서 모델이 받는 점수는 순수 모델 점수가 아니다. 어떤 도구를 줬는지, 몇 턴까지 허용했는지, 컨텍스트를 어떻게 관리했는지에 따라 같은 모델의 점수가 크게 출렁인다. Fable 5 벤치마크 글에서 다룬 점수들도 전부 특정 하네스 위에서의 결과다. 모델 비교 기사를 읽을 때 “어떤 하네스에서?”를 묻는 습관이 필요하다.

2. 모델은 못 바꾸지만 하네스는 내가 설계할 수 있다

모델의 가중치는 내 손 밖이다. 하지만 하네스는 전부 내 손 안에 있다. CLAUDE.md에 뭘 적을지, 어떤 훅으로 뭘 막을지, 에이전트를 어떻게 계층화할지는 모두 사용자의 설계 영역이다. 같은 모델을 쓰는 두 사람의 생산성이 몇 배씩 차이 나는 지점이 바로 여기다. 모델 성능의 상향은 분기 단위로 오지만, 하네스 개선은 오늘 당장 할 수 있다.

3. 모델이 바뀌어도 하네스는 남는다

Opus에서 Fable로 모델을 갈아타도 CLAUDE.md, 훅, 에이전트 구조, 워크플로는 그대로 작동한다. 모델은 소모품처럼 교체되지만 하네스는 자산으로 누적된다. 하네스에 투자한 시간이 모델 세대를 넘어 이월된다는 뜻이다.

하네스를 구성하는 다섯 레이어

내가 실제로 운용하는 구조를 기준으로 하네스를 분해하면 다섯 레이어로 나뉜다.

각 레이어의 실제 구축 과정은 이전 글들에 있다. 컨텍스트와 규칙 레이어는 ECC 규칙셋 도입기에서, 오케스트레이션 레이어는 Ultra Harness 구축기에서, 가드레일이 실제로 에이전트를 막은 사례는 요양시설 플랫폼 실전기에서 다뤘다.

이 글을 쓰는 동안에도 가드레일 레이어가 작동했다. 포스트 파일을 생성하려는 순간 GateGuard 훅이 끼어들어 “이 파일이 어디서 호출되는지, 같은 목적의 파일이 이미 있는지, 사용자 지시가 뭐였는지”를 먼저 제시하라고 막았다. 귀찮아 보이지만 이게 하네스의 본질이다. 모델이 똑똑한지와 무관하게, 구조가 실수를 걸러낸다.

정리

• 하네스는 마구에서 온 말로, 동력을 더 키우는 장치가 아니라 동력을 원하는 방향으로 전달하는 연결 구조다.
• 테스트 하네스를 거쳐, 지금은 모델 주변을 감싸는 모든 것(컨텍스트, 도구, 가드레일, 오케스트레이션, 피드백 루프)을 가리킨다.
• 벤치마크 점수는 모델+하네스의 합산 점수고, 모델은 교체돼도 하네스는 자산으로 남는다.
• 그래서 에이전트 시대의 실력은 모델 선택보다 하네스 설계에서 갈린다.

모델은 말이고 하네스는 마구다 — 빨라지고 싶다면 더 좋은 말을 기다리기 전에 마구부터 손보자.