LLM을 움직이는 하네스 구조를 16개 장으로 뜯어본다

GitHub에 'Harness Engineering 101'이라는 온라인 책이 공개됐다. AI 에이전트를 프레임워크 없이 1원칙부터 조립해 보는 실습형 연재물로, 핵심 관점은 한 문장으로 요약된다. 추론을 담당하는 LLM은 두뇌이고, 그 두뇌를 둘러싸고 실제로 일이 돌아가게 만드는 프로그램인 하네스는 몸이라는 것이다.

출발점은 LLM API의 무상태성이다. 모델 서버는 이전 대화를 기억하지 않으므로, 매 요청마다 대화 전체를 JSON 배열로 다시 실어 보내고 텍스트를 돌려받는다. 저자가 말하는 하네스란 결국 이 배열을 조립하고, 갱신하고, 망가지지 않게 지키는 코드다. 세간에 '에이전트'라 불리는 것들은 이 하나의 루프 위에 덧대는 패치 묶음이며, 패치마다 실제로 터졌던 구체적인 실패가 존재 이유로 붙어 있다.

책은 16개 장과 부록으로 구성된다. 약 300줄 분량의 장난감 수준 에이전트에서 시작해 필요한 기능을 하나씩 붙여 나가는 방식이고, 각 장은 '무엇이 깨졌는가 → 최소한의 수정 → 그 수정이 남긴 것'이라는 동일한 흐름을 따른다. 설명을 먼저 늘어놓고 예제를 끼워 넣는 대신, 고장을 먼저 보여주고 고치는 순서로 진행되는 셈이다.

1부는 통신 계층을 다룬다. 다음 토큰을 예측하는 블랙박스로서의 모델, JSON을 함수 호출로 연결하는 도구 규격, 그리고 캐싱에서 순서가 왜 구조적으로 중요한지를 설명한다. 2부는 대화 배열이 길어지며 받는 압력으로 넘어간다. 하나의 배열에 모든 작업을 담을 수 없게 되는 순간과, 동기적으로 도는 루프가 비동기적인 외부 세계와 부딪히는 지점을 짚는다.

3부는 생태계를 정리한다. 어떤 프레임워크든 결국 1장에서 만든 루프를 감싼 포장이라는 시각에서, MCP와 스킬, 지연 로딩, 훅처럼 배열 용량 밖으로 밀려난 능력을 어떻게 다루는지 다룬다. 4부는 신뢰와 도메인, 데이터로 향한다. 루프가 어처구니없는 짓을 할 때의 대응, 몸을 얼마나 특화해야 하는가, 그리고 RAG 역시 별도 기술이 아니라 하네스 패턴의 한 갈래였다는 재해석이 담긴다.

부록은 실무에서 자주 부딪히는 주제를 따로 떼어 놓았다. 모델 라우팅과 프롬프트 티어, 비용 엔지니어링, 병렬 에이전트에 각각의 작업 공간을 주는 워크트리 격리, 하네스가 강제하는 운용 상태인 플랜 모드, 그리고 재시도·레이트 리밋·스트리밍 같은 눈에 잘 안 띄는 배관 작업이다. 플랜 모드처럼 코딩 에이전트에 특화된 항목은 그렇다고 명시해 두었다.

책은 mdbook과 mdbook-mermaid로 빌드되며, 수치형 다이어그램은 matplotlib 스크립트로 다시 생성할 수 있다. 저장소에는 단계별로 파일을 나눈 실행 가능한 토이 하네스가 함께 들어 있다. 라이선스는 이원화되어 있어 코드는 MIT로 자유롭게 쓸 수 있지만, 각 장과 부록의 산문은 CC BY-NC-ND 4.0이라 상업적 이용과 수정 배포가 제한된다.

실무적으로 얻어갈 것은 프레임워크 사용법이 아니라 디버깅의 좌표다. 컨텍스트가 왜 비싸지는지, 도구 호출이 어디서 어긋나는지, 장시간 작업이 왜 중간에 흐트러지는지를 배열과 루프 수준에서 설명할 수 있게 되면, 라이브러리를 바꿔 끼울 때도 무엇이 달라지는지 판단하기 쉬워진다.

다만 이 책의 패턴은 특정 오픈소스 코딩 에이전트 구현에서 길어 올린 것이라 코딩 도구 쪽으로 기울어 있다. 또 산문 라이선스가 2차 가공을 막고 있어, 내용을 요약·각색해 재배포하려면 조건을 먼저 확인해야 한다.