테스트 42/0, 비용 3.84달러짜리 영수증이 에이전트 런 하나마다 남습니다

에이전트가 무너지는 장면은 늘 비슷합니다. 같은 명령을 세 번 돌리고, 고치지도 않은 파일을 계속 열어보고, 끝에는 아무도 못 읽는 로그만 남깁니다.

rari라는 개발자가 이 장면을 놓고 교본을 한 편 썼습니다. 제목은 "Harness Engineering: How to Build AI Agents That Don't Fall Apart", 무너지지 않는 에이전트를 만드는 법이에요. 링크 트윗이 조회 33만 8천을 넘겼습니다. 북마크는 729건이 붙었어요.

뼈대는 날짜별 작업 목록과 체크리스트 한 장입니다. 읽고 나면 손에 남는 게 관점이 아니라 할 일 목록이라는 점이 이 글 성격을 말해줍니다.

왜 같은 가중치가 다른 에이전트가 됩니까?

교본은 첫 진단부터 방향을 틉니다. 에이전트가 실패하는 이유는 모델이 멍청해서가 아니라 환경이 부실해서라는 겁니다.

모델은 추론 엔진일 뿐이라고 봐요. 같은 가중치를 채팅창에 앉히면 답을 뱉고 끝납니다. 레포와 툴, 리뷰 루프 안에 앉히면 파일을 고치고 테스트를 돌리고 PR을 엽니다.

가중치는 한 글자도 안 바뀌었습니다. 바뀐 건 모델이 손을 뻗을 수 있는 범위예요. 그러니 같은 모델도 하네스가 다르면 다른 에이전트라는 결론이 나옵니다.

오픈AI도 같은 진단을 내놨다고 인용합니다. 에이전트가 헤매는 원인을 환경이 덜 규정된 상태에서 찾는다는 거예요. 과제는 줬는데 무엇이 성공인지, 어디까지 만져도 되는지, 실패하면 어떻게 되는지를 안 정해준 상태입니다.

세 층을 가르는 문장이 이 글에서 가장 또렷합니다. "프롬프트 엔지니어링은 모델에게 무엇을 할지 알려준다. 컨텍스트 엔지니어링은 모델이 무엇을 볼지 정한다. 하네스 엔지니어링은 모델이 행동하는 세계를 짓는다."

일주일 동안 무엇을 세웁니까?

교본 본론은 프로덕션 하네스를 하루 단위 작업으로 쪼갭니다. 하루에 하나씩 쌓아 올리면 뼈대가 서는 순서예요.

1일은 계약입니다. 입력과 출력, 성공 조건을 문서로 못 박습니다.

2일은 맵입니다. 에이전트가 만질 수 있는 영역을 그려줍니다.

3일은 툴과 환경입니다. 실제로 도는 명령만 남기고 나머지는 치웁니다.

4일은 외부 메모리입니다. 기억을 모델 안이 아니라 모델 밖 파일에 둡니다.

5일은 센서입니다. 행동을 붙이기 전에 관측을 먼저 붙입니다. 무엇이 벌어지는지 못 보는 상태에서 권한부터 주면, 사고가 나도 사고인 줄 모릅니다.

6일은 권한입니다. 승인 판정을 모델 밖으로 꺼냅니다. 모델에게 "위험하면 하지 마"라고 부탁하는 대신, 모델이 넘을 수 없는 경계를 밖에 세우는 방식이에요.

7일은 트레이스와 복구입니다. 런 하나를 처음부터 끝까지 되짚을 기록을 남기고, 로컬에서 되돌릴 길을 뚫어둡니다.

일곱 항목을 다시 보면 공통점이 보입니다. 모델을 더 똑똑하게 만드는 항목이 하나도 없어요. 전부 모델 바깥에 배선을 까는 일입니다.

규칙은 어디에 두 번 새깁니까?

규칙을 다루는 대목이 실무에서 제일 아플 겁니다.

교본은 규칙을 두 군데 새기라고 합니다. 사람이 읽는 가이드 문서에 한 번, 기계가 돌리는 체크에 한 번. 이중 인코딩입니다.

문서에만 써두면 지켜지는지 아무도 모릅니다. 에이전트가 규칙을 어겼는지 확인하려고 사람이 매번 로그를 읽어야 한다면, 그건 규칙이 아니라 희망이에요. 같은 규칙을 기계 체크로도 박아두면, 어긴 순간 런이 멈춥니다.

12항짜리 체크리스트가 붙어 있는 이유도 같습니다. 판단을 매번 새로 하지 말고, 통과해야 넘어가는 관문으로 굳혀두라는 겁니다.

루프는 어디서 멈춰야 합니까?

실행 루프 설계에는 네 가지가 들어갑니다. 증거, 재시도 상한, 예산, 에스컬레이션.

에이전트는 자기가 다 했다고 말하면 안 됩니다. 테스트가 통과했다는 증거를 내야 다음으로 넘어갑니다.

재시도에는 숫자를 박습니다. 교본이 든 예시 루프는 attempt <= 3이에요. 상한에 걸리면 루프가 스스로 멈춥니다.

예산도 상한입니다. 토큰과 비용이 정해둔 선을 넘으면 거기서 끊습니다.

마지막이 에스컬레이션입니다. 멈춘 자리에서 사람에게 넘깁니다. 막힌 에이전트가 창의적으로 우회하기 시작하는 구간이 제일 위험하니까요.

앤스로픽 쪽 원칙도 같은 방향으로 인용됩니다. 필요한 최소 복잡도로 시작하라는 겁니다. 멀티 에이전트부터 짜는 대신, 루프 하나를 제대로 닫는 데서 출발하라는 얘기예요.

런이 끝나면 무엇이 남습니까?

구조 쪽 제안은 셋으로 나누는 겁니다. 뇌와 손과 기록. 판단하는 자리, 실행하는 자리, 남기는 자리를 섞지 말라는 뜻이에요.

기록 쪽에서 나온 물건이 체인지 리싯입니다. 런 하나가 끝날 때마다 영수증 한 장을 남깁니다.

교본에 실린 예시가 이렇게 생겼습니다. 테스트는 42/0입니다. 재시도는 2회였어요. 비용은 3.84달러입니다. 붙은 자리는 PR 1842번입니다.

한 줄짜리 영수증인데 여기 다 들어 있습니다. 무엇을 검증했는지, 몇 번 헛돌았는지, 얼마를 태웠는지, 결과물이 어디 붙었는지. 이 칸들이 비어 있는 에이전트는 무슨 일을 했는지 아무도 모르는 에이전트입니다.

교본은 여섯 시간짜리 코딩 런을 기준선으로 듭니다. 파일을 고치고, 네트워크를 타고, PR까지 여는 런이라면 진짜 하네스가 필요하다는 거예요. 반대로 말하면 5분짜리 질의응답에는 이 장비가 다 필요 없습니다.

남는 생각

저는 이 교본에서 문장 하나만 남기려 합니다.

"좋은 하네스는 에이전트 실수를 인프라로 바꾼다."

에이전트가 같은 실수를 반복하면, 프롬프트에 주의사항 한 줄을 더 쓰는 게 보통입니다. 저도 그렇게 해왔어요. 그런데 그 한 줄은 다음 모델로 갈아타는 순간 같이 사라집니다.

같은 실수를 기계 체크로 박아두면 남습니다. 모델을 바꿔도 체크는 그대로 돌아요. 실수 한 번이 자산 한 줄로 바뀌는 겁니다.

교본 결론도 같은 자리에 있습니다. 목록 전체를 한꺼번에 세우려 들지 말고, 루프 하나를 닫는 최소 하네스부터 만들라는 겁니다. 증거를 요구하고, 상한을 걸고, 영수증을 남기는 루프 하나면 시작이 됩니다.

저는 프롬프트를 다듬는 시간과 체크를 박는 시간 중에 뒤엣것만 쌓인다고 봅니다. 프롬프트 엔지니어링은 지시를 고칩니다. 하네스 엔지니어링은 지시가 실행되는 조건을 고칩니다. 고쳐놓은 조건은 다음 런에도, 다음 모델에도 그대로 남아 있습니다.

---

원문·소스

• 하네스 엔지니어링 교본 링크 트윗 (@0xwhrrari, 조회 33만 8천·북마크 729건): https://x.com/0xwhrrari/status/2093685107534000560