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

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

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

뼈대는 날짜별 작업 목록과 체크리스트 한 장입니다. 읽고 나면 관점보다 바로 해 볼 할 일 목록을 손에 쥐게 됩니다.

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

rari는 첫 진단부터 방향을 틉니다. 에이전트가 실패하는 이유를 모델보다 부실한 환경에서 찾아요.

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

가중치는 한 글자도 안 건드렸습니다. 모델이 손을 뻗을 수 있는 범위만 넓혔어요. 그래서 rari는 하네스가 다르면 같은 모델도 다른 에이전트라고 봅니다.

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

rari는 세 층을 이렇게 나눕니다. "프롬프트 엔지니어링은 모델에게 무엇을 할지 알려준다. 컨텍스트 엔지니어링은 모델이 무엇을 볼지 정한다. 하네스 엔지니어링은 모델이 행동하는 세계를 짓는다."

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

rari는 본론에서 프로덕션 하네스를 하루 단위 작업으로 쪼갭니다. 하루에 하나씩 만들면 일주일 뒤에 뼈대를 세울 수 있어요.

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

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

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

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

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

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

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

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

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

실무자는 규칙을 다루는 대목에서 제일 뜨끔할 겁니다.

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

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

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

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

rari는 실행 루프에 네 가지를 넣습니다. 증거, 재시도 상한, 예산, 에스컬레이션.

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

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

예산도 상한입니다. 에이전트가 토큰과 비용을 정해둔 선 넘게 쓰면 거기서 끊습니다.

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

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

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

rari는 구조를 셋으로 나누자고 제안합니다. 뇌와 손과 기록. 판단, 실행, 기록을 섞지 말라는 뜻이에요.

rari는 기록용으로 체인지 리싯(change receipt)을 제안합니다. 런 하나가 끝날 때마다 영수증 한 장을 남깁니다.

교본에 실린 예시는 이렇습니다. 테스트는 42/0입니다. 재시도는 2회였어요. 비용은 3.84달러입니다. 결과물은 PR 1842번에 올라갔습니다.

rari는 영수증 한 줄에 이걸 다 담습니다. 무엇을 검증했는지, 몇 번 헛돌았는지, 얼마를 태웠는지, 결과물을 어디에 올렸는지. 이 칸들이 비어 있는 에이전트는 무슨 일을 했는지 아무도 모르는 에이전트입니다.

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

남는 생각

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

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

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

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

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

저는 프롬프트를 다듬는 시간보다 체크를 박는 시간을 오래 남는 투자로 봅니다. 하네스 엔지니어링은 지시 자체보다 지시를 실행하는 조건을 고칩니다. 한 번 고쳐놓은 조건은 다음 런에서도, 다음 모델에서도 그대로 쓸 수 있습니다.

---