같은 모델을 쓰는데 결과물 품질이 팀마다 다릅니다. 한쪽은 AI가 리팩토링을 통째로 해내고, 다른 쪽은 간단한 수정도 사람이 다 고쳐 씁니다.
차이는 프롬프트 문구가 아닙니다. 모델을 감싸고 있는 실행 환경, 즉 하네스(harness)의 차이예요.
하네스 엔지니어링을 한 문장으로 정리하면, 모델이 도구를 쓰고 결과를 검증받으며 일하는 루프 전체를 설계하는 작업입니다. 프롬프트 엔지니어링이 “말을 잘 거는 법”이라면, 하네스 엔지니어링은 “일 잘하는 작업장을 차려주는 법”이죠.
이 글에서는 하네스가 정확히 무엇인지, 구성 요소는 뭔지, 좋은 하네스의 판단 기준까지 정리합니다.
핵심 요약부터 보고 갈게요.
- 하네스는 모델을 감싼 실행 루프입니다. 도구, 권한, 컨텍스트 관리, 피드백이 구성 요소예요
- 에이전트의 성능은 모델 지능 × 하네스 품질로 결정됩니다
- 좋은 하네스의 핵심은 모델이 자기 결과를 스스로 확인할 수 있는 피드백 루프입니다
- Claude Code, Cursor 같은 코딩 에이전트의 실체가 바로 하네스입니다
하네스란 정확히 무엇인가
원래 하네스는 말에 채우는 마구(馬具)를 뜻합니다. 말의 힘 자체를 키우는 게 아니라, 그 힘을 수레 끌기라는 유용한 일로 전환하는 장치죠.
테스트 하네스라는 용어도 같은 계보입니다.
LLM 하네스도 마찬가지입니다. 모델(지능)은 그대로 두고, 그 지능이 실제 작업으로 이어지도록 감싸는 소프트웨어 전부를 가리켜요.
구체적으로는 이런 것들입니다.
- 도구 계층: 모델이 호출할 수 있는 함수들. 파일 읽기·쓰기, 셸 실행, 검색
- 권한 계층: 뭘 물어보고 실행할지, 뭘 자동 승인할지에 대한 정책
- 컨텍스트 계층: 무엇을 모델에게 보여주고 무엇을 숨길지, 언제 요약할지
- 루프 계층: 도구 결과를 받아 다음 행동으로 잇는 반복 구조와 종료 조건
Claude Code나 Cursor를 “AI 코딩 도구”라고 부르지만, 모델 자체는 API 뒤에 있는 같은 모델입니다. 제품의 실체는 하네스예요.
성능 = 모델 × 하네스
같은 모델로 벤치마크 점수가 크게 갈리는 사례는 이미 흔합니다. 에이전트 벤치마크 리더보드를 보면 동일 모델인데 하네스에 따라 성공률이 수십 퍼센트포인트씩 차이 나요.
이유는 단순합니다. 에이전트 작업은 수십 번의 도구 호출이 이어지는 연쇄이고, 하네스는 그 모든 단계에 개입하기 때문입니다.
| 하네스가 나쁠 때 | 하네스가 좋을 때 |
|---|---|
| 도구 결과 전체를 컨텍스트에 붓는다 | 필요한 부분만 요약해 전달한다 |
| 실패해도 같은 시도를 반복한다 | 에러 메시지가 다음 시도의 입력이 된다 |
| 작업 완료를 모델의 주장으로 판정한다 | 테스트·빌드로 검증하고 통과해야 종료한다 |
모델은 확률적으로 실수합니다. 하네스의 역할은 실수를 없애는 게 아니라, 실수가 검증 단계에서 걸러지고 스스로 고쳐지게 만드는 겁니다.
좋은 하네스의 세 가지 조건
실무 관점에서 하네스 품질을 가르는 조건은 세 가지로 압축됩니다.
첫째, 검증 가능한 피드백 루프. 모델이 코드를 고쳤으면 테스트를 돌려 결과를 보여줘야 합니다.
사람도 컴파일 안 해보고 짠 코드는 못 믿는 것처럼, 피드백 없는 에이전트는 자기 확신만 쌓아요. 에이전트 도입 효과가 가장 큰 곳이 테스트가 잘 갖춰진 코드베이스인 이유입니다.
둘째, 컨텍스트 예산 관리. 컨텍스트 윈도우는 유한한데 도구 결과는 무한정 쏟아집니다.
긴 출력을 자르고, 오래된 내용을 요약하고, 탐색 작업을 서브에이전트로 격리하는 전략이 하네스의 몫이에요.
셋째, 안전한 실패 경로. 권한 정책과 샌드박스로 “실수해도 복구 가능한 범위”를 정의해야 합니다.
되돌릴 수 있는 작업은 자동 승인하고, 파괴적인 작업만 사람에게 묻는 식으로요.
프롬프트 엔지니어링과의 관계
프롬프트 엔지니어링이 쓸모없어졌다는 얘기가 아닙니다. 층이 다를 뿐이에요.
프롬프트는 한 번의 요청을 최적화합니다. 하네스는 요청 수십 개가 이어지는 루프를 최적화하고요. 시스템 프롬프트 작성은 하네스 설계의 부분집합이 됩니다.
관심의 무게중심이 “무엇을 말할까”에서 “어떤 환경을 줄까”로 옮겨간 겁니다. 모델이 좋아질수록 이 경향은 강해져요. 지시는 짧아져도 되지만, 도구와 검증 루프의 가치는 오히려 커지니까요.
마무리
에이전트 결과물이 아쉽다면 프롬프트를 다듬기 전에 하네스를 점검해 보세요. 모델이 결과를 확인할 수단이 있는지, 컨텍스트가 잡동사니로 차 있지는 않은지, 실패가 다음 시도로 이어지는지.
다음 글에서는 이 중 컨텍스트 계층만 깊게 파는 컨텍스트 엔지니어링을 다루겠습니다.