"하네스"란 무엇인가?
TMT솔직히 말씀드리겠습니다. 제가 이 글을 쓰는 건 계속 이걸 설명해야 하는 데 지쳤기 때문이고, 하네스(harness)가 실제로 무엇인지 제대로 설명해 주는 "자료"가 한 군데도 없는 것 같아서입니다.
이 글을 다 읽고 나면 하네스가 무엇이고 어떻게 동작하는지에 대해 알아야 할 모든 것을 알게 되실 겁니다.
사람은 인터페이스를 사용합니다
일반적으로 사람은 코드를 직접 작성하는 방식으로 컴퓨터를 쓰지 않습니다. 터미널이든 웹사이트든 앱이든, 어떤 형태로든 인터페이스를 사용합니다.
이론적으로는 사람이 하고 싶은 작업마다 그 작업만을 위한 Python이나 JS 코드를 직접 작성할 수도 있습니다. 그렇게 하게 만드는 대신, 버튼이나 단축키, 명령어 같은 것을 통해 그 코드를 쓸 수 있게 해 줍니다.
인터페이스의 예로는 Chrome, Claude Code, ChatGPT 앱(이전 이름은 Codex)이 있습니다.
또 하나 짚어 둘 점은, 사람은 그 밑에 있는 코드를 보지 않는다는 것입니다... 대개는요. 사람은 인터페이스만 봅니다.
LLM은 하네스를 사용합니다
기본적으로 LLM이 할 수 있는 일은 텍스트를 생성하는 것뿐입니다. 언어 모델이 그 이상의 일을 하려면 도구가 필요합니다. 요즘은 대부분의 LLM이 "read_file"(컴퓨터에 있는 파일에 접근), "edit_file"(그 파일을 수정), "bash"(명령 실행), "search"(온라인에서 데이터 검색) 같은 도구를 다루도록 학습됩니다.
하지만 LLM이 보내는 건 여전히 텍스트뿐입니다! 사람처럼 버튼을 누를 수는 없습니다. 그래서 LLM이 "코드를 실행해야 한다"는 뜻을 나타낼 때 쓸 전용 텍스트 형식이 필요합니다. 예를 들어 LLM에게 다음과 같은 도구 호출 형식을 준다고 해 보겠습니다.
<read_file name="README.md">이제 LLM은 이 형식으로 응답할 수 있다는 걸 압니다. 하지만 이것도 텍스트일 뿐이라 아무 일도 일어나지 않습니다! 컴퓨터가 꺼진 상태에서 키보드를 두드리거나 마우스를 움직이는 것과 같습니다.
무언가가 이 응답을 해석한 다음, LLM이 응답한 내용에 맞춰 알맞은 코드를 실행해야 합니다.
LLM이 실제로 일을 하려면 다음이 필요합니다.
- 실제로 일을 하는 도구(read_file, edit_file, bash, search 등)
- 그 도구를 텍스트로 호출하는 특수 문법
- 메시지를 파싱해서 그 문법을 찾아내고 코드를 실행하는 시스템
- 도구의 응답을 LLM에게 다시 돌려주는 방법
- 사용할 수 있는 도구 목록과 각 도구의 사용법 설명
이것이 바로 하네스입니다.
"Claude Code가 하네스 아닌가요?"
어느 정도는 그렇습니다.
Claude Code는 두 부분으로 이루어져 있습니다. 인터페이스와 하네스입니다.
터미널에서 "claude" 명령을 실행하면 Claude TUI가 열립니다. Claude 데스크톱 앱에서 "code" 탭으로 가면 Claude Code GUI가 열립니다. 이 둘은 모두 하네스가 아닙니다.
내부적으로 Claude Code는 Anthropic Agent SDK를 통해 에이전트와 연결됩니다. ChatGPT도 마찬가지로, ChatGPT/Codex 앱이 (CLI에 내장된) Codex App Server와 연결됩니다.
사람들이 왜 헷갈리는지는 이해합니다. Claude Code와 Codex는 둘 다 하네스를 앱 안에 내장하고 있으니까요.
하지만 같은 하네스를 다른 앱에 내장할 수도 있습니다! 몇 가지 예를 들면 다음과 같습니다.
- Cursor 하네스는 Grok Bot에서 쓰입니다
- Anthropic Agents SDK와 Codex App Server는 T3 Code에서 쓰입니다
- Pi는 OpenClaw에서 쓰입니다
하네스는 별도의 구성 요소이고, 앱을 쓰는 사람에게는 거의, 혹은 전혀 드러나지 않습니다.
도구는 누구의 것일까요?
하네스를 주방이라고 상상해 보겠습니다.
주방에는 여러 가지 도구가 있습니다. 냄비, 프라이팬, 칼, 뒤집개, 블렌더 말고도 많습니다.
모든 셰프에게 필요한 것을 전부 갖춘 주방은 없습니다.
좋은 하네스는 이 점을 전제로 만들어지고, 사용자가 자기 도구를 직접 가져올 수 있게 해 줍니다.
분명히 말해 두자면, 중요한 도구 대부분은 하네스가 직접 제공합니다. Codex와 Claude Code는 둘 다 도구를 많이 갖추고 있지만, Pi 같은 다른 하네스는 훨씬 간소합니다.
여기서부터 이야기가 복잡해지기 시작하니, 다이어그램을 하나 더 그려 보겠습니다.
주황색 상자는 "Claude Code에 포함된 것들"을 나타냅니다(정확히 말하면 Agents SDK입니다).
추가할 수 있는 커스텀 도구도 많습니다. LLM에게 코드를 검사하는 도구를 주는 TypeScript 플러그인이나, 에이전트가 컴퓨터를 조작할 수 있게 해 주는 CUA 플러그인 같은 것들입니다.
"tool plane"과 사람/LLM 계층 사이에 있는 선을 눈여겨보세요. 사람도 LLM도 도구를 보거나 만질 수 없습니다. 우리로서는 도구가 있는지조차 알 방법이 없습니다. 도구를 LLM에게도, 인터페이스에도 드러내 주는 것이 바로 하네스입니다(우리는 인터페이스를 통해 도구를 봅니다).
MCP 때문에 조금 더 복잡해집니다
MCP(Model Context Protocol)는 하네스가 외부에 있는 것들에 더 쉽게 접근할 수 있게 해 주는 표준입니다. 간단히 말하면, 도구는 "무언가를 하려고 여기서 코드를 실행하는 것"이고, MCP는 "무언가를 하려고 다른 곳에 API 요청을 보내는 것"입니다.
도구는 코드를 직접 제공합니다. MCP를 쓰면 코드를 다른 곳에 둘 수 있지만, 그래도 LLM은 MCP를 통해 요청을 보내 일을 처리할 수 있습니다.
MCP는 LLM에게 데이터를 제공하는 용도로 가장 많이 쓰입니다. ChatGPT가 이메일을 훑어보게 하고 싶으신가요? MCP입니다. Claude가 사이트 분석 데이터를 살펴보게 하고 싶으신가요? MCP입니다.
Chrome 확장 프로그램은 도구와 비슷한 면이 있습니다. 확장 프로그램은 웹사이트가 동작하는 방식을 바꿀 수 있는데, 이를 위해 여러분 컴퓨터의 Chrome 안에서 코드를 실행합니다.
MCP는 웹사이트에 더 가깝습니다. 아무것도 설치할 필요 없이 URL만 알면 됩니다. URL만 있으면 사용하는 데 필요한 정보를 (원칙적으로는) 전부 얻을 수 있습니다 :)
이걸 모두 합치면 대략 이런 모습입니다.
...잠깐, T3 Code는 왜 저기 있는 걸까요? 설명해 드리겠습니다.
T3 Code는 하네스가 하지 않는 일을 할 수 있도록 LLM에게 자체 기능을 노출합니다. 예를 들어 저희는 Claude Code를 쓰는 스레드가 Codex에서 서브에이전트를 띄울 수 있게 합니다. 다른 도구들도 이런 일을 하니, Herdr, Orca, Superset 같은 예를 살펴보세요.
그럼 이 기능을 왜 MCP로 노출할까요? 저희만의 하네스를 만들지 않으려고 쓴 얄팍한 꼼수일 뿐일까요?
앞에서 했던 이 말을 다시 떠올려 보세요.
도구는 코드를 직접 제공합니다. MCP를 쓰면 코드를 다른 곳에 둘 수 있지만, 그래도 LLM은 MCP를 통해 요청을 보내 일을 처리할 수 있습니다.
T3 Code에는 여러 하네스를 넘나드는 서브에이전트처럼 멋진 기능을 가능하게 하는 코드가 많습니다. 기술적으로는 T3 Code의 가장 멋진 기능을 전부 Claude Code용, Codex용, Antigravity용, Pi용, Cursor용, Muse용... 플러그인 세트로 다시 만들 수도 있었습니다.
아니면 모든 코드를 T3 Code 안에 그대로 두고, 대신 LLM이 쓸 수 있는 간단한 MCP 서버를 노출할 수도 있습니다 :)
주방 비유로 돌아가면, MCP는 레시피에 가깝습니다. 무언가를 하는 방법이지, 그 무언가 자체는 아닙니다.
T3 Code는 주방에 요리책을 건네는 셈입니다. 주방이 돌아가는 방식은 전혀 바꾸지 않습니다. 셰프들이 저희 요리책을 보기로 한다면 정말 좋은 일입니다! 아예 무시해도 되고, 그래도 달라지는 건 없습니다.
...그래서 에이전트는 무엇일까요?
제가 "에이전트"라는 말을 정의도 없이 남발하지 않고 여기까지 온 게 얼마나 뿌듯한지 아시나요? 쉽지 않았거든요 ㅋㅋ
한 줄 요약: 에이전트는 하네스와 LLM을 합쳤을 때 생기는 것입니다.
LLM은 텍스트를 생성할 뿐, 아무것도 하지 않습니다. 하네스는 그저 주방일 뿐이라 아무것도 요리할 수 없습니다. LLM과 하네스를 합치면 "에이전트"가 만들어집니다.
서로 다른 "에이전트"라고 해도, 실은 커스텀 도구, 지침, MCP 서버 같은 하네스 구성만 다른 경우가 많습니다.
T3 Code는 하네스일까요?
아닙니다. T3 Code는 하네스를 가져오지 않으면 동작하지 않습니다.
다시 주방 비유로 돌아가 보겠습니다.
- 셰프 = LLM
- 주방 = 하네스
- T3 Code = 레스토랑
T3 Code는 원하는 주방을 무엇이든 가져올 수 있는 레스토랑입니다. 저희가 좋아하는 자체 레시피가 있어서 그 요리책을 주방마다 건네지만, 여러분이 시키지 않는 한 셰프는 그 책을 펴 보지 않습니다 :)
더 깊이 알고 싶은 분들을 위해...
이렇게 위에서 아래까지 전부 훑는 설명이 마음에 드셨다면, 제가 다음 주에 공개하는 Mega.dev 강의 비용을 상사에게 내 달라고 하세요. 거기서 이 모든 내용을 훨씬 깊이 다룹니다 :)
T3 Code도 한번 살펴보세요. 오픈 소스라서, 에이전트에게 동작 방식을 설명해 달라고 해서 훨씬 더 깊이 파고들 수 있습니다.
