ChatGPT나 Claude 같은 AI를 써 보면 똑같은 모델인데도 제품마다 느낌이 다릅니다. 어떤 곳에서는 파일을 읽고 코드를 실행하지만, 다른 곳에서는 텍스트만 돌려줍니다. 이 차이를 만드는 것이 바로 하네스(Harness)입니다.
모델과 하네스의 차이
2026년 AI 엔지니어링 커뮤니티에서는 이런 말이 유행합니다: '당신이 모델이 아니라면, 당신은 하네스다(If you are not the model, you are the harness).' 즉, 모델 주변에 있는 모든 것 — 도구 정의, 컨텍스트 주입 방식, 권한 범위, 반환값 처리 — 이 전부 하네스에 속합니다.
요리사와 주방 비유
모델을 요리사라고 하면, 하네스는 주방 전체입니다. 아무리 실력 좋은 요리사라도 칼이 없고, 냉장고가 잠겨 있고, 레시피 책이 없으면 제대로 된 요리를 낼 수 없습니다. 반대로 주방이 잘 갖춰지면 평범한 요리사도 훌륭한 요리를 냅니다.
하네스의 4대 구성 요소
| 구성 요소 | 역할 | 예시 |
|---|---|---|
| 도구(Tools) | 모델이 실제로 할 수 있는 행동 | 파일 읽기, 코드 실행, API 호출 |
| 컨텍스트(Context) | 모델에게 전달되는 정보 | 시스템 프롬프트, 파일 내용, 이전 기록 |
| 권한(Permissions) | 허용·차단할 행동의 범위 | 쓰기 가능 경로, 외부 URL 허용 여부 |
| 인터페이스(Interface) | 모델과 환경의 연결 방식 | MCP 서버, API, CLI 명령어 |
왜 하네스가 중요한가
2025년 이후 AI 연구자들은 '대부분의 에이전트 실패는 모델 실패가 아니라 컨텍스트 실패'라는 사실을 반복해서 확인했습니다. 모델을 더 좋은 것으로 바꾸기 전에, 하네스를 제대로 설계하는 것이 훨씬 효과적인 개선책인 경우가 많습니다.
- 하네스가 빈약하면 모델이 아무리 뛰어나도 할 수 있는 일이 제한됩니다.
- 하네스가 정보를 과도하게 쏟아부으면 모델이 길을 잃습니다.
- 하네스가 검증 도구를 갖추면 모델이 스스로 실수를 바로잡을 수 있습니다.
Claude Code가 하네스인 이유
Claude Code(Anthropic의 공식 CLI)는 Claude 모델 위에 올라간 하네스의 대표 사례입니다. 파일 읽기/쓰기, 셸 명령 실행, MCP 서버 연결, 서브에이전트 생성 같은 기능이 모두 하네스 레이어에서 처리됩니다. 모델은 '무엇을 할지' 결정하고, 하네스는 '어떻게 실제로 하는지'를 담당합니다.
하네스 설계 체크리스트 프롬프트
아래 에이전트 작업에 필요한 하네스 요소를 설계해 줘.
[작업 설명]
{여기에 작업 내용 작성}
다음 항목을 각각 구체적으로 알려줘:
1. 필요한 도구 (파일 접근, 실행 명령, 외부 API 등)
2. 제공해야 할 컨텍스트 (문서, 코드, 규칙 등)
3. 권한 범위 (허용/차단할 행동)
4. 검증 방법 (작업 성공 여부를 어떻게 확인할지)하네스를 설계할 때는 '모델에게 무엇을 줄 것인가(컨텍스트)'와 '모델이 무엇을 할 수 있는가(도구)'를 구분해서 생각하세요. 이 두 가지를 따로 최적화하면 훨씬 강력한 에이전트를 만들 수 있습니다.
하네스에 너무 많은 도구를 주는 것도 문제입니다. 모델은 관련 없는 도구를 선택하거나 혼동할 수 있습니다. '최소 권한(least privilege)' 원칙을 적용해 꼭 필요한 도구만 제공하세요.