1줄 정의

LLM 주변을 감싸는 틀. 도구·루프·권한·컨텍스트 관리를 묶어 ‘에이전트를 성립시키는 뼈대’.

전체 시스템에서 맡는 역할

“하네스” 는 말 장구나 안전 벨트를 가리키는 영어로, 그 뉘앙스가 그대로 기술 용어로 옮겨왔다. 모델 본체를 고정해서 날뛰지 않게 하면서 의도한 방향으로 작용시키기 위한 장구 라는 이미지다.

LLM 혼자서는 그저 질문에 답하는 기계에 그친다. 거기에 다음 층을 더하면 agent 가 된다.

• Tools: 파일 조작, API 호출, 검색, 명령 실행
• Loop: 판단 → 실행 → 결과 읽기 → 다시 판단, 의 제어
• Permissions: 어디까지 허가할지, 어디서 사람 확인을 끼울지
• Context management: 과거 대화나 결과를 어떻게 기억시키고 어떻게 잊게 할지
• Error handling: 도구 실패 시 재시도·강등·에스컬레이션

이 일습이 하네스. Claude Code 의 Claude Agent SDK 가 대표 예로, 하네스 부분을 분리 제공한다.

LLM 과 하네스의 관계를 집과 건자재로 비유하면, LLM 이 목재, 하네스가 기둥·벽·지붕의 조립 방식이다. 같은 목재라도 설계에 따라 전혀 다른 집이 된다. 그래서 “어느 모델을 쓸까” 보다 “어떤 하네스를 짜느냐” 가 제품 품질을 크게 좌우한다 — 이게 최근 agent 엔지니어링의 핵심 깨달음이다.

흔한 오해

• 오해 1: 하네스 = 프롬프트 템플릿, 으로 좁게 여겨지기 쉽다.

– 실제로 하네스는 프롬프트보다 넓은 개념. 프롬프트 설계는 하네스의 한 요소지만 도구 구현, 루프 제어, 권한 정책 등을 포함한다. 프롬프트만 갈고 닦아도 하네스는 안 된다.

• 오해 2: 하네스 설계는 한 번 하면 끝이다, 라고 여겨지기 쉽다.

– 실제로는 모델 거동·유스케이스·실패 패턴을 보며 지속적으로 조정하는 운영물. 초기 릴리스 뒤의 “하네스 개선” 이 제품의 진짜 승부가 된다.

• 오해 3: 강한 모델이면 하네스는 필요 없다, 라고 기대되기 쉽다.

– 실제로는 모델이 강해질수록 도구 호출 선택지가 늘어나고, 하네스에서 뭘 허용하고 뭘 제한할지의 설계가 오히려 중요해진다. “똑똑하니까 풀어둬도 된다” 는 운영 사고의 전형.

이 용어가 중요한 이유

하네스를 설계 단위로 다룰 수 있게 되면 자사 제품에 AI 를 넣을 때 판단이 한 단계 깊어진다. 이게 T1 으로서의 가치.

설계 회의에서 나오는 질문의 질이 달라진다.

• 이 하네스는 어떤 유스케이스에 최적화되어 있는가
• 도구 호출의 입자는 어디서 끊었는가
• 위험 조작 확인 다이얼로그는 어느 타이밍에 띄울 것인가
• 서브에이전트와의 경계는 어디인가
• Skills 나 Commands 같은 사용자 확장 지점을 둘 것인가

이런 것에 구체적인 답을 가질 수 있는 팀은 AI 제품의 차별화를 설계 단계에서 만들 수 있다. 하네스라는 개념이 없는 팀은 “ChatGPT Wrapper” 를 벗어나지 못한다.

Claude Code 초기에 Boris Cherny 등의 발언에 있듯이, “prompt engineering 에서 harness engineering 으로” 라는 구호가 퍼지고 있다. 이 이행을 자기 안에서 해냈느냐가 앞으로의 개발자 실력을 가른다.

이 용어가 나오는 기사

• 하네스 엔지니어링, Claude Code, 에이전트 설계 관련 기사 다수

다음에 읽을 용어 3개

• agent — 하네스가 감싸는 대상.
• Claude Code — 하네스의 대표 구현.
• tool use — 하네스의 핵심 기능.