Harness Handbook으로 에이전트 행동을 코드에 맵핑하기

문제: 에이전트 행동의 복잡성

AI 에이전트의 실제 행동은 모델 성능보다는 에이전트를 감싸는 하네스(harness)에 의해 결정된다. 예를 들어 Codex는 2,267개 파일, 34,000개 이상의 함수, 160,000개의 코드 연결로 구성되어 있다. 이 규모에서 파일 트리나 검색만으로는 코드 조각들이 어떻게 함께 작동해 실제 행동을 만드는지 파악할 수 없다.

해결책: 3단계 행동 맵

Harness Handbook은 동작을 세 개 레벨로 구조화한다. **L1(시스템 개요)**은 요청이 어떻게 시스템을 통과하는지 전체 흐름을 보여준다. **L2(행동 단위 개요)**는 시스템을 일관된 행동 단위들로 분해하고 각각의 책임, 입출력, 의존성을 기록한다. **L3(행동 단위 상세)**는 특정 행동을 깊이 있게 살펴보며 트리거, 상태 변화, 예외 경로, 코드 증거를 연결한다. 예를 들어 "파일 삭제 전 사용자 확인"이라는 행동은 권한 정책, 확인 상태 기록, 샌드박스 실행 등 여러 부분에 걸쳐 있는데, L3는 이를 검증 가능한 단위로 분해한다.

생성 방식: 코드 사실 기반

생성 과정은 세 단계다. 첫째, 정적 분석으로 파일, 함수, 호출 관계, 상태 읽기/쓰기 등 프로그램 사실들을 추출해 프로그램 그래프를 만든다. 둘째, 이 그래프를 행동 중심으로 재조직하며 제안-검수 루프를 거쳐 단계와 단위 경계를 맞춘다. 셋째, 수렴된 맵을 핸드북으로 렌더링한다. 핵심은 "산문은 설명하고, 사실은 고정한다" —모든 주장이 추출된 프로그램 사실에 닻을 내린다.

세 가지 용도

이해: L1과 L2에서 시작해 시스템의 전체 실행 흐름과 행동 단위 간 연결을 파악한 후 L3에서 세부 구현을 확인한다. 감시: L3로 내려가 트리거, 권한 규칙, 상태 변화, 폴백 경로를 하나씩 검증하고 우회 경로가 없는지 확인한다. 수정: 행동 단위, 구현 링크, 의존성 경로를 찾아 변경 범위를 정의하고 코딩 에이전트의 편집 계획으로 활용한다.

코딩 에이전트의 성능 향상

Harness Handbook을 참고하는 에이전트와 그렇지 않은 에이전트의 계획 수립(편집 전)을 비교했다. Terminus-2와 Codex 두 프로덕션 하네스에서 테스트했고, GPT-5.5, Opus 4.8, DeepSeek-V4-Pro 세 개 판사 모델이 각각 평가했다. 결과는 Handbook이 에이전트가 정확한 구현 사이트를 찾고 적절한 범위의 편집 계획을 세우는 데 도움을 준다는 것을 보여준다.