Skip to content
←

Split View: 하네스 엔지니어링이란 무엇인가 — 모델은 고정 입력이고, 배포하는 것은 그 주위 전부입니다

✨ Learn with Quiz
|

하네스 엔지니어링이란 무엇인가 — 모델은 고정 입력이고, 배포하는 것은 그 주위 전부입니다

같은 모델인데 왜 결과가 다를까요

두 팀이 같은 기반 모델로 같은 종류의 과제를 자동화한다고 해 보겠습니다. 한 팀의 에이전트는 이슈를 받아 테스트가 통과하는 패치를 만들어 내고, 다른 팀의 에이전트는 비슷한 이슈에서 파일을 뒤지다 절반쯤에서 멈춥니다. 이 대비는 설명을 위해 구성한 예시지만, 구도 자체는 에이전트를 운영해 본 팀이라면 낯설지 않을 것입니다. 모델이 같다면, 차이는 모델 바깥에서 나온 것입니다.

모델 바깥에 무엇이 있는지 적어 보면 목록이 생각보다 깁니다. 어떤 도구를 몇 개 노출했는지. 도구가 실패했을 때 모델에게 무엇을 돌려주는지. 몇 번까지 다시 시도하고, 무엇을 근거로 멈추는지. 매 턴 컨텍스트 창에 무엇을 넣고 무엇을 빼는지. 에이전트가 어떤 경로까지 쓸 수 있는지. 그리고 결과가 좋았는지를 누가, 어떤 기준으로 판정하는지. 이 목록 전체가 코드로 존재하고, 배포되고, 과제 성공률을 움직입니다.

하네스: 모델을 둘러싼 실행 시스템 전부

Lilian Weng이 2026년 7월에 쓴 글은 이 목록에 이름을 붙였습니다. 하네스는 기반 모델을 둘러싸고 실행을 조율하는 시스템입니다. 모델이 어떻게 사고하고 계획할지, 도구를 어떻게 부르고 행동할지, 컨텍스트를 어떻게 인지하고 관리할지, 산출물을 어디에 저장할지, 결과를 어떻게 평가할지를 결정하는 층 전부가 하네스입니다.

이 시리즈는 그 경계 안을 여섯 개의 손잡이로 나눠 다룹니다.

  • 도구 표면 — 모델에게 노출하는 도구의 집합과 스키마. 몇 개를, 어떤 이름과 설명으로 줄 것인가.
  • 실패 반환 형식 — 도구가 실패했을 때 예외 문자열을 그대로 줄 것인가, 원인과 대안을 구조화해 줄 것인가.
  • 루프 — 재시도 상한, 정지 조건, 막혔을 때의 에스컬레이션.
  • 컨텍스트 정책 — 무엇을 넣고, 무엇을 빼고, 언제 요약할 것인가.
  • 권한 — 에이전트가 읽고 쓸 수 있는 범위. 특히 평가 코드가 그 안에 있는가.
  • 평가자 — 결과를 판정하는 채점기. 이것이 시스템 전체의 상한을 정합니다.

전제는 하나입니다. 대부분의 팀에게 모델은 고정 입력입니다. 기반 모델을 만들지 않고 파인튜닝도 하지 않는 팀이 손댈 수 있는 것은 이 여섯 개가 전부이고, 동시에 이 여섯 개면 충분히 많습니다.

"프롬프트 엔지니어링"이라는 이름이 감추는 것

이 일을 오래 불러 온 이름은 프롬프트 엔지니어링이었습니다. 그 이름이 틀린 것은 아니지만 범위를 크게 과소평가합니다. 프롬프트는 위 여섯 손잡이 어디에도 단독 항목으로 없습니다. 시스템 프롬프트는 컨텍스트 정책의 한 조각이고, 도구 설명 문구는 도구 표면의 일부입니다. 문장으로 지시할 수 있는 공간보다 코드로 정의할 수 있는 공간이 훨씬 넓고, 성공률을 크게 움직이는 결정은 대부분 후자에 있습니다.

Anthropic이 2024년 12월에 공개한 에이전트 구축 가이드는 이 지점을 도구 쪽에서 짚습니다. 사람에게 UI가 있듯 에이전트에게는 도구 정의가 인터페이스이므로, 프롬프트에 들이는 만큼의 공을 도구 설계에 들여야 한다는 것입니다. 같은 글은 자체 SWE-bench 작업에서 전체 프롬프트보다 도구 최적화에 더 많은 시간을 썼다고 적고 있습니다.

실패 반환 형식도 같은 종류의 예입니다. 예외 문자열을 그대로 돌려주는 하네스에서 모델은 같은 호출을 반복하기 쉽고, 실패 원인과 지금 시도 가능한 대안을 구조화해 돌려주는 하네스에서는 다음 호출이 달라집니다. 이 차이는 프롬프트를 아무리 다듬어도 얻을 수 없습니다. 전적으로 코드 쪽 결정입니다.

워크플로든 에이전트든 하네스는 있습니다

같은 Anthropic 글은 에이전트형 시스템을 둘로 구분합니다. 워크플로는 LLM과 도구를 미리 정해진 코드 경로로 배치하는 방식이고, 에이전트는 모델이 스스로 다음 행동과 도구 사용을 정하는 방식입니다. 그리고 가장 단순한 해법에서 시작해 필요할 때만 복잡도를 올리라고 권합니다. 단일 호출에 검색과 예시를 붙이는 것으로 충분한 문제가 실제로 많습니다.

하네스 관점에서 이 구분을 다시 읽으면 이렇게 됩니다. 워크플로에서도 도구 표면, 실패 반환 형식, 권한, 평가자는 전부 필요합니다. 에이전트로 갈수록 루프의 주도권이 모델로 넘어가므로 재시도 상한, 정지 조건, 컨텍스트 정책의 비중이 급격히 커집니다. 어느 쪽이든 당신이 배포하는 것은 하네스이고, 무엇을 배포했는지 말할 수 있어야 관리가 시작됩니다.

손잡이는 따로 돌아가지 않습니다

여섯 손잡이를 코드로 쓰면 이 시리즈의 목차가 됩니다.

harness = {
    "tools": ["read_file", "write_file", "run_tests"],      # 3편: 도구 표면
    "on_error": "cause_plus_alternatives",                  # 3편: 실패를 어떻게 돌려줄 것인가
    "loop": {"max_retries": 3, "stop": "goal_check"},       # 4편: 루프와 정지 조건
    "context": {"policy": "playbook", "budget": 12000},     # 2편: 컨텍스트 예산
    "permissions": {"write": ["src/"], "deny": ["eval/"]},  # 6편: 리워드 해킹과 권한
    "evaluator": "rubric_v3",                               # 5편: 평가자 병목
}

주의할 것은 손잡이들이 얽혀 있다는 점입니다. 재시도 상한을 올리는 결정은 실패 반환 형식과 얽혀 있습니다. 원인 없는 재시도는 같은 실패를 더 비싸게 반복할 뿐입니다. 도구를 늘리는 결정은 컨텍스트 예산과 얽혀 있습니다. 도구 스키마도 토큰을 먹기 때문입니다. 그리고 모든 손잡이는 평가자와 얽혀 있습니다. 어느 조합이 나은지 판정하는 것이 평가자인데, 평가자가 약하면 비교 자체가 성립하지 않습니다. 그래서 이 시리즈는 손잡이를 하나씩 다루되 늘 같은 질문으로 돌아옵니다. 이 변경이 나아졌다는 것을 무엇으로 알 수 있는가.

직접 연습하기

이 블로그에는 하네스 엔지니어링을 게임으로 연습하는 하네스 엔지니어링 RPG가 있습니다. 방금 본 여섯 손잡이를 직접 조립해 27개 시나리오를 통과하는 구조이고, 1티어 "관측과 지문"이 이 글의 내용에 해당합니다. 프롬프트 쪽 기본기를 다지고 싶다면 프롬프트 엔지니어 연습 도구도 있습니다.

참고 자료

What Is Harness Engineering — The Model Is a Fixed Input; What You Ship Is Everything Around It

Same model, so why the different results

Suppose two teams automate the same kind of task with the same foundation model. One team's agent takes an issue and produces a patch that passes the tests; the other team's agent digs through files on a similar issue and stalls halfway. This contrast is a constructed example for the sake of explanation, but the shape of it will feel familiar to any team that has operated agents. If the model is the same, the difference came from outside the model.

Write down what sits outside the model and the list is longer than you expect. Which tools were exposed, and how many. What the model gets back when a tool fails. How many retries are allowed, and on what grounds the run stops. What goes into the context window each turn, and what gets dropped. Which paths the agent is allowed to write. And who judges whether the result was good, by what standard. That entire list exists as code, gets deployed, and moves the task success rate.

The harness: the whole execution system around the model

The post Lilian Weng wrote in July 2026 gave this list a name. The harness is the system that wraps a foundation model and orchestrates its execution — the layer that decides how the model thinks and plans, how it calls tools and acts, how it perceives and manages context, where it stores artifacts, and how results are evaluated.

This series divides what sits inside that boundary into six knobs.

  • The tool surface — the set of tools exposed to the model, with their schemas. How many, under what names and descriptions.
  • The failure return format — when a tool fails, does the model get the raw exception string, or a structured cause plus alternatives.
  • The loop — retry caps, stopping conditions, escalation when stuck.
  • The context policy — what goes in, what gets dropped, when to summarize.
  • Permissions — the range the agent can read and write. In particular, whether the evaluation code sits inside it.
  • The evaluator — the grader that judges results. This one sets the ceiling for the whole system.

There is one premise. For most teams, the model is a fixed input. A team that neither builds nor fine-tunes a foundation model can touch exactly these six things — and these six are plenty.

What the name "prompt engineering" hides

The long-standing name for this work was prompt engineering. The name is not wrong, but it badly undersells the scope. The prompt appears nowhere in the six knobs as a standalone item. The system prompt is one piece of the context policy, and tool description copy is part of the tool surface. The space you can define in code is far larger than the space you can instruct in sentences, and most of the decisions that move success rates live in the former.

The agent-building guide Anthropic published in December 2024 makes this point from the tool side. Just as humans get a UI, agents get tool definitions as their interface, so tool design deserves as much care as the prompt. The same post notes that in their own SWE-bench work, more time went into optimizing the tools than the overall prompt.

The failure return format is the same kind of example. In a harness that returns the raw exception string, the model tends to repeat the same call; in a harness that returns the cause of failure plus the alternatives currently available, the next call is different. No amount of prompt polishing buys you this difference. It is entirely a code-side decision.

Workflow or agent, the harness is there either way

The same Anthropic post splits agentic systems in two. Workflows arrange LLMs and tools along predefined code paths; agents let the model decide its own next actions and tool use. And it recommends starting with the simplest solution and adding complexity only when needed. For many problems, a single call with retrieval and examples is genuinely enough.

Reread that distinction from the harness point of view and it comes out like this. A workflow still needs the tool surface, the failure return format, permissions, and an evaluator. As you move toward agents, control of the loop shifts to the model, so the weight of retry caps, stopping conditions, and context policy grows sharply. Either way, what you deploy is a harness — and management begins when you can say what you deployed.

The knobs do not turn independently

Write the six knobs as code and you get this series in outline.

harness = {
    "tools": ["read_file", "write_file", "run_tests"],      # Part 3: the tool surface
    "on_error": "cause_plus_alternatives",                  # Part 3: how to return failure
    "loop": {"max_retries": 3, "stop": "goal_check"},       # Part 4: loops and stopping
    "context": {"policy": "playbook", "budget": 12000},     # Part 2: the context budget
    "permissions": {"write": ["src/"], "deny": ["eval/"]},  # Part 6: reward hacking and permissions
    "evaluator": "rubric_v3",                               # Part 5: the evaluator bottleneck
}

The thing to watch is that the knobs are entangled. Raising the retry cap is entangled with the failure return format: retries without a cause just repeat the same failure at higher cost. Adding tools is entangled with the context budget: tool schemas eat tokens too. And every knob is entangled with the evaluator, because the evaluator is what judges which combination is better — with a weak evaluator, the comparison itself does not hold. So this series takes the knobs one at a time but keeps returning to the same question: how do you know this change made things better?

Practice it yourself

This blog ships a harness engineering RPG that turns this into a game: you assemble the six knobs you just saw and clear 27 scenarios. Tier 1, "Observation and fingerprints", corresponds to this post. If you want to build up the prompt-side fundamentals, there is also a prompt engineering practice tool.

References