출처 URL: https://arxiv.org/html/2607.13285
라이선스: CC BY 4.0 arXiv:2607.13285v1 [cs.AI] 2026년 7월 14일
프로젝트 링크: https://ruhan-wang.github.io/Harness-Handbook/
초록(요약)
현대 AI 에이전트의 성능은 기초 모델뿐만 아니라 프롬프트를 구성하고, 상태를 관리하며, 도구를 호출하고, 실행을 조정하는 ‘하네스’에도 달려 있다. 모델, API, 실행 환경 및 애플리케이션 요구 사항이 변화함에 따라, 하네스는 기능을 추가하거나 기존 동작을 조정하기 위해 지속적으로 수정되어야 한다. 인간 개발자나 코딩 에이전트가 이러한 변경을 수행하기 전에, 대상 동작을 구현하는 모든 코드 위치를 파악해야 한다. 실제 운영 중인 하네스는 규모가 크고 밀접하게 결합되어 있으며, 파일, 함수, 실행 단계, 상태 전환에 걸쳐 행동이 분산되어 있는 반면, 수정 요청은 시스템이 수행해야 할 작업을 기술하고 리포지토리는 파일, 함수, 모듈 단위로 구성되어 있기 때문에 이는 어려운 작업이다. 코드 검색, 리포지토리 색인 생성, 긴 컨텍스트 처리에 대한 기존 접근 방식은 코드 검토를 용이하게 하지만, 개발자와 코딩 에이전트가 여전히 이 매핑 관계를 직접 파악해야 하는 과제는 남는다.
따라서 행동의 위치 파악은 하네스 진화 과정에서 핵심적인 병목 현상입니다. 본 논문에서는 정적 프로그램 분석과 LLM을 활용한 행동 구조화를 통해 하네스 코드베이스에서 자동으로 합성된 행동 중심 표현인 ‘하네스 핸드북(Harness Handbook)’을 소개합니다. 이 핸드북은 시스템 행동을 중심으로 구현 지식을 체계화하고, 각 행동을 해당 소스 코드와 연결해 줍니다. 또한, 코딩 에이전트가 고수준 행동 설명에서 관련 구현 세부 사항으로 이동하도록 안내하고, 후보 위치를 현재 소스 코드와 대조하여 검증하는 ‘행동 기반 점진적 공개(Behavior-Guided Progressive Disclosure, BGPD)’를 소개합니다. 우리는 두 개의 오픈소스 에이전트 하네스에서 나온 다양한 수정 요청을 대상으로 ‘하네스 핸드북’을 평가했습니다. 핸드북을 활용한 계획 수립은 더 적은 수의 플래너 토큰을 사용하면서도 행동 위치 파악 및 편집 계획의 품질을 향상시킵니다. 가장 큰 개선 효과는 구현 위치가 흩어져 있거나, 거의 실행되지 않는 코드 경로, 모듈 간 상호작용이 포함된 변경 사항에서 나타납니다. 이러한 결과는 복잡한 에이전트 시스템의 진화가 단순히 수정 내용을 생성하는 것뿐만 아니라, 해당 수정이 어디에서 이루어져야 하는지를 결정하는 데에도 달려 있음을 시사한다.
최근 대규모 언어 모델(LLM) 분야의 발전은 에이전트 기반 시스템의 개발을 가속화했다 [wang2024survey, yao2022react, huang2025towards]. 이러한 시스템은 도구, API 및 복잡한 실행 환경과 상호작용함으로써 모델의 기능을 확장한다 [schick2023toolformer, zhou2024webarena, xie2024osworld, yang2024swe]. 이러한 상호작용은 기초 모델만으로는 제어되지 않는다. 이는 프롬프트를 구성하고, 상태를 관리하며, 도구를 호출하고, 시스템 구성 요소 전반에 걸친 실행을 제어하는 ‘하네스(harness)’에 의해 조정된다. 따라서 하네스는 모델의 역량이 어떻게 시스템 동작으로 전환되는지를 결정한다. 모델, API, 실행 환경 및 애플리케이션 요구 사항이 진화함에 따라 하네스도 이에 맞춰 조정되어야 한다. 결과적으로 하네스의 진화는 현대 에이전트 개발에서 반복적으로 발생하는 공학적 과제가 되었다 [lin2026agentic, lopopolo2026harness, zhong2026ai].
실제로 하네스의 진화를 위해서는 기능을 추가하거나, 기존 동작을 조정하거나, 실행 워크플로를 개선하는 등의 변경이 필요합니다 [wang2025federated, wang2026fera]. 전통적으로 인간 개발자는 리포지토리를 읽고, 관련 동작을 추적한 뒤, 해당 구현을 편집하여 이러한 변경을 수행해 왔다. 코딩 에이전트가 자연어 요청을 바탕으로 동일한 작업을 수행할 것으로 기대되는 경우가 점점 늘어나고 있다 [yang2024swe, wang2025openhands, zhong2026ai, zhu2026semaclaw]. 그러나 수정 요청은 어떤 동작이 변경되어야 하는지는 설명하지만, 해당 동작이 어디에 구현되어 있는지는 명시하지 않는다. 따라서 수정이 인간 개발자에 의해 수행되든 코딩 에이전트에 의해 수행되든, 첫 번째 단계는 모든 관련 구현 위치를 찾아내는 것이다.