올해 들어 AI 에이전트 이야기에서 ‘하네스(harness)’라는 단어가 모델 이름만큼 자주 나옵니다. 2026년 10월 1일 Alexander Polomodov가 공개한 정리에 따르면, 2026년 5월 Google 보고서는 코딩 에이전트 경험을 “모델 10%, 하네스 90%”로 추정했습니다. 정밀한 측정값이 아니라 방향을 보여 주는 추정치이지만, 사내 시스템에 에이전트를 실제로 붙여 본 팀이라면 대체로 수긍할 비율입니다. 모델 API를 호출하는 코드는 수십 줄이고, 나머지 수천 줄은 모두 하네스이기 때문입니다.
문제는 ‘90%’라는 말이 너무 커서 아무것도 설명하지 않는다는 점입니다. 이 글은 그 90%를 구성요소로 쪼개고, 각 구성요소를 무엇으로 구현해야 하는지, 그리고 모델이 바뀌면 무엇을 걷어내고 무엇을 남겨야 하는지를 아키텍트 관점에서 정리합니다.
하네스의 정의: 모델을 뺀 에이전트의 전부
Claude Code 문서는 하네스를 모델을 실제로 일하는 에이전트로 만드는 도구, 컨텍스트 관리, 실행 환경으로 설명하고, Birgitta Böckeler는 “모델을 뺀 에이전트의 전부”라고 표현합니다. LangChain과 Faros는 이를 Agent = Model + Harness라는 식으로 줄입니다. 용어의 흐름을 보면 하네스가 어디서 왔는지가 보입니다.
| 시기 | 중심 개념 | 대표 사건 |
|---|---|---|
| 2022–2023 | 프롬프트 | 텍스트 입출력, 2023년 6월 function calling |
| 2024 | 스캐폴드 | 10월 computer use, 11월 MCP |
| 2025 | 제품으로서의 하네스 | Claude Code, Codex, Gemini CLI 등 CLI 에이전트 |
| 2026 | 하네스 엔지니어링 | 용어 정리, 관리형 에이전트 런타임 등장 |
프롬프트가 ‘무엇을 말할까’의 문제였다면, 하네스는 ‘모델이 실수해도 시스템이 어떻게 버틸까’의 문제입니다. 소프트웨어 아키텍처로 보면 프롬프트 엔지니어링이 함수 하나를 다듬는 일이고, 하네스 엔지니어링은 그 함수를 감싸는 런타임과 운영 체계를 설계하는 일입니다.
최소 하네스를 코드로 보면
개념이 추상적일 때는 가장 작은 구현을 보는 것이 빠릅니다. 아래는 구조를 보이기 위한 파이썬 의사 코드입니다. 특정 SDK의 API가 아닙니다.
def run(task, model, tools, policy, max_steps=40, budget_usd=2.0):
ctx = Context(system=load_instructions(), task=task) # 컨텍스트
for step in range(max_steps): # 루프·중단
if ctx.over_limit(): ctx.compact() # 메모리
reply = model.call(ctx.render(), tools.schemas())
trace.log(step, reply) # 관측
if reply.is_final():
if verify(task, workspace): # 검증
return reply
ctx.add("검증 실패: 테스트 결과를 확인하고 수정하라")
continue
for call in reply.tool_calls:
if not policy.allows(call): # 경계
ctx.add(f"거부됨: {call.name}은 허용되지 않음")
continue
result = sandbox.execute(call) # 도구·환경
ctx.add(result.summary(), artifact=result.path)
if cost.total() > budget_usd: break # 비용 한도
return escalate_to_human(task, trace)
스무 줄 남짓이지만 하네스의 거의 모든 구성요소가 들어 있습니다. 실제 제품의 하네스는 이 각 줄이 수백~수천 줄로 커진 것입니다.
일곱 가지 구성요소와 ‘말’과 ‘벽’
Polomodov는 하네스를 일곱 요소로 나눕니다. 업계 표준 분류는 아니라고 스스로 밝히지만 설계 점검표로 쓰기 좋습니다. 저는 여기에 ‘모델이 좋아지면 어떻게 되는가’라는 열을 붙여 봅니다.
| 구성요소 | 하는 일 | 주된 구현 | 모델이 좋아지면 |
|---|---|---|---|
| 루프·중단 | 언제 계속하고 언제 멈출지 | 지시문 + 상한값 | 지시문은 줄고 상한은 남음 |
| 컨텍스트·메모리 | 무엇을 보여 주고 기억할지 | 지시문 + 파일 | 요약 규칙이 단순해짐 |
| 도구·환경 | 무엇을 실행할 수 있는지 | 도구 정의 + 샌드박스 | 도구 설명이 짧아도 됨 |
| 검증 | 결과가 맞는지 확인 | 코드(테스트, 린트, 스키마) | 그대로 남음 |
| 오케스트레이션 | 여러 에이전트·단계 조율 | 코드 | 단계 수가 줄어듦 |
| 관측성·평가 | 무슨 일이 있었는지 기록·측정 | 코드 | 그대로 남음 |
| 신뢰·경계 | 하면 안 되는 일을 강제 | 코드(권한, 정책) | 그대로 남음 |
앞의 세 가지는 주로 ‘말'(지시문)로 답하고, 뒤의 네 가지는 ‘벽'(코드)으로 답합니다. 말은 모델이 좋아질수록 줄어들지만, 벽은 모델이 아무리 좋아져도 남습니다. 사람에 비유하면, 신입에게 주는 업무 요령 문서는 경력이 쌓이면 필요 없어지지만 결재 규정과 출입 통제는 사장에게도 적용되는 것과 같습니다.
숫자가 말하는 것과 말하지 않는 것
Polomodov의 정리에는 하네스 효과를 보여 주는 사례가 여럿 인용되어 있습니다. 모두 2차 인용이므로 원문을 확인하기 전에는 방향만 읽는 것이 좋습니다.
- Claw-SWE-Bench에서 GLM 5.1이 최소 어댑터로 19.1%, 전체 하네스로 73.4%를 기록했다는 보고
- OS 수준 샌드박스를 붙이자 사람에게 확인을 요청하는 횟수가 84% 줄었다는 사례
- 반대로 최상위 모델에서는 하네스 차이가 통계적으로 유의하지 않다는 결과, METR 비교에서 Claude Code가 단순 ReAct 루프를 이긴 비율이 50.7%에 그쳤다는 결과
두 방향의 숫자를 함께 놓으면 해석이 정리됩니다. 하네스는 약한 모델의 성능을 크게 끌어올리고, 강한 모델에서는 성능보다 안정성과 안전을 책임진다. 두 번째 사례가 특히 흥미롭습니다. 샌드박스라는 벽이 생기자 위험한 행동을 사람에게 물어볼 필요가 줄었고, 그 결과 자율성이 오히려 높아졌습니다. 벽은 에이전트를 묶는 장치이면서 풀어 주는 장치이기도 합니다. Addy Osmani의 말처럼 하중을 받치는 기둥은 여전히 모델이지만, 그 기둥을 어디에 세울 수 있는지는 하네스가 정합니다.
모델 업그레이드 날의 첫 질문: 무엇을 걷어낼까
Anthropic은 2026년 3월 글에서 하네스의 모든 구성요소가 ‘모델이 혼자 못 하는 일에 대한 가정’을 담고 있다고 정리했습니다. 가정이 틀리면 그 구성요소는 비용이 됩니다. Claude Code 팀이 새 모델에 맞춰 시스템 프롬프트를 80% 넘게 지웠는데도 품질이 떨어지지 않았다는 이야기도 같은 맥락입니다. 실무 기준으로 정리하면 다음과 같습니다.
- 재측정 후 삭제 후보: “단계별로 생각하라”, “파일을 먼저 읽어라” 같은 장문의 행동 지침. 새 모델에서 해당 행동 테스트를 돌려 지시 없이도 통과하면 지웁니다.
- 축소 대상: 쓰지 않는 도구. 도구 정의는 컨텍스트를 차지하고 오선택을 늘립니다. 사용 로그에서 최근 한 달간 호출되지 않은 도구는 빼 봅니다.
- 유지: 테스트·린트 검증, 권한 경계, 감사 로그, 비용 한도. 모델 성능과 무관하게 남깁니다.
지시문은 쌓이기만 하고 지워지지 않는 경향이 있습니다. 사고가 날 때마다 한 줄씩 추가되고, 왜 들어갔는지 아무도 기억하지 못해 지우지 못합니다. 그래서 다음 습관이 필요합니다.
하네스 결정 기록
저는 하네스의 구성요소마다 아래 세 줄을 남기도록 권합니다. 아키텍처 결정 기록(ADR)의 축소판입니다.
규칙: 수정 후 반드시 테스트를 실행하고 결과를 보고한다
막으려는 실패: 테스트 없이 완료 선언 (모델 X, 리팩터링 과제, 2026-07)
제거 판단 방법: 행동 테스트 T-014 지시문 없이 50회 중 48회 이상 통과 시 제거 검토
이렇게 적어 두면 모델 업그레이드가 곧 하네스 정리 작업이 됩니다. 실패가 더 이상 재현되지 않는 규칙은 지우고, 여전히 재현되는 규칙은 지시문에서 코드 검증으로 옮길지 검토합니다. 말로 부탁하던 것을 벽으로 바꾸는 방향입니다.
사내 플랫폼에서는 벽을 공통 계층으로
폐쇄망 사내 생성형 AI 플랫폼을 설계할 때 저는 하네스를 두 층으로 나눕니다.
- 플랫폼 공통 계층(벽): 인증·권한 경계, 샌드박스 실행 환경, 감사 로그와 추적, 비용·호출 한도, 공통 검증(출력 스키마, 개인정보 필터). 모든 에이전트가 공유합니다.
- 에이전트별 계층(말): 업무 지시문, 도구 선택, 컨텍스트 구성, 단계 설계. 업무팀이 빠르게 바꿉니다.
국내 기업은 조직 사정에 따라 오픈 모델과 상용 모델을 오가게 되는데, 벽이 모델 옆에 붙어 있으면 모델을 바꿀 때마다 보안 심의를 다시 받아야 합니다. 벽을 공통 계층으로 빼 두면 모델 교체는 에이전트별 계층의 재측정 문제로 줄어듭니다. 작은 팀이라도 에이전트에 파일 쓰기나 명령 실행을 맡긴다면 테스트 실행 검증, 작업 디렉터리 제한, 실행 로그 세 가지는 첫날부터 두는 것이 좋습니다.
하네스와 프레임워크의 관계도 짚어 둘 만합니다. 프레임워크는 하네스를 만드는 재료이고, 하네스는 특정 모델과 과제에 맞게 조립된 실행 환경 전체입니다. 같은 프레임워크로도 전혀 다른 하네스가 나옵니다. 도구별 하네스의 차이는 에이전트 도구 3종 비교 글에서 따로 다뤘습니다.
맺으며
“모델 10%, 하네스 90%”는 정확한 숫자라기보다 시선을 옮기라는 말입니다. 그 90% 안에서도 모델이 좋아지면 사라질 말과, 끝까지 남을 벽을 구분해야 합니다. 각 구성요소가 어떤 가정 위에 서 있는지 기록해 두면, 다음 모델이 나온 날 무엇을 걷어낼지 몇 시간 안에 판단할 수 있습니다. 하네스는 계속 덧붙이는 구조물이 아니라, 모델과 함께 가벼워져야 하는 구조물입니다.