하네스 핸드북은 에이전트 하네스를 이해하고 수정하기 위한 세 가지 부분으로 구성되어 있습니다. 표현 방식은 런타임 동작을 중심으로 소스 코드를 체계화합니다(3.1절). 구축 파이프라인은 리포지토리에서 이 표현 방식을 생성합니다(3.2절). 수정 워크플로는 핸드북을 활용하여 코드 변경을 안내하고, 리포지토리 diff가 비어 있지 않을 때마다 자동으로 재동기화합니다(3.3절).
3.1 하네스 핸드북 표현
소스 저장소는 코드가 저장된 위치를 보여주지만, 런타임 동작이 어떻게 전개되는지는 직접적으로 보여주지 않습니다. 하나의 동작은 여러 파일, 실행 단계 및 공유 상태를 가로지를 수 있습니다. 하네스 핸드북은 소스와의 연결을 유지하면서 이 정보를 동작을 중심으로 재구성합니다. 그림 1에서 볼 수 있듯이, 여기에는 L1–L3 문서 트리 𝒟와 이를 보완하는 상태 레지스터 뷰 𝒵를 포함하고 있다.
그림 1: ‘Harness Handbook’ 표현 방식의 개요. 3단계 계층 구조는 시스템 수준 개요에서 시작하여 스테이지 수준 구성 요소 개요, 그리고 소스 코드를 기반으로 한 단위 세부 정보로 이어집니다. 탐색 창은 직접 액세스 및 스테이지 간 추적을 위한 구성 요소 및 상태 색인을 제공합니다.
독자는 일반적으로 L1(시스템 개요)에서 시작하며, 여기에는 아키텍처, 실행 모델, 주요 스테이지 및 전역 데이터 흐름이 요약되어 있습니다. 그런 다음 독자는 L2(구성 요소 개요)로 이동하여 선택한 스테이지의 책임, 입력, 출력, 종속성 및 로컬 상태를 확인합니다. 마지막으로, L3(단위 심층 분석)은 해당 스테이지를 소스 코드에 기반한 구현 항목과 연결합니다. 보완적인 뷰 𝒵는 스테이지 경계를 넘나드는 상태 관계를 기록합니다.
두 가지 규칙이 이 표현 방식의 유용성을 보장합니다. 점진적 공개(progressive disclosure)는 독자가 작업에 더 자세한 정보가 필요할 때만 L1에서 L3로 이동함을 의미합니다. 동작-구현 정렬(behavior–implementation alignment)은 활성화된 모든 L3 로케이터가 여전히 현재 저장소로 해결되어야 함을 의미합니다. 로케이터를 재검증할 수 없는 경우, 해당 항목은 동결되며 갱신될 때까지 로컬라이제이션에서 제외됩니다. 따라서 저장소는 구현 세부 사항에 대한 최종 권위자로 남습니다.
3.2 하네스 핸드북 생성
생성 과정은 저장소 ℛ를 기반으로 핸드북을 구축합니다. 리프 모드 𝑔 ∈ {function, file} 는 핸드북의 수명 기간 동안 고정되며, L3 항목의 세분화 수준을 결정합니다. function-as-leaf 모드에서는 각 L3 항목이 전체 함수 또는 하나 이상의 연속된 영역을 포함하는 반면, file-as-leaf 모드에서는 각 L3 항목이 하나의 파일을 나타냅니다.
두 모드는 스테이지 스켈레톤을 얻는 방식에서 차이가 있습니다. function-as-leaf는 스테이지 및 상태 레지스터 정의를 포함하는 시드 스켈레톤 𝒮0를 시드 골격으로 사용하며, 이는 스테이지 및 상태 레지스터 정의를 포함합니다. 이 모드는 하네스의 실행 스테이지를 충실히 반영하는 신뢰할 수 있는 시드 골격이 존재하고, 함수 수준 L3 항목이 할당된 예산에 부합할 때 사용됩니다. 반면, 파일-어스-리프 모드는 시드 골격에서 시작하는 대신 스테이지 골격을 추론합니다. 이 모드는 그러한 시드 골격이 없거나, 함수 수준 구성이 할당된 예산을 초과할 때 사용됩니다. 두 모드 모두 3.1절에서 설명한 표현을 생성하며, 알고리즘 2는 두 분기를 정의한다.
일단 𝑔가 선택되면, 구축은 세 단계로 진행되며, 이는 그림 2에서 function-as-leaf 분기를 예로 들어 설명되어 있다.
그림 2: Harness Handbook의 구축 파이프라인. 정적 분석은 소스 연동 사실을 추출하고, 행동 조직은 소스 단위를 실행 단계에 매핑하며, 계층적 합성은 L1–L3 핸드북을 구축한다.
1단계.
정적 사실 추출. 언어별 어댑터가 저장소를 구문 분석하여 함수, 명명된 외부 경계, 소스 위치, 시그니처 및 호출 에지를 추출합니다. 프로그램 그래프 𝒢는 내부 함수나 명명된 경계로 해결되는 호출만 유지합니다. 해결되지 않은 호출은 추측된 대상을 할당하지 않고 로그에 기록됩니다. 이 단계는 결정론적이며 LLM 호출을 수행하지 않습니다.
2단계.
행동 조직화. 파이프라인은 선택된 리프 모드에 따라 소스 유닛을 실행 단계 스켈레톤 𝒮로 구성합니다.
부록 A에는 두 모드에 대한 전체 구성 절차와 유효성 검사 방법이 제시되어 있습니다.
3단계.