하네스 엔지니어링 웹 리서치

1. 소스별 핵심 요약

1-1. madplay.github.io (한국어 블로그)

하네스 = 에이전트를 둘러싼 스캐폴딩, 제약, 피드백 루프 전체 환경
핵심 전환: 코드를 직접 짜는 것 -> 에이전트가 일할 환경을 설계하는 것
구성 요소: Context Files(CLAUDE.md), MCP 서버, Skill 파일, 기계적 강제(린터/구조 테스트), 자동 가비지 컬렉션
실증: OpenAI Codex 실험에서 5개월간 100만 줄 생성, 1,500+ PR 머지, 수동 코드 제로
결정적 증거: Hashline 편집 포맷만 변경(하네스만 수정, 모델 동일)으로 벤치마크 6.7% -> 68.3% 향상
원칙: "에이전트 성능 병목은 모델 지능이 아니라 환경 설계다"

1-2. brunch.co.kr/@aimuse/84 (실전 가이드)

3가지 실패 유형 분류 체계:
방향 실패(Direction): 근본적으로 잘못된 출력, 핵심 요구사항 누락
실행 실패(Execution): 방향은 맞지만 버그/미완성
품질 실패(Quality): 기능은 되지만 기준 미달
3-에이전트 구조: Planner -> Generator -> Evaluator
역할 분리 원칙: 인지적 충돌이 있는 역할을 분리(만드는 것 vs 평가하는 것)
평가자 강화: 기본 Claude는 너무 관대함 -> 회의적 태도 명시, Playwright로 실제 UI 테스트, 경계값 커트오프 설정
스프린트 계약: 실행 전에 테스트 가능한 성공 기준 합의
반복 사이클: Generator-Evaluator를 5-15회 반복, 중간 결과 보존(마지막이 항상 최선은 아님)
경량화: 체계적 컴포넌트 제거(한 번에 하나씩 빼며 영향 측정)

1-3. blog.risemoment.ai

Mitchell Hashimoto 정의: "에이전트가 실수하면 그 실수가 다시는 일어나지 않도록 엔지니어링하는 것"
3대 핵심 구성:
도구 통합/오케스트레이션 (API, 파일시스템, DB 연결)
가드레일/제어 메커니즘 (도구 호출 인터셉트, 출력 검증, 위험 작업 승인)
컨텍스트 관리/메모리 설계 ("런타임에 접근 불가한 정보는 존재하지 않는 것과 같다")
5단계 구현 프로세스: 문서화 -> 아키텍처 제약 -> 피드백 루프(CI/CD, 린터) -> 검증 메커니즘 -> 실패 신호 기반 반복
2026년 핵심 전환: 모델 정교함이 아니라 하네스 품질이 조직의 해자(moat)

1-4. channel.io (채널톡 블로그)

가드레일: 입출력 필터링(프롬프트 인젝션, 환각, 기밀 유출 방지)
데이터 거버넌스: 민감정보 탐지/익명화, 역할 기반 접근 제한
모니터링/피드백 루프: 실시간 에러 감지, 성능 메트릭 수집
관련 프레임워크: Meta Llama Guard, NVIDIA NeMo Guardrails
주의: 개념적 개요 수준이며, eval 파이프라인이나 hooks 구현 상세는 없음

1-5. shuntailor.net (일본어 가이드, 40+ 참조문헌)

4대 기능적 기둥: Constrain(제한) / Inform(알림) / Verify(검증) / Correct(교정)
Eval-Driven Development(EDD): TDD의 확률적 버전. 평가 하네스를 에이전트 로직보다 먼저 작성
PreCompletionChecklist 구현 항목:
테스트 스위트 자동 실행
생성 코드 구문 검증
보안 스캔(하드코딩된 자격증명, 위험한 syscall)
성능 프로파일링(실행 시간, 메모리)
출력 일관성 검사(스키마/포맷 매칭)
실패 패턴 감지: 트레이스 수집 -> 분류(환각/도구 오용/논리 에러) -> 실패 클래스별 예방 제약 추가
Hashimoto의 Ghostty: "과거 실수 하나당 예방 한 줄"
이중 메모리 아키텍처: 에피소드 메모리(세션 내) + 워킹 메모리(압축) + 장기 메모리(CLAUDE.md, git) + 외부 메모리(코드베이스)
5단계 적응적 압축: 요약 -> 중복 제거 -> 통합 -> 메모리 압축 -> 저우선 콘텐츠 폐기
샌드박싱 계층: MicroVM(최대 격리) > gVisor(10-20% 오버헤드) > 강화 컨테이너(5-10%)

1-6. 추가 검색 소스 (HumanLayer, MorphLLM, DEV.to 등)

HumanLayer - Skill Issue 블로그: - CLAUDE.md 60줄 이하 유지, LLM이 자동생성한 버전은 성능 20%+ 하락 - ETH Zurich 연구: 잘못 설계된 컨텍스트 파일은 14-22% 추가 추론 토큰 소비하면서 해결률은 향상 없음 - hooks = 라이프사이클 이벤트에서 실행되는 사용자 정의 스크립트 (exit code 2 = 에이전트 재개입) - 역압(Back-Pressure) 메커니즘: 성공은 무시, 에러만 표시 -> 컨텍스트 오염 방지 - CLIs > MCP: 학습 데이터에 있는 기능은 MCP보다 CLI가 더 나음

MorphLLM - IMPACT 프레임워크: - Intent(목표 검증) / Memory(세션 간 일관성) / Planning(편집 가능 계획) / Authority(신뢰/권한) / Control Flow(LLM 주도) / Tools(RAG, 샌드박스) - 에러 복구 계층: 재시도 -> git 체크포인트 롤백 -> 서브에이전트 분해 -> 사람에게 에스컬레이션 - Spec-Driven: 코딩 전 상세 spec.md 작성으로 에이전트 드리프트 방지 - Apply Layer: 추론과 파일 머지를 분리하는 전문 모델

2. Eval 파이프라인 구축법

2-1. Eval-Driven Development (EDD)

TDD를 확률적 시스템에 맞게 변형한 접근법: 1. 에이전트 로직 전에 평가 하네스 먼저 작성 2. 이진(pass/fail) 대신 확률적 임계값 설정 (AI 출력은 비결정적) 3. 최종 출력이 아닌 전체 실행 트레이스 기반 디버깅

2-2. 평가 파이프라인 성숙도 수준

레벨	상태	커버리지
0	배포 전 수동 테스트	0%
1	결정적 검사 + 수십 개 eval 케이스	~30%
2	자동화된 eval + 회귀 테스트	~60%
3	프로덕션 트래픽 기반 eval	~80%
4	연속 eval + 자동 레드팀	95%+

대부분의 팀은 레벨 0-1에 머무름. 세계 최고 수준이 레벨 4.

2-3. 3단계 평가 구조 (brunch.co.kr)

Planner ──> Generator ──> Evaluator
  (방향)      (실행)        (품질)
    ^                        |
    └────── 피드백 루프 ──────┘

Planner: 고수준 계획, 스코프 방지
Generator: 저수준 구현
Evaluator: 메타 수준 평가, 회의적 태도 필수
5-15회 반복, 중간 결과 보존

2-4. 평가 기준 설계 핵심

품질을 독립적 축으로 분해 (통합 메트릭 지양)
각 기준별 긍정/부정 구체 예시 제공
모델의 약점에 가중치 부여 (강점이 아닌)
few-shot 예시로 점수 부여 기준 캘리브레이션
평가 기준 언어가 생성기 행동을 조종한다는 인식

3. PreCompletionChecklist 패턴

3-1. 체크리스트 항목

에이전트가 "완료"를 선언하기 전에 자동으로 실행되는 검증:

테스트 스위트 실행: 생성된 코드에 대해 기존 테스트 + 새 테스트 자동 실행
구문 검증: 문법 오류, 타입 에러 검사
보안 스캔: 하드코딩된 자격증명, 위험한 시스템 호출 탐지
성능 프로파일링: 실행 시간, 메모리 사용량 측정
출력 일관성: 기대 포맷/스키마 일치 여부
린트/빌드 확인: 린터 통과 + 빌드 성공 여부

3-2. 구현 방법 (hooks 기반)

[에이전트 작업 완료 선언]
       |
   PreToolUse/Stop hook 발동
       |
   ┌───┴───┐
   │검증 스크립트│ (테스트, 빌드, 린트, 보안 스캔)
   └───┬───┘
       |
  exit code 0 → 통과, 완료 허용
  exit code 2 → 실패, 에이전트 재개입 (에러 내용이 컨텍스트에 주입)

3-3. 핵심 원칙

성공은 무시, 에러만 표시: 컨텍스트 오염 방지를 위해 통과 결과는 에이전트에게 보여주지 않음
부분 실행: 전체 테스트 스위트가 아닌 관련 서브셋만 실행 (자원 효율)
에러 메시지에 교정 지시 내장: 린터/테스트 에러 메시지 자체가 에이전트에게 수정 방향 제시

4. 실패 패턴 감지

4-1. 3대 실패 유형

유형	설명	대응 하네스
방향 실패	근본적으로 잘못된 결과물, 스코프 축소	Planner 강화, 스프린트 계약
실행 실패	방향은 맞지만 버그/미완성	Evaluator + 테스트, 빌드 검증
품질 실패	기능은 되지만 기준 미달	반복 개선 루프, 채점 기준 세분화

4-2. 흔한 에이전트 실패 패턴

컨텍스트 고갈: 모든 걸 한번에 해결하려다 컨텍스트 바닥남 -> 절반만 구현
조기 종료: 어느 정도 진행 후 "다 됐다" 선언 -> PreCompletionChecklist로 방지
거대 파일 함정: 모든 지시를 한 파일에 넣으면 에이전트가 규칙을 무시하고 패턴 매칭으로 후퇴
도구 과잉: 너무 많은 도구 등록 -> "멍청 구간(dumb zone)" 진입 (ETH Zurich 연구)
컨텍스트 부패: 긴 세션에서 중간 노이즈가 누적 -> 서브에이전트로 격리
환각/도구 오용/논리 에러: 트레이스 수집 후 각 클래스별 예방 제약 추가

4-3. 감지 메커니즘

트레이스 기반 디버깅: 최종 출력이 아닌 전체 실행 과정 검사
에러 메시지 = 교정 지시: 린터/테스트 실패 메시지가 에이전트 컨텍스트에 직접 주입
Hashimoto 규칙: 관찰된 실패 하나당 예방 장치 하나 추가 (Ghostty 프로젝트 사례)
체계적 제거(Ablation): 한 번에 하나씩 컴포넌트 제거하여 실제 성능 영향 측정
에러 복구 계층: 재시도 -> 롤백 -> 서브에이전트 분해 -> 사람에게 에스컬레이션

5. Claude Code Hooks 활용

5-1. Hooks 개념

Git hooks와 유사하게 에이전트 라이프사이클의 특정 시점에 자동 실행되는 사용자 정의 스크립트. 보안 스캔, 린팅, 정책 강제, 외부 서비스 통합에 활용.

5-2. 주요 hook 이벤트

이벤트	시점	용도
SessionStart	세션 시작	환경 초기화, 컨텍스트 로딩
UserPromptSubmit	사용자 입력 후	입력 검증, 라우팅
PreToolUse	도구 실행 전	권한 검사, 위험 작업 차단, 드리프트 감지
PostToolUse	도구 실행 후	결과 검증, 로깅, 품질 검사
Stop	세션 종료 시	완료 검증, 보고, 정리

5-3. exit code 규약

0: 성공, 에이전트에게 결과 표시 안 함 (컨텍스트 오염 방지)
1: 에러, 에이전트에게 에러 내용 표시
2: 실패 + 에이전트 재개입 요청 (에러 메시지가 컨텍스트에 주입되어 수정 유도)

5-4. 하네스 패턴으로서의 hooks 활용 사례

PreCompletionChecklist: Stop hook에서 테스트/빌드/린트 자동 실행 -> 실패 시 에이전트 재개입
드리프트 감지: PreToolUse hook에서 도구 호출 횟수/패턴 모니터링 -> 비정상 시 경고
보안 게이트: PreToolUse에서 위험 명령(rm -rf, DROP TABLE 등) 차단
외부 서비스 연동: PostToolUse에서 Slack/GitHub PR/프리뷰 환경에 알림
컨텍스트 관리: SessionStart에서 컴팩션 자동 실행, 장기 메모리 로딩
품질 게이트: PostToolUse에서 Edit/Write 후 자동 린트/타입체크

6. OpenClaw 시스템에 적용 가능한 것

6-1. 현재 OpenClaw hooks 현황 (16개, 5 이벤트)

이벤트	개수	현재 용도
UserPromptSubmit	1	입력 처리
SessionStart	2	초기화, 컴팩션
Stop	3	세션 종료 처리
PreToolUse	4	Bash/MCP/Read 감시
PostToolUse	6	Bash/Edit/Write/Skill 후처리

6-2. 추가해야 할 하네스 요소

우선순위 높음 (즉시 적용 가능):

PreCompletionChecklist (Stop hook 강화)
현재 Stop hook 3개에 완료 검증 로직 추가
에이전트가 "완료" 선언 전에 관련 테스트/빌드 자동 실행
exit code 2로 미달 시 재개입 강제
실패 패턴 자동 분류 (PostToolUse 확장)
에러 트레이스를 방향/실행/품질 실패로 자동 분류
분류별 대응 전략을 CLAUDE.md에 누적
Hashimoto 규칙: 실패 하나당 예방 한 줄
도구 호출 드리프트 감지 (PreToolUse 강화)
현재 4개 PreToolUse hook에 호출 패턴 분석 추가
동일 도구 반복 호출, 진전 없는 루프 자동 감지
임계값 초과 시 에이전트에 경고 주입

우선순위 중간 (설계 후 적용):

Eval 파이프라인 도입
company-research 스킬 등 주요 워크플로에 Evaluator 에이전트 추가
품질을 독립 축으로 분해한 채점 기준 설계
생성-평가 반복 루프 (3-5회)
스프린트 계약 패턴
복잡 작업 시작 전 테스트 가능한 성공 기준 합의 자동화
Plan Mode 진입 시 계약 문서 자동 생성
적응적 컨텍스트 압축
5단계 압축 전략 적용 (요약 -> 중복 제거 -> 통합 -> 압축 -> 폐기)
현재 compact hook을 확장

우선순위 낮음 (장기 과제):

Eval-Driven Development 체계화
새 스킬/파이프라인 개발 시 eval 하네스 먼저 작성하는 프로세스
확률적 임계값 기반 성공 판정
멀티세션 패턴 (Anthropic 방식)
초기화 에이전트가 환경 설정 후 코딩 에이전트가 세션당 1 기능씩 구현
progress.json으로 세션 간 상태 공유

6-3. 현재 OpenClaw가 이미 잘하고 있는 것

CLAUDE.md 계층 구조 (전역 + 프로젝트 + 메모리)
서브에이전트 병렬 실행 패턴
모델별 라우팅 (haiku/sonnet/opus)
hooks 기반 라이프사이클 관리 (16개)
드리프트 감지 기본 구현 (PreToolUse)
에러 자동 수리 + 3회 실패 시 보고 규칙

6-4. 가장 큰 갭

체계적 PreCompletionChecklist 부재: 현재 Stop hook에 완료 검증 로직이 약함
실패 패턴 누적 시스템 없음: 실패를 분류하고 CLAUDE.md에 예방책으로 누적하는 자동화 부재
Evaluator 에이전트 부재: 생성 결과를 독립적으로 평가하는 에이전트가 없음
Eval 파이프라인 미구축: 스킬/파이프라인 품질을 정량적으로 측정하는 체계 없음

참고 소스

madplay.github.io/en/post/harness-engineering
brunch.co.kr/@aimuse/84
blog.risemoment.ai/harness-engineering/
channel.io/ko/blog/articles/what-is-harness-2611ddf1
shuntailor.net/harness-engineering-guide/
humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents
morphllm.com/agent-engineering
dev.to (Claude Code harness 분석 - 만우절 풍자글로 확인, 기술 허구 포함)
github.com/Chachamaru127/claude-code-harness
github.com/EleutherAI/lm-evaluation-harness
arxiv.org/html/2603.25723v1 (Natural-Language Agent Harnesses)