Harness Engineering 101: LLM은 뇌, harness는 몸

TL;DR Highlight

에이전트는 JSON 배열을 관리하는 루프이고, 16개 챕터로 직접 만들어 본다

Who Should Read

에이전트 프레임워크가 마법처럼 느껴져 내부 구조를 직접 이해하고 싶은 LLM API 백엔드 개발자

Core Mechanics

LLM API는 매 턴 대화 전체를 보낸다
- LLM API는 상태가 없다(stateless).
- 매 턴 전체 대화를 JSON 배열로 보내고 텍스트를 돌려받는다.
harness는 그 배열을 관리하는 프로그램
- harness는 배열을 만들고, 유지하고, 보호한다.
- 저자는 에이전트라 불리는 것들이 이 루프 하나에 덧댄 패치 모음이라고 본다.
패치는 실제 고장에서 나왔다
- 각 챕터는 같은 모양이다: 실패, 최소 패치, 패치의 비용.
- 예로 컨텍스트가 차는 문제, 한 배열로 일을 다 못 담는 문제, 실행 중 방향이 틀어지는 문제를 다룬다.
약 300줄 파이썬 장난감 에이전트를 키워 간다
- 16개 챕터를 따라 plain Python 에이전트를 점점 확장한다.
- 실행 가능한 코드는 src/harness/에 단계별 파일로 들어 있다.
프레임워크도 챕터 1의 래퍼로 본다
- 10장은 모든 프레임워크가 1장(JSON 배열)의 래퍼라는 관점이다.
- RAG도 harness 패턴 중 하나로 다룬다(15장).

Community Reactions

내 harness를 직접 만들었더니 문제가 풀렸다는 경험
- 다른 에이전트 방식을 따르지 않고 자기 문제를 기준으로 만들었다는 댓글이다.
- 추론을 표준보다 더 돌리는 비용을 감수하고, 몇 시간 뒤 결과만 확인하는 자율 에이전트를 얻었다고 한다.
harness 최적화가 모델 크기를 이겼다는 경험
- Jev를 harness 최적화했더니 원래는 deepseek보다 훨씬 못했지만 최적화 후 훨씬 낫고 비용은 극히 일부였다는 댓글이다.
harness가 뇌만큼 지능을 가질 수 있다는 반론
- 모델 라우팅, 플래닝 도구, 직접 만든 메모리, 고전 ML, 강화학습 등을 harness에 넣을 수 있다는 의견이다.
- 용도에 따라 LLM이 아예 필요 없을 수도 있다고 한다.
직접 만들어 보라는 조언과 AI 글 비판
- 설명글 대신 Thorsten Ball의 how-to-build-an-agent 글로 시작해 직접 구현하라는 의견이 있다.
- 책이 AI 작성 같다는 비판도 여러 개 있었다.

How to Apply

오늘 내 에이전트의 메시지 배열을 출력해 보기
- 쓰는 에이전트나 프레임워크가 매 턴 보내는 messages를 로그로 찍어라.
- 시스템 프롬프트, 툴 결과, 이력이 어떤 순서로 쌓이는지 확인하라.
실패 하나를 골라 챕터 대응표 만들기
- 최근 겪은 에이전트 장애(컨텍스트 초과, 방향 이탈 등)를 목차의 실패 항목에 매핑하라.
- 해당 챕터의 최소 패치부터 읽어라.
toy harness를 로컬에서 돌려 루프 직접 수정하기
- 저장소의 src/harness/ 단계별 파일을 실행하라.
- 툴 하나를 추가하고 루프가 어떻게 변하는지 확인하라.

Try It

복사해서 바로 해보기

# Claude나 ChatGPT에 그대로 붙여넣기 (원문 개념의 간이 버전)

내 에이전트는 매 턴 아래 messages 배열 전체를 LLM API에 보낸다고 가정해 줘.

{{messages JSON 또는 로그}}

이 배열을 'harness가 만들고, 유지하고, 보호해야 할 배열'이라는 관점으로 분석해 줘.
1) 어떤 부분이 컨텍스트를 가장 많이 차지하는가
2) 캐싱을 깨뜨리는 순서 문제가 있는가
3) 실패 시 어떤 패치(요약, 서브에이전트, 가드레일)가 필요한가

이어서 해 볼 것: 가장 급한 패치 하나를 파이썬 20줄 이내로 작성해 달라고 요청하라.

Terminology

harnessLLM을 둘러싼 프로그램. 뇌(LLM)가 쓰는 몸처럼 메시지 배열을 만들고 툴을 실행하며 루프를 돌린다.

stateless서버가 이전 대화를 기억하지 않는 방식. 매번 전체 대화를 다시 보내야 한다.

Minto pyramid결론을 먼저 쓰고 근거를 뒤에 붙이는 글쓰기 구조.

subagent컨텍스트를 포크해 일을 나눠 맡는 하위 에이전트. 별도 작업장을 쓰는 동료 같은 것.

MCP외부 툴을 에이전트에 연결하는 표준 방식. 책에서는 확장 방법 중 하나로 다룬다.