클로드 코드(Claude Code)를 어느 정도 익히고 나면 문서나 커뮤니티에서 자꾸 마주치는 단어가 있습니다. 바로 하네스(harness)입니다. “이 동작은 클로드가 아니라 하네스가 한다”, “하네스 설정을 바꾸세요” 같은 표현이 자주 등장하는데, 정작 그 정의를 따로 설명해 주는 곳은 많지 않습니다. 어렵게 들리지만 개념만 한 번 잡아 두시면 클로드 코드의 거의 모든 동작이 자연스럽게 이해되기 시작합니다. 이 글에서는 하네스가 무엇인지, 모델과 어떻게 다른지, 어디에 영향을 주는지를 한 번에 정리해 드립니다.
목차
하네스, 한 줄로 정의하면
하네스는 모델 자체가 아닌, 모델을 둘러싸고 실제로 일을 하게 만드는 모든 코드와 설정입니다. 클로드 코드의 경우, 우리가 매일 쓰는 그 CLI 자체가 하네스에 해당합니다. 모델(Claude)이 답을 만들 수 있게 도와주는 입력 정리, 도구 호출, 결과 해석, 권한 검사, 세션 저장 같은 일들이 전부 하네스에서 일어납니다.
업계에서 자주 쓰는 공식이 있습니다.
에이전트 = 모델 + 하네스
모델은 “지능”이고, 하네스는 그 지능이 현실 세계에서 무언가를 할 수 있게 만드는 “몸체”라고 보시면 됩니다. 모델이 아무리 똑똑해도 하네스가 부실하면 결과는 별로고, 반대로 하네스가 잘 짜여 있으면 같은 모델이 훨씬 더 강력해집니다.
모델과 하네스, 어떻게 다른가
둘은 분명히 다른 층위입니다. 헷갈리실 때 다음 비교를 떠올리시면 정리가 쉽습니다.
| 구분 | 모델 (Claude) | 하네스 (Claude Code) |
|---|---|---|
| 역할 | 읽고 추론하고 답을 생성 | 모델이 일하도록 환경을 구성 |
| 비유 | 엔진 | 차체·핸들·브레이크 |
| 예시 | Opus, Sonnet, Haiku | CLI, settings.json, hooks, 도구 |
| 업데이트 단위 | 모델 버전 (예: 4.6 → 4.7) | CLI 릴리스, 설정 파일 변경 |
| 개선의 한계 | “이론적 천장”을 결정 | “실제 활용도”를 결정 |
“어떤 AI가 더 똑똑하냐”는 질문은 보통 모델 이야기입니다. 반면 “이 도구가 실제로 일을 잘하냐”는 질문은 거의 대부분 하네스 이야기입니다. 둘 중 어느 쪽이 부족한지에 따라 개선 방향이 완전히 달라집니다.
하네스가 실제로 하는 일 6가지
클로드 코드 하네스가 매 세션에서 하는 일은 생각보다 많습니다. 대표적인 것들만 정리해 드립니다.
- 도구 접근 제공: 모델이 직접 셸을 두드리거나 파일을 읽지 못하므로, 하네스가 bash·파일 편집·웹 검색 같은 도구를 대신 호출하고 결과를 모델에게 돌려줍니다.
- 컨텍스트 관리: 세션 동안 읽은 파일, 실행한 명령, 에러 메시지를 누적해 모델 입력에 쌓아 줍니다. “기억”처럼 보이는 것이 사실 이 누적의 결과입니다.
- 권한·안전 검사: 어떤 명령은 허용, 어떤 명령은 차단, 어떤 명령은 사용자 확인을 받도록 사이에서 거릅니다. 이 규칙이 들어가는 곳이
settings.json입니다. - 세션 관리: 대화를 저장하고, 끊어졌을 때 복원하고, 분기시키는 일을 처리합니다.
- 오케스트레이션: 서브에이전트를 띄우고, 어떤 모델로 어떤 작업을 보낼지 라우팅합니다.
- 도구 발견(lazy load): 모든 도구의 정의를 처음부터 모델에게 보여 주지 않고, 필요할 때만 꺼내 줍니다. 컨텍스트 절약을 위한 핵심 트릭입니다.
“이건 모델이 한 게 아니라 하네스가 한 겁니다”의 실체
문서나 채팅에서 자주 보이는 이 표현은 단순한 책임 분담의 문제가 아닙니다. 모델은 약속할 수 없지만 하네스는 강제할 수 있는 일이 따로 있다는 뜻입니다.
예를 들어 “내가 명령할 때마다 자동으로 lint를 돌려 줘”는 모델 한 명에게 부탁한다고 해서 매번 지켜진다는 보장이 없습니다. 모델이 깜빡할 수 있고, 컨텍스트가 길어지면 잊혀집니다. 그래서 클로드 코드는 이런 “반드시 매번 실행”되는 동작을 모델이 아니라 하네스의 hook으로 처리합니다.
대표적인 hook 예시는 다음과 같습니다.
SessionStart: 세션 시작 시 자동 실행PreToolUse: 모델이 도구를 호출하기 직전PostToolUse: 도구 실행 결과가 나온 직후Stop: 모델이 답변을 마쳤을 때
이 hook은 .claude/settings.json에 정의해 두면 클로드 코드(=하네스)가 시점마다 알아서 실행합니다. 모델의 의지에 기대지 않고 동작이 보장됩니다. 그래서 “자동화·검증·강제 규칙”은 하네스 영역, “추론·생성·판단”은 모델 영역이라는 큰 분담선이 그어집니다.
하네스가 좋아지면 같은 모델이 더 강해진다
같은 클로드 모델을 써도 하네스에 따라 결과가 크게 달라집니다. 하네스가 잘 갖춰져 있으면 다음과 같은 일이 가능해집니다.
- 긴 작업을 끊김 없이 이어 가는 컨텍스트 누적
- 위험한 명령을 자동으로 막는 권한 정책
- 특정 도구만 골라 쓰게 강제하는 규칙
- 매 단계마다 자동으로 lint·테스트 실행
- 여러 서브에이전트로 작업을 분산
같은 모델로도 결과 품질이 달라지는 진짜 이유는 거의 항상 하네스 설계에 있습니다. 그래서 클로드 코드를 잘 쓰는 사람과 그렇지 않은 사람의 격차도, 모델 선택이 아니라 settings.json과 hook을 얼마나 본인 워크플로우에 맞춰 설정했느냐에서 갈립니다.
내가 직접 손댈 수 있는 하네스 부분
좋은 소식은, 클로드 코드 하네스의 거의 모든 영역을 사용자가 직접 조정할 수 있다는 점입니다.
- settings.json: 권한, 환경 변수, 모델 오버라이드, hook 정의
- CLAUDE.md: 프로젝트·사용자별 컨텍스트 지침
- hooks: SessionStart·PreToolUse·PostToolUse·Stop 시점에 자동 실행할 셸·HTTP·LLM 호출
- MCP 서버: 외부 도구·데이터로 가는 통로 추가
- 스킬·플러그인: 특정 작업 절차와 도구 패키지 추가
- 서브에이전트: 특정 역할 전문 에이전트 분리
이 항목들이 모두 하네스의 일부입니다. 하나씩 손에 익히실 때마다 같은 모델로도 더 많은 일이 가능해집니다.
자주 묻는 질문
“하네스”가 한국어로 적절한 번역이 있나요?
업계에서는 그대로 “하네스”로 쓰는 경우가 가장 많습니다. 굳이 번역하시면 “실행 환경”, “스캐폴딩”, “에이전트 골격” 정도가 가깝습니다. 직역인 “마구”는 의미 전달이 어려워 거의 쓰이지 않습니다.
그러면 ChatGPT나 Cursor도 하네스가 있나요?
네. 어떤 LLM 기반 도구든 모델 위에는 하네스가 있습니다. ChatGPT의 웹 인터페이스, Cursor의 IDE 통합, GitHub Copilot의 자동완성 모두 각자의 하네스입니다. 같은 모델을 써도 도구마다 경험이 다른 이유가 여기에 있습니다.
모델이 좋아지면 하네스는 안 만들어도 되나요?
오히려 반대입니다. 모델이 좋아질수록 하네스가 할 수 있는 일이 많아져 더 중요해집니다. 도구·권한·세션 설계가 잘 되어 있을수록 좋은 모델의 잠재력이 끝까지 발휘됩니다.
하네스 설정을 잘못 건드리면 위험한가요?
settings.json 같은 파일은 JSON 문법 오류 한 줄로 클로드 코드 실행이 막힐 수 있습니다. 그러나 파일을 되돌리면 즉시 복구되므로 두려워하실 필요는 없습니다. 변경 전에는 백업을 떠 두시고, 한 번에 한 항목만 바꾸시는 것이 안전합니다.
정리
하네스는 어렵게 생각하지 않으셔도 됩니다. 모델을 둘러싼 실행 환경이라는 한 줄만 기억하시면 충분합니다. 클로드 코드에서 자동화·권한·세션·도구·hook과 관련된 거의 모든 동작이 하네스의 영역입니다. 모델 자체는 본인이 바꿀 수 없지만 하네스는 settings.json·hook·MCP·CLAUDE.md를 통해 본인 손으로 조정할 수 있습니다. 같은 모델로 더 좋은 결과를 내고 싶으시다면, 그 차이를 만드는 곳이 바로 하네스입니다.