01-개념

01. 개념 — 하네스(Harness)는 모델과 세계 사이의 모든 것

가장 짧은 정의

WaveSpeedAI의 분석은 하네스를 이렇게 정의한다.

“everything between the language model and the real world”

의역 — 언어 모델과 현실 사이에 있는 모든 것.

즉 Claude 모델이 직접 파일을 읽거나 셸을 실행하는 것이 아니다. 모델은 텍스트(특히 tool_use 블록)를 뱉을 뿐이고, 그 텍스트를 받아 권한을 검사하고 실제 시스템을 건드리는 코드 계층이 따로 존재한다. 이 코드 계층이 하네스다.

Anthropic 공식 문서도 같은 표현을 쓴다.

“Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.”

의역 — Claude Code는 Claude를 둘러싼 에이전트 하네스다. 도구, 컨텍스트 관리, 실행 환경을 제공해 언어 모델을 실제로 일하는 코딩 에이전트로 바꿔 준다.

왜 “하네스”라는 이름인가

말(馬)에 채우는 마구(馬具, harness)가 어원이다. 말의 힘은 그대로지만 마구가 어떻게 채워지느냐에 따라 그 힘이 쟁기를 끄는 데 쓰일 수도, 마차를 끄는 데 쓰일 수도, 아무것도 못 하고 날뛰기만 할 수도 있다. LLM도 똑같다. 모델 가중치는 같아도 하네스가 다르면 결과물이 완전히 달라진다.

모델·도구·지시문(Model/Tools/Instructions) 3요소

Cline의 Nick Baumann은 에이전트의 정의에서 합의된 핵심을 이렇게 정리한다.

“agents require three fundamental components: model, tools, and instructions.”

의역 — 에이전트는 세 가지 근본 요소가 필요하다. 모델, 도구, 지시문.

이 셋을 분리해 생각하는 것이 하네스 사고의 출발점이다.

요소	무엇	Claude Code에서의 예
Model (모델)	추론과 결정을 담당하는 LLM 가중치	Claude Sonnet/Opus/Haiku
Tools (도구)	모델이 호출할 수 있는 행동 단위	Read, Edit, Bash, Grep, Glob, WebFetch, MCP 서버
Instructions (지시문)	모델이 항상 보는 컨텍스트	시스템 프롬프트, CLAUDE.md, AGENTS.md, hooks 출력

ChatGPT의 기본 채팅이 “에이전트가 아니다”라고 말할 수 있는 이유도 같다. 모델은 같은 GPT여도 도구·지시문·루프가 결합돼 있지 않으면 “사용자 요청 → 답변” 한 번으로 끝난다.

한 줄로 다시

하네스 = (모델 ⊕ 도구 ⊕ 지시문 ⊕ 루프 ⊕ 권한 ⊕ 컨텍스트 관리)를 묶은 실행 계층.

이 챕터가 끝나면 “Claude Code는 그냥 Claude를 CLI에 띄운 것 아닌가?”라는 오해는 사라져야 한다. CLI에 떠 있는 것은 모델이 아니라 하네스다.