LLM Harness란 무엇인가: AI 에이전트 실행 구조의 핵심

LLM¹ 도구를 활용하면서 크게 배운 것은 일의 해체입니다. 한 번도 일을 쪼개서 해나간다는 생각을 해본 적이 없는 것 같습니다. 회사에서 일을 할 때도 주어진 과제를 그저 수행할 뿐이었습니다. LLM을 쓰고 스킬을 만들어보다 보니, 최대한 쪼개고 단계적으로 던질수록 LLM이 더 잘 처리한다는 걸 배웠고, 사람 역시 마찬가지라는 생각이 듭니다.

많은 양의 업무에 하나씩 쳐나가는 데 급급해서 어떻게 잘해야 하나에 대한 고민을 해볼 시간이 없었던 것 같습니다.

그래서 요즘은 어떤 일을 할 때 그 구조를 분석하고 쪼개보려고 노력합니다. 그리고 오늘 소개할 Harness도 같은 원리라는 생각을 하게 되었습니다.

---

Hermes²를 사용하면서 살짝 아쉬운 부분이 있었고, Claude Code에서부터 OpenClaw³까지 점점 일을 잘하게 되는 이유가 궁금했습니다. 직접 만들어볼까 하는 생각을 가지다가, 공개된 자료도 찾아보고 LLM에게 물어가며 이제 조금 이해하게 된 것 같습니다.

핵심은 분할

2025년 중반, Claude Opus 4 버전 전후였던 걸로 기억하는데, 이때부터 Claude Code에서 계획을 짜고 일을 단계적으로 실행하기 시작했습니다. 처음엔 좀 의아했던 게, 원래는 코드를 파일별로 한 번에 수정해버렸던 기억이 있어서 뭔가 더 자주 LLM을 호출하는 로직이 좀 이상하다고 생각했습니다.

물론 체감상 결과물은 훨씬 좋아졌지만, 단순히 모델의 성능 개선이라고 생각했던 것 같습니다. 당시에는…

LLM한테 일을 몽땅 던지면 이렇게 됩니다.

graph LR
    User[사용자] -- "A-E 전부 해줘" --> LLM[LLM]
    LLM -.-> Mistake[실수 발생]

    style LLM fill:#1E293B,stroke:#6366F1,stroke-width:2px,color:#818CF8
    style Mistake fill:#1E293B,stroke:#94A3B8,stroke-width:1px,color:#94A3B8,stroke-dasharray: 5 5

Harness⁴가 있으면 달라집니다. 단계마다 결과를 받아 컨텍스트에 쌓고 다음 단계를 넘깁니다.

실제 Harness는 이보다 훨씬 복잡한 구조를 갖지만, 이해를 돕기 위해 큰 틀만 아래로 정리했습니다. (저도 아직 이해하는 중입니다.)

graph LR
    User[사용자] --> Request[요청]
    Request --> Harness[Harness]

    subgraph Loop [↻ ITERATION LOOP]
        Harness --> Decide[판단 요청]
        Decide --> LLM[LLM]
        LLM --> Action[행동 실행]
        Action --> Result[결과 누적]
        Result --> Harness
    end

    Harness --> Response[결과 반환]
    Response --> User

    style Harness fill:#1E293B,stroke:#6366F1,stroke-width:2px,color:#818CF8
    style LLM fill:#1E293B,stroke:#334155,stroke-width:1px,color:#F8FAFC
    style Loop fill:#0F172A,stroke:#1E293B,stroke-dasharray: 5 5

LLM의 추론 능력이 워낙 좋기에, 주어진 도구를 알려주고 맥락을 주입하면서 특정 행동을 유도하는 것이 Harness라는 결론을 내렸습니다.

모델이 데이터를 읽고 판단합니다. 판단을 통해 도구를 선택하고, 도구 실행은 Harness가 합니다. 그 결과를 다시 모델에게 주고, 모델이 다음 결정을 합니다. 쉽게 말해 이 과정의 반복입니다.

def read_file(path):
    with open(path, "r", encoding="utf-8") as file:
        return file.read()

tools = {
    "read_file": read_file
}

# LLM의 응답
decision = {"tool": "read_file", "args": {"path": "posts/ko/example.md"}}

# Harness가 도구 이름으로 실제 함수를 찾아 호출
result = tools[decision["tool"]](**decision["args"])

# 읽어온 파일 내용을 다시 LLM에게 전달
llm.send({"role": "tool", "content": result})

사실 게을러서 그렇지 이미 Anthropic이나 OpenAI에 문서 형태로 꽤 많이 올라온 자료입니다. 더 깊이 공부하고 싶으시면 아래 링크를 참고하시길 바랍니다.

• Harness design for long-running apps — Anthropic
• How Claude Code works — Anthropic
• Inside the Agent Harness: How Codex and Claude Code Actually Work
• What is an agent harness — Parallel.ai
• Harness engineering — Martin Fowler

(1) LLM (Large Language Model) — 대규모 언어 모델. GPT, Claude, Gemini 등 텍스트를 이해하고 생성하는 AI 모델의 총칭.

(2) Hermes — LLM 기반 자동화 에이전트 프레임워크. 반복 작업을 자동으로 처리해주는 도구.

(3) OpenClaw — 오픈소스 코딩 에이전트. 코드 작성과 실행을 자동화하는 도구.

(4) Harness — LLM의 행동을 제어하는 실행 프레임워크. 도구·권한·컨텍스트를 주입하고, LLM이 단계별로만 행동하도록 구조적으로 강제한다.