이 글은 Claude Opus 5.5 를 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

2025년 12월 초 Terminal-Bench 2.0 리더보드에서 GPT-5.1-Codex 는 4위였습니다. 57.8%. 같은 표의 21위에도 GPT-5.1-Codex 가 있었는데 점수는 36.9% 였어요. 모델은 같고, 바뀐 건 모델을 감싸고 돌린 프로그램뿐입니다. 위쪽은 OpenAI 의 Codex CLI, 아래쪽은 벤치마크 쪽이 만든 범용 에이전트 Terminus 2. 같은 두뇌를 다른 몸에 넣었더니 21점이 차이 난 셈입니다.

그 “몸” 을 요즘은 하네스(harness)라고 부릅니다. 저는 업무에서 Claude Code 를 쓰고 Codex 도 써 봤는데, 둘을 같은 종류의 물건으로 묶어 부르는 말이 생긴 건 꽤 최근 일이에요. 이 말을 제대로 들여다보게 된 건 개발자 친구가 Pi 라는 하네스를 소개해 준 뒤였습니다. Pi 가 무엇인지 알아보려다 보니 하네스가 무엇인지부터 정리해야 했어요. 그리고 Claude Code 를 쓰면서 아쉬웠던 것들, 컨텍스트에 무엇이 얼마나 들어가는지 보이지 않는다거나 세션을 되돌리고 갈라 보기가 불편하다는 것들이 사실은 모델이 아니라 하네스의 성질이라는 걸 이 글을 준비하면서 알았습니다.

이번 시리즈는 네 편입니다. 이 편에서는 하네스가 무엇인지, 무엇으로 이루어지는지, 왜 점수를 바꾸는지를 봅니다. 다음 편은 하네스가 없던 시절부터 2026년 10월까지의 지형, 세 번째 편은 “minimal agent harness” 를 내건 Pi, 마지막 편은 Claude Code 나 Codex 를 쓰는 사람이 Pi 를 들였을 때 무엇이 달라지는지를 예제로 다룹니다.

모델이 아닌 모든 것#

정의부터 모아 보면, 사람마다 조금씩 다르지만 가리키는 곳은 같습니다.

Simon Willison 은 2025년 9월에 오랫동안 미뤄 온 “에이전트” 의 정의를 이렇게 정했습니다. “An LLM agent runs tools in a loop to achieve a goal.” 도구를 루프로 돌려 목표를 이루는 LLM. 그 설명 안에 하네스라는 말이 이미 들어 있어요. LLM 이 행동을 요청하면 그 행동을 실제로 실행해 주는 쪽이 하네스이고, 실행 결과를 다시 모델에게 먹여 다음 판단을 하게 만드는 것도 하네스입니다. 2026년 3월에는 코딩 에이전트를 아예 “LLM 의 하네스 역할을 하는 소프트웨어” 라고 설명했고요.

LangChain 의 Vivek Trivedy 는 2026년 3월 글에서 등식을 하나 내놓았습니다. Agent = Model + Harness. 그리고 한 줄을 덧붙였는데, 이 시리즈에서 제일 자주 떠올릴 문장입니다.

If you’re not the model, you’re the harness.

모델이 아니면 전부 하네스라는 뜻입니다. 시스템 프롬프트, 도구와 그 설명, 파일 시스템과 샌드박스, 서브 에이전트를 띄우는 오케스트레이션, 컴팩션 같은 훅. Thoughtworks 의 Birgitta Böckeler 도 2026년 4월 martinfowler.com 에 같은 정리를 했습니다. 하네스는 “에이전트에서 모델을 뺀 전부” 를 가리키는 줄임말로 자리 잡았고, 정의가 너무 넓으니 코딩 에이전트에 한정하면 사용자가 그 위에 덧붙이는 바깥 하네스(규칙 파일, 검사 도구 같은 것)까지 생각해야 한다는 거예요.

도구를 만드는 쪽의 정의도 같습니다. Claude Code 문서는 에이전트 루프를 “추론하는 모델과 행동하는 도구” 두 부품으로 나누고, 모델을 둘러싸고 도구를 제공하며 모델이 보는 컨텍스트를 관리하는 층을 agentic harness 라고 부릅니다. OpenAI 의 Michael Bolin 은 2026년 1월 Codex 의 에이전트 루프를 해부하는 글에서 자사 에이전트를 괄호 안에 “harness” 라고 쓰고, Codex harness 를 Codex CLI·Codex Cloud·VS Code 확장 모두의 밑에 깔린 에이전트 루프와 실행 로직이라고 정의했고요. Pi 를 만드는 Earendil 은 2026년 8월에 “하네스는 AI 모델이 일할 환경을 제공하는 소프트웨어” 라고 쓰면서 한 문장을 강조했습니다. 모델과 달리 하네스는 사용자가 소유할 수 있다고. 이 말은 3편에서 다시 나옵니다.

하네스라는 단어가 원래 말이나 개에게 채우는 마구, 암벽 등반가가 허리에 차는 장비라는 걸 생각하면 이름이 잘 붙은 편이에요. 힘센 것에 끈을 매서 원하는 방향으로 쓰는 도구니까요. Earendil 글은 등반용 하네스에 장비를 매달고 지형에 따라 바꿔 단다는 점까지 비유를 밀고 갑니다. Böckeler 는 하네스 바깥에 하네스를 또 감는다는 표현에 누군가 “개 몸속에 하네스를 채워 본 적 있느냐” 고 했다는 이야기를 적어 두었고요. 비유는 거기까지만 쓰겠습니다.

하네스가 실제로 하는 일#

Bolin 의 글이 루프를 가장 짧게 설명합니다. 에이전트가 사용자 입력을 받아 모델에게 보낼 프롬프트를 만들고, 모델은 최종 답을 내거나 도구 호출을 요청합니다. 도구 호출이면 에이전트가 그 도구를 실행해 결과를 프롬프트 뒤에 붙이고 다시 모델에게 묻습니다. 모델이 더 이상 도구를 부르지 않고 사람에게 말을 걸 때까지 이게 반복돼요. 이 반복을 도는 프로그램이 하네스이고, 루프 한 바퀴마다 하네스가 정하는 것들이 생각보다 많습니다.

flowchart LR
    U["사용자 입력"] --> P["프롬프트 조립<br/>시스템 프롬프트 · 규칙 파일 · 이전 대화"]
    P --> M["모델 추론"]
    M -->|"최종 답"| A["사용자에게 응답"]
    M -->|"도구 호출 요청"| G["권한 확인<br/>샌드박스"]
    G --> T["도구 실행<br/>read · edit · bash · MCP"]
    T --> C["결과를 컨텍스트에 추가<br/>넘치면 컴팩션"]
    C --> P
    P -.-> S[("세션 저장<br/>JSONL · 트리")]
    style M fill:#FFD700,color:#000000
    style P fill:#87CEEB,color:#000000
    style G fill:#87CEEB,color:#000000
    style T fill:#87CEEB,color:#000000
    style C fill:#87CEEB,color:#000000
    style S fill:#87CEEB,color:#000000

노란 상자 하나가 모델이고, 파란 상자가 전부 하네스입니다. 부품을 나눠 보면 대략 이렇습니다.

시스템 프롬프트는 하네스가 대화 맨 앞에 넣는 지시문입니다. Earendil 은 이걸 “새 직원이 첫날 받는 업무 지침” 에 비유하는데, 모델이 학습으로 내면화한 규칙과 달리 대화마다 주입되는 것이라는 뜻이에요. 프로젝트의 AGENTS.md 나 CLAUDE.md 를 읽어 여기에 붙이는 것도 하네스의 일입니다. Codex 는 AGENTS.md 를, Claude Code 는 CLAUDE.md 를 읽죠(Claude Code 는 AGENTS.md 가 있으면 그걸 대신 읽기도 합니다).

도구는 모델이 “부를 수 있는” 능력입니다. 파일 읽기와 쓰기, 부분 수정, 셸 실행이 코딩 하네스의 기본이고, 검색·웹·MCP 서버가 붙습니다. 하네스는 도구를 설명해서 모델에게 보여 주고 실제 실행 코드도 제공하지만, 언제 어떤 도구를 쓸지는 보통 모델이 정합니다. 도구 설명 자체도 컨텍스트를 차지한다는 게 중요한데, 이건 3편에서 Pi 가 MCP 를 오랫동안 거부한 이유로 다시 나옵니다.

컨텍스트 관리는 루프가 길어질수록 커지는 일입니다. 도구 결과가 쌓여 모델의 컨텍스트 창이 차면 하네스가 오래된 부분을 요약해 줄입니다. 이걸 컴팩션이라고 부르고, Claude Code 와 Codex 모두 자동으로 합니다. Claude Code 문서는 오래된 도구 출력부터 지우고 그래도 모자라면 대화를 요약하며, 그 과정에서 초반의 자세한 지시가 사라질 수 있다고 적고 있어요. Codex 는 OpenAI API 의 전용 엔드포인트로 압축하고, 프롬프트 캐시를 살리려고 이전 프롬프트를 바꾸지 않고 접두어로 유지한다고 Bolin 이 설명했어요. 무엇을 남기고 무엇을 버릴지는 하네스가 정합니다. 사용자는 대개 그 결정을 보지 못하고요.

권한과 샌드박스는 도구가 실행되기 직전의 관문입니다. Claude Code 의 권한 모드와 체크포인트, Codex 가 자기 셸 도구에 거는 샌드박스가 여기에 속합니다. Bolin 의 글에 따르면 Codex 의 샌드박스는 Codex 가 제공하는 셸 도구에만 적용되고, MCP 서버가 제공하는 도구는 각자 알아서 막아야 해요. 하네스마다 철학이 가장 크게 갈리는 부품이기도 해요. 3편에서 보겠지만 Pi 는 이 관문을 일부러 비워 둡니다.

세션 저장은 대화를 어떻게 남기느냐입니다. Claude Code 는 세션을 홈 디렉터리의 .claude/projects/ 아래에 JSONL 로 저장하고 이어 하기와 분기를 지원합니다. 형식이 문서화돼 있는지, 트리로 갈라지는지, 다른 사람에게 공유할 수 있는지가 하네스마다 달라요.

번역 계층은 Earendil 이 따로 꼽은 부품입니다. 여러 회사의 모델 API 차이를 흡수해서 같은 루프로 돌리는 층인데, Claude Code 나 Codex 처럼 한 회사가 자기 모델을 위해 만든 하네스에는 사실상 없는 부품이죠. 그리고 이 모든 것 위에 사람이 보는 화면, 즉 터미널 TUI 나 IDE 확장이나 웹 화면이나 메신저가 얹힙니다.

같은 모델, 다른 점수#

하네스가 점수를 바꾼다는 건 이제 벤치마크 표에서 그냥 보입니다. 처음에 말한 리더보드는 Pi 를 만든 Mario Zechner 가 2025년 12월 2일 기준으로 캡처해 블로그에 올린 Terminal-Bench 2.0 표인데, 같은 모델이 여러 하네스로 돌아간 줄만 골라 보면 이렇습니다.

모델하네스별 정확도 (Terminal-Bench 2.0, 2025-12-02)
GPT-5.1-CodexCodex CLI 57.8% · Terminus 2 36.9%
GPT-5Codex CLI 49.6% · OpenHands 43.8% · Terminus 2 35.2% · Mini-SWE-Agent 33.9%
Gemini 2.5 ProTerminus 2 32.6% · Mini-SWE-Agent 26.1% · Gemini CLI 19.6% · OpenHands 16.4%
Claude Sonnet 4.5Terminus 2 42.8% · OpenHands 42.6% · Mini-SWE-Agent 42.5% · Claude Code 40.1%
Claude Opus 4.1Terminus 2 38.0% · OpenHands 36.9% · Mini-SWE-Agent 35.1% · Claude Code 34.8%

읽는 법은 둘이에요. GPT-5.1-Codex 와 GPT-5 는 자기 회사 하네스에서 확실히 잘합니다. 모델이 그 하네스의 도구와 프롬프트 모양에 맞춰 훈련됐을 가능성이 크고, 다른 하네스로 옮기면 20점 가까이 떨어져요. 반대로 Claude Sonnet 4.5 는 네 하네스의 점수가 오차 범위(±2.8 안팎) 안에 모여 있고, 자사 하네스인 Claude Code 가 오히려 맨 아래입니다. Gemini 2.5 Pro 는 자사 Gemini CLI 보다 범용 하네스에서 13점 높았고요. 모델에 따라 하네스의 영향이 다르고, 자사 하네스가 늘 최선인 것도 아니라는 걸 이 표가 보여 줍니다.

2026년에는 하네스만 고쳐 점수를 올린 실험이 나왔습니다. LangChain 이 2026년 2월 자사 코딩 에이전트 deepagents-cli 를 gpt-5.2-codex 로 고정해 두고 시스템 프롬프트·도구·미들웨어만 손봐서 Terminal-Bench 2.0 점수를 52.8% 에서 66.5% 로 올렸다고 발표했어요. 리더보드 30위권 밖에서 5위권으로 올라갔다고 합니다. LangChain 이 자기 제품을 두고 한 발표라 할인해서 들어야 하지만, 모델을 바꾸지 않고 13.7점이라는 숫자는 하네스가 장식이 아니라는 걸 보여 주기엔 충분합니다. 이런 일에 “harness engineering” 이라는 이름이 붙은 것도 2026년입니다. Mitchell Hashimoto 가 2월 초에 에이전트가 한 실수를 다시는 못 하게 만드는 작업을 그렇게 불렀고, 며칠 뒤 OpenAI 가 같은 제목의 글을 냈어요.

하네스를 알면 보이는 것#

이 지점에서 처음의 아쉬움으로 돌아갑니다. Claude Code 를 쓰면서 컨텍스트에 무엇이 들어가는지 잘 안 보인다고 느꼈는데, 그건 Claude 모델의 문제가 아니라 Claude Code 라는 하네스가 시스템 프롬프트와 도구 설명과 규칙 파일과 컴팩션 요약을 어떻게 조립하고 얼마나 보여 주느냐의 문제입니다. 세션을 되돌리고 가지를 쳐 보기 어렵다는 것도 세션 저장 부품의 설계예요. 모델을 바꿔도 안 풀리고, 하네스를 바꾸거나 고쳐야 풀리는 종류의 불편이었던 거죠.

Pi 를 만든 Zechner 가 2025년 11월에 같은 이야기를 했습니다. 컨텍스트 엔지니어링이 가장 중요한데 기존 하네스는 UI 에 드러나지도 않는 것들을 “behind your back” 으로 주입해서 그걸 정확히 통제하기가 매우 어렵거나 불가능하다고요. 그는 모델과의 상호작용을 전부 들여다보고 싶었고, 자동으로 후처리할 수 있게 깔끔하게 문서화된 세션 형식을 원했다고 썼습니다. 그래서 직접 만든 게 Pi 입니다. 그 결과가 정말 그런지는 3편과 4편에서 직접 설치해 보고 확인하겠습니다.

그 전에 한 걸음 물러나서 볼 게 있어요. 하네스라는 말은 언제 생겼고, 그 전에는 사람들이 AI 로 어떻게 코딩을 했는지. 그리고 2026년에 managed agents, durable harness, agent OS 같은 새 이름들이 쏟아지는 지금, 하네스가 다른 무언가로 대체되고 있는 건지. 그게 Part 2 의 질문입니다.

자료에 대해#

정의는 Simon Willison 과 Birgitta Böckeler 의 개인 글, LangChain·OpenAI·Anthropic·Earendil 의 회사 글과 문서에서 가져왔습니다. 회사 글은 자기 제품을 설명하는 글이라 정의에도 각자의 입장이 묻어 있어요. Terminal-Bench 표는 Zechner 블로그에 실린 2025년 12월 2일자 스크린샷을 직접 옮겨 적은 것이고, 지금 tbench.ai 는 4.0 리더보드로 바뀌어 같은 모델을 여러 하네스로 비교한 줄이 거의 없어서 2026년 수치로 갱신하지 못했습니다. LangChain 의 52.8% → 66.5% 는 벤더 자체 발표이고 제3자 재현은 찾지 못했습니다. OpenAI 의 “Harness engineering” 글은 본문에서 하네스를 따로 정의하지 않아서 정의 목록에 넣지 않았습니다.

편주제
Part 1 (이 글)하네스란 무엇인가
Part 2하네스 이전과 지금
Part 3Pi 라는 하네스
Part 4Pi 를 옆에 두기

References#

최신 자료 (2026)

비교·배경 자료 (2025)