하네스 엔지니어링 — 모델을 감싸고, 그 위에 또 감싸는 일
하네스는 한 겹이 아니다. 모델을 감싸면 에이전트가 되고, 그 에이전트를 또 감싸면 내 목적에 맞는 시스템이 된다. 양파처럼 중첩되는 하네스 구조와, 왜 요즘 Claude 위에 하네스를 또 얹는지를 그림 한 장으로 풉니다.
요즘 AI 에이전트 이야기에서 빠지지 않는 말이 하네스(harness) 입니다. 그런데 “하네스 = AI 에이전트”라고 생각하면 금방 막히는 데가 있습니다. 이미 에이전트인 Claude Code 위에, 사람들이 또 무언가를 얹어 쓰기 때문입니다. 하네스의 진짜 핵심은 한 겹이 아니라 겹친다는 데 있습니다.
1. 한 문장으로
하네스 = 안에 든 것을, 실제 일에 묶어 돌아가게 만드는 바깥 실행 골격. 여기서 “안에 든 것”은 모델일 수도, 이미 하네스인 에이전트일 수도 있습니다. 그래서 하네스는 겹겹이 쌓입니다.
“하네스”는 원래 말이나 낙하산을 몸에 묶는 마구·결박장치입니다. 소프트웨어에선 “핵심 부품을 감싸 실제로 동작하게 붙드는 골격”이라는 뜻으로 쓰죠(test harness처럼). 중요한 건 무엇을 감싸느냐가 고정이 아니라는 점입니다.
2. 큰 그림 — 하네스는 양파처럼 겹친다
위 그림이 그 구조입니다. 안쪽부터 바깥으로 한 겹씩 읽어봅시다.
3. 세 겹 읽기
- ① 모델 — 사실 한 가지만 합니다: “다음 토큰”을 뱉는 것. 파일을 읽지도, 명령을 실행하지도, 기억하지도 못합니다. 혼자선 아무 일도 못 하는 엔진입니다.
- ② 에이전트 하네스 — 그 모델을 감싸 도구를 쥐여주고, 컨텍스트를 관리하고, 루프를 돌리고, 결과를 검증합니다. 비로소 “일하는 에이전트”가 됩니다. Claude Code, Codex CLI가 바로 이 겹입니다.
- ③ 바깥 하네스 — 그런데 ②도 결국 “요청을 주면 결과를 내놓는 한 덩어리”입니다. 그러면 그걸 또 감쌀 수 있습니다. 내 목적에 맞게 절차를 고정하고, 반복시키고, 한 번 더 검증하고, 여러 개를 한꺼번에 부리는 층 — 이게 요즘 사람들이 “Claude에 더 얹는” 부분입니다.
핵심은 세 겹이 다 똑같은 모양이라는 점입니다. “안의 것을 감싸 일하게 만든다”가 반복됩니다.
4. 왜 또 감싸나 — 하네스는 재귀한다
각 겹은 자기 안쪽 전체를 “한 번에 부를 수 있는 한 칸”으로 취급합니다. ②가 모델을 한 칸으로 보고 감쌌듯, ③은 ②(에이전트 전체)를 한 칸으로 보고 감쌉니다. 똑같은 패턴이라 원하는 만큼 더 바깥으로 쌓을 수 있습니다(④ 멀티 에이전트 오케스트레이터, headless 파이프라인, CI·스케줄러…).
겹을 나누는 이유는 역할이 다르기 때문입니다.
- 안쪽일수록 — 범용적 유능함. 모델은 일반 지능, 에이전트 하네스는 “웬만한 작업을 알아서”.
- 바깥일수록 — 내 목적에 맞춘 제약·반복·검증·규모·신뢰성. “이 절차로만, 매일, 결과를 한 번 더 확인해서, 100건을 한꺼번에.”
범용 유능함과 내 목적은 층이 다르기 때문에, 한 겹에 다 욱여넣지 않고 나눠서 감쌉니다.
5. “요즘 Claude에 하네스를 또 얹는다”가 바로 이것
Claude Code는 이미 ② 겹(하네스)입니다. 그대로도 쓰지만, 그 위에 ③ 겹을 두르는 방법이 잘 갖춰져 있습니다.
| 바깥 하네스 수단 | 하는 일 |
|---|---|
| 스킬 · 슬래시 커맨드 | 작업 절차를 패키지로 얹기 |
| 훅(hook) | 특정 시점에 모델이 아니라 하네스가 결정적으로 실행하는 자동화 |
| MCP | 바깥에서 도구를 더 꽂아 넣기 |
| 서브에이전트 · 멀티 에이전트 | Claude가 Claude를 부린다(오케스트레이터–워커) |
headless(claude -p) · Agent SDK | Claude Code 전체를 라이브러리·스크립트의 한 단계로 박기 |
| 워크플로 · cron · CI | 반복·스케줄·대규모로 안쪽 하네스를 돌리기 |
예를 들어 “초안 작성 → 도식 생성 → 게시”를 슬래시 커맨드 하나로 묶으면, 그 커맨드가 곧 Claude Code 위에 얹힌 ③ 바깥 하네스입니다. 안쪽(②)은 그대로 두고, 바깥에서 내 작업 흐름만 고정한 겁니다.
6. 그래서 하네스 엔지니어링이 다루는 것
모델을 더 똑똑하게 만드는 건 모델 학습의 일입니다. 하네스 엔지니어링은 어느 겹을 어떻게 감쌀지를 설계하는 일입니다.
- ② 겹 안에서 — 컨텍스트에 무엇을 남기고 무엇을 압축할지, 도구를 어떤 스키마로 줄지, 언제 루프를 멈출지.
- ③ 겹을 새로 두를 때 — 어떤 절차를 고정할지, 어디서 사람 확인을 받을지, 실패를 어떻게 잡아 되돌릴지, 여러 에이전트를 어떻게 나눠 맡길지.
같은 모델·같은 Claude Code라도, 바깥 겹을 잘 두르면 복잡하고 반복적인 일을 신뢰성 있게 끝까지 해냅니다.
7. 한 줄 요약
하네스는 한 겹이 아니다. 모델을 감싸면 에이전트가 되고, 그 에이전트를 또 감싸면 내 목적에 맞는 시스템이 된다. 어느 겹을 어떻게 감쌀지 정하는 일 — 그게 하네스 엔지니어링이다.