🤖 AI

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

이 논문은 고수준의 행동 요구사항을 특정 소스 코드 위치로 자동 매핑함으로써 로컬라이제이션 병목 현상을 극복하고 복잡한 AI 에이전트 하네스의 진화 효율성과 품질을 향상시키는, 행동 중심 표현 방식인 Harness Handbook과 행동 유도 점진적 공개(BGPD) 방법을 소개한다.

원저자: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

게시일 2026-07-16

📖 3 분 읽기☕ 가벼운 읽기

CC BY 4.0

원저자: Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

원본 논문은 CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/) 라이선스로 제공됩니다. ✨ 이것은 아래 논문에 대한 AI 생성 설명입니다. 저자가 작성하거나 승인한 것이 아닙니다. 기술적 정확성을 위해서는 원본 논문을 참조하세요. 전체 면책 조항 읽기

당신이 방금 아주 똑똑한 로봇 비서를 만들었다고 상상해 보세요. 당신은 로봇에게 거대한 AI 모델인 '두뇌'를 주고 이렇게 명령했습니다. "가서 내 컴퓨터를 고쳐!" 하지만 두뇌만으로는 충분하지 않습니다. 로봇에게는 몸체와 신경계, 그리고 손가락을 어떻게 움직이고, 드라이버를 어떻게 잡으며, 언제 작업이 끝났는지 아는 법에 대한 지침이 필요합니다. AI의 세계에서 이 '몸과 신경계'를 **하네스(harness)**라고 부릅니다. 이것은 AI에게 언제 말해야 하는지, 언제 도구를 사용해야 하는지, 그리고 방금 무엇을 했는지 어떻게 기억할지를 알려주는 소프트웨어 계층입니다.

이제, 그 로봇을 업그레이드하고 싶다고 상상해 봅시다. 예를 들어, 파일을 삭제하기 전에 더 신중하게 행동하도록 만들거나, 혹은 작업을 한 번 확인하는 대신 세 번 확인하도록 만들고 싶을 수 있습니다. 옛날 방식이라면, 인간 프로그래머가 로봇의 신경계 중 정확히 어디에 "작업을 확인하라"는 규칙이 숨겨져 있는지 알아내기 위해 수천 줄의 코드를 뒤져야 했을 것입니다. 이는 마치 지도 없이 거대하고 엉킨 실타래 속에서 특정 신경 하나를 찾아내려는 것과 같습니다. 코드는 종종 여러 다른 파일에 흩어져 있고, 다른 로직과 뒤섞여 있어 추적하기 어렵습니다. 만약 단 한 군데라도 놓친다면, 당신의 로봇은 실수로 파일을 삭제할 수도 있습니다. 이 논문은 이러한 숨겨진 지점들을 찾아내어 우리의 AI 조력자들을 안전하게 업그레이드할 수 있도록 하는 좌절스러운 문제를 다룹니다.

Ruhan Wang과 동료들이 이끄는 연구진은 가장 큰 병목 현상이 AI에게 변화를 만드는 방법을 가르치는 것이 아니라, 인간(또는 다른 AI 에이전트)이 어디에서 변화를 만들어야 할지를 파악하도록 돕는 것이라는 점을 깨달았습니다. 그들은 이 문제를 **행동 국소화(behavior localization)**라고 부릅니다. 이를 해결하기 위해 그들은 **하네스 핸드북(Harness Handbook)**이라는 것을 발명했습니다.

하네스 핸드북을 단순히 파일 목록이 아니라, 로봇의 행동에 대한 사용자 매뉴얼이라고 생각하십시오. 정보를 "파일 A, 파일 B, 파일 C"(코드가 보통 저장되는 방식)로 정리하는 대신, 핸드북은 "로봇이 실제로 무엇을 하는가"를 기준으로 정보를 정리합니다. 이는 마치 "만약 로봇이 '작업 완료' 신호를 처리하는 방식을 바꾸고 싶다면, 그 신호가 처리되는 세 가지 특정 위치는 여기이며, 이들이 서로 어떻게 통신하는지는 다음과 같다"라고 적힌 가이드북을 가진 것과 같습니다.

연구팀은 로봇의 코드를 읽고 스마트한 AI를 사용하여 연결 관계를 매핑함으로써 이 핸드북을 자동으로 생성하는 시스템을 구축했습니다. 이 지도를 사용하는 방법을 그들은 **행동 유도 점진적 공개(Behavior-Guided Progressive Disclosure)**라고 부릅니다. 당신이 복잡한 시계를 고치려고 노력하고 있다고 상상해 보십시오. 500개의 톱니바퀴와 스프링 더미를 멍하니 바라보는 대신, 당신은 먼저 "시간 알림" 섹션을 보여주고, 그다음 "시침" 톱니바퀴로 줌인하며, 마지막으로 돌려야 할 정확한 나사를 강조해 주는 매뉴얼을 펼칩니다. 핸드북은 AI 코드에 대해 이와 같이 작동합니다. 즉, 시스템이 무엇을 하는지에 대한 높은 수준의 개요에서 시작하여, 사용자를 편집이 필요한 구체적인 코드 라인까지 안내합니다.

연구진은 이 아이디어를 두 가지 실제 AI 시스템(Terminus-2 및 Codex)에 대해 테스트했습니다. 그들은 코딩 에이전트들에게 "작업 점수를 매기기 전에 확인 요청을 세 번 하도록 만들어라"와 같은 간단한 요청을 바탕으로 변경을 수행하도록 했습니다. 그들은 두 그룹을 비교했습니다. 한 그룹은 전통적인 방식(파일 검색)으로 코드를 찾아야 했고, 다른 그룹은 하네스 핸드북을 사용했습니다.

결과는 명확했습니다. 핸드북을 사용한 그룹은 편집할 적절한 지점을 찾는 데 훨씬 더 뛰어났습니다. 그들은 실수를 덜 저질렀고, 건드리지 말아야 할 것을 실수로 변경하는 일도 없었으며, 이 모든 과정을 더 적은 컴퓨팅 자원(AI가 생각하는 데 사용하는 화폐와 같은 '토큰')을 사용하여 수행했습니다. 핸드북은 코드가 지저ка롭거나, 여러 파일에 흩어져 있거나, 시스템의 드문 부분에 숨겨져 있을 때 특히 유용했습니다. 실제로 핸드북을 사용하는 에이전트들은 지도를 가지고 있는 덕분에 "더 약한" AI 모델이 "더 강한" 모델과 거의 대등한 성능을 낼 수 있을 정도로 코드를 잘 찾아냈습니다.

이 논문은 AI 시스템이 더 복잡해짐에 따라, 우리는 단순히 더 똑똑한 두뇌에만 의존할 것이 아니라 더 나은 지도가 필요하다고 제안합니다. 하네스 핸드북은 코드를 파일이 있는 곳이 아니라 시스템이 무엇을 하는지를 중심으로 정리한다면, 이러한 강력한 에이전트를 진화시키는 과정을 훨씬 더 안전하고, 빠르고, 신뢰할 수 있게 만들 수 있음을 증명합니다. 이는 거대한 실타래를 푸는 혼란스러운 작업을 잘 정돈된 도서관을 통한 단순하고 안내된 여정으로 바꾸어 놓습니다.

기술 요약: 하네스 핸드북 (Harness Handbook)

문제 정의

현대 AI 에이전트 시스템의 진화는 프로덕션 규모의 에이전트 하네스 내에서 **행위 국지화(behavior localization)**를 수행하는 어려움으로 인해 점점 더 병목 현상을 겪고 있습니다. 하네스는 프롬프트를 구성하고, 상태를 관리하며, 도구를 호출하고, 실행을 조정하는 소프트웨어 계층으로, 기초 모델(foundation model)의 능력을 시스템 행위로 변환하는 역할을 합니다. 요구사항이 변경됨에 따라 개발자나 코딩 에이전트는 이러한 하네스를 수정해야 합니다. 그러나 특정 행위 요청을 구현하는 모든 코드 위치를 식별하는 것은 매우 어렵습니다. 그 이유는 다음과 같습니다:

구조적 복잡성: 행위는 인접하지 않은 파일, 함수, 실행 단계 및 공유 상태 전이(shared state transitions)에 걸쳐 분산되어 있는 경우가 많습니다.
표현의 불일치: 수정 요청은 시스템이 무엇을 해야 하는지(행위)를 설명하지만, 저장소는 코드가 어떻게 구조화되어 있는지(파일, 모듈, 함수)를 기준으로 조직됩니다.
기존 도구의 한계: 현재의 접근 방식(코드 검색, 저장소 인덱싱, 롱 컨텍스트 처리)은 구현 산물(implementation artifacts)을 중심으로 정보를 조직합니다. 이들은 개별 코드 스니펫을 찾는 데는 도움이 되지만, 흩어진 조각들이 어떻게 결합하여 특정 행위를 만들어내는지 명시적으로 매핑하는 데는 실패하며, 이로 인해 에이전트나 개발자가 이러한 연결 관계를 수동으로 추론해야 하는 상황을 초래합니다.

이러한 격차로 인해 개발자는 시스템의 멘탈 모델을 구축해야 하며, 에이전트는 저장소를 반복적으로 탐색하면서 흩어져 있거나 드물게 실행되는 코드 경로를 놓치는 경우가 빈번하게 발생합니다.

방법론

본 논문은 하네스 코드베이스로부터 자동으로 합성된 행위 중심 표현인 **하네스 핸드북(Harness Handbook)**과 이 표현을 활용하기 위한 워크플로우인 **행위 유도 점진적 공개(Behavior-Guided Progressive Disclosure, BGPD)**를 소개합니다.

1. 하네스 핸드북 표현

핸드북은 구현 지식을 파일 구조가 아닌 런타임 행위를 중심으로 재구성합니다. 이는 두 가지 상호 보완적인 뷰로 구성됩니다:

문서 트리 (Document Tree, $D$ ): 고수준의 시스템 개요에서 상세한 소스 근거 단위로 진행되는 3단계 계층 구조(L1–L3)입니다.
- L1 (시스템 개요): 아키텍처, 실행 모델, 주요 단계 및 글로벌 데이터 흐름.
- L2 (컴포넌트 개요): 특정 실행 단계의 책임, 입출력, 의존성 및 로컬 상태.
- L3 (유닛 딥다이브): 특정 코드 위치와 연결된 소스 근거 구현 엔트리(함수 또는 파일).
상태 레지스터 뷰 (State-Register View, $Z$ ): 단계 경계를 가로지르는 상태 관계를 추적하여, 구조적으로는 멀리 떨어져 있더라도 공유 상태에 의존하는 행위가 포착되도록 보장하는 교차 단계 뷰입니다.

이 표현은 두 가지 규칙을 준수합니다:

점진적 공개 (Progressive Disclosure): 독자는 작업에 더 많은 세부 정보가 필요할 때만 L1에서 L3로 이동합니다.
행위-구현 정렬 (Behavior–Implementation Alignment): 모든 활성 L3 로케이터는 현재 소스 저장소로 해결(resolve)되어야 합니다. 만약 로케이터를 재검증할 수 없는 경우, 환각(hallucination)을 방방지하기 위해 해당 위치는 동결됩니다.

2. 구축 파이프라인

핸드북은 세 단계를 거쳐 저장소( $R$ )로부터 자동으로 구축됩니다:

1단계: 정적 사실 추출 (Static Fact Extraction): 결정론적 파싱을 통해 함수, 콜 그래프, 상태 액세스를 추출합니다. 해결되지 않은 호출은 추측하지 않고 로그로 기록됩니다.
2단계: 행위적 조직화 (Behavioral Organization): 소스 유닛을 실행 단계 스켈레톤( $S$ $S$ )에 매핑합니다. 파이프라인은 두 가지 리프(leaf) 모드를 지원합니다:
- 함수-리프 (Function-as-leaf): 시드 스켈레톤에서 시작하여 함수(또는 연속된 영역)를 단계에 할당합니다.
- 파일-리프 (File-as-leaf): 파일 요약으로부터 단계 스켈레톤을 추론하고 그에 따라 파일을 조직합니다.
3단계: 계층적 합성 (Hierarchical Synthesis): 조직화된 내용을 L1–L3 문서 트리 및 상태 레지스터 뷰로 변환하며, 모든 로케이터를 소스에 대해 검증합니다.

3. 수정 워크플로우 (BGPD)

핸드북을 사용하여 하네스를 수정하는 워크플로우는 네 단계로 이루어집니다:

국지화 (Localization): 에이전트는 BGPD를 사용하여 핸드북을 거친(coarse, L1/L2) 수준에서 미세한(fine, L3) 수준으로 탐색합니다. 관련 단계와 상태 레지스터를 식별하고, 콜 그래프를 통해 후보군을 확장한 뒤, 이를 현재 소스 저장소와 대조하여 검증된 증거($bEq$)를 생성합니다.
계획 (Planning): 플래너는 $bEq $를 편집 계획($ P $)과 액션 선언($ \Gamma$)으로 변환합니다.
실행 (Execution): 실행기(executor)가 저장소에 계획을 적용합니다.
재동기화 (Resynchronization): 비어 있지 않은 모든 디프(diff)는 핸드북의 자동 재동기화를 트리거합니다. 시스템은 전체 핸드북을 다시 구축하는 대신 핑거프린트나 콘텐츠 해시를 사용하여 영향을 받은 부분만 업데이트함으로써, 표현이 진화하는 코드베이스와 일관성을 유지하도록 합니다.

주요 기여

행위 국지화의 정의: 본 논문은 행위 국지화를 편집을 계획하기 전에 특정 행위 요청을 구현하는 모든 코드 위치를 찾는 필수 단계로 공식 정의합니다.
하네스 핸드북: 구현을 파일 구조가 아닌 "하네스가 무엇을 하는가"를 기준으로 직접 연결하는, 자동으로 생성된 새로운 표현 방식입니다.
BGPD 워크플로우: 고수준의 행위 기술에서부터 단계별 구현 세부 사항으로 코딩 에이전트를 안내하고, 라이브 소스에 대해 후보를 검증하는 방법론입니다.
경험적 검증: 두 개의 오픈 소스 하네스(Terminus-2 및 Codex)에 대한 평가를 통해, 핸드북이 보조하는 계획이 국지화 정확도와 편집 계획의 품질을 높이는 동시에 토큰 사용량을 줄임을 입증했습니다.

실험 결과

저자들은 세 가지 유형(Query: 기존 행위 수정, Cross-file: 모듈을 가로지르는 기능 추가, Search-Hostile: 찾기 어려운 경로에 구현을 숨김)에 대해 60개의 수정 요청(하네스당 30개)을 대상으로 접근 방식을 평가했습니다.

계획 품질 및 비용: 핸드북 보조 계획은 저장소를 직접 탐색하는 베이스라인에 비해 계획 품질에서 유의미하게 높은 승률을 기록했습니다 (예: Terminus-2에서 +18.9%). 결정적으로, 이러한 개선은 더 적은 플래너 토큰(Codex에서 12.7%, Terminus-2에서 8.6% 감소)으로 달성되었으며, 이는 단순히 예산을 늘린 것이 아니라 효율성이 높아졌음을 나타냅니다.
국지화 정확도: 핸드북의 도움을 받은 더 약한 플래너(DeepSeek-V4-Pro)가 훨씬 강력한 모델(Opus 4.8, GPT-5.5)의 구현 사이트 국지화 성능과 일치하는 결과를 보였습니다. 파일 수준 및 심볼 수준 국지화에 대한 F1 점수는 모든 비교에서 5.0~18.8 포인트 향상되었습니다. "Wrong"(참조와 겹침이 전혀 없음) 지표가 크게 감소하여 완전한 실패가 줄어들었음을 보여주었습니다.
강건성 (Robustness): 이점은 모든 요청 유형(Query, Cross-file, Search-Hostile)과 난이도(Easy, Medium, Hard)에 걸쳐 지속되었습니다. 가장 큰 개선은 흩어진 구현 사이트와 모듈 간 상호작용이 포함된 변경 사항에서 관찰되었습니다.

의의 및 주장

본 논문은 복잡한 에이전트 시스템을 진화시키는 데 있어 단순히 편집을 생성하는 것뿐만 아니라, 그 편집이 어디에서 이루어져야 하는지를 결정하는 것이 핵심이라고 주장합니다. 행위와 구현 사이의 연결을 명시적으로 만듦으로써, 하네스 핸드북은 행위 국지화라는 중앙 병목 현상을 해결합니다.

저자들은 이 연구를 **하네스 자가 진화(harness self-evolving)**를 향한 단계로 규정합니다. 이들은 코드와 동기화되는 행위 중심의 저장소 표현이 행위 감사(auditing) 및 회귀 영향 분석(regression-impact analysis)과 같은 더 넓은 용도로 사용될 수 있다고 제안합니다. 궁극적인 목표는 에이전트가 국지화, 계획, 실행 및 재동기화의 루프를 자율적으로 닫을 수 있도록 하여, 더 큰 플래닝 토큰 예산 없이도 에이전트 하네스가 스스로 개선될 수 있도록 만드는 것입니다.