하네스(harness) — 모델을 감싸 실제로 일하게 만드는 실행 프로그램¶
한 줄 요약: LLM은 "텍스트 in → 텍스트 out" 함수일 뿐, 스스로 파일을 읽거나 명령을 돌리거나 과거를 기억하지 못한다. 이 모델을 감싸 도구 실행·컨텍스트 조립·권한·상태 저장을 담당하며 실제 컴퓨터 위에서 행동하는 에이전트로 바꿔주는 실행 프로그램이 하네스다. CLI형 코딩 에이전트에서는 그 CLI 프로그램 자체가 하네스. 모델 = 두뇌, 하네스 = 손발·기억.
어원 — 말에 채우는 마구(馬具)¶
harness 는 본래 말에 채우는 마구다. 날것의 힘(말 = 모델)을 묶어 수레를 끌게 만드는 장치. LLM 분야에선 모델을 감싸 도구·루프·상태를 붙이는 이 계층을 agent harness 또는 scaffold(비계) 라 부른다.
모델 vs 하네스 — 두뇌 vs 몸¶
LLM(모델)은 본질적으로 텍스트 함수 하나다. 그 자체로는:
| 모델이 못 하는 것 | 그래서 하네스가 한다 |
|---|---|
| 파일 읽기 · 명령 실행 (손발 없음) | 셸 · 파일 · 네트워크 접근 |
| 과거 기억 (매 호출 독립, 무상태) | 대화 이력 · 메모리를 매번 다시 먹여줌 |
| 부작용 발생 | 도구 호출(텍스트)을 실제 행위로 변환 |
| 자기 출력 강제 | 권한 · 훅으로 결정론적 통제 |
핵심: 모델이 "이걸 하겠다"고 텍스트로 말하면, 실제로 실행하는 건 전부 하네스다.
하네스가 하는 일 — 에이전트 루프¶
flowchart LR
U[사용자] -->|① 입력| H[하네스<br/>코딩 에이전트 CLI]
H -->|② 컨텍스트 + 프롬프트| M[모델 LLM<br/>무상태 추론]
M -->|③ 도구 호출 텍스트| H
H <-->|④ 실제 실행| SYS[(시스템<br/>파일 · 셸 · 네트워크 · MCP)]
H -->|⑤ 결과| U- 에이전트 루프 — 입력 → 모델 호출 → 모델이 낸 도구 호출 실행 → 결과를 다시 모델에 먹임 → 반복. 이 루프 자체가 하네스다.
- 컨텍스트 조립 — 시스템 프롬프트 · 프로젝트 규칙 파일 · 메모리 · 대화 이력 · (길면) 요약을 모델 입력에 조립. 모델이 "기억"하는 것처럼 보이는 건 하네스가 매번 과거를 다시 넣기 때문.
- 도구 실행 — 셸 · 파일 · 검색 · MCP 서버 · 서브에이전트를 실제로 구동하고 출력을 회수.
- 권한 · 안전 게이트 — 위험한 동작 전 사용자 승인, 허용/거부 모드 관리.
- 훅(hooks) —
SessionStart·UserPromptSubmit·SessionEnd등 이벤트에 셸 명령 실행 (→ 훅 노트). - 상태 저장 — 세션 트랜스크립트 · 메모리 파일 기록.
왜 이 구분이 실전에서 중요한가¶
1) "결정론(하드) vs 모델 판단(소프트)" 경계가 여기서 갈린다¶
- 하드 — 권한 게이트 · 훅 · 컨텍스트 주입은 하네스가 결정론적으로 실행 → 모델이 무시·변경 불가.
- 소프트 — 프로젝트 규칙 파일(예:
CLAUDE.md) · 메모리는 모델이 읽고 따를지 판단 → 확률적. - 어떤 동작을 "반드시" 강제하고 싶으면 소프트(모델 설득)가 아니라 하드(하네스 훅)로 박아야 한다. (→ 훅 노트)
2) 하네스 프로세스가 죽으면 하네스가 하던 모든 게 멈춘다¶
- 자동화(예: 종료 시 자동 커밋)를 "하는 주체"는 모델이 아니라 하네스 프로세스다.
- 크래시 · 정전 · 강제 종료로 프로세스가 죽으면 그 자동화도 안 돈다 → 재난 백업을 종료 훅에 의존하면 안 되는 이유.
같은 모델, 다른 하네스¶
모델이 같아도 하네스가 다르면 할 수 있는 일이 달라진다. 같은 LLM을 감싸는 하네스는 여럿:
- CLI 에이전트 — 셸 · 파일 · git 풀 액세스
- 데스크톱 / 웹 앱 — 도구 · 제약이 다름
- IDE 확장
- Agent SDK — 직접 하네스를 만들어 원하는 도구 · 루프 · 제약으로 모델을 묶음
→ "이 AI가 뭘 할 수 있냐"는 사실 "어떤 하네스가 그 모델을 감싸고 있냐" 의 문제다.
발표 시 한 줄¶
"LLM은 무상태 텍스트 함수라 스스로는 아무것도 못 합니다. 도구 실행·컨텍스트 조립·권한·상태를 붙여 실제로 행동하는 에이전트로 만드는 실행 계층이 하네스고, 모델이 두뇌라면 하네스가 손발과 기억입니다. 그래서 '강제'가 필요한 동작은 모델 설득(소프트)이 아니라 하네스(하드)에 박아야 합니다."
FAQ¶
Q: 모델이 직접 파일을 읽는 거 아니었나? → 아니다. 모델은 "이 파일 읽어줘"라는 도구 호출을 텍스트로 낼 뿐, 실제 읽기는 하네스가 하고 그 내용을 다시 모델 입력에 넣어준다.
Q: 그럼 모델이 기억하는 건 어떻게? → 모델은 무상태다. 매 호출마다 하네스가 과거 대화·메모리를 통째로 다시 먹인다. "기억"은 모델 능력이 아니라 하네스의 컨텍스트 관리.
Q: 프롬프트로 "반드시 X 해라" 박으면 강제되나? → 그건 소프트(모델 판단)다. 대체로 따르지만 확률적이라 샐 수 있다. 진짜 강제는 하네스의 훅/권한 같은 하드 메커니즘이 필요.