서론

"2025년은 에이전트의 해였습니다. 2026년은 에이전트 하네스(agent harnesses)의 해가 될 것입니다."

이 글은 Open Source Project of the Day 시리즈의 #136번째 기사입니다. 오늘의 프로젝트는 Harness Handbook입니다. 이 도구는 arXiv:2607.13285 논문(2026년 7월)과 함께 발표되었으며, AI 에이전트 하네스(harness) 코드베이스를 탐색 가능한 행동 매뉴얼로 변환해 줍니다.

먼저 개념부터 짚어보겠습니다: **하네스 (harness)**란 파운데이션 모델 (foundation model)을 감싸고 있는 오케스트레이션 레이어 (orchestration layer)를 의미합니다. 즉, 프롬프트를 구성하고, 상태를 관리하며, 도구를 호출하고, 실행을 조정하는 역할을 합니다. Claude Code의 훅 시스템 (hook system), Open Interpreter의 Harness 모듈, 그리고 모든 에이전트 프레임워크의 디스패치 레이어 (dispatch layer)가 모두 하네스에 해당합니다.

하네스를 유지 관리하는 것은 지속적인 엔지니어링 문제입니다. 요구 사항이 변경될 때, 개발자는 "이 동작을 바꾸고 싶다"라는 말을 "코드베이스의 어느 특정 위치를 변경해야 하는가"로 번역해야 합니다. 하지만 실제 운영 중인 하네스는 규모가 크고, 밀접하게 결합되어 있으며, 동작이 분산되어 있습니다. 예를 들어 "모든 캡처 경로에 비밀값 마스킹 (secret masking)을 추가하라"라는 요구 사항은 로그 캡처 경로, 디스크 쓰기 전 핸들러 (pre-disk-write handler), 콜드 스타트 폴백 경로 (cold-start fallback path)와 같이 서로 인접하지 않은 세 곳의 위치를 변경해야 할 수도 있습니다. 키워드 검색만으로는 이들을 모두 찾아낼 수 없습니다.

Harness Handbook의 접근 방식은 다음과 같습니다. 먼저 각 동작을 코드 증거 (code evidence)와 매핑하는 핸드북을 자동으로 생성합니다. 그다음, 에이전트에게 동작 설명을 바탕으로 특정 코드 위치를 점진적으로 찾아내는 탐색 알고리즘 (navigation algorithm)을 제공합니다.

학습 내용

• 에이전트 하네스 (agent harness)란 무엇이며 왜 유지 관리가 어려운가
• 핸드북의 3단계 문서 구조 (L1/L2/L3) 및 상태 레지스터 뷰 (state-register view)
• BGPD (Behavior-Guided Progressive Disclosure) — 4단계 탐색 알고리즘
• 왜 분산된 위치 (scattered sites)가 AI 코드 편집에서 가장 어려운 카테고리인가
• Resync: 코드가 진화함에 따라 핸드북이 최신 상태를 유지하는 방법
• Codex (Rust, 2,267개 파일) 및 Terminus-2의 평가 수치

사전 요구 사항

• AI 에이전트 프레임워크 개념(도구 호출 (tool calls), 상태 관리 (state management))에 대한 기본적인 이해
• LLM 에이전트 시스템을 유지 관리하거나 사용해 본 경험
• 코드 정적 분석 (code static analysis)에 대한 어느 정도의 지식

프로젝트 배경

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

한 문장 정의: 하네스(harness)는 파운데이션 모델 (foundation model)을 둘러싼 껍데기로, LLM을 무언가를 수행할 수 있는 에이전트 (agent)로 변환해 주는 역할을 합니다.

사용자 입력 (User input)
    ↓
하네스 계층 (Harness layer)
...

하네스는 단일 구성 요소가 아닙니다. 이는 전체 코드베이스에 분산되어 있는 로직입니다. 프롬프트 템플릿 (Prompt templates)은 한 파일에 존재하고, 도구 등록 (tool registration)은 다른 모듈에, 상태 지속성 (state persistence)은 또 다른 디렉토리에 존재합니다.

핵심 유지 관리 문제

제품 요구 사항이 변경될 때:

요구 사항: "모든 도구 호출 (tool call) 결과에 사용 통계 추가"

개발자가 찾아야 할 것:
...

이것이 Harness Handbook이 목표로 하는 문제인 편집 로컬라이제이션 (edit localization), 즉 행동 설명과 코드 위치 사이의 신뢰할 수 있는 매핑을 구축하는 것입니다.

저자 / 팀

• 저자: Ruhan Wang
• 논문: arXiv:2607.13285 (2026년 7월 14일)
• 라이선스: Apache-2.0
• 언어: Python, OpenAI 호환 API 호출

프로젝트 통계

• ⭐ GitHub Stars: 252
• 🍴 Forks: 25
• 📄 License: Apache-2.0
• 📝 arXiv: 2607.13285

핸드북 구조

3단계 문서 트리 (𝒟)

핸드북은 평면적인 문서가 아닙니다. 이는 3단계 계층 구조를 가집니다:

L1 — 시스템 개요 (System Overview)
    전체 아키텍처 (architecture), 실행 모델 (execution model), 주요 단계 (major stages), 글로벌 데이터 흐름 (global data flow)
    ("이 하네스의 핵심 부분은 무엇이며 어떻게 협력하는가")
...

두 가지 리프(leaf) 모드:

• 함수 기반 리프 (Function-as-leaf): L3 항목 = 하나의 함수 또는 연속된 영역; 미리 제공된 스켈레톤 (skeleton.yaml)이 필요함; 작은 코드베이스에 적합
• 파일 기반 리프 (File-as-leaf): L3 항목 = 하나의 파일; 단계별 스켈레톤이 자동으로 추론됨; 약 2,267개의 파일을 가진 Codex에 사용됨

상태 레지스터 뷰 (𝒵)

이것은 핸드북의 가장 중요한 설계 중 하나로, 특히 분산된 위치 문제를 해결하기 위한 것입니다.

스테이지 경계를 넘나드는 각 공유 상태 변수(레지스터)에 대해, 뷰(view)는 다음을 기록합니다:

• 해당 상태에 대한 모든 읽기 (read) 위치 (모든 스테이지에 걸쳐)
• 해당 상태에 대한 모든 쓰기 (write) 위치 (모든 스테이지에 걸쳐)

예시: session_context 레지스터

쓰기 위치:
...

하향식(Top-down) 코드 읽기는 이러한 구조적 상호 의존성을 드러내지 않습니다. 즉, 위치들이 코드베이스 상에서는 인접하지 않지만 논리적으로는 결합되어 있습니다. 상태 레지스터 뷰(state-register view)는 이러한 숨겨진 의존성을 명시적으로 만들어 줍니다.

BGPD: 행동 가이드 기반 점진적 공개 (Behavior-Guided Progressive Disclosure)

핸드북 생성 이후의 두 번째 핵심 기여는 BGPD 알고리즘입니다. 이는 코드 에이전트가 행동 묘사로부터 정밀한 코드 위치로 점진적으로 나아가도록 안내합니다.

4단계:

수정 요청: "모든 도구 실행 전에 권한을 검증하세요"

1단계: 스테이지 선택
...

핵심 설계: 모든 것을 한꺼번에 쏟아내는 대신 점진적 공개 (progressive disclosure) 방식을 사용합니다. L3 항목은 "온 디맨드 (on demand)" 방식으로 확장됩니다. 즉, 선택 전에는 에이전트가 요약본만 보게 되고, 선택 후에는 전체 소스 링크가 공개됩니다. 이는 토큰 효율성 (token efficiency)을 유지합니다.

Resync: 핸드북 최신 상태 유지

코드는 지속적으로 진화합니다. 핸드북은 한 번 사용하고 만료될 수 없습니다. 리싱크 (resync) 모듈은 코드 변경 후 증분 동기화 (incremental synchronization)를 처리합니다:

코드 변경 (diff Δ) 발생
        ↓
버전 정렬 (Version alignment)
...

리싱크 과정 중의 LLM 호출은 분류 (classification), 파일 할당 (file assignment), 스테이지 내 조직화 (within-stage organization), 설명 수정 (description revision)의 네 가지 유형으로 제한됩니다. 이 설계는 LLM 호출을 최소화합니다. 즉, 정적 분석 (static analysis)으로 처리할 수 있는 모든 것은 LLM으로 보내지 않습니다.

평가 결과

두 개의 실제 오픈 소스 하네스 (harness)에서 테스트되었습니다:

• Terminus-2: Python, 6개 파일, 소규모 하네스
• Codex (Open Interpreter의 Rust 버전): Rust, 2,267개 파일, 대규모 하네스

결과는 세 가지 판사 모델 (GPT-5.5, Opus 4.8, DeepSeek-V4-Pro), 세 가지 요청 유형, 그리고 세 가지 난이도 수준 모두에서 유지되었습니다.

가장 큰 이득을 본 세 가지 카테고리:

1. 흩어진 사이트 (Scattered Sites, SH): 인접하지 않은 여러 위치에 행동이 분산되어 있는 경우
2. 드물게 실행되는 경로 (Rarely Executed Paths): 빈도가 낮게 트리거되는 코드 브랜치 (code branches)
3. 파일 간 (Cross-File, CF) / 모듈 간 상호작용 (Cross-Module Interactions): 여러 파일 또는 컴포넌트에 걸쳐 있는 기능

이 세 가지 카테고리는 키워드 검색이 가장 많이 실패하는 지점입니다. 관련 코드가 명확한 위치에 있지 않고, 흩어져 있거나, 에러 핸들러 (error handlers) 및 폴백 경로 (fallback paths)에 숨겨져 있기 때문입니다.

규모 데이터 (Phase I, 결정론적 (deterministic), LLM 미사용):

• Terminus-2 (Python, 6개 파일): 103개 내부 함수 (internal functions) → 20개 단계 (stages), 106개 L3 엔트리 (entries), 10개 상태 레지스터 (state registers)
• Codex (Rust, 2,267개 파일): 34,363개 내부 함수, 159,960개 호출 엣지 (call edges) → 140개 단계, 2,267개 L3 엔트리, 62개 상태 레지스터

빠른 시작 (Quick Start)

설치 (Installation)

git clone https://github.com/Ruhan-Wang/Harness_Handbook.git
cd Harness_Handbook
python -m venv .venv && source .venv/bin/activate
...

LLM API 설정 (OpenAI 호환):

export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1  # 또는 다른 호환 가능한 엔드포인트
export LLM_MODEL=gpt-4o

핸드북 생성하기 (Generate a Handbook)

대규모 코드베이스 (스켈레톤 (skeleton) 불필요, 자동 추론):

cd handbook_generate_large
python run.py --repo /path/to/your/harness/
# ./output/ 경로로 출력: overview.md, 모듈별 페이지, module_tree.json

소규모 코드베이스 (skeleton.yaml 필요):

cd handbook_generate_small
# 단계 구조를 정의하기 위해 skeleton.yaml을 편집하세요
python run.py --repo /path/to/your/harness/ --skeleton skeleton.yaml

에이전트 플래너로 사용하기 (Use as Agent Planner)

cd handbook_as_helper
python planner.py \
  --handbook /path/to/generated/handbook/ \
...

코드 변경 후 재동기화 (Resync After Code Changes)

cd handbook_as_helper
python resync.py \
  --handbook /path/to/handbook/
...

링크 및 자료 (Links and Resources)

• 🌟 GitHub: Ruhan-Wang/Harness_Handbook
• 📄 논문 (Paper): arXiv:2607.13285
• 🌐 프로젝트 페이지 (Project page): ruhan-wang.github.io/Harness-Handbook
• 💬 Hacker News 토론: Making Agent Harnesses Understandable, Auditable and Editable

결론 (Conclusion)

Harness Handbook은 "AI가 AI 코드를 편집하는" 과정에서 발생하는 정밀도 문제를 해결합니다.

AI 에이전트를 사용하여 harness 코드를 수정할 때 가장 큰 실패 모드는 모델의 역량 부족이 아니라, 지역화 오류(localization error)입니다. 에이전트가 세 군데를 변경하고 두 곳을 놓치거나, 시스템 동작이 부분적으로 바뀌고 버그가 구석에 숨어버리는 식입니다. 더 크고 많은 토큰을 가진 모델도 이 문제를 해결하지 못하는데, 그 근본 원인은 '관련 위치들이 다른 곳에 흩어져 있다'는 정보의 누락이기 때문입니다.

세 단계의 문서 트리와 상태 레지스터 뷰(state-register view)를 추가함으로써 숨겨진 의존성(hidden dependencies)을 명시적으로 보여주어, 에이전트에게 이전에 없던 지도를 제공합니다. BGPD의 점진적 공개(progressive disclosure) 기능은 전체 코드베이스를 컨텍스트에 쑤셔 넣기보다는, 충분한 정보를 얻었을 때 에이전트가 멈출 수 있게 합니다. Resync는 이러한 지도가 만료되지 않도록 최신 상태로 유지합니다.

기준선 대비 45.6%의 승률을 기록하고 토큰 사용량은 12.7% 적게 사용하여, 품질은 향상시키면서 비용은 절감했습니다. 이 조합은 좋은 신호입니다: handbook은 에이전트를 더 장황하게 만드는 것이 아니라 더 정밀하게 만듭니다.

별점(Stars) 252개는 여전히 낮은 수치입니다. 하지만 이 문제의 중요성은 harness 코드베이스 크기에 비례하며, harness는 점점 커지고 있습니다. 2026년이 에이전트 harness의 해가 될 것입니다. 이러한 도구에 대한 수요는 이제 막 증가하기 시작했습니다.

PrimeSkills를 탐색해 보세요 — 엄선된 AI 에이전트(AI Agents)와 기술(skills)을 위한 마켓플레이스입니다. 각 기술은 실제 기업 워크플로(enterprise workflows)에서 검증되었으며, 과장된 광고를 걷어내고 실제로 작동하는 것만을 제공합니다.

더 유용한 통찰력과 흥미로운 제품들을 확인하시려면 저의 홈페이지를 방문해 주세요.