LLM은 두뇌, 하네스는 몸… AI 에이전트 '몸 만들기' 교과서 나왔다

깃허브에 올라온 무료 온라인 북 **'Harness Engineering 101'**이 해커뉴스에서 127점, 63개 댓글을 모으며 화제다. 저자 이수루 위제시리는 WSO2에서 코파일럿 제품을 만들며 겪은 시행착오를 16개 챕터로 정리했다.

핵심은 한 줄이다. LLM API는 상태가 없다. 매 턴마다 대화 전체를 JSON 배열로 보내고 텍스트를 받는다. 이 배열을 만들고 지키고 다듬는 프로그램이 바로 '하네스'다.

책의 구성: 실패→패치→비용, 16단계 실습

책은 장난감 에이전트 300줄 파이썬 코드를 챕터마다 한 단계씩 키운다. 각 장은 실패 → 최소 패치 → 패치의 비용 세 부분으로 똑같이 구성된다. 15장은 기본 루프다. JSON 배열 기초, 도구 호출 매핑, 에이전트 루프, 캐싱 순서를 다룬다. 69장은 장시간 실행 문제다. 컨텍스트 예산 관리, 서브에이전트로 문맥 분할, 루프 조향, 비동기 작업을 해결한다. 1012장은 생태계 편이다. 프레임워크는 1장 래퍼일 뿐임을 보이고, MCP(모델 컨텍스트 프로토콜)·훅·스킬로 몸을 확장하는 법, 배열 디버깅을 설명한다. 1315장은 신뢰와 도메인이다. 반사·가드레일(안전장치), 코딩 에이전트 특화, RAG(검색 증강 생성)도 하네스 패턴 중 하나임을 보인다. 에필로그엔 완성된 장난감 하네스 코드와 주석이 실려 있다.

커뮤니티 반응: "주방과 셰프" 비유가 공감 얻다

해커뉴스 댓글 중 **"하네스는 주방, 모델은 셰프"**라는 비유가 큰 호응을 얻었다. 셰프(모델)가 아무리 유능해도 오븐(도구)과 밀가루(데이터)가 없으면 케이크를 못 만든다는 뜻이다. 또 다른 댓글은 **"같은 작업을 수천 번 반복하면 그 작업을 하네스 쪽(도구·지시·가이드)으로 옮겨야 한다"**고 지적했다. 반복 작업일수록 모델이 아닌 하네스에서 해결해야 비용과 지연이 준다는 실무 조언이다. 저자 본인도 "핵심 제품 표면이 완성되기 전이라 문서화는 나중 순위"라며 벤치마크 부재를 인정했다.

앞서 다룬 기사들과 연결되는 지점

이 책이 다루는 문제는 본지가 앞서 다룬 세 기사와 겹친다. 타입세이프 '제브' 등장 기사는 LLM 출력을 구조화해 하네스가 다루기 쉽게 만드는 시도였다. 스트롯(Strot) 등장 기사는 하네스 쪽에서 라우팅·분류를 소형 모델로 대체해 API 호출을 줄이는 패턴을 다뤘다. 'AI가 생각을 숨기고 말만 내놓는다면' 기사는 하네스가 모델 내부 추론을 볼 수 없을 때 생기는 신뢰 문제를 짚었다. 모두 하네스가 모델의 빈틈을 메우는 몸체라는 이 책의 주제와 이어진다.

쉽게 풀어보면

이수루 위제시리가 쓴 'Harness Engineering 101'은 LLM을 뇌에, 하네스를 몸에 비유한 무료 교과서다. 뇌(LLM)는 똑똑하지만 눈·귀·손이 없다. 몸(하네스)이 도구를 쥐여 주고, 대화 기록을 관리하고, 실수를 막는 가드레일(안전장치)을 세워야 비로소 일을 한다.

책은 16개 챕터를 네 파트로 나눴다. 15장은 기본 루프: JSON 배열 주고받기, 도구 연결, 에이전트 루프, 캐싱 순서. 69장은 장시간 실행: 컨텍스트 예산, 서브에이전트로 문맥 분할, 루프 조향, 비동기 작업. 1012장은 생태계: 프레임워크는 1장 래퍼일 뿐, MCP(모델 컨텍스트 프로토콜)·훅·스킬로 몸 확장, 배열 디버깅. 1315장은 신뢰: 반사·가드레일, 코딩 에이전트 특화, RAG(검색 증강 생성)도 하네스 패턴 중 하나. 에필로그엔 완성된 장난감 하네스 코드가 주석과 함께 실려 있다.

저자는 클로드 코드와 자사 도구 '원 코드'로 초안을 다듬었다고 밝혔다. 원문은 isuruwijesiri.com/harness-engineering-101에서 무료로 읽을 수 있다. 깃허브 저장소에는 마크다운 원문과 실행 가능한 파이썬 코드, 다이어그램 생성 스크립트가 모두 공개돼 있다.

나에게 미치는 영향

챗GPT·클로드·제미나이 같은 채팅창을 쓸 때도 '대화 기록이 곧 컨텍스트 배열'이라는 사실만 알면 답답함이 줄어든다. 이전 대화가 길어지면 모델이 앞 내용을 잊는다. 이건 모델 탓이 아니라 배열 크기 한도(컨텍스트 윈도우) 때문이다. 새 대화창을 열면 배열이 비워지니 답이 달라질 수 있다.

직장에서 프롬프트 엔지니어링을 맡았다면 12장 '배열 디버깅'부터 읽어보라. 모델이 보낸 프롬프트 전체(시스템·유저·어시스턴트·도구 결과)를 한눈에 볼 수 있는 로깅 도구가 없다면, 프롬프트 수정은 추측 게임이 된다. 오늘 바로 할 수 있는 것:

• 사용 중인 LLM 클라이언트에서 '원시 요청/응답 보기' 기능을 켠다
• 다음 답변이 이상할 때 JSON 배열 전체를 복사해 저장해 둔다
• 그게 하네스 디버깅의 시작이다

개발자라면 저장소의 src/harness/ 폴더를 열어 300줄 장난감 에이전트를 돌려보라. mdbook serve로 로컬에서 책을 보며 코드와 설명을 나란히 놓으면 개념이 잡힌다. 파이썬 3.10 이상, matplotlib만 있으면 다이어그램도 다시 그릴 수 있다.

남은 쟁점

책은 '하네스 패턴'을 체계화했지만 성능 벤치마크는 없다. 해커뉴스 댓글 작성자도 "핵심 제품 표면이 완성되기 전이라 문서화는 나중 순위"라고 밝혔다. 벤치마크 없는 교과서를 지금 읽는 이유는 패턴 이름만이라도 알아두면 나중에 프레임워크 갈아탈 때 헤매지 않기 때문이다.

또 한국어 번역본은 아직 없다. 영문 독해가 부담이면 브라우저 번역 기능을 쓰되, 기술 용어(컨텍스트 윈도우, 서브에이전트, 가드레일 등)는 원문 대비 확인하는 습관이 필요하다.

국내에서 이 패턴을 도입하려면 LLM API 요금제와 컨텍스트 한도를 먼저 확인해야 한다. 챕터 5·6에서 말하는 캐싱 순서·컨텍스트 예산 관리가 요금 절감으로 직결되기 때문이다. 본지가 다룬 스트롯 기사처럼 판단·라우팅을 소형 로컬 모델로 옮기는 하네스 패턴도 국내 GPU 환경에서 검토해 볼 만하다.