Harness Engineering 101, 300줄로 읽는 AI 에이전트의 구조

 

이번 주 GeekNews에서 "Harness Engineering 101"이라는 입문서 소개 글을 봤습니다.
프레임워크나 SDK 없이 순수 Python으로 HTTP 요청부터 시작해, 약 300줄짜리 코딩 에이전트를 만들어 가는 16장 분량의 글이라고 해요.
저는 개발자가 아니라 서비스 기획자라서 코드를 한 줄씩 해석할 수는 없습니다.
그래도 이 글을 골랐어요.
AI 에이전트 이야기는 대부분 어떤 모델을 쓰느냐에서 시작하는데, 이 글은 모델 바깥의 구조를 정면으로 다루고 있었기 때문입니다.

오늘 내용은 GeekNews의 소개와 댓글을 읽으며 정리한 것이고, 원문 코드를 직접 돌려 본 것은 아니에요.
따라 해 볼 계획은 마지막에 적어 두겠습니다.

 

두뇌와 몸, 하네스라는 말

이 글의 핵심 비유는 LLM은 두뇌이고 하네스는 몸이라는 것입니다.
출발점은 LLM API가 상태를 기억하지 않는다는 사실이에요.
모델은 직전 대화를 따로 기억하지 못하기 때문에, 매 턴마다 지금까지의 대화 전체를 JSON 배열로 묶어 다시 보내야 합니다.
하네스는 바로 이 배열을 만들고 관리하는 쪽이에요.

이 한 가지만 이해해도 에이전트를 보는 느낌이 달라집니다.
채팅에서 AI가 앞의 말을 기억한다고 느끼는 것은 모델 혼자의 능력이 아니라, 대화를 매번 다시 건네주는 바깥 구조 덕분이라는 이야기니까요.
그러면 무엇을 배열에 넣고 무엇을 빼느냐가 곧 제품의 동작을 정하게 됩니다.

 

 

입문서의 구성이 인상 깊었습니다.
각 장은 실패 상황을 먼저 보여 주고, 그것을 고치는 최소한의 수정을 하고, 그 수정에 따르는 비용을 말하는 순서라고 해요.
완성된 구조를 먼저 보여 주는 대신, 문제가 생기는 순간부터 따라가게 하는 방식입니다.

캐싱에서 순서가 중요한 이유나 컨텍스트를 예산으로 봐야 하는 이유도 실제 문제와 연결해서 다룬다고 합니다.
제가 이해한 바로는, 모델에 넘길 수 있는 대화의 양에는 한도가 있어서 무엇을 남기고 무엇을 덜어낼지 정하는 일이 곧 설계라는 뜻 같아요.
기획자에게도 낯설지 않은 순서입니다.
좋은 기획서도 문제 상황, 해결안, 그 해결안이 만드는 트레이드오프를 같이 적어야 하니까요.

 

 

후반부에는 하위 에이전트, 백그라운드 작업, MCP와 Skills, 훅, 디버깅, 가드레일, RAG가 이어집니다.
부록에는 모델 라우팅, worktree 격리, 계획 모드, 재시도와 스트리밍이 있다고 해요.
16장에는 주석이 붙은 완성형 실습 하네스가 있고, Python 3.10 이상이면 외부 패키지 없이 실행된다고 합니다.
다만 기본 예제에는 Anthropic API 키가 필요해요.
작성자는 같은 아이디어를 pi 기반 오픈소스 코딩 에이전트 One Code에도 적용했다고 소개했습니다.

라이선스는 나눠서 봐야 합니다.
본문은 CC BY-NC-ND 4.0이라 상업적 이용과 수정본 배포가 안 되고, 코드는 MIT예요.
그래서 저는 이 글에서 내용을 요약해 소개하는 데 그치고, 본문을 옮겨 쓰지 않았습니다.
관심이 생기셨다면 아래 출처의 원문을 직접 읽어 보시기 바랍니다.

 

댓글에서 눈에 띈 의견은 크게 세 가지였어요.

첫째는 찬성입니다.
직접 하네스를 만들어 보면 에이전트에게 어디까지 권한을 줄지 범위가 분명해지고, 기존 제품의 결함도 잘 보인다고 합니다.
한 사용자는 사흘쯤 걸릴 것으로 예상한 작업을 하루 만에 끝냈다고 해요.

둘째는 문체에 대한 반대입니다.
AI 특유의 표현이라며 "Load-Bearing"이라는 단어를 보고 읽기를 멈췄다고 했어요.
엔지니어가 글쓰기를 외주화하는 것을 비판하는 의견이었습니다.

셋째는 의문입니다.
하네스가 반드시 몸의 역할만 할 필요는 없고, 계획이나 기억 같은 지능을 담을 수도 있다는 지적이었어요.
더 똑똑한 모델일수록 하네스에 덜 의존한다는 주장의 근거가 무엇이냐는 질문도 있었습니다.

 

문체 비판은 기술 내용과는 별개의 이야기입니다.
그래도 글을 쓰는 사람으로서는 남의 일처럼 들리지 않았어요.
셋째 의견은 비유가 깔끔할수록 하네스를 몸이라는 한 가지 역할로만 단순하게 보게 될 수 있다는 경고로 읽혔습니다.
이 질문에 대한 답은 소개 글만으로는 알 수 없었어요.

 

 

가장 먼저 든 생각은 에이전트 제품의 경험이 모델 선택만큼 하네스에 달려 있다는 점입니다.
컨텍스트를 어떻게 관리하는지, 도구에 어떤 권한을 주는지, 가드레일을 어디에 두는지, 실패했을 때 어떻게 재시도하는지가 사용자가 느끼는 품질을 만들기 때문이에요.
같은 모델을 써도 이 부분이 다르면 전혀 다른 제품이 됩니다.
이런 항목들은 개발자만의 영역이 아니라 기획서에 적혀야 하는 결정이라고 생각해요.

예약 시스템에 AI를 붙이는 상황에 대입해 보면 더 분명합니다.
예약을 조회하는 일은 읽기이고, 예약을 만들거나 바꾸거나 취소하는 일은 쓰기입니다.
읽기는 넓게 허용해도 쓰기는 반드시 사용자에게 한 번 더 확인받고 실행하도록 정하는 식이 되겠지요.
테넌트 구조라면 한 업장의 정보가 다른 업장 쪽으로 섞이지 않도록 도구의 범위를 좁히는 일도 필요합니다.
이런 선은 모델이 알아서 지켜 주는 것이 아니라 하네스에서 정해야 한다는 점이 이번 글에서 가장 와닿았어요.

두 번째는 직접 만들어 보면 기존 제품의 결함이 보인다는 댓글에서 떠올린 제 경험입니다.
Claude 같은 도구로 목업을 기획해 본 적이 있는데, 화면은 그럴듯해도 왜 그렇게 동작하는지 설명이 없어서 개발자와 소통이 어긋났던 경험이 있어요.
만들어 보기 전에는 그 한계가 어디인지 감이 오지 않았습니다.
하네스도 비슷할 것 같아요.
써 보는 것과 만들어 보는 것은 다르고, 만들어 봐야 AI 도구의 한계와, 어디서부터 사람이 확인해야 하는지가 보일 것 같다는 생각이 들었어요.

요즘 만들고 있는 스팩브릿지는 화면 위에 정책과 데이터, API 스펙을 연결하는 도구입니다.
이런 맥락을 AI에게 넘기게 된다면 무엇을 컨텍스트에 넣고 무엇을 뺄지가 결국 고민이 되겠지요.
컨텍스트를 예산으로 보라는 말을 만나고 나니, 그 고민을 미리 해 둬야겠다는 생각이 들었어요.

 

정리하면 이 글은 에이전트를 마법이 아니라 공학으로 보게 해 주는 입문서 같습니다.
모델이 좋아져도 대화를 어떻게 건네고, 무엇을 허용하고, 실패를 어떻게 다루는지는 여전히 누군가 정해야 해요.
그 누군가에 기획자가 빠져 있으면 안 된다고 생각합니다.

남은 질문도 있습니다.
모델이 더 똑똑해지면 하네스는 얇아질까요, 아니면 책임이 커지는 만큼 더 두꺼워질까요.
예약처럼 쓰기가 따르는 서비스에서는 확인 단계를 어디까지 넣어야 사용자가 불편해하지 않을까요.
저는 먼저 16장을 한 장씩 읽으며 정리하고, API 키 비용을 확인한 뒤 작은 예제를 따라 해 볼 계획입니다.
해 보고 나면 그때 느낀 점을 이어서 적어 볼게요.

 

 

출처 : 원문(GitHub): IsuruMaduranga/harness-engineering-101