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

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

대규모 하니스에서는 하나의 런타임 행동이 여러 파일과 함수, 실행 단계, 공유 상태에 걸쳐 분산되어 구현된다. 기존 저장소 중심의 탐색 도구들은 파일·함수 단위로 정보를 제공하므로 개발자가 행동과 구현 사이의 매핑을 스스로 복구해야 했고, 이는 사람과 코딩 에이전트 모두에게 비용이 컸다. 행동 위치화 문제는 바로 이 차이에서 발생하며, 수정 요청의 '무엇(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 모드 선택과 예산 제약이 품질에 영향을 미칠 수 있음을 명시했다. 일부 소스 호출이 해결되지 않거나 파싱 불능 항목이 있을 경우 해당 항목을 보수적으로 동결하거나 커버리지 기록에 남겨 자동 조직에서 배제한다. 재동기화 절차는 가능한 한 부분 갱신을 시도하지만 단계 골격이 무효화되면 전체 재구성이 필요하므로 대규모 구조 변경 시 비용이 발생할 수 있다.