AI Sparkup

최신 AI 쉽게 깊게 따라잡기⚡

에이전트 하네스 엔지니어링 – AI 에이전트 성능을 결정하는 스캐폴딩 설계

/ Last Modified:
목차

에이전트 하네스 엔지니어링(Agent Harness Engineering)은 AI 에이전트를 구성하는 모델 외부의 모든 요소—프롬프트, 툴, 컨텍스트 정책, 훅, 샌드박스, 피드백 루프—를 체계적으로 설계하고 개선하는 방법론이다. Viv Trivedy가 제안한 개념으로, “좋은 하네스를 갖춘 평범한 모델이 나쁜 하네스의 뛰어난 모델을 이긴다”는 원칙에서 출발한다.

핵심 원칙

“Agent = Model + Harness. 모델이 아니라면, 당신은 하네스다.” — Viv Trivedy

코딩 에이전트(Claude Code, Cursor, Codex, Cline)는 동일한 모델을 쓰더라도 하네스 설계에 따라 결과가 크게 달라진다. Terminal Bench 2.0에서 같은 Claude Opus 4.6이 Claude Code 내에서보다 커스텀 하네스에서 훨씬 높은 점수를 기록한 사례가 이를 증명한다. 한 팀은 하네스만 바꿔 순위를 Top 30→Top 5로 끌어올렸다.

하네스와 스캐폴딩을 구분할 때

현업에서는 모델 외부의 모든 것을 넓은 뜻의 하네스라고 부르기도 한다. Hugging Face가 정리한 보다 좁은 구분은 설계 책임을 나눌 때 유용하다.

용어좁은 의미예시
스캐폴딩(scaffolding)모델이 어떤 정보와 형식으로 행동할지 규정하는 계층시스템 프롬프트, 도구 설명, 출력 파서, 컨텍스트 정책
하네스(harness)모델을 반복 호출하고 도구 요청을 실행하며 종료를 결정하는 실행 계층에이전트 루프, 오류 처리, 승인 게이트
오케스트레이터(orchestrator)여러 하네스를 가진 에이전트를 작업 단위로 조율하는 상위 계층리드 에이전트와 서브에이전트 배치

이 구분은 보편 표준이 아니다. Claude Code와 Codex 같은 제품 문맥에서는 프롬프트와 도구를 포함한 전체 실행계를 하네스라고 부를 수 있다. 다만 실패 원인이 지침 설계인지 실행 루프인지, 또는 멀티 에이전트 조율인지 분리해 진단할 때는 세 용어를 구분하는 편이 정확하다.

하네스의 구성 요소

1. 파일시스템 + Git

  • 에이전트가 컨텍스트 창을 넘는 작업을 처리하게 해주는 가장 기본적인 기반
  • 중간 결과 오프로드, 멀티 에이전트 협업, 버전 관리(롤백·브랜치)에 활용

2. Bash / 코드 실행

  • ReAct 루프(추론→툴 호출→관찰→반복)의 일반 목적 엔진
  • 미리 툴을 다 만들 필요 없이, 에이전트가 필요한 툴을 셸에서 즉시 생성

3. 샌드박스

에이전트가 생성한 코드를 안전하게 실행하는 격리 환경.

  • 명령어 허용 목록, 네트워크 격리, 온디맨드 프로비저닝
  • 기본 탑재 도구: 언어 런타임, Git, 테스트 CLI, 헤드리스 브라우저

4. 메모리 + 검색

  • AGENTS.md / CLAUDE.md 등 파일에 세션 간 유지할 지식 저장
  • 훈련 데이터 이후 정보는 웹 검색·MCP 툴(Context7 등)로 보완

5. 컨텍스트 로트(Context Rot) 대응

컨텍스트 창이 채워질수록 추론 품질이 저하되는 현상을 막는 기법들:

기법설명
컴팩션(Compaction)오래된 컨텍스트를 지능적으로 요약해 오프로드
툴 결과 오프로딩대용량 로그는 파일로 저장, 필요 시 불러오기
스킬(Skills)지시사항·툴을 필요할 때만 점진적으로 공개
컨텍스트 초기화장기 작업에선 세션을 새로 시작하고 요약 핸드오프 파일로 연속성 유지

6. 장기 실행: Ralph 루프 + 플래닝

  • Ralph 루프: 훅이 에이전트의 종료 시도를 인터셉트해 원래 프롬프트를 새 컨텍스트 창에 재주입 → 멀티 세션 에이전트 구현
  • 플래닝: 목표를 단계로 분해해 디스크의 플랜 파일에 저장, 각 단계마다 자가 검증
  • 플래너/생성자/평가자 분리: 자기 평가 편향을 막기 위해 생성과 평가를 별도 에이전트로 분리

7. 훅(Hooks): 강제 실행 레이어

성공은 침묵, 실패는 상세히. 타입 체크 통과 시 에이전트는 아무것도 안 듣는다. 실패 시 에러 텍스트가 루프에 주입된다.

훅이 담당하는 대표 작업:

  • 모든 편집 후 타입 체크·린트·테스트 실행
  • 파괴적 명령(rm -rf, git push --force, DROP TABLE) 차단
  • PR 생성·main 푸시 전 승인 요구
  • 저장 시 자동 포매팅

8. AGENTS.md / CLAUDE.md

하네스의 단일 최대 레버리지 지점. 시스템 프롬프트에 매 턴마다 주입된다.

  • 짧게 유지: HumanLayer는 60줄 이하 권장. 규칙이 많을수록 각 규칙의 효과 감소
  • 실패 기반으로 작성: 모든 줄은 실제 발생한 오류로 정당화되어야 함

래칫(Ratchet) 원칙

에이전트가 실수를 할 때마다 그 실수를 영구 신호로 취급하고 하네스에 반영하라.

  • 주석 처리된 테스트 머지 → AGENTS.md에 “테스트는 주석 처리 금지” 추가 + 훅에서 .skip( 탐지
  • 파괴적 명령 실행 → 훅에서 해당 명령 차단
  • 좋은 AGENTS.md의 모든 줄은 구체적 과거 실패로 추적 가능해야 한다

하네스는 축소되지 않고 이동한다

모델이 개선될수록 일부 스캐폴딩은 불필요해지지만, 동시에 새로운 실패 모드가 등장해 새 스캐폴딩이 필요해진다. 하네스는 “모델이 아직 못 하는 것”에 대한 가정의 집합이다. 모델이 향상되면 해당 컴포넌트를 제거하고, 새로운 한계에 맞는 컴포넌트를 추가한다.

사용 대상 및 케이스

  • AI 코딩 에이전트 구축자: Claude Code·Cursor 같은 도구를 직접 만들거나 자사 코드베이스에 맞게 커스터마이징하는 팀
  • ML 엔지니어: 에이전트 성능 벤치마크를 높이고 싶을 때 모델 교체보다 하네스 개선을 우선 고려
  • DevOps/플랫폼 팀: 24/7 자율 코딩 에이전트를 운영 환경에 안정적으로 배포해야 할 때

하네스 엔지니어링 연구 현황

LangChain은 deepagents 라이브러리를 통해 하네스 엔지니어링 도구를 제공하며, 다음 문제를 연구하고 있다.

  • 수백 개의 에이전트가 공유 코드베이스에서 병렬 작업하는 오케스트레이션
  • 에이전트가 자신의 실행 트레이스를 분석해 하네스 수준 실패 모드를 스스로 식별·수정
  • 고정 설정 대신 태스크에 맞는 툴과 컨텍스트를 적시에 동적으로 조합하는 하네스

AHE: 관찰 가능성 기반 자동 하네스 진화 (arXiv 2604.25850)

복단대·마이크로소프트 연구팀이 제안한 에이전트 하네스 엔지니어링(Agentic Harness Engineering, AHE) 프레임워크는 하네스 엔지니어링을 수동 작업이 아닌 자동화된 폐루프로 전환한다 (2026-04-28).

핵심 문제: 하네스를 자동으로 개선하려면 세 가지 장벽을 넘어야 한다. ① 편집 가능한 컴포넌트의 이질적인 액션 스페이스, ② 유용한 신호가 묻히는 수백만 토큰의 실행 트레이스, ③ 편집 효과를 귀인하기 어려운 특성.

3가지 관찰 가능성 기둥:

기둥설명
컴포넌트 관찰 가능성편집 가능한 모든 하네스 컴포넌트에 파일 레벨 표현을 부여 → 액션 스페이스를 명시적·가역적으로
경험 관찰 가능성수백만 토큰의 로우 트레이스를 계층적 증거 코퍼스로 요약 → 진화 에이전트가 실제로 소비 가능
결정 관찰 가능성모든 편집에 자기 선언 예측을 페어링하고, 다음 라운드 태스크 수준 결과로 검증

세 기둥이 함께 작동하면 모든 편집이 반증 가능한 계약(falsifiable contract)이 되어 시행착오 없이 하네스가 자율 진화할 수 있다.

실험 결과:

  • Terminal-Bench 2에서 10회 AHE 반복으로 pass@1 69.7% → 77.0% 향상 (인간 설계 Codex-CLI 71.9% 초과)
  • SWE-bench-verified에서 시드 대비 12% 적은 토큰으로 최고 성공률 달성
  • 다른 모델 패밀리 3종 적용 시 +5.1~+10.1pp 크로스 패밀리 성능 향상 (하네스가 벤치마크 특화 아닌 일반 엔지니어링 경험을 인코딩함을 시사)
  • 성능 향상은 시스템 프롬프트가 아닌 툴·미들웨어·장기 메모리에서 발생

Microsoft Agent Framework: 데이터 접근, 승인, 메모리

Microsoft Agent Framework의 harness/claw 튜토리얼은 하네스를 실제 업무 데이터에 붙일 때 필요한 세 가지 기본 기능을 보여준다.

기능의미운영상 포인트
File access지정 폴더의 파일 읽기·쓰기·검색 도구 제공포트폴리오 CSV 같은 실제 사용자 데이터를 기반으로 답변
Tool approvals위험 도구 호출 전 사람 승인 요청거래 실행, 파일 삭제, 보고서 저장 같은 부작용 있는 행동을 게이트
Durable memory파일 메모리와 Foundry memory 병행에이전트가 명시적으로 관리하는 문서와 자동 추출된 사용자 사실을 분리

읽기 전용 파일 도구는 auto-approval rule로 마찰을 줄이고, 쓰기·삭제·거래 같은 부작용 작업은 계속 승인 대상에 두는 구성이 실용적이다. “항상 승인”도 세션 상태에 저장해 같은 세션 내 반복 확인을 줄일 수 있다.

2026년 7월 Microsoft는 Agent Framework Harness를 별도 릴리스로 공개했다. 이 하네스는 Python과 .NET에서 함수 호출 루프, 계획/실행 모드, 파일 메모리, 스킬, 컨텍스트 압축, 도구 승인, OpenTelemetry를 기본값으로 묶어 제공한다. 직접 하네스를 조립하기보다 “배터리 포함” 실행계를 가져와 커스텀 도구와 정책을 얹는 접근이다.

Self-Improvement를 위한 하네스 설계

Lilian Weng은 recursive self-improvement의 가까운 경로가 모델이 직접 자기 가중치를 고치는 방식보다는, 모델을 둘러싼 하네스·워크플로·컨텍스트·평가 루프를 개선하는 방식일 가능성이 크다고 정리했다.

핵심 패턴은 세 가지다.

패턴의미
Workflow automation계획, 실행, 관찰/테스트, 개선을 목표 달성까지 반복하는 루프
File system as persistent memory긴 로그·실험 결과·diff·요약을 컨텍스트가 아니라 파일 시스템에 보관
Sub-agent and backend jobs병렬 가설 탐색, 장시간 실험, 격리된 하위 작업을 프로세스처럼 관리

하네스 최적화의 대상도 프롬프트에서 구조화 컨텍스트, 워크플로, 하네스 코드, optimizer code로 이동한다. 즉, 좋은 하네스는 모델에게 더 많은 지시를 넣는 것이 아니라 모델이 관찰하고, 행동하고, 기억하고, 검증하는 실행 환경 자체를 개선한다.

Harness Handbook: 읽고 고칠 수 있는 하네스

Harness Handbook 연구는 에이전트 하네스가 커질수록 “성능”만큼 “사람이 이해하고 수정할 수 있는가”가 중요해진다고 본다. 하네스는 프롬프트, 도구, 메모리, 승인 정책, 복구 루프가 얽힌 실행 시스템이므로, 변경 이유와 영향 범위를 사람이 따라갈 수 있어야 한다.

실무적으로는 하네스 구성요소를 문서화 가능한 단위로 나누고, 각 단위에 목적·입력·출력·실패 모드·소유자를 붙이는 방식이 필요하다. 하네스가 자동 진화하더라도 사람이 diff를 읽고 verdict를 내릴 수 없다면 ai-agent-tips-outer-loop의 책임 경계가 무너진다.

참고 자료

관련 문서

  • edgebench — 장시간 실세계 환경 학습을 측정하는 자율 에이전트 벤치마크
  • opentag — Slack 안에서 직접 운영하는 오픈소스 AI 에이전트
  • symphony — 하네스 엔지니어링의 다음 단계: 이슈 트래커를 에이전트 오케스트레이터로 변환하는 OpenAI 스펙
  • agentic-autonomy-levels — AI 에이전트 자율성을 단계별로 운영하는 프레임워크
  • large-action-models — 행동 실행 특화 모델과 에이전틱 LLM의 차이
  • claude-code — 하네스 엔지니어링의 대표적인 상용 구현체
  • agent-governance — 에이전트 거버넌스와 하네스 보안 정책
  • agent-skills — AGENTS.md에 담기는 에이전트 스킬 설계
  • microsoft-agent-framework-harness — Python·.NET용 배터리 포함 에이전트 실행 하네스
  • kimi — 하네스 엔지니어링에 최적화된 코딩 모델
  • generic-agent — 3K 라인 시드 코드에서 스킬 트리를 자율 성장시키는 자기진화 에이전트
  • browser-harness — LLM이 헬퍼 함수를 직접 작성해 브라우저 하네스를 자기치유하는 최소 구현체
  • long-running-agents — 수시간~수주 장기 실행 에이전트 설계 원칙과 Ralph 루프·Brain/Hands/Session 패턴
  • ai-agent-evaluation — 긴 작업과 도구 사용을 검증하는 에이전트 평가 하네스 설계
  • codex-tips-goal-command — /goal을 완료 조건과 검증 명령이 있는 작업 계약으로 쓰는 방법
  • context-engineering — 컨텍스트 창을 유한 자원으로 관리하는 방법론
  • ai-agent-tips-tool-design — 실패를 줄이는 에이전트 도구 이름·스키마·오류 설계 원칙
  • ai-code-review-tips-agentic — 에이전트 시대의 코드 리뷰 병목과 위험 기반 리뷰 시스템
  • omnigent — 여러 코딩 에이전트를 한 세션에서 조율하는 메타 하네스
  • halo — RLM으로 에이전트 트레이스를 분석해 하네스를 자동 최적화하는 루프
  • flue — Astro 팀이 만든 TypeScript 에이전트 하네스 프레임워크 (Markdown 우선, 런타임 불가지론)
  • lobehub — 에이전트를 업무 단위로 구성하는 협업형 AI 워크스페이스
  • fusion — 작업 보드와 git worktree로 에이전트 실행을 조율하는 멀티 노드 오케스트레이터
  • zerostack — Rust 기반 초경량 코딩 에이전트와 worktree/loop 하네스
  • agentic-ai-tips-prompt-engineering — 챗봇 프롬프트와 다른 에이전트 프롬프트 설계법
  • agent-friendly-websites — AI 에이전트가 읽고 조작하기 쉬운 웹 UX 설계
  • pro-workflow — 교정에서 학습하는 Claude Code 자기교정 워크플로 스택
  • multi-stream-llms — 단일 스트림 챗 모델 병목을 모델 아키텍처 차원에서 줄이는 병렬 스트림 연구
  • ai-q-skill — 에이전트 하네스가 딥리서치 작업을 전문 백엔드에 위임하는 NVIDIA 스킬
  • clawless — WebContainers 기반 브라우저 AI 에이전트 런타임
  • skillopt — 모델을 고정한 채 스킬 문서를 검증 기반으로 개선하는 텍스트 공간 최적화기
  • harness-1 — 검색 특화 20B 검색 서브에이전트
  • onecode — Claude Code와 Codex를 한 앱에서 조율하는 코딩 에이전트 오케스트레이터
  • agentic-stack — 코딩 에이전트 간 기억과 스킬을 이식하는 .agent 레이어
  • mex — AI 코딩 에이전트를 위한 영속 프로젝트 메모리
  • ai-agent-memory-tips-strategy — 에이전트 메모리 전략을 고르는 의사결정 트리
  • ai-agent-memory-tutorial-reusable — 재사용 가능한 에이전트 메모리 만들기
  • qwen-agentworld — 범용 에이전트를 위한 언어 월드 모델
  • micro-agent — 모델 API 안에서 실행되는 라우터 기반 협업 런타임
  • go-micro — Go로 작성하는 에이전트 하네스와 서비스 프레임워크
  • herdr — 터미널 안에서 여러 코딩 에이전트를 조율하는 멀티플렉서
  • deepsec — 코딩 에이전트로 대형 코드베이스 취약점을 찾는 보안 하네스
  • ouroboros — 명세 우선 AI 코딩 워크플로를 재생 가능하게 만드는 Agent OS
  • code-as-agent-harness — 코드가 에이전트 실행 기반이 되는 관점
  • codebase-memory-mcp — 코드베이스를 Tree-Sitter 지식 그래프로 인덱싱하는 MCP 서버
  • orca — 여러 코딩 에이전트를 worktree 단위로 조율하는 Agent IDE
  • ai-agent-tips-outer-loop — 하네스가 만든 결과를 사람이 검증·판정·설명하는 책임 경계

AI Sparkup 구독하기

최신 게시물 요약과 더 심층적인 정보를 이메일로 받아 보세요! (무료)