AI 에이전트 하네스(AI Agent Harness)란 무엇인가?

이 글은 Claude Code, Codex, Cursor, LangGraph, MCP 서버, 레포지토리 지침(repo instructions), 권한(permissions), 훅(hooks), 그리고 새롭게 등장한 모든 에이전트 배관(agent plumbing) 등 대규모 언어 모델(LLM) 주변의 인프라를 이해하려는 분들을 위한 글입니다.

짧은 답변은 다음과 같습니다:

모델은 두뇌입니다. 하네스(Harness)는 그 두뇌를 유용하게 만드는 운영 환경입니다.

더 짧게 말하자면:

모델은 답변을 생성합니다. 하네스는 신뢰를 생성합니다.

에이전트(Agent)부터 시작하기

가장 단순한 수준에서 AI 에이전트는 루프(loop) 안에 있는 모델입니다:

사용자가 작업을 부여합니다.
모델이 무엇을 할지 생각합니다.
모델이 답변하거나 도구(tool)를 호출합니다.
도구가 무언가를 수행합니다.
결과가 다시 모델로 전달됩니다.
작업이 완료될 때까지 루프가 반복됩니다.

An AI agent is a while loop: user input feeds the model, which completes and responds

이 루프는 수십 줄의 코드가 될 수도 있고, 권한, 메모리, 도구, 로그, 테스트 및 UI를 갖춘 하나의 완전한 제품이 될 수도 있습니다. 루프는 씨앗입니다. 하네스는 그것을 실제 업무에서 안전하고 유용하게 만드는 것입니다.

동일한 모델, 다른 결과

에이전트와 관련하여 가장 범하기 쉬운 실수는 모든 문제의 원인을 모델 탓으로 돌리는 것입니다. 때로는 모델이 정말 문제일 때도 있지만, 그렇지 않은 경우가 훨씬 많습니다.

동일한 모델과 작업이라도 결과가 다를 수 있는데, 이는 에이전트가 확률적(probabilistic)인 특성을 가질 뿐만 아니라, 환경이 모델이 보는 것, 할 수 있는 것, 검증되는 방식, 그리고 언제 멈출 수 있는지를 변화시키기 때문입니다.

어떤 설정은 깔끔한 풀 리퀘스트(pull request)를 생성하고, 테스트를 실행하며, 예외 케이스(edge case)를 포착하고, 유용한 요약을 남깁니다.

반면 다른 설정은 잘못된 파일을 수정하고, 프로젝트 컨벤션(conventions)을 잊어버리며, 확인 없이 "완료"라고 말하고는 쓰레기 같은 결과물(slop)을 던져줍니다.

더 나은 모델이 도움이 될 수는 있지만, 더 나은 하네스는 변동성(variance)을 줄여줍니다.

모델 vs 에이전트 vs 하네스

사람들은 이 단어들을 혼용하곤 하므로, 먼저 구분해 보겠습니다.

용어	쉬운 영어 의미	예시
모델 (Model)	예측, 추론, 작성을 수행하는 두뇌	Claude, GPT, Gemini
...	...	...

딱 한 줄만 기억해야 한다면:

모델은 생각합니다. 에이전트(Agent)는 행동합니다. 하네스(Harness)는 에이전트가 바보처럼 행동하지 않도록 붙잡아 줍니다.

하네스는 프레임워크(Framework)가 아닙니다

프레임워크는 인간이 에이전트를 조립하는 것을 돕습니다. LangGraph, LangChain 및 유사한 도구들은 그래프(graphs), 상태(state), 노드(nodes), 도구 바인딩(tool bindings), 메모리(memory), 미들웨어(middleware), 라우팅(routing)을 제공합니다. 당신은 이러한 조각들을 사용하여 하네스를 구축할 수 있습니다.

하지만 프레임워크 그 자체가 자동으로 하네스가 되는 것은 아닙니다.

하네스는 에이전트 주변의 작업 환경(working environment)입니다. 하네스는 루프(loop)를 실행하고, 도구를 노출하며, 프로젝트 컨텍스트(context)를 주입하고, 권한을 강제하며, 출력을 검증하고, 유용한 메모리를 유지합니다.

이러한 구분은 중요합니다. 프레임워크를 구매하거나 구축하더라도, 하네스 설계에 대한 책임은 여전히 당신에게 있습니다. 만약 Claude Code, Codex, Cursor 또는 Windsurf를 사용하고 있다면, 당신은 이미 하네스 내부에서 작업하고 있는 것입니다. 문제는 그것이 당신의 코드베이스(codebase), 위험 허용 범위(risk tolerance), 그리고 워크플로우(workflow)에 얼마나 잘 부합하느냐 하는 것입니다.

당신이 이미 알고 있는 가장 단순한 하네스: CLAUDE.md

Claude Code는 하네스가 눈에 보이기 때문에 이 개념을 이해하기 위한 유용한 관문이 됩니다.

모든 진지한 Claude Code 설정에는 CLAUDE.md 파일이나 도구 간 호환 버전인 AGENTS.md 파일이 있습니다. Anthropic의 문서에서는 메모리를 세션 시작 시 Claude가 읽는 지속적인 지침(persistent instruction)으로 설명합니다. 여기에는 명령, 구조, 표준, 워크플로우 선호도, 그리고 반복되는 실수들이 포함됩니다.

이것이 바로 하네스의 역할입니다.

당신의 CLAUDE.md는 에이전트나 모델이 아닙니다. 그것은 하네스 내부의 하나의 가이드일 뿐입니다.

훌륭한 가이드는 마치 당신의 코드베이스를 건드리기 전, 유능한 계약직 직원에게 전달하는 브리프(brief)처럼 느껴집니다:

# CLAUDE.md

## 프로젝트 (Project)
...

그 파일은 모델의 지능(intelligence)에 영향을 주지 않습니다. 대신 환경을 더 엄격하게 만들고, 모델이 엉뚱한 곳으로 벗어날 수 있는 경로를 줄여줍니다.

Harness architecture: agent loop on the left with user request, agent loop, model, tools, and observation — harness components on the right with instructions, permissions, verification, and memory feeding into the loop

하네스(harness)는 모델이 어떤 컨텍스트(context)를 받는지, 무엇을 건드릴 수 있는지, 작업 결과물을 어떻게 증명하는지, 그리고 세션이 종료된 후 무엇이 남는지를 결정합니다.

하네스가 실제로 하는 일

하네스에는 두 가지 역할이 있습니다:

에이전트가 처음부터 제대로 수행하도록 돕기
에이전트가 스스로 수정할 수 있을 만큼 충분히 일찍 문제를 포착하기

여기서는 Martin Fowler의 프레임워크가 유용합니다. 그는 하네스를 가이드(guides)와 센서(sensors)로 나눕니다.

구성 요소	역할	예시
가이드 (Guides)	에이전트가 행동하기 전에 형태를 잡아줌	`CLAUDE.md`, `AGENTS.md`, 기술(skills), 도구 설명(tool descriptions), 프로젝트 문서
...

가이드는 에이전트가 행동하기 전에 방향을 안내합니다. 센서는 작업이 제대로 유지되었는지 알려줍니다. 메모리(Memory)는 향후 참조를 위한 노트입니다. 유용한 하네스에는 이 세 가지가 모두 필요합니다.

The feedback loop: guides feed into agent acts, sensors check the output, passing triggers memory that loops back to guides — failing loops back to agent acts

마지막 화살표에 주목하세요. 하네스는 이번에 에이전트가 어떻게 행동할지를 제어하며, 다음 실행이 조금은 덜 막막하게(less cold) 시작되도록 합니다.

내부 아키텍처 (The architecture underneath)

가장 단순한 버전을 넘어서면, 현대적인 하네스는 작은 제어 평면(control plane)처럼 보이기 시작합니다.

Arize infographic showing the nine components of the Harness 1.0 architecture: outer iteration loop, context management, skills and tools, sub-agent management, built-in skills, session persistence, system prompt assembly, lifecycle hooks, and permission and safety

Arize primer는 아홉 가지 요소를 하나의 시스템으로 정의합니다: 루프(loop), 컨텍스트(context), 도구(tools), 시스템 프롬프트 조립(system prompt assembly), 권한(permissions), 훅(hooks), 지속성(persistence), 내장 기술(built-in skills), 그리고 서브 에이전트 관리(sub-agent management).

이것이 바로 이것을 단순한 프롬프트 엔지니어링 (prompt engineering) 이상으로 만드는 요소입니다. 프롬프트는 모델에게 주의를 기울이라고 요청할 수 있습니다. 하네스 (harness)는 모델을 체크 (checks), 권한 (permissions), 그리고 복구 경로 (recovery paths)를 통해 라우팅 (routing)함으로써 주의를 기울일 가능성을 더 높여줍니다.

최상의 하네스는 판단 (judgment)은 모델에게 맡기고, 제어 (control)는 시스템에 유지합니다. 모델은 어떤 파일을 작업할지 결정합니다. 하네스는 그 파일을 수정해도 되는지 결정합니다.

동일한 모델, 더 나은 하네스

이것은 단순한 의미론적 차이가 아닙니다.

LangChain은 2026년 2월에 유용한 사례를 발표했습니다. 그들은 모델을 고정시킨 채 코딩 에이전트 (coding agent) 주변의 하네스를 변경했습니다. 그 결과 Terminal Bench 2.0에서의 점수가 52.8에서 66.5로 상승했습니다.

더 나은 하네스가 동일한 모델의 성능을 약 14포인트 향상시킨 것입니다.

변경 사항에는 더 나은 프롬프트 (prompts), 도구 설정 (tool setup), 검증 미들웨어 (verification middleware), 추적 분석 (trace analysis), 그리고 루프 탐지 (loop detection)가 포함되었습니다. 이것이 바로 팀들이 본받아야 할 패턴입니다.

"어떤 모델이 이 문제를 해결할 것인가?"라고 묻는 것부터 시작하지 마세요. "모델이 이를 신뢰성 있게 수행하기 위해 주변에 무엇이 필요한가?"라고 물으세요.

간단한 예시

에이전트에게 실패하는 테스트를 수정하라고 요청한다고 가정해 봅시다. 하네스가 별로 없다면, 세션은 종종 다음과 같이 진행됩니다:

모델이 프롬프트를 읽습니다.
몇 개의 파일을 스캔합니다.
코드를 일부 수정합니다.
자신이 작성한 코드를 다시 읽습니다.
"완료"라고 말합니다.

누락된 단계, 즉 테스트를 전혀 실행하지 않았다는 점을 깨닫기 전까지는 괜찮게 들릴 수 있습니다.

기본적인 하네스가 있다면 흐름이 다음과 같이 바뀝니다:

에이전트가 시작되고 프로젝트 지침 (project instructions)을 로드합니다.
중요한 명령어, 컨벤션 (conventions), 그리고 파일들을 확인합니다.
코드를 수정합니다.
하네스가 종료하기 전에 테스트 명령어를 실행하라고 지시합니다.
테스트가 실패하면 에이전트는 계속 진행합니다.
작업이 끝나면 짧은 인계 노트 (handoff note)를 작성합니다.

최소 기능 하네스 (Minimum Viable Harness)

대부분의 팀에게 최소 기능 하네스는 네 가지 레이어 (layers)를 가집니다:

레이어	작은 버전	중요한 이유
지침 (Instructions)	`CLAUDE.md` 또는 `AGENTS.md`	당신이 다시 설명하기 전에 에이전트가 프로젝트를 파악함
...

그것만으로도 이미 하네스입니다. 단순함을 유지하세요. 핵심은 복잡성이 아니라 신뢰성입니다.

엔지니어링 조직에서의 모습

엔터프라이즈 팀의 경우, 하네스(harness)는 엔지니어링 운영(engineering operations)의 일부가 됩니다. 이는 공유된 운영 협약(operating agreement)과 같습니다:

아키텍처(architecture), 명령어(commands), 경계(boundaries), 리뷰 기대치(review expectations)가 포함된 레포지토리 수준의 AGENTS.md 또는 CLAUDE.md
승인된 소규모 도구 세트: 검색(search), 편집(edits), 셸(shell), 브라우저(browser), 테스트 러너(test runner), 문서 조회(docs lookup)
읽기 전용 작업(read-only work), 워크스페이스 편집(workspace edits), 위험한 작업(dangerous actions)에 대한 권한 모드(permission modes)
비밀 정보(secrets), 파괴적인 명령어(destructive commands), 운영 환경 자격 증명(production credentials), 또는 검토되지 않은 배포 경로(unreviewed deploy paths)를 차단하는 훅(hooks)
에이전트가 인간 엔지니어가 수행할 것과 동일한 체크를 실행하도록 만드는 검증 게이트(verification gates)
무엇이 변경되었는지 설명하는 세션 노트(session notes)
하네스가 개선되고 있는지 아니면 단순히 소음만 커지고 있는지를 보여주는 실제 작업 기반의 소규모 평가 세트(eval set)

지침 파일(instruction file)을 작성하는 방법

CLAUDE.md를 작성할 때 저지르는 실수는 이를 희망 목록(wish list)처럼 취급하는 것입니다.

"시니어 엔지니어가 되어라."

"단계별로 생각하라."

"깨끗한 코드를 작성하라."

괜찮습니다만, 대부분 공간 낭비입니다. 에이전트가 그렇지 않으면 틀릴 법한 사항들에 파일을 사용하세요:

핵심 명령어(Critical commands): 빌드(build), 테스트(test), 린트(lint), 타입 체크(type check), 단일 파일 실행(run one file).
아키텍처 맵(Architecture map): 파일들이 어디에 위치하며 무엇이 어디에 속하는지.
엄격한 규칙(Hard rules): 에이전트가 절대 범해서는 안 되는 구체적인 실수들.
워크플로 선호도(Workflow preferences): 언제 질문하고, 행동하고, 변경하고, 검증할 것인지.
범위 외 사항(Out of scope): 에이전트가 건드려서는 안 되는 파일, 시스템 또는 통합(integrations).

짧게 유지하세요.

Anthropic의 현재 메모리(memory) 문서들은 모호한 가이드보다는 계층 구조(hierarchy), 임포트(imports), 재귀적 조회(recursive lookup), 그리고 구체적인 지침(specific instructions)을 강조합니다. CLAUDE.md는 행동을 형성(shapes behavior)합니다. 그것이 물리적으로 나쁜 행동을 막아주는 것은 아닙니다.

강제(enforcement)를 위해서는 설정(settings), 권한(permissions), 테스트(tests), 훅(hooks) 또는 인간의 리뷰(human review)가 필요합니다. 그것이 가이드(guide)와 가드레일(guardrail)의 차이입니다.

도구(tools)의 역할

도구는 에이전트의 손입니다.

도구는 모델이 파일을 검색하고, 명령어를 실행하며, API를 쿼리하고, 계산하고, 브라우저를 열고, 스프레드시트를 읽거나, 문서를 편집할 수 있게 해줍니다.

흔히 하는 실수는 더 많은 도구(tool)가 더 똑똑한 에이전트(agent)를 의미한다고 생각하는 것입니다. 보통은 더 혼란스러운 에이전트를 의미하게 됩니다. 도구의 개수가 늘어남에 따라 도구 선택 정확도(tool-selection accuracy)는 약 43%에서 14% 미만으로 떨어지며, 각 도구 정의(tool definition)는 사용 여부와 관계없이 대략 300~1,400개의 토큰(token)을 소비합니다.

업무를 수행할 수 있는 가장 작은 도구 세트부터 시작하세요. 코드 재작성(Rewriting)은 아마도 도구가 필요 없을 것입니다. 버그 수정(Fixing a bug)에는 파일 접근 권한과 테스트 명령어가 필요합니다. 현재 가격을 조사(Researching current prices)하려면 웹 검색(web search)이나 API가 필요합니다.

하나의 도구는 하나의 명확한 작업만을 가져야 합니다.

나쁜 예:

manage_files(action, file, destination, overwrite, format, permissions)

좋은 예:

read_file(path)
write_file(path, content)
delete_file(path)

도구 설계(Tool design)는 하네스(harness)의 일부입니다.

메모리(Memory)의 역할

메모리는 사람들이 이 과정을 필요 이상으로 어렵게 만드는 부분입니다. 두 가지 단순한 버전이 있습니다: 이번 세션(session)에서 말한 내용, 그리고 세션 간에 유지되어야 하는 내용입니다.

초기 단계에서 장기 메모리(longer-term memory)는 지루한 마크다운(markdown) 형태일 수 있습니다:

무엇이 변경되었는지
무엇이 여전히 고장 난 상태인지
다음에 실행할 명령어가 무엇인지
다음 세션에서 반복하지 말아야 할 것이 무엇인지

이는 인수인계 노트(handoff note), INDEX.md, 세션 요약(session recap), 또는 프로젝트 메모리 파일(project memory file)에 저장될 수 있습니다. 저의 노트 시스템에서는 에이전트가 무엇인가를 건드리기 전에 인덱스(index), 토픽 맵(topic map), 그리고 CLAUDE.md를 읽습니다.

화려하지는 않지만, 유용합니다.

에이전트 이전의 워크플로우(Workflows)

모든 문제에 완전 자율형 에이전트(fully autonomous agent)가 필요한 것은 아닙니다.