하네스와 메타 하네스 Harness and Meta-Harness

1주차 실습에서 while 루프 하나에 도구 두 개를 붙여 첫 에이전트를 만들었다. 그 루프에 무엇을 넣어 주고, 언제 멈추고, 에러가 나면 어떻게 넘기는지를 조금씩 바꾸면 같은 모델이라도 성공률이 달라진다. 모델을 감싸는 이 코드 전부를 하네스(harness)라 부른다.

Shunyu Yao 등이 2022년에 발표한 ReAct는 추론(reasoning)과 행동(acting)을 한 루프 안에서 번갈아 수행하게 한다. 그전까지 두 계열은 따로 있었다. 한쪽은 Chain-of-Thought로 대표되는 순수 추론이다. 모델은 단계를 밟아 결론에 도달한다. 앞 단계의 사실이 틀리면 그 위에 쌓은 추론 전체가 틀린다. Yao 등은 이것을 CoT의 환각과 오류 전파 문제로 짚었다. 다른 한쪽은 도구를 부르는 행동 계열이다. 검색하고 계산하지만 왜 지금 그 도구를 부르는지가 텍스트로 남지 않는다.

ReAct는 매 스텝을 세 조각으로 나눈다. 모델은 먼저 Thought를 쓴다. 지금 상황이 어떻고 다음에 무엇을 해야 하는지를 자연어로 적는다. 그다음 Action을 낸다. 어떤 도구를 어떤 인자로 부를지 정한다. 도구가 실행되면 환경이 Observation을 내놓는다. 검색 결과, 계산 값, 에러 메시지 같은 것이다. 이 Observation이 다음 스텝의 Thought로 들어가고, 모델은 이 Observation을 근거로 다시 생각한다.

순수 추론은 이 그림에서 Observation 상자가 없는 경우다. 모델은 자기가 아는 것만 가지고 끝까지 간다. ReAct에서는 매 스텝 실제 실행 결과가 들어온다. 모델이 “이 API의 응답은 이런 형식일 것이다”라고 잘못 가정하면 다음 Observation이 실제 응답을 보여 주고, 모델은 그 자리에서 가정을 고친다. Yao 등은 HotpotQA와 Fever에서 ReAct가 위키피디아 API 하나로 CoT의 환각과 오류 전파를 줄였다고 보고했다. Thought가 텍스트로 남으므로 에이전트가 왜 그 행동을 했는지 사람이 나중에 읽을 수 있다. 매주 logs/에 커밋하는 실행 로그가 이 텍스트다.

ReAct는 패턴이다. Thought를 쓰게 한다고 그 Thought가 옳아지지는 않는다. 모델은 그럴듯한 추론을 적어 놓고 엉뚱한 Action을 낼 수 있다. ReAct가 보장하는 것은 그 어긋남이 다음 Observation에서 드러난다는 점까지다. 어긋남을 잡아 되돌리는 일은 종료 조건, 에러 복구, 반복 상한 같은 나머지 하네스 설계가 맡는다.

harness는 원래 말에 씌워 힘을 한 방향으로 쓰게 하는 장치를 가리킨다. 2026년 Yoonho Lee 등이 Meta-Harness 논문에서 쓴 정의는 이렇다.

하네스가 정하는 것을 다섯 요소로 나눈다. 첫째는 컨텍스트 관리다. 컨텍스트 창은 유한하고, 무엇을 그 안에 넣느냐가 성능을 좌우한다. 지난 스무 스텝의 Observation을 전부 넣으면 최근 정보가 묻히고, 너무 잘라 내면 모델이 방금 한 일을 잊는다. 무엇을 보여 주고 무엇을 숨길지, 오래된 기록을 어떻게 요약해 접을지가 첫 결정이다. 둘째는 도구 granularity다. 도구를 가늘게 쪼갤수록(read_line(n)) 모델의 통제는 정밀해지지만 호출 횟수와 토큰이 늘고, 굵게 묶을수록(read_file()) 한 번에 많은 일을 하지만 실패했을 때 어디서 틀렸는지 짚기 어렵다.

셋째는 종료 조건이다. 모델이 답을 냈다고 선언하는 순간을 종료 조건으로 삼으면 위험하다. 모델은 다 못 풀고도 끝났다고 말한다. 그래서 실무 하네스는 최대 반복 횟수 상한, 목표 달성을 확인하는 별도 검증 단계, 명시적 종료 도구(finish(answer)) 같은 장치를 둔다. 넷째는 에러 복구다. 도구가 예외를 던지거나 인자 형식이 어긋났을 때, 하네스는 거기서 멈출 수도 있고 에러 메시지를 Observation으로 되돌려 모델이 고치게 할 수도 있다. 후자가 ReAct에 맞는다. 다섯째는 인간 개입 지점(human-in-the-loop)이다. 결제나 파일 삭제처럼 돌이킬 수 없는 행동 앞에서 멈추고 승인을 구할지, 끝까지 자율로 갈지를 정한다. 실습에서는 이 개입 횟수를 센다.

# ReAct형 하네스의 뼈대. 다섯 요소가 코드 어느 줄에 들어가는지 표시
def run_react(task, tools, max_steps=8):
    history = [system_prompt(tools), user(task)]   # [요소1] 컨텍스트 관리
    interventions = 0
    for step in range(max_steps):        # [요소3] 종료 조건: 반복 상한
        reply = model(history)                # Thought + Action을 한 번에 생성
        history.append(assistant(reply))
        if reply.tool_call is None:
            return reply.text            # [요소3] 모델이 finish를 택함 → 종료
        if reply.tool_call.name in IRREVERSIBLE:
            if not ask_human(reply.tool_call):  # [요소5] 개입 지점
                interventions += 1
                history.append(observation("거부됨: 사람이 승인하지 않음"))
                continue
        try:
            obs = tools.call(reply.tool_call)     # [요소2] 도구 granularity는 tools 정의에
        except Exception as e:
            obs = f"에러: {e}"              # [요소4] 에러 복구: 에러도 Observation
        history.append(observation(obs))          # Observation → 다음 Thought로
    return "MAX_STEPS 도달: 미완"            # 상한에서 강제 종료

이 코드에서 다섯 요소의 값은 어느 것도 모델이 정하지 않는다. 전부 사람이 정한다. 같은 모델이라도 이 값을 다르게 잡으면 다른 에이전트가 된다. 하네스는 실험으로 탐색할 수 있는 설계 공간이다. 실습에서는 그 공간에서 두 점을 골라 비교한다.

다섯 요소의 값을 사람이 손으로 바꿔 가며 A/B를 돌리는 대신, 그 탐색 자체를 에이전트에게 맡길 수 있다. 하네스가 자기 실행 기록을 분석해 반복이 많았던 지점을 찾아 다음 버전의 하네스 코드를 고치는 구조다.

Yoonho Lee, Roshen Nair, Qizheng Zhang, Kangwook Lee, Omar Khattab, Chelsea Finn이 2026년 3월에 낸 논문 “Meta-Harness: End-to-End Optimization of Model Harnesses”가 이 구조를 그대로 구현했다. 바깥 루프는 세 단계를 반복한다. 코딩 에이전트인 proposer가 새 하네스 코드를 제안하고, 그 하네스로 태스크를 풀어 점수를 매기고, 소스 코드와 점수와 실행 trace를 전부 파일시스템에 남긴다. 다음 제안 때 proposer는 이전 후보 전부의 코드와 trace를 그 파일시스템에서 직접 읽는다.

논문의 핵심 주장은 기존 텍스트 최적화기가 피드백을 너무 압축한다는 것이다. 이전 시도를 기억하지 않고, 점수 하나나 짧은 요약만 받는다. Lee 등은 online text classification에서 proposer에게 주는 정보를 세 조건으로 나눠 비교했다.

Lee et al. (2026) Table 3의 수치. 요약은 점수만 줄 때와 거의 같고, 전체 trace를 줄 때만 median 후보가 다른 두 조건의 best 후보를 넘는다. 이 수치는 논문의 태스크에서 나온 것이고 이 수업의 측정값이 아니다.

“나아졌는가”를 판정하는 함수가 루프 안에 있으면 자기 개선은 표류(drift)한다. 모델이 자기 답을 자기가 채점하는 구조가 되기 때문이다. Meta-Harness에서 이 판정은 proposer가 손댈 수 없는 태스크 점수다. 아래 Ouroboros에서는 사람이 인터뷰로 고정한 acceptance criteria와 deterministic verify command다.

CASEOuroboros의 메타 하네스 루프

Ouroboros는 1주차 소개에서 언급한 오픈소스 Agent OS다. Meta-Harness가 점수를 최대화하는 하네스를 찾는다면, Ouroboros는 사람이 확정한 요구사항을 충족하는 실행이 나올 때까지 실행 규칙을 고친다. 저장소에서 이 루프는 네 모듈로 나뉜다. core/seed_contract.py의 SeedContract가 실행 전에 goal과 acceptance criteria를 고정한다. orchestrator가 실행을 관리하고 trace를 남긴다. evaluation/pipeline.py가 결과를 모으고 orchestrator/verifier.py가 verify command로 통과 여부를 판정한다. evolution/loop.py가 이 판정과 기록을 다음 generation의 입력으로 삼는다.

SeedContract        core/seed_contract.py     goal, acceptance criteria, ontology
OrchestratorRunner  orchestrator/runner.py    runtime 호출, 세션 이벤트, 실행 상태
EvaluationPipeline  evaluation/pipeline.py    결과 수집과 독립 평가
Verifier            orchestrator/verifier.py  verify command의 deterministic 판정
EvolutionaryLoop    evolution/loop.py         generation별 수정, 재실행, 회귀 확인

이 구조를 메타 하네스라 부르는 이유는 EDIT의 대상이 답변이 아니라 다음 실행을 만드는 규칙이기 때문이다. acceptance criteria와 verify command는 Seed에 고정되어 EDIT가 손대지 못한다. 이 경계를 넘기면 모델의 자기 채점만 남는다.

LINEAGE자기 개선 루프의 계보

메타 하네스 이전에도 출력 하나를 더 만드는 데서 그치지 않고 다음 실행의 조건을 바꾸는 연구가 여럿 있었다. 여섯 방법은 무엇을 바꾸는지와 무엇을 판정 신호로 쓰는지로 구분한다. Self-Refine(Madaan et al. 2023)은 같은 LLM이 초안과 피드백과 수정본을 번갈아 만든다. 바꾸는 것은 출력이고 신호는 자기 피드백이다. Reflexion(Shinn et al. 2023)은 실패 원인을 언어로 적어 다음 trial의 episodic memory에 넣는다. 바꾸는 것은 컨텍스트다. DSPy(Khattab et al. 2023)는 파이프라인을 선언적으로 쓰고, compiler가 metric을 최대화하는 prompt와 demonstration을 찾는다. GEPA(Agrawal et al. 2025)는 trajectory를 읽고 자연어로 반성해 prompt 후보를 Pareto frontier에 쌓는다. Meta-Harness는 하네스 코드를 바꾸고, Darwin Gödel Machine(Zhang et al. 2025)은 에이전트 코드 자체를 수정한 후보를 archive에 보관하고 코딩 벤치마크로 검증한다.

Self-Refine을 뺀 다섯 방법은 판정 신호를 수정 대상과 분리해 둔다. Self-Refine은 같은 모델이 피드백까지 만들고, 그래서 뒤의 연구들이 환경 결과, metric, 벤치마크로 신호를 옮겼다. 논문들이 제시한 수치는 각자의 태스크에서 나온 것이므로 실습 보고서에 그대로 옮기지 않는다.

모델과 태스크와 도구는 상수로 고정하고, 하네스만 독립변수로 바꾼다. 같은 모델에 같은 태스크를 주되, 하나는 ReAct형 하네스로, 다른 하나는 Plan-then-Execute형 하네스로 풀게 한 뒤 네 지표를 나란히 잰다. 태스크는 도구가 필요한 다단계 문제면 된다. “주어진 로그 파일에서 에러가 가장 많이 난 시간대를 찾아 요약하라”처럼 파일을 읽고, 세고, 정리해야 답이 나오는 것을 권한다. 준비물은 1주차와 같다. Python 3.10 이상, anthropic 또는 openai 패키지, API 키 하나.

ReAct형은 매 스텝 Thought → Action → Observation을 돌며 다음에 무엇을 할지를 매번 다시 판단한다. Plan-then-Execute형은 먼저 전체 계획을 한 번에 세운 뒤(Plan) 그 계획의 단계를 순서대로 실행한다(Execute). 계획을 미리 굳히므로 토큰이 적게 들고 흐름이 예측 가능하지만, 중간 Observation이 계획과 어긋나면 방향을 틀기 어렵다. 두 방식의 우열은 태스크마다 실행 결과로 갈린다.

1. 공용 도구와 모델 래퍼를 한 모듈에 둔다. 두 하네스가 공유할 도구(read_file, count_pattern)와 모델 호출 함수, 토큰 카운터를 tools_shared.py에 둔다. 도구가 다르면 하네스 비교가 성립하지 않는다.
2. ReAct형 하네스를 구현한다. 위의 run_react 뼈대를 태스크에 맞게 채운다. 종료는 모델의 finish 호출 또는 max_steps 상한으로. 반복 횟수와 개입 횟수를 실행 중에 센다.
3. Plan-then-Execute형 하네스를 구현한다. 1차 호출로 단계 리스트(계획)를 받고, 2차부터 각 단계를 실행한다. 계획이 어긋나면 재계획을 1회까지만 허용해 유연성 상한을 명시한다.
4. 같은 태스크로 각각 3회씩 실행한다. 모델 출력은 확률적이라 1회 실행은 우연이다. 하네스당 최소 3회를 돌려 성공률과 지표의 분산을 함께 본다. 실행마다 프롬프트, 도구 집합, max_steps 같은 실험 조건을 기록한다.
5. 결과를 results.csv에 기록한다. 실행마다 성공 여부, 토큰, 반복 횟수, 개입 횟수를 한 줄씩 적는다. 실패한 실행도 남긴다.
6. 해석을 한 문단 쓴다. 어느 하네스가 이 태스크에서 어떤 지표로 이겼고 왜인지.

# 두 하네스가 공유하는 도구, 모델, 측정 유틸. 같은 도구를 써야 공정한 비교
import os, anthropic, openai, re, json

OPENROUTER_KEY = os.environ.get("OPENROUTER_API_KEY")
if OPENROUTER_KEY:                      # 키 하나로 벤더 자동 판별
    client = openai.OpenAI(base_url="https://openrouter.ai/api/v1", api_key=OPENROUTER_KEY)
    MODEL = "anthropic/claude-sonnet-4.5"
else:
    client = anthropic.Anthropic()
    MODEL = "claude-sonnet-4-5"

def read_file(path):                    # 도구 1
    with open(path, encoding="utf-8") as f:
        return f.read()[:4000]           # 컨텍스트 보호용 상한

def count_pattern(text, pattern):        # 도구 2
    return len(re.findall(pattern, text))

TOOLS = {"read_file": read_file, "count_pattern": count_pattern}

class Meter:                             # 네 지표를 한곳에서 센다
    def __init__(self):
        self.tokens = 0; self.iters = 0; self.interventions = 0
    def add(self, n_in, n_out):
        self.tokens += n_in + n_out
        self.iters += 1

def call_model(messages, meter):
    if OPENROUTER_KEY:                 # OpenAI 호환 포맷: choices, prompt/completion_tokens
        resp = client.chat.completions.create(model=MODEL, max_tokens=1024, messages=messages)
        meter.add(resp.usage.prompt_tokens, resp.usage.completion_tokens)
        return resp.choices[0].message.content
    resp = client.messages.create(model=MODEL, max_tokens=1024, messages=messages)
    meter.add(resp.usage.input_tokens, resp.usage.output_tokens)
    return resp.content[0].text

# Plan-then-Execute형: 계획을 먼저 굳히고 순서대로 실행한다
import json
from tools_shared import TOOLS, Meter, call_model

def run_plan_execute(task, max_replan=1):
    meter = Meter()
    # 1) PLAN: 전체 계획을 한 번에 요청
    plan_raw = call_model(
        [{"role": "user", "content": f"다음 태스크의 단계별 계획을 JSON 리스트로만 답하라: {task}"}],
        meter)
    plan = json.loads(plan_raw)          # 파싱 실패도 하나의 실패 모드
    replans = 0
    # 2) EXECUTE: 계획의 각 단계를 순서대로 수행
    context = []
    for step in plan:
        result = execute_step(step, context, meter)     # 도구 호출 포함
        context.append(result)
        if result.get("off_plan") and replans < max_replan:
            plan = replan(task, context, meter); replans += 1   # 유연성 상한
    return summarize(context, meter), meter, replans

run,harness,success,tokens,iters,interventions,note
# run: 1..6 / harness: react | plan_exec / success: O | X (실행 전에 정한 기준으로)
# tokens: Meter.tokens / iters: Meter.iters / interventions: 사람이 승인 또는 거부한 횟수

성공 여부의 기준은 실행 전에 문장으로 적어 둔다. “에러가 가장 많은 시간대를 14시로 답하면 O”처럼 정답이 확인되는 형태여야 한다. 실행 후에 기준을 정하면 실패가 성공으로 바뀐다.

제출 규칙은 1주차와 같다.

• 필수S. Yao et al., “ReAct: Synergizing Reasoning and Acting in Language Models” (2022)ReAct의 원전. Thought, Action, Observation의 교차가 CoT-only와 act-only 대비 무엇을 바꾸는지를 실험 설계와 함께 읽고, 실습의 ReAct형 하네스와 대조하기 위해. arXiv:2210.03629
• 필수Y. Lee, R. Nair, Q. Zhang, K. Lee, O. Khattab, C. Finn, “Meta-Harness: End-to-End Optimization of Model Harnesses” (2026)메타 하네스의 원전. 하네스 정의, 바깥 루프 세 단계, 그리고 proposer에게 전체 trace를 주는 것이 왜 요약보다 나은지를 Table 3과 함께 읽기 위해. arXiv:2603.28052
• 선택A. Madaan et al., “Self-Refine: Iterative Refinement with Self-Feedback” (2023)생성, 피드백, 수정의 반복. 같은 모델이 피드백까지 만들 때 판정 신호가 어디에 있는지 확인하기 위해. arXiv:2303.17651
• 선택N. Shinn et al., “Reflexion: Language Agents with Verbal Reinforcement Learning” (2023)실패의 언어적 기록을 다음 trial에 넣는 방법. Ouroboros의 trace와 다음 generation 입력을 비교하기 위해. arXiv:2303.11366
• 선택O. Khattab et al., “DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines” (2023)metric을 기준으로 파이프라인의 prompt와 demonstration을 찾는 compiler. Meta-Harness 저자 중 한 명의 앞선 작업이다. arXiv:2310.03714
• 선택L. Agrawal et al., “GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning” (2025)trajectory를 읽고 prompt 후보를 만들며 Pareto frontier를 유지하는 방법. Meta-Harness가 ‘피드백을 너무 압축한다’고 비교하는 대상 중 하나다. arXiv:2507.19457
• 선택J. Zhang et al., “Darwin Gödel Machine: Open-Ended Evolution of Self-Improving Agents” (2025)에이전트 코드 후보를 archive에 보관하고 코딩 벤치마크로 검증하는 사례. 계보 중 수정 범위가 가장 넓다. arXiv:2505.22954