Harness Handbook: 행동 중심 하니스 문서화와 BGPD를 통한 수정 위치 탐지

왜 중요한가

현대 에이전트 시스템의 동작은 기본 모델뿐 아니라 프롬프트 구성, 상태 관리, 도구 호출과 실행 제어를 담당하는 하니스에 크게 의존한다. 하니스가 대규모이고 실행 로직이 파일·함수·단계·상태에 걸쳐 분산되면 수정 요청이 요구하는 행동을 실제로 구현한 모든 코드 위치를 식별하는 작업이 병목이 된다. 본 논문은 행동과 구현을 직접 연결하는 표현을 제공하여 위치 탐색 비용을 낮추고 자동화된 편집 계획의 정확도를 높였다는 점에서 하니스 진화의 실무적 난제를 해결하는 기여를 가진다.

핵심 기여

행동 위치화(behavior localization) 정의 및 중요성 규정

행동 위치화는 수정 요청이 요구하는 런타임 행동을 구현하는 모든 소스 위치를 찾아내는 문제로 규정되었다. 이 정의는 수정을 계획하기 위한 전제 조건으로 위치 식별이 선행되어야 한다는 공학적 문제를 명확히 했다. 논문은 이 문제를 해결하지 않으면 편집 계획의 완전성과 신뢰도가 낮아진다는 점을 실험적으로 보였다.

Harness Handbook이라는 행동 중심 표현 도입

핸드북은 L1(시스템 개요)·L2(단계/구성요소 개요)·L3(소스-연계 단위 심층) 계층과 교차 단계 상태 레지스터로 구성되는 행동 중심 문서 표현이다. 각 L3 항목은 정적 프로그램 분석으로 획득한 소스 로케이터에 직접 연결되어 행동과 구현을 정렬한다. 이 구조는 개발자와 코딩 에이전트가 행동을 출발점으로 하여 구현 위치로 직접 이동하도록 설계되었다.

구현 자동화 파이프라인: 정적 추출·행동 조직·계층 합성

핸드북 구축 파이프라인은 언어별 어댑터로부터 함수·시그니처·호출 간선 등 정적 사실을 추출하고 이를 호출 그래프와 문맥으로 실행 단계에 배치한 뒤 L1–L3 문서 트리를 합성한다. function-as-leaf와 file-as-leaf 두 모드를 지원하여 신뢰 가능한 시드 골격 유무와 예산 제약에 따라 L3 세분도를 조절했다. 파이프라인은 가능한 부분만 갱신하는 재동기화 절차를 통해 저장소 변경과의 정합성을 유지한다.

Behavior-Guided Progressive Disclosure(BGPD) 워크플로 제시

BGPD는 핸드북을 탐색하여 L1·L2 수준에서 관련 실행 단계를 좁히고 교차 단계 상태를 따라 L3 후보를 확장한 뒤 저장소에서 후보를 검증하여 최종 근거 집합을 생성한다. 이렇게 획득한 검증 근거는 편집 플래너가 수정 블록과 행동 근거를 연결하는 데 사용되며 편집 실행과 재동기화로 이어진다. BGPD는 계층적 탐색과 저장소 기반 검증을 결합하여 위치 탐지의 정확도를 높였다.

실험을 통한 실효성 입증

두 개의 오픈소스 하니스(Codex, Terminus-2)에서 30개의 행동 중심 수정 요청을 사용한 비교 평가를 수행했다. Handbook-Assisted 플래닝은 전체 승률과 로컬라이제이션 F1, 그리고 완전 실패 비율(Wrong)에서 일관된 개선을 보였으며 플래너 토큰 사용량은 감소했다. 실험 결과는 흩어진 구현 지점, 드물게 실행되는 코드 경로, 교차 모듈 상호작용을 포함한 난이도 높은 요청에서 가장 큰 이득이 나타남을 보여주었다.

핵심 아이디어 이해하기

대규모 하니스에서는 하나의 런타임 행동이 여러 파일과 함수, 실행 단계, 공유 상태에 걸쳐 분산되어 구현된다. 기존 저장소 중심의 탐색 도구들은 파일·함수 단위로 정보를 제공하므로 개발자가 행동과 구현 사이의 매핑을 스스로 복구해야 했고, 이는 사람과 코딩 에이전트 모두에게 비용이 컸다. 행동 위치화 문제는 바로 이 차이에서 발생하며, 수정 요청의 '무엇(behavior)'과 저장소의 '어디(implementation)'를 직접적으로 연결해야 한다는 점이 출발점이다.

방법론

핸드북 구축은 세 단계 파이프라인으로 구성되며 첫 단계는 정적 사실 추출이다. 언어별 어댑터가 저장소를 파싱하여 함수, 외부 경계, 호출 간선 등 결정적 사실을 수집하고 호출 그래프 𝒢를 구성하며, 해결되지 않은 호출은 로그에 남겨서 추측을 금지한다. 두 번째 단계는 행동 조직으로서 선택한 leaf 모드(function-as-leaf 또는 file-as-leaf)에 따라 소스 유닛을 실행 단계 골격 𝒮에 배치한다.

주요 결과

핸드북 보조 플래닝은 Codex 저장소에서 전체 승률을 28.3%에서 38.3%로, Terminus-2에서는 26.7%에서 45.6%로 높였다. 플래너 토큰 사용량은 Codex에서 평균 0.102M에서 0.089M으로 12.7% 감소했고 Terminus-2에서는 0.058M에서 0.053M으로 8.6% 감소했다. 참조 모델(Opus 4.8, GPT-5.5)과의 파일·심볼 수준 비교에서 Handbook-Assisted는 모든 Recall·Precision·F1 비교에서 개선을 보였고 F1 상승폭은 5.0에서 18.8 포인트 범위였다.

기술 상세

핸드북 표현은 L1 시스템 개요, L2 단계/구성요소 개요, L3 단위 심층의 세 수준 문서 트리 𝒟와 교차 단계 상태 레지스터 𝒵로 구성된다. L3의 리프 모드는 function 또는 file로 고정되며 function-as-leaf 모드는 신뢰 가능한 시드 골격 𝒮0에서 시작하여 함수 또는 연속 영역 단위로 L3 항목을 만든다. file-as-leaf 모드는 파일 요약 카드와 유도된 파일 호출 그래프를 사용해 단계 골격을 추론하고 파일을 단계에 배치한다.

한계점

논문은 핸드북 구축에서 leaf 모드 선택과 예산 제약이 품질에 영향을 미칠 수 있음을 명시했다. 일부 소스 호출이 해결되지 않거나 파싱 불능 항목이 있을 경우 해당 항목을 보수적으로 동결하거나 커버리지 기록에 남겨 자동 조직에서 배제한다. 재동기화 절차는 가능한 한 부분 갱신을 시도하지만 단계 골격이 무효화되면 전체 재구성이 필요하므로 대규모 구조 변경 시 비용이 발생할 수 있다.

키워드

agent harness(에이전트 하니스)behavior localization(행동 위치화)BGPD(행동 유도 점진 공개)static analysis(정적 분석)handbook(핸드북)

용어 해설

행동 위치화(Behavior Localization): — 수정 요청으로 기술된 런타임 행동을 구현하는 모든 소스 코드 위치를 찾아내는 작업이다. 정적 호출 그래프, 실행 단계(stage) 및 상태 연계 정보를 사용해 행동과 코드 경로를 대응시키는 방식으로 수행된다. 하니스 변경 전에 정확한 편집 대상 위치를 확보하여 이후의 편집 계획 신뢰도를 높이는 핵심 전처리 단계이다.
하니스 핸드북(Harness Handbook): — 레거시 저장소에서 런타임 행동을 중심으로 구현 지식을 계층화한 문서화 표현이다. 시스템 개요(L1), 구성요소/단계 개요(L2), 소스-연계 단위 심층(L3) 구조와 교차 단계 상태 레지스터를 포함한다. 각 L3 항목은 정적 분석으로 식별한 소스 로케이터에 연결되어 행동과 구현을 직접적으로 대응시킨다.
행동 유도 점진 공개(Behavior-Guided Progressive Disclosure): — 핸드북의 계층적 문서를 이용해 상위 수준 행동에서 출발하여 단계적으로 관련 구현 세부로 접근하는 탐색 워크플로이다. L1·L2를 통해 관련 실행 단계를 좁힌 뒤 공유 상태 연결을 따라 L3 후보를 확장하고 저장소에서 검증한다. 이렇게 얻은 검증된 근거를 바탕으로 편집 계획과 실행을 구성하므로 위치 탐지 정확도가 향상된다.
단계 골격(Stage Skeleton): — 하니스의 실행 단계와 상태 관계를 구조적으로 요약한 중간 표현으로서 L2 구성을 뒷받침한다. 정적 사실 추출과 호출 그래프 정보를 기반으로 함수-단계 또는 파일-단계 매핑을 포함하며 function-as-leaf와 file-as-leaf 모드에 따라 생성 방식이 달라진다. 단계 골격은 이후 L1~L3 문서 트리와 상태 레지스터로 합성될 때 기반 구조로 작용한다.
재동기화(Resync)(Resynchronization): — 소스 저장소에 변경이 생겼을 때 핸드북을 현재 저장소 상태와 정합시키는 절차이다. 변경된 유닛을 재파싱하고 함수 지문 또는 파일 해시로 대응을 찾은 뒤 영향을 받는 항목만 갱신하거나 필요한 경우 전체 골격을 재구성한다. 파싱 불가 항목은 동결하거나 커버리지 기록에 남겨 오해 소지를 방지한다.

Harness Handbook: 행동 중심 하니스 문서화와 BGPD를 통한 수정 위치 탐지

왜 중요한가

핵심 기여

핵심 아이디어 이해하기

방법론

주요 결과

기술 상세

한계점

키워드

용어 해설

관련 토론

댓글

관련 피드

왜 중요한가

핵심 기여

핵심 아이디어 이해하기

방법론

주요 결과

기술 상세

한계점

키워드

관련 토론

댓글

관련 피드