하네스
한 줄 정의
모델을 감싸서 실제로 일하게 만드는 바깥 껍데기 코드
1. 비유로 이해하기
하네스(harness)는 원래 말에게 씌우는 마구(馬具)를 가리키는 말이다.
말은 힘이 아주 세다. 그런데 말만 있으면 들판을 뛰어다닐 뿐이다. 굴레와 고삐를 채우고 안장을 얹고 마차를 연결해야 비로소 짐을 싣고 원하는 곳으로 갈 수 있는 상태가 된다.
- 말 = AI 모델. 힘의 원천
- 마구(하네스) = 그 힘을 붙들어 방향을 잡아주는 장비
- 짐을 나르는 마차 = 우리가 쓰는 AI 에이전트
말이 아무리 좋아도 마구가 엉망이면 마차는 제대로 굴러가지 않는다. 반대로 마구가 훌륭하면 평범한 말로도 꽤 많은 짐을 나를 수 있다. 하네스가 중요한 이유는 여기서 끝난다.
2. 왜 필요한가
AI 모델이 실제로 하는 일은 하나뿐이다. 글자를 이어서 내놓는 것.
모델은 파일을 열지 못한다. 명령어를 실행하지 못한다. 어제 나눈 대화를 기억하지도 못한다. 모델에게 “이 파일 고쳐줘”라고 하면, 모델이 할 수 있는 최선은 “이 파일을 고치려면 이렇게 하면 됩니다”라는 글자를 내놓는 것까지다.
그 글자를 받아서 실제로 파일을 여닫고, 결과를 다시 모델에게 보여주고, 틀렸으면 다시 시키는 주변 코드 전체가 하네스다.
| 하네스가 하는 일 | 설명 |
|---|---|
| 루프 돌리기 | “생각 → 도구 실행 → 결과 확인 → 다시 생각”을 반복 |
| 도구 연결 | 어떤 도구를 쥐여줄지 정하고, 그 사용법을 모델에게 전달 |
| 도구 실행 | 모델이 도구를 부르면 실제로 실행하고 결과를 되돌려줌 |
| 컨텍스트 관리 | 대화가 길어지면 요약하거나 잘라냄 |
| 에러 처리 | 실패하면 다시 시도하거나 방향을 바꿈 |
| 안전장치 | 위험한 명령은 사람에게 확인받음 |
| 시스템 프롬프트 | “너는 이런 역할이다”라는 기본 지시 |
가장 단순한 하네스의 뼈대는 이 정도다.
def agent_harness(user_input, tools, max_steps=10):
messages = [{"role": "user", "content": user_input}]
for step in range(max_steps): # ← 루프 (마구의 고삐)
response = call_model(messages, tools) # ① 모델에게 물어본다
messages.append(response)
if response.stop_reason != "tool_use": # ② 도구를 안 쓰면 끝
return response
for call in response.tool_calls: # ③ 도구를 실제로 실행
try:
result = run_tool(call.name, call.input)
except Exception as e:
result = f"에러 발생: {e}" # ④ 에러도 결과로 전달
messages.append({"role": "user", "content": result})
return "최대 단계 도달" # ⑤ 무한루프 방지
짧지만 여기에 루프, 도구 실행, 에러 처리, 종료 조건이 전부 들어 있다. 제품으로 나온 하네스는 여기에 컨텍스트 압축, 권한 확인, 기록 저장이 붙어서 훨씬 커진다.
여기서 중요한 사실 하나. Claude Code, Cursor, Aider 같은 도구는 전부 하네스다. 안에 들어 있는 모델이 같아도 하네스가 다르면 결과의 품질이 크게 달라진다. “어떤 모델을 쓰느냐”만큼 “어떤 껍데기를 쓰느냐”가 중요하다는 뜻이다.
3. 어디서 만났나
7회차에서 만났다. 그때까지 나는 AI에게 “이런 화면 만들어 줘”라고 시켜 왔는데, 그 도구가 정확히 무엇인지는 몰랐다. 수업에서 에이전트 = 모델 + 하네스라는 구조를 처음 그림으로 봤다.
7회차 — 에이전트, MCP, 스킬 — 범용 AI를 내 전용 조수로
4. 헷갈리는 개념
| 이 용어 | 비슷하지만 다른 것 | 차이 |
|---|---|---|
| 하네스 | 모델 | 모델은 판단만 한다. 하네스는 그 판단을 실행한다. 에이전트 = 모델 + 하네스 |
| 하네스 | 프레임워크 | 프레임워크는 하네스를 만들 때 쓰는 재료(LangChain 등). 하네스는 그 재료로 조립된 완성품 |
| 하네스 | MCP | MCP는 하네스에 도구를 꽂는 규격. 하네스는 그 꽂힌 도구를 부리는 몸통 |
| 에이전트 하네스 | 평가 하네스 | 같은 단어, 다른 물건. 평가 하네스(Evaluation Harness)는 에이전트를 자동 채점하는 장치다. 문제를 꺼내 주고, 격리된 환경에서 실행시키고, 정답인지 확인해 점수를 낸다. SWE-bench 같은 벤치마크가 이 형태로 배포된다 |
5. 많이들 오해하는 지점
ㄱ. “좋은 모델만 쓰면 된다”
가장 흔한 오해다. 같은 모델을 쓰는 두 도구의 결과가 눈에 띄게 다른 경우가 많은데, 그 차이는 대개 모델이 아니라 하네스에서 나온다. 컨텍스트를 어떻게 관리하는지, 실패했을 때 어떻게 되돌아오는지, 도구를 몇 개 쥐여줬는지가 전부 하네스의 설계다.
ㄴ. “하네스 = 시스템 프롬프트”
“너는 친절한 비서다” 같은 지시문이 하네스의 전부라고 생각하기 쉽다. 시스템 프롬프트는 위 표의 일곱 항목 중 하나일 뿐이다. 프롬프트를 아무리 잘 써도 루프와 도구 실행이 없으면 그건 그냥 챗봇이다.
ㄷ. 등산 장비 하네스와 같은 말이라 헷갈린다
안전벨트도 하네스, 강아지 가슴줄도 하네스, 자동차 전선 뭉치도 와이어 하네스다. 헷갈리는 게 당연한데, 사실 뿌리가 같다. 전부 “흩어진 힘이나 요소를 붙들어 하나로 다스린다”는 뜻이다. 이 감각을 알고 나면 오히려 기억하기 쉬워진다.