Agent Harness

한 줄 정의

Agent Harness는 stateless LLM을 multi-step task를 수행하는 agent로 바꾸기 위해 모델 바깥에서 상태, 도구, 검증, 복구, 안전을 관리하는 실행 인프라다.

핵심 요지

실행 환경의 주권: 좋은 에이전트와 데모형 챗봇의 차이는 모델 자체보다 에이전트의 제어 루프를 통제하고 보호하는 외부 하네스 설계에서 결정된다.
제어 문제 해결: RAG(지식 접근 문제)나 결정론적 워크플로(프로세스 문제)와 달리, 에이전트는 목표와 도구를 쥐고 최적의 경로를 탐색하는 제어 문제를 풀며, 하네스는 이 탐색 루프(Thought -> Action -> Observation -> State Update)를 중재한다.
하네스의 모델 내재화 (Harness Absorption): 빅테크 모델(Anthropic Opus 4.8 등)이 사후 학습 및 테스트 시점 추론(CoT) 레이어를 통해 예외 처리, 자가 교정, 툴 호출 제어 등의 상당 부분을 모델 내부로 흡수(Absorb)하고 있다.
외부 하네스의 역할 재정립: 모델이 똑똑해질수록 복잡한 프롬프트 가드라인이나 파이프라인 코드는 모델에 통합되며, 개발자는 금융 예산 통제(Budget Governor), 물리적 샌드박싱, 인간 최종 승인 게이트(HITL) 등 모델 내부로 우회할 수 없는 ‘물리적 통제선’ 구축에 집중해야 한다.
하네스 엔지니어링의 기원: Terraform의 창시자인 Mitchell Hashimoto가 2026년 초 제창한 개념으로, 에이전트가 실수할 때마다 채팅 창에서 일회성으로 프롬프트를 고쳐주는 대신, 동일한 실수가 다신 발생하지 않도록 모델 바깥의 실행 환경/설정(Harness)을 영구적으로 수정해주는 규율을 의미한다.
AI 에이전트의 4대 실전 규격: 단일 프롬프트를 넘어서는 명시적이고 구조화된 state schema(메모리) 유지, state 기반 행동 자율 선택(policy engine/router), 제한된 예산(max_steps, timeouts, cost, retries cap) 운영, durable checkpoints 및 idempotency 기반 crash 안전 복구가 필수 조건이다.
pydantic-ai 및 logfire의 통합: prompt 내부에 메모리를 섞는 대신 type-safe dependency injection과 pydantic schema 검증 및 Logfire 자동 tracing 스패닝을 통해 에이전트의 오작동을 기계적으로 차단한다.
규칙 선언의 한계 극복: CLAUDE.md나 AGENTS.md와 같은 프롬프트 기반 계약은 강제력이 없고 세션 간 문맥이 단절된다. Harness는 Memory(진행 스냅샷 복원), Skill(워크플로우 제어), Hook(포맷팅 및 보안 감지), Feedback(기계적 검증)을 통합하여 나쁜 출력이 나오기 어려운 구조를 설계한다.
컨텍스트 계층화(Layering) 전략: 프롬프트 캐싱 비용을 극단적으로 아끼기 위해 안정성에 따라 컨텍스트를 층으로 나누어 캐싱을 활성화한다 (Layer 0: System policies, Layer 1: Agent skill definitions, Layer 2: User session instructions, Layer 3: JIT-retrieved fresh outputs).
Anthropic Opus 4.8 출시(2026년 5월)는 검증(L4), 실행(L3), 제약(L1) 레이어가 모델 자체 가중치 및 오케스트레이션 내부로 흡수(Harness Absorption)되는 티핑 포인트다.
Opus 4.8은 자화자찬식 코드 결함 방관 확률을 4배 감소시켰으며, 750,000줄 Rust 코드베이스를 11일 만에 마이그레이션(테스트 통과율 99.8%)하는 동적 워크플로를 플랫폼 내재화했다.
100만 토큰의 컨텍스트 창에서 장기 검색 성공률은 기존 40.3%에서 68.1%로 상승했다.
독자적 해자는 이제 제약/실행/검증 인프라에서 기업 고유의 L2. 컨텍스트(Context) 및 L5. 라이프사이클(Lifecycle, Evals) 영역으로 이동한다.
개인용 PC의 오염/안전 리스크 격리를 위해 저전력, 상시 기동이 가능한 라즈베리 파이 4(RPi 4) 환경을 하네스 인프라로 채택. [출처: 라즈베리 파이 에이전트 하네스 구동 후기]
에이전트 자율성에 따른 잘못된 연쇄 결정(비정상적 무한 루프 등)을 억제하기 위해 Obsidian 지식 베이스 및 CLAUDE.md를 활용해 세션 컨텍스트를 제한하고 장기 작업을 조율. [출처: 라즈베리 파이 에이전트 하네스 구동 후기]
장기 실행 에이전트의 지속성(Durability)은 모델의 지능이 아닌 Temporal과 같은 외부 durable execution 플랫폼 백본을 통한 엔지니어링의 영역이다. [출처: raw/일주일 동안 지속 실행되는 에이전틱 시스템 구축하기.md]
에이전트 제어권을 잃지 않기 위해 실제 상태(Real state)는 Git 리포지토리와 물리적인 정형 상태 파일(체크리스트, 의사결정 로그) 형태로 컨텍스트 윈도우 바깥에 보존되어야 한다. [출처: raw/일주일 동안 지속 실행되는 에이전틱 시스템 구축하기.md]
에이전트가 예산 한도를 초과해 요금을 폭주시키지 않도록 사이클 실행 전 비용 가버너(Budget Governor)를 통해 예산 잔액을 검증해야 하며, Fareed Khan의 ‘lra’ 패키지 실무 미션에서는 400달러 ceiling 중 178.60달러만을 사용하는 비용 가버너를 적용했다. [출처: raw/일주일 동안 지속 실행되는 에이전틱 시스템 구축하기.md]
Terminal Bench 2.0 성능 격차: 모델 가중치는 그대로 두고 하네스 인프라(오케스트레이션 루프, 컨텍스트 관리, 검증 미들웨어 등)만 튜닝하여 점수를 52.8%에서 66.5%로 (+13.7포인트) 향상시켰으며, 메타 하네스로 최적화 시 76.4%를 달성함.
Vercel SQL 에이전트 도구 축소: 15개 이상의 마이크로 툴 중 80%를 제거하고 bash execution 1개만 남겼을 때 성공률이 80%에서 100%로 상승하고, 속도는 3.5배 빨라졌으며 토큰은 37% 절감됨.
연쇄 실패의 수학 (Step Reliability): 개별 도구 호출의 신뢰도가 99%여도 10단계에서 90.4%, 50단계에 다다르면 최종 성공률이 60.5%로 수렴하여 하네스의 에러 복원력이 필수가 됨.
Claude Code 유출 규모: 2026년 3월 유출본 기준 1,906개 파일, 513,000줄(51.3만 줄)의 TypeScript 코드로 구성되어 있었으며, 모델 가중치 없이 오직 주변 인프라(Harness)로만 경쟁력을 형성함.
자가 검증 루프(Verification Loops): 에이전트에게 자체 테스트 팩을 수행하고 실패 결과를 피드백하여 교정할 기회를 주면 최종 아웃풋 품질이 2~3배 상승함 (Boris Cherny 실무 검증).

상세

1. 에이전트 하네스의 11대 아키텍처 구성 요소 (11 Components)

프로덕션 환경의 에이전트는 다음 11가지의 유기적으로 연결된 모듈을 통해 상태와 제어권을 통제받는다.

오케스트레이션 루프 (Orchestration Loop): Thought ➡️ Action ➡️ Observation으로 순환하는 ReAct 루프를 구동하고, 루프가 탈선하지 않도록 종료 조건을 모델이 아닌 하네스 엔진 수준에서 하드 가이드한다.
도구 레이어 (Tool Layer): 도구 등록, 스키마 유효성 검증, 샌드박스 실행 및 결과 포맷팅을 처리한다. 호출 전후에 승인과 감사를 실행할 수 있는 Pre/Post-tool hooks를 장착한다.
메모리 시스템 (Memory Systems): 컨텍스트 윈도우 내 단기 기억(Short-term), Vector DB나 지식 그래프 기반 장기 기억(Long-term), 성공/실패했던 문제 접근법을 기록하는 에피소드 기억(Episodic)을 계층화하여 서빙한다.
컨텍스트 관리 (Context Management): 입력 길이에 따른 지능 저하를 막기 위해 대화 압축(Compaction), 오래된 결과 마스킹(Observation Masking), JIT 검색(JIT Retrieval), 서브 에이전트 위임(Sub-agent Delegation) 등의 요약 룰을 작동한다.
프롬프트 구성 (Prompt Construction): 캐시 효율을 위해 정적 프리픽스(Static Prefix)를 맨 앞에 두고 동적 컨텍스트(Dynamic Context)를 뒤에 두어 조립하며, 충돌 시 우선순위 계층(Priority Hierarchy)을 강제한다.
출력 파싱 (Output Parsing): 단순 문자열 파싱 대신 정형 API(Tool call) 또는 최종 답변(Final Answer), 타 에이전트 이관(Handoff)의 3가지 분기를 Pydantic과 같은 스키마로 검증하고 에러 피드백을 전달하는 Error-aware retry 루틴을 둔다.
상태 관리 (State Management): 장기 가동 중 런타임이 붕괴해도 재개할 수 있도록 각 단계 완료 시점마다 직렬화 상태를 저장하는 Durable Checkpoints를 보존한다.
오류 처리 (Error Handling): 실패율을 차단하기 위해 도구 오용 시 Validation 피드백, API 오류 시 지수 백오프(Exponential Backoff), 통제 불가 시 서킷 브레이커(Circuit Breaker)를 탑재한다.
가드레일 & 보안 (Guardrails & Safety): 민감 데이터, 시스템 파일, 외부 통신망의 3대 치명 권한이 겹쳐 터지지 않게 분리 통제하며, 파괴적인 액션 직전에는 HITL(Human-In-The-Loop) 게이트를 거치게 설계한다.
검증 루프 (Verification Loops): 작성된 코드를 테스트 팩(pytest, jest 등) 및 정적 분석기(Ruff, ESLint)로 기계적 검증하여 자가 교정을 시도하는 루프를 중재한다.
서브 에이전트 조율 (Subagent Orchestration): 대규모 프로젝트 시 특정 역할(기획, 코딩, 리뷰)을 쪼개어 독립된 에이전트 런타임에 이관하고 결과 요약만 공유해 메인 컨텍스트를 보호한다.

2. 에이전트의 5대 실패(Crash) 모드와 하네스 방어선

무한 루프(Infinite loops): 동일 상태에서 무의미한 도구 호출을 반복하는 모드. max_steps 하드 가이드로 해결한다.
도구 오용(Tool misuse): 모델이 헛소리로 도구 인자값을 입력하는 모드. Pydantic이나 JSON Schema를 통한 강제 스키마 검증(Validation Loop)을 두고, 오류 발생 시 모델에 피드백을 전달해 스스로 교정하도록 설계한다.
비용 폭주(Runaway costs): 유료 API의 재시도가 제어되지 않고 소모되는 모드. Exponential backoff 및 retry limit을 지정하고, 임계치가 넘을 시 도구를 정지하는 서킷 브레이커(Circuit Breaker)를 도입한다.
비영속성 실행(Non-durable execution): 런타임 크래시 시 모든 진행 상황이 유실되는 모드. 각 도구 호출 완료 단계마다 상태를 직렬화해 Checkpoint DB에 백업한다.
프롬프트 주입(Prompt injection): 악성 외부 입력을 실행해 시스템을 파괴하는 모드. 도구 허용 목록(Allowlist), 실행 전 입력 검사 필터링, 그리고 파괴적 명령어 실행 시 사람의 직접 승인을 강제하는 human-in-the-loop gate를 둔다.

3. 하네스 엔지니어링의 핵심 지표 및 실무 검증 사례

Terminal Bench 2.0 성능 격차: LangChain 연구팀이 모델 가중치를 전혀 손대지 않고, 오케스트레이션 루프, 컨텍스트 매니지먼트, reasoning budget 등 하네스 인프라만 튜닝했더니 벤치마크 점수가 52.8%에서 66.5%로 (+13.7포인트) 상승하여 리더보드 Top 5에 진입했다. 하네스 구성을 최적화하는 메타 하네스(Meta-Harness) 활용 시 **76.4%**까지 상승했다.
Vercel SQL 에이전트 도구 축소 사례: 당초 15개가 넘는 세분화된 도구를 가졌으나, 이를 단 1개의 bash 실행 도구로 통폐합했더니 성공률이 80%에서 100%로 상승하고 속도는 3.5배 빨라졌으며 토큰 소모량은 37% 감소했다. 모델에 좁고 자잘한 도구를 쥐여주는 것은 오히려 추론의 성능을 저해한다.
연쇄 실패의 수학 (Step Reliability): 개별 툴 콜의 신뢰도가 **99%**로 매우 높더라도, 10단계 태스크의 성공률은 **90.4%**로 떨어지며, 프로덕션에서 흔한 50단계가 되면 성공률은 **60.5%**까지 급감한다. 이 때문에 단 한 번의 에러로 전체 흐름이 깨지지 않게 실패를 복원하는 하네스의 내충격성(Fault-tolerance)이 필수다.
Lost in the Middle (Stanford 연구): Stanford 대학 연구팀에 따르면 모델의 컨텍스트 윈도우 한계에 닿기 훨씬 전부터, 본문 중간에 배치된 지식을 추론하고 인출하는 정확도가 30% 이상 급감한다 (Context Rot 현상). 따라서 Position-aware 컨텍스트 설계와 요약 압축은 필수적이다.
Surrounding Engineering의 부피: 2026년 3월 유출된 Claude Code의 소스코드는 무려 1,906개 파일, 513,000줄에 달하는 TypeScript로 이루어져 있었는데, 여기에는 단 한 줄의 모델 가중치도 포함되어 있지 않았다. 에이전트의 실무 경쟁력은 모델 그 자체보다 51만 줄에 달하는 하네스 코드에서 결정됨을 뜻한다.

3. 모델 수준의 하네스 흡수 (Harness Absorption by Models)

추론 모델의 제어권 내재화: Anthropic의 Opus 4.8이나 OpenAI O1/O3 계열과 같이 강화 학습(RL)과 생각의 사슬(CoT) 연산을 사후 학습에 고밀도로 탑재한 모델들은, 도구 호출 시 인자 포맷팅 결함이나 예외 발생 시 외부 코드가 개입하지 않아도 모델 내부 추론 루프에서 스스로 에러를 인지하고 교정하여 재시도한다.
개발 오버헤드 축소: 예전에는 복잡한 LangChain 루프나 커스텀 Pydantic 검증 파이프라인을 구축해 에러를 수습했으나, 이제는 간단한 도구 명세만 쥐어주면 모델 가중치 수준에서 자율 디버깅을 완수한다.
외부 통제 경계의 중요성: 이와 같은 트랜드로 인해 개발자가 짜야 할 외부 하네스는 단순 프롬프트 가드나 JSON 재시도 루프에서 탈피한다. 대신 모델 내부 가중치가 절대 우회하거나 변조할 수 없는 하드웨어 샌드박스, 금융 크레딧 고정(Ceiling), **실제 사용자 인증 게이트(HITL)**처럼 시스템 외부의 물리 보안 경계를 방어하는 형태로 한정되어야 한다.

4. 멀티 에이전트 분할 (Multi-Agent Decomposition) 설계

(이하 기존과 동일)

역할 분할 및 상태 연동: 실라버스 설계, 본문 작성, 퀴즈 설계 등 단계를 쪼개어 각각 독립된 에이전트가 이를 담당하게 하고, 중앙의 상태 스키마(State Object)를 거쳐 데이터를 연속적으로 이행(LangGraph 등 활용)한다.
최적 모델 및 도구 매칭: 무거운 논리 구조를 짤 때는 Reasoning 모델을, 본문 작성에는 저렴하고 신속한 모델을, 최종 문서/슬라이드 렌더링 단계에는 확정적 규칙 코드를 배치하여 효율성을 극대화한다.
안티 슬롭(Anti-slop) 검토기 및 휴먼 인 더 루프: 각 에이전트의 중간 출력물 전환 시점에 AI Slop(기계적인 반복 어구, 상투적 서사)을 걸러내는 자동 검토 필터를 배치하고, 핵심 기획안 수립 직후 사람의 수정과 승인을 거치는 휴먼 승인 게이트(Human Approval Gate)를 하네스 수준에서 제어한다.

5. 지속성 실행 백본 (Durable Execution Backbone)

(이하 기존과 동일) 일주일 단위의 장기 작업을 중단 없이 실행하기 위해, 에이전트 루프는 단순 파이썬 프로세스를 넘어 **Temporal**과 같은 지속성 실행(Durable Execution) 플랫폼을 백본으로 삼아 구동된다.

Workflow와 Activity의 격리: 전체 제어 흐름을 결정론적인 ‘워크플로우(Workflow)‘와 비결정론적인 ‘액티비티(Activity)‘로 이분화한다. 워크플로우 코드는 일체의 외부 API 호출이나 무작위 연산을 배제하고 순수 상태 전이만 처리하여, 시스템 크래시 시 과거 히스토리 저널링(Journaling) 데이터를 바탕으로 리플레이(Replay)해 이전과 100% 동일한 상태로 메모리를 복원한다. 파일 쓰기, 네트워크 통신 등 불확실한 실무는 모두 액티비티로 위임하며, 성공한 액티비티 결과는 캐시에 저장되어 리플레이 시 토큰 낭비나 중복 작업 없이 즉시 복원된다.
지속성 있는 대기 (Durable Sleep): 대기 상태(예: 야간 비기동 또는 수동 승인 대기) 진입 시 클라우드 분산 타이머로 워크플로우를 잠재운다. 서버 리소스를 소모하지 않아 비용이 발생하지 않으며, 서버 재부팅 시에도 정확히 지정된 시간에 기상하여 재개된다.
신규 실행 계속 (Continue-As-New): 장기 가동에 따른 수만 건의 이벤트 로그 누적으로 메모리가 고갈되는 문제를 막기 위해, 주기적으로 중간 진척도를 압축하고 최소한의 상태 스냅샷만 쥔 채 워크플로우를 새로 시작(continue_as_new)한다.
클레임 체크 (Claim-Check) 패턴: LLM 출력 본문이나 대용량 테스트 로그를 그대로 이벤트 저장소에 넣으면 데이터베이스가 붕괴한다. 대형 페이로드는 외부 오브젝트 스토리지에 봉인하고, 워크플로우 내에는 조회용 키값(영수증)만 기록하는 아키텍처를 채택한다.

6. 안전 및 금융 가드레일 (Safety & Financial Guardrails)

에이전트가 통제를 벗어나 무제한 요금을 청구하거나 시스템에 치명적인 파괴 행위를 하는 것을 방지하기 위해, 하네스는 프롬프트가 아닌 코드 레이어에서 강제되는 보안 정책을 적용한다.

비용 가버너 (Budget Governor): 매 사이클 실행 직전 authorize_next 게이트를 통해 요금을 검증한다. 이전의 사이클당 평균 비용 소모를 기준으로 차기 예상 비용을 산정하고, 설정된 예산 한도(Ceiling)를 초과할 가능성이 감지되면 allow를 차단하고 루프를 기동 취소 및 셧다운한다.
무한 루프 탐지기 (Loop Detector): 에이전트가 버그에 막혀 제자리걸음을 하는 현상을 차단한다. 이전 사이클의 코드 수정 내용(action)과 그 시점의 상태(state) 정보의 해시값(지문 시그니처)을 매핑하고, 동일 행위가 임계치(예: 4회)를 넘어 기계적으로 무한 반복되면 즉시 차단기(Trip)를 올린 뒤, 주 에이전트를 대기시키고 리뷰어 에이전트를 긴급 소환하는 구조 요청(Escalation)을 보낸다.
2인 통제 규칙 (The Rule of Two) 기반 보안: 메타(Meta) 보안 엔지니어링 팀의 설계 사상에 입각하여 소프트웨어 보안의 3대 치명 권한을 격리 통제한다:
1. 검증되지 않은 외부 입력 (Untrusted content)
2. 기밀 정보 조회 (Private data)
3. 외부 인터넷망 데이터 송출 (External comms) 위 3대 위험 요소가 한 프로세스에 동시에 겹쳐 폭발하지 않도록 하드웨어/코드 레이어 규제를 적용하고, 기본적으로 아웃바운드 인터넷을 차단(Egress default-deny)하며, 위협적인 행위 수행 시 사람의 승인을 받는 HITL(Human-In-The-Loop) 게이트를 강제한다.

7. 에이전트의 4대 구성 요건 상세

명시적 State Schema: 채팅 히스토리 문자열 단순 전달이 아닌 전체 목표, 마지막 도구 결과, scratchpad, 중간 데이터를 구조화하여 추적하는 state object를 쥐어주어 진행 상황을 추론하게 한다.
Policy Engine 기반 행동 선택: 모델이 텍스트 생성이 아닌 router로 기능하도록 하여 도구 호출 / 질문 요청 / state 갱신 / 작업 종료 분기를 자율 제어한다.
예산 가이드라인 (Budgets): 무한 루프 탈선 시 비용 폭주를 차단하기 위해 max_steps 하드 리밋(예: 10 steps), timeout 시간 제한, 비용 상한선, 도구별 retry limit을 강제 제어한다.
지속성 및 멱등성 (Durable & Idempotent): 런타임 pod 재시작 시 정보 유실을 방지하기 위해 Postgres/Redis에 각 단계별 상태를 저장(durable checkpoints)하며, 이메일 재발송 등 중복 행동이 없도록 도구 호출 멱등성을 하네스 단에서 보장한다.

하네스 도입 프로세스 (Map-Identify-Blueprint-Implement-Launch)

Map: 도메인 식별, 자율성 수준(Level 0~4), 위험 분류(read_only, draft, external_write), 외부 시스템 맵핑.
Identify: 난이도에 알맞은 에이전트 블루프린트 레벨 선택.
Blueprint: 목표, 도구 레지스트리, 권한 매트릭스, 메모리 계층, 스킬 청사진 작성.
Implement: 뼈대와 검증 경로(Validation Path)부터 점진적으로 구현.
Launch: 예산(Step/Time/Token/Cost) 강제 여부, 주입 및 타임아웃 평가, Tracing 로그 점검 후 론칭.

Opus 4.8의 하네스 기능 내재화

정직성(L4 검증): 모델 스스로 코드 오류를 감지해내는 자가 크리틱 가중치가 이전 4.7 대비 4배 향상.
동적 워크플로(L3 실행): 계획-디스패치-검증-보고의 병렬 서브에이전트 제어를 Claude Code 런타임 및 API 수준에서 일괄 처리.
노력 제어(L1 제약): effort control(low, high, extra, max 4단계, 기본 high)을 통해 모델 라우팅 및 비용 제어를 단순화. 빠른 모드(/fast)는 속도 2.5배 향상, 비용 3배 절감.
해자의 이동: 배관 인프라가 범용화(commodity)됨에 따라, 벤더가 탈취할 수 없는 보안 데이터, 지능형 메모리 설계(L2), 그리고 비즈니스 정의 기반 Evals/관제 파이프라인(L5)이 차별점의 핵심 보루가 된다.

라즈베리 파이 4 기반 하네스 환경 구축 실무

물리적 격리: 터미널 및 브라우저 자동화 등 에이전트 자율 권한을 24시간 가동할 때 호스트 시스템 보호를 위해 RPi 4를 Ephemeral Sandbox 대안으로 사용. 마이크로 SD 카드를 분리 운영하여 유사시 즉각 포맷 리셋하도록 구성.
주요 도구 비교:
- Claude Code: 컨텍스트 관리가 직관적이며, 로컬 Obsidian 볼트 연동과 CLAUDE.md 스킬 제어 적합.
- OpenClaw / Hermes: 터미널/파일시스템/메시징 권한 오케스트레이션 수행. Hermes가 상대적으로 더 안정적인 기동과 구성을 보여줌.

Temporal 기반 Durable Execution 백본

일주일 이상 지속 기동되는 장기 실행 에이전트를 안정적으로 구축하려면, 에이전트 제어 루프를 Temporal 백본으로 설계하여 지속성 실행을 실현해야 합니다.

워크플로우와 액티비티 격리: 순수 비즈니스 상태 전이만을 처리하고 비결정론적 행위를 배제한 ‘워크플로우(Workflow)‘와, 실제 파일 쓰기나 모델 API 호출 등의 불확실성을 담당하는 ‘액티비티(Activity)‘로 코드를 격리합니다. 워크플로우의 실행 이력은 저널링(Journaling)되어 크래시 발생 시 리플레이(Replay)를 통해 100% 이전 메모리 상태로 자동 복원됩니다.
지속성 있는 대기 (Durable Sleep): 태스크가 없거나 인간의 승인을 기다려야 하는 대기 시 분산 타이머를 작동시켜 프로세스 리소스를 0으로 유지하면서도, 가상 서버가 재부팅되어도 정확한 기상 시간을 기억해 복귀합니다.
신규 실행 계속 (Continue-As-New): 수만 건의 이벤트 로그가 한 파일에 쌓여 메모리가 터지는 것을 막기 위해, 주기적으로 중간 요약본만 쥔 채 완전히 새 워크플로우로 리기동 (continue_as_new)합니다.
클레임 체크 코덱 (Claim-Check Codec): 거대한 파일 페이로드나 상세 실행 로그는 외부 오브젝트 스토리지에 저장하고, 워크플로우 이벤트 저장소에는 영수증(조회용 키값)만 기록하여 DB 붕괴를 예방합니다.
사가(Saga) 패턴: 에이전트 작업 실패 시, 이전에 성공했던 이메일 발송 등 외부 쓰기 작업을 롤백하거나 취소하기 위해 보상 트랜잭션(Compensating Transactions)을 자동으로 실행하는 사가 엔진을 장착합니다.

1. 하네스 인프라의 파괴력 입증 지표

LangChain Terminal Bench 2.0 실험: 모델의 성능 개량 없이 오케스트레이션, 검증 레이어, 예산 통제를 담당하는 하네스 튜닝만으로 리더보드 순위가 30위 밖(52.8%)에서 Top 5(66.5%)로 껑충 뛰어올랐다.
Vercel SQL 에이전트의 툴 다이어트: 자잘한 도구를 늘리는 것은 모델의 추론 검색 공간을 늘려 오작동을 야기한다. 툴의 80%를 도려내고 범용 bash 툴로 대체하여 성공률 100%와 3.5배 속도 향상을 이루어 냈다.
Claude Code 51만 줄 TypeScript: 2026년 3월 유출본 분석 결과, 에이전트의 압도적 프로덕션 성능은 모델 가중치가 아니라 51.3만 줄에 달하는 정교한 하네스 인프라(상태 제어, 린터 통합, git diff 추적 등)에서 기인한다.

2. 컨텍스트의 감쇠와 Lost in the Middle

Chroma 및 Stanford 대학의 연구에 따르면, 컨텍스트가 길어질수록 윈도우 중간에 위치한 정보 활용 신뢰도가 30% 이상 붕괴하는 현상(Context Rot)이 규명되었다. 하네스는 이를 방어하기 위해 JIT 검색, sliding-window compaction, position-aware context injection을 강제해야 한다.

예시

coding agent: AGENTS.md를 읽고, 필요한 파일만 찾고, 테스트를 돌리고, 실패 시 다시 수정하는 loop 전체가 harness다.
research agent: 검색 결과를 전부 context에 넣지 않고 memory index와 JIT retrieval로 필요한 근거만 불러온다.
enterprise agent: pre-tool hook으로 승인 흐름을 넣고 post-tool hook으로 audit log를 남긴다.

예시

pydantic-ai 기반 가드레일 에이전트 구축: TripContext를 메모리 의존성(deps)으로 주입하고, LLM 출력을 TripItinerary Pydantic 클래스 형식으로 자동 강제 검증하며, Logfire tracing 연동 및 validation error 발생 시 자동 retry(최대 2회)를 탑재한 파이썬 에이전트 빌드 코드 구현.

CLAUDE.md 단독 사용과 Harness 비교

CLAUDE.md 단독 (Before): ‘사용자 인증 API 구현’ 지시 시, NextAuth.js 기존 정책 무시, 비밀번호 평문 로그 출력(보안 위반), 에러 응답 불일치, 테스트 없음 등 세션마다 품질이 크게 흔들림.
Harness 환경 (After): progress.md 메모리로 이전 결정을 복원하고, /add-feature 스킬로 테스트를 강제하며, Biome 포맷터 및 console.log 감지 훅이 즉각 개입하여 typecheck 및 tests 통과 시점에만 머지함.

Canonical Agentic Loop 의사코드

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50)
context = build_initial_context()
permissions = load_permission_matrix()
 
while not budgets.exhausted():
    response = model.generate(context, tools=typed_tool_schemas)
    if response.finish_reason == "stop":
        break
    if response.tool_calls:
        for tool_call in response.tool_calls:
            if not permissions.is_allowed(tool_call):
                observation = "Permission denied: " + tool_call.name
            else:
                if permissions.risk(tool_call) == "external_write":
                    approval = request_human_approval(tool_call.draft)
                    if not approval:
                        observation = "Human rejected: " + tool_call.name
                    else:
                        observation = execute_tool(tool_call)
                else:
                    observation = execute_tool(tool_call)
            context.append(observation)
        if context.token_count() > budgets.token_per_turn:
            context = compact_context(context, preserve_approvals=True)
    else:
        break

L1/L3/L4 레이어의 리팩터링 및 걷어내기 가이드

L4 검증: 불완전 코드를 필터링하기 위해 별도로 띄웠던 크리틱 모델 게이트를 제거하고 Opus 4.8의 자체 교정 가중치를 우선 이용.
L3 실행: 직접 짠 fan-out/planner 배관 대신 플랫폼이 제공하는 동적 워크플로 위임을 검토하여 Undifferentiated heavy lifting을 차단.
L1 제약: 복잡한 라우터 코드 대신 /fast 스위치 및 effort control 옵션 활용.

라즈베리 파이 하네스 초기 환경 설정 명령어

sudo apt update && sudo apt upgrade -y
# 각 하네스 도구 CLI 표준 curl 설치 수행

LRA (Long Running Agents) 패키지 CLI 기동 예제

# 설치 및 환경 정보 출력
uv sync  
uv run lra version  
uv run lra config
  
# 비용이 들지 않는 stub 모델을 활용해 로컬 샌드박스에서 태스크 실행
uv run lra mission --task "hello를 출력하는 hello.py와 이에 대한 테스트 코드를 작성해라" \
                   --workdir .lra/workspaces/demo

ChecklistItem Pydantic 스키마 정의

class ChecklistItem(BaseModel):  
    id: str  
    description: str  
    status: Literal["todo", "in_progress", "blocked", "done"] = "todo"
    verified_by: list[str] = Field(default_factory=list)  # 감사 추적용 검증기 ID
    depends_on: list[str] = Field(default_factory=list)   # 의존하는 타 항목 ID
    attempts: int = 0                                     # 시도 횟수
    notes: str = ""
    schema_version: int = 1

Canonical Agentic Loop 의사코드:

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50)
context = build_initial_context()
permissions = load_permission_matrix()
 
while not budgets.exhausted():
    response = model.generate(context, tools=typed_tool_schemas)
    if response.finish_reason == "stop":
        break
    if response.tool_calls:
        for tool_call in response.tool_calls:
            if not permissions.is_allowed(tool_call):
                observation = "Permission denied: " + tool_call.name
            else:
                if permissions.risk(tool_call) == "external_write":
                    approval = request_human_approval(tool_call.draft)
                    if not approval:
                        observation = "Human rejected: " + tool_call.name
                    else:
                        observation = execute_tool(tool_call)
                else:
                    observation = execute_tool(tool_call)
            context.append(observation)
        if context.token_count() > budgets.token_per_turn:
            context = compact_context(context, preserve_approvals=True)
    else:
        break

충돌

현재 확인된 충돌 없음.

LLM Wiki

탐색기