에이전트 하네스를 수정할 때, 사용자는 보통 이렇게 말한다. “이 명령에만 임시 환경변수를 넣게 해줘.” “파일 삭제 전에는 꼭 확인하게 해줘.” “이 도구는 승인 없이는 실행하지 말아줘.” 요구는 한 문장이다. 그런데 저장소를 열면 이 한 문장은 스키마, 프롬프트, 도구 설명, 실행 래퍼, 상태 관리, 테스트로 흩어진다.
앞선 글에서는 Harness Handbook 논문의 핵심을 정리했다. 행동 중심 지도는 하네스 수정에서 localization과 planning 품질을 개선했고, Codex와 Terminus-2 실험에서 플래너 토큰 사용량도 줄였다. 이번 2탄은 논문 수치보다 프로젝트 페이지가 보여주는 작업 장면에 초점을 둔다.
프로젝트 페이지의 메시지는 단순하다. 오픈소스 코드가 공개되어 있다고 해서, 그 시스템의 행동이 저절로 읽히는 것은 아니다. 복잡한 에이전트 하네스에는 파일 트리보다 먼저 행동 질문에서 코드 증거로 내려가는 길이 필요하다.
그림: 하나의 행동 요청은 여러 구현 위치로 흩어진다. Harness Handbook은 L1 시스템 개요, L2 행동 단위, L3 구현 증거를 거쳐 행동과 코드 위치를 연결한다.
파일 트리는 위치를 보여주지만, 행동을 설명하지 않는다
프로젝트 페이지는 첫 화면에서 예시를 하나 든다. “파일을 삭제하기 전에 사용자에게 물어보는가?” 이 질문에 답하려면 delete, permission, confirm 같은 키워드를 검색하면 될 것처럼 보인다. 실제로는 그렇게 간단하지 않다.
삭제 확인 행동은 보통 단일 confirmBeforeDelete() 함수에 들어 있지 않다. 모델에게 어떤 도구 설명을 보여주는지, 도구 호출을 어디서 가로채는지, 권한 정책이 삭제를 고위험 작업으로 표시하는지, 사용자 응답이 어디에 기록되는지, 샌드박스 실행 전에 그 상태를 다시 확인하는지, headless mode나 auto-approval policy가 우회 경로를 만드는지까지 봐야 한다.
그래서 저자들은 이 문제를 “코드를 못 찾는 문제”가 아니라 행동과 구현 사이의 경로가 없는 문제로 본다. 코드 인덱스는 어디에 코드가 있는지 알려준다. 하지만 “이 시스템이 실제로 어떤 행동을 하는가”는 파일 위치만으로 복원되지 않는다.
이 차이가 중요하다. 하네스 작업에서 우리가 확인하려는 것은 파일명이 아니라 행동이다.
- 이 요청은 어느 단계에서 도구 호출로 바뀌는가?
- 권한 판단은 어디에서 일어나는가?
- 실패나 거절은 어떤 상태로 기록되는가?
- 우회 경로와 fallback path는 있는가?
- 변경하면 어떤 테스트와 문서가 같이 바뀌어야 하는가?
Harness Handbook은 이 질문들을 파일 트리 위에 억지로 올리는 대신, 행동 단위의 지도를 먼저 만든다.
Understand, Audit, Adapt: 세 작업이 사실은 같은 길을 걷는다
프로젝트 페이지는 Handbook의 용도를 세 가지로 나눈다. Understand, Audit, Adapt다.
첫째, Understand. 하네스가 어떻게 실행되는지 이해하는 일이다. 사용자 요청이 들어오고, 모델 입력이 구성되고, 도구가 호출되고, 상태가 바뀌고, 실패가 처리되는 전체 흐름을 본다. 이 단계에서는 아직 특정 파일을 고치는 것이 아니라, 시스템이 어떤 실행 구조를 갖는지 확인한다.
둘째, Audit. 문서나 기대와 실제 코드가 맞는지 확인하는 일이다. 예를 들어 “파일 삭제 전에는 확인한다”는 설명이 있다면, 주요 경로뿐 아니라 예외 경로, 자동 승인 정책, headless 실행, fallback path까지 확인해야 한다. 프로젝트 페이지는 이때 결론이 문서 약속이 아니라 검증 가능한 구현 증거에 근거해야 한다고 설명한다.
셋째, Adapt. 기존 하네스를 내 목적에 맞게 바꾸는 일이다. 어떤 기능을 추가하거나 정책을 바꾸려면, 수정 대상 행동이 어떤 파일·함수·상태·테스트에 걸쳐 있는지 먼저 찾아야 한다.
세 작업은 달라 보이지만, 실제로는 같은 경로를 공유한다.
행동 질문 → 시스템 맥락 → 관련 행동 단위 → 구현 증거 → 검증 또는 수정 계획
이 구조가 마음에 드는 이유는, 에이전트 하네스 작업에서 이해와 수정이 분리되어 있지 않기 때문이다. 이해가 얕으면 감사가 부정확해지고, 감사가 부정확하면 수정 범위가 새기 쉽다.
BGPD: 한 번에 전부 읽지 않고, 필요한 만큼만 내려간다
프로젝트 페이지는 이 경로를 Behavior-Guided Progressive Disclosure, 줄여서 BGPD라고 부른다. 말 그대로 행동 질문이 탐색을 이끌고, 정보는 단계적으로 열린다.
그림: Handbook 생성 파이프라인. 정적 분석으로 코드 사실을 추출하고, 이를 행동 중심 구조로 재조직한 뒤, L1-L3 Handbook으로 합성한다.
여기서 중요한 점은 “컨텍스트를 많이 넣는다”가 아니다. 오히려 반대에 가깝다. 먼저 L1에서 하네스 전체 실행 흐름을 잡고, L2에서 관련 행동 단위를 좁히고, L3에서 트리거·상태 변화·실행 경로·소스 링크를 확인한다.
이 방식은 사람에게도 유용하고, 코딩 에이전트에게도 유용하다. 사람은 저장소 전체를 외우지 않아도 특정 행동이 어느 경로에 있는지 이해할 수 있다. 에이전트는 무작정 grep하고 긴 컨텍스트를 채우는 대신, 관련 행동 단위에서 출발해 더 좁은 후보를 확인할 수 있다.
다만 여기서도 객관적으로 볼 필요가 있다. BGPD는 코드 수정 자체를 자동으로 보장하는 방법이 아니다. 프로젝트 페이지와 논문이 보여주는 것은 주로 localization과 planning을 더 잘하게 만드는 구조다. 실제 diff가 안전한지, 테스트가 충분한지, 프로덕션 요구사항을 만족하는지는 여전히 별도 검토가 필요하다.
Handbook Studio는 문서가 아니라 작업대에 가깝다
프로젝트 페이지 후반부에서 더 흥미로운 부분은 Handbook Studio다. 논문이 행동 지도 자체의 효과를 보였다면, Studio는 그 지도를 실제 작업 인터페이스로 바꾸려는 시도다.
Studio의 흐름은 세 가지다.
-
Read — Handbook
시스템 개요, 실행 단계, 행동 단위, 핵심 개념을 계층적으로 읽는다. 사용자는 저장소 구조부터 외우는 대신 “이 행동은 어떻게 실행되는가?”라는 질문으로 들어간다. -
Cross-check — Handbook ⇄ Code
행동 설명은 코드 증거로 연결된다. 왼쪽에서는 행동 설명을 보고, 오른쪽에서는 해당 구현을 확인하는 식이다. 중요한 건 설명이 소스 코드를 대체하지 않는다는 점이다. 프로젝트 페이지도 repository가 source of truth라고 못박는다. -
Modify — Co-Edit
수정은 행동 지도 위에서 시작된다. 사용자가 행동 단위를 선택하고 변경 의도를 설명하면, 시스템은 reviewable edit plan과 code diff를 만든다. 단, 아무것도 바로 저장소에 쓰지 않는다. 사용자가 확인해야 코드와 Handbook이 함께 업데이트된다.
이 설계는 꽤 현실적이다. 요즘 많은 코딩 에이전트 데모는 “말하면 바로 고쳐준다”에 초점을 둔다. 반면 Handbook Studio는 중간에 검토 가능한 계획과 증거 경로를 둔다. 자동화하되, 사람이 확인할 수 있는 형태로 자동화한다는 점이 하네스 작업에는 더 맞다.
임시 환경변수 하나가 14개 구현 위치로 퍼지는 사례
프로젝트 페이지에서 가장 좋은 예시는 “한 명령에만 임시 환경변수를 넣고 싶다”는 요구다.
상황은 이렇다. 정량 리서처가 Codex 기반 에이전트로 데이터 실험을 자동화한다. 백테스트를 여러 파라미터로 반복 실행해야 한다. 어떤 명령에는 시장 데이터 API 키와 날짜 범위를 넘기고 싶지만, 그 환경변수가 다음 명령까지 남아 있으면 안 된다. 요구는 간단하다.
“이 명령 하나만 자기 환경변수를 갖게 해줘.”
파일 트리에서 보면 이 요구는 여러 곳으로 퍼진다. 프로젝트 페이지에 따르면 이 변경은 ShellCommandToolCallParams, ExecCommandArgs, to_exec_params, ExecCommandRequest, process_manager, 그리고 세 개 테스트 파일까지 영향을 준다. 모두 합쳐 10개 파일의 14개 구현 위치다.
이 숫자는 과장된 마케팅 문구라기보다, 하네스 수정의 성격을 잘 보여주는 사례다. 한 필드가 추가되는 것처럼 보여도 실제로는 다음을 맞춰야 한다.
- 명령 스키마에
env필드가 들어가는가? - 도구 설명은 모델에게 이 필드의 존재와 사용 범위를 알려주는가?
- 일반 shell 실행 경로와 unified exec 경로가 모두 env를 전달하는가?
- process spawn 지점에서 환경변수를 현재 명령에만 merge하는가?
- 실행이 끝난 뒤 다음 명령으로 누수되지 않는가?
- 도구 스펙 테스트와 런타임 테스트가 함께 바뀌는가?
Handbook Studio는 사용자가 이 파일명을 먼저 알 필요가 없게 만드는 것을 목표로 한다. 사용자는 “command execution and environment variables” 같은 행동 단위에서 변경을 설명하고, Studio가 증거 경로를 따라 영향을 받는 위치와 edit plan을 제시한다. 이후 사람이 검토하고 확인해야 실제 코드와 Handbook이 업데이트된다.
이 예시는 에이전트 하네스 수정에서 왜 행동 지도가 필요한지 잘 보여준다. 요구는 제품 언어로 들어오지만, 수정은 시스템 경계 전체에 퍼진다.
수치보다 중요한 건 ‘탐색 폭’이 아니라 ‘관련성’이다
앞선 글에서 다룬 실험 결과를 프로젝트 페이지는 이렇게 해석한다. Handbook은 플래너에게 더 많은 코드를 보여줘서 좋아진 것이 아니라, 더 관련 있는 구현 영역으로 빨리 가게 만들었다.
그림: 프로젝트 페이지와 논문은 Handbook-assisted planner가 Codex와 Terminus-2에서 더 높은 preference rate와 더 낮은 planner token cost를 보였다고 보고한다.
이 해석은 조심스럽지만 유용하다. 긴 컨텍스트 모델이 좋아질수록 “그냥 많이 넣으면 된다”는 유혹이 커진다. 하지만 하네스 수정에서는 많은 코드보다 맞는 코드가 중요하다. 권한 정책 하나를 바꾸는데 관련 없는 렌더러, CLI 옵션, 테스트 유틸까지 한꺼번에 읽는다고 좋은 계획이 나오지는 않는다.
논문 수치도 이 방향을 지지한다. Handbook-assisted arm은 localization metric에서 recall, precision, F1을 전반적으로 개선했고, planner token cost는 낮췄다. 단, 다시 강조하지만 이 결과는 end-to-end 수정 성공률이 아니라 localization과 planning 품질에 대한 평가다.
OpenClaw 같은 시스템에도 바로 떠오르는 숙제가 있다
이 프로젝트 페이지를 읽으면서 가장 먼저 떠오른 것은 OpenClaw 같은 장기 실행 에이전트 시스템이다. 사용자 입장에서는 “메시지 보내기 전에 확인해줘”, “이 작업은 크론으로 돌려줘”, “브라우저 자동화는 기존 로그인 세션만 써줘”처럼 행동 단위로 요구한다. 하지만 구현은 세션, 도구 정책, 스케줄러, 메시징, 승인, 메모리, 브라우저 프로필에 흩어질 수 있다.
그렇다면 실무적으로는 완전한 Handbook Studio까지 가지 않더라도, 다음 정도는 바로 해볼 수 있다.
- 자주 바뀌는 행동 10개를 정한다.
- 각 행동에 대해 “트리거 / 권한 / 상태 변화 / 실행 경로 / 실패 경로 / 테스트”를 적는다.
- 각 항목에 실제 파일·함수·문서 링크를 붙인다.
- 에이전트에게 수정 요청을 줄 때 파일명보다 행동명으로 먼저 지시한다.
- 수정 후 행동 지도와 테스트를 함께 갱신한다.
이건 거창한 연구 시스템이 아니라, 하네스를 오래 운영하기 위한 문서화 습관에 가깝다. 다만 차이는 있다. 일반 문서는 사람이 읽으려고 쓰고, 행동 지도는 사람과 에이전트가 함께 수정 경계를 찾으려고 쓴다.
2탄의 결론: 하네스 문서는 설명서가 아니라 제어면이 될 수 있다
Harness Handbook 프로젝트 페이지가 논문보다 더 잘 보여주는 점은 이것이다. 하네스 문서는 단순 설명서에 머물 필요가 없다. 제대로 구조화되면 이해, 감사, 수정이 같은 지도 위에서 이어지는 제어면(control surface) 이 될 수 있다.
이 표현은 제 해석이다. 프로젝트 페이지 자체는 “understandable, auditable, editable”이라는 표현을 쓴다. 하지만 실무적으로 보면 의미는 꽤 분명하다. 좋은 하네스 문서는 “이 코드는 이렇게 생겼다”가 아니라 “이 행동은 이렇게 발생하고, 여기서 검증되고, 바꾸려면 이 경계를 봐야 한다”를 알려줘야 한다.
에이전트가 더 많은 일을 맡을수록, 하네스 수정은 기능 추가보다 행동 관리에 가까워진다. 그래서 앞으로 필요한 것은 더 긴 README가 아니라, 행동 질문에서 코드 증거로 내려가는 지도일 가능성이 크다.
더 실습해보고 싶은 분들께
이 글에서 다룬 에이전트 하네스, 자동화, 루프 설계를 직접 실습해보고 싶은 분들을 위해 제가 정리한 자료도 함께 남깁니다. 오픈클로를 일상 자동화 도구로 써보고 싶다면 『이게 되네? 오픈클로 미친 활용법 50제』를, 에이전트가 반복적으로 실행·검증·개선되는 구조를 더 깊게 보고 싶다면 AIFrenz의 「모두를 위한 루프 엔지니어링」 강의를 참고하시면 됩니다.