본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
하네스 엔지니어링

문제 설정·구조

하네스 엔지니어링의 기초Repo-readable 시스템하네스의 5요소하네스의 기술 메커니즘

검증·해석

검증 루프 설계외부 사례 비교

사례별 도입

사례: OpenAI사례: Anthropic사례: Toss사례: gstack사례: revfactory/harness

도메인별 적용

도메인별 적용 지도시나리오: 프론트엔드 팀시나리오: 플랫폼 팀시나리오: 결제·정산 팀시나리오: AI 제품 팀왜 결국 자기 하네스로 가는가

도입·운영

팀 하네스 배포 전략팀 하네스 설계 체크리스트운영: 엔트로피와 가비지 컬렉션

부록

검증 리포트업데이트 내역
핸드북›하네스 엔지니어링›사례: Anthropic
한국어English

사례: Anthropic

Anthropic의 long-running harness를 planner/evaluator, Managed Agents, auto approval 관점에서 해부합니다.

핵심 요약

  • Anthropic 사례의 핵심 질문은 "역할을 몇 개 둘까"가 아니라 "어떤 scaffolding이 실제로 품질을 떠받치는 load-bearing인가"입니다.
  • planner·builder·evaluator·QA는 입력도 판정 기준도 제각각이라, 자기평가 편향을 떼어내는 control loop로 작동합니다.
  • Managed Agents는 session(append-only event log)·harness·sandbox를 분리해, 컨테이너가 죽어도 이벤트 로그에서 복구하고 credential을 vault·MCP proxy 뒤에 둡니다.
  • auto mode는 prompt-injection probe와 transcript classifier로 위험 행동을 검사하되, 고위험 변경의 사람 리뷰까지 대체하지는 않습니다.
  • retry budget(예: 동일 실패 3회 후 handoff)이 없으면 하네스는 품질 시스템이 아니라 토큰 소모 장치가 됩니다.

Anthropic 사례는 하네스를 "역할을 많이 두는 법"으로 보지 않습니다. 핵심 질문은 오히려 이겁니다.

어떤 scaffolding이 실제로 품질을 떠받치고 있는가?

이게 중요한 건 장시간 작업의 실패가 대개 모델 지능 부족이 아니라 스코프 과소추정, 자기평가 편향, 부실한 handoff에서 나오기 때문입니다.

2026년 3~5월 업데이트로 추가된 관점

Anthropic 사례는 이제 planner/evaluator만으로 읽으면 부족합니다. 2026년 3월 25일 Claude Code auto mode와 4월 8일 Managed Agents 글이 하네스를 다음 세 경계로 넓혔습니다.

업데이트하네스 관점의 의미
Claude Code auto mode승인 피로를 줄이되, prompt-injection probe와 transcript classifier로 위험 행동을 차단
Managed Agentssession, harness, sandbox를 독립 인터페이스로 분리해 장애 복구, 보안, 확장성을 확보
Financial agent templates도메인 템플릿을 skills, connectors, subagents, approval flow, audit log 묶음으로 배포

그래서 Anthropic의 최신 흐름은 "역할을 나눠라"보다 넓습니다. 역할, 실행 환경, 세션 로그, credential, 승인 정책을 서로 다른 실패 경계로 분리하라에 가깝습니다.

해결하려는 문제

  • builder가 너무 빨리 "끝났다"고 판단함
  • 작업이 길어질수록 목표와 현재 상태가 어긋남
  • 브라우저 검증 전에 구현이 완료 처리됨
  • 역할이 많아도 실제 load-bearing 단계가 불명확함

기술적 메커니즘

Anthropic식 하네스에서 중요한 건 역할 이름이 아니라 각 단계가 입력도 판정 기준도 다르다는 점입니다.

역할주 입력주 출력실패를 잡는 방식
Planner목표, 제약, 비목표범위와 계약스코프 누락 감소
Builder계획, 관련 파일코드/문서 수정구현
Evaluator산출물, 요구사항pass/fail, gap report자기평가 편향 분리
QA브라우저, 테스트, 로그실행 검증 결과실제 동작 확인

Managed Agents: brain, hands, session을 분리한다

Managed Agents 글에서 곧장 가져올 점은 agent를 하나의 긴 프로세스로 보지 않는다는 것입니다.

컴포넌트역할분리하지 않으면 생기는 문제
Sessionappend-only event log, 장시간 작업의 durable context컨테이너나 harness 실패 시 상태 손실
HarnessClaude 호출, tool routing, context management실행 환경과 결합되어 교체·복구가 어려움
Sandbox / hands코드 실행, 파일 수정, 외부 도구 호출credential과 생성 코드가 같은 경계에 놓임

핵심 인터페이스는 단순합니다.

type Hand = {
  execute(name: string, input: unknown): Promise<string>
}

type SessionStore = {
  getSession(id: string): Promise<Event[]>
  emitEvent(id: string, event: Event): Promise<void>
}

이렇게 나누면 실무에서 세 가지를 얻습니다.

  • sandbox나 container가 죽어도 harness는 실패를 tool result로 받아 재시도할 수 있습니다.
  • harness가 죽어도 session log에서 다시 시작할 수 있습니다.
  • credential은 sandbox 안의 생성 코드가 아니라 vault나 MCP proxy 뒤에 둘 수 있습니다.

장시간 에이전트의 상태는 "현재 컨텍스트 창"이 아니라 복구 가능한 이벤트 로그에 있어야 합니다.

auto mode: 권한 승인을 classifier로 바꿀 때의 조건

Claude Code auto mode는 permission prompt를 없애자가 아니라 모든 승인을 사람 팝업으로 처리하는 방식의 피로를 줄이자에 가깝습니다.

설계 포인트:

  • 도구 출력이 agent context에 들어가기 전에 prompt injection probe가 의심 신호를 붙입니다.
  • tool call 실행 전 transcript classifier가 사용자 의도와 실제 행동의 blast radius를 비교합니다.
  • broad shell access, wildcard interpreter, package manager run처럼 임의 코드 실행으로 빠지는 blanket allow는 auto mode 진입 시 유지하지 않는 방향입니다.
  • subagent handoff도 위임 시점과 반환 시점에 따로 검사합니다.
  • 차단되면 즉시 세션을 죽이기보다 safer path를 찾게 하고, 반복 차단 후 사람에게 넘깁니다.

과대 해석 금지

auto approval classifier는 고위험 변경의 사람 리뷰를 대신하는 만능 안전장치가 아닙니다. Anthropic 문서도 sensitive operation에는 잔여 위험이 남는다고 인정하고, 환경별 trust boundary와 deny rule을 명시하라고 말합니다.

왜 이게 엔지니어링인가

Anthropic 방식은 품질을 "모델이 잘 하겠지"로 떠넘기지 않고 역할별 편향을 분리하는 제어 루프로 다룹니다.

전형적인 시스템 설계 문제입니다.

  • planner는 초기 오판을 줄입니다.
  • evaluator는 builder의 낙관을 깨뜨립니다.
  • QA는 텍스트 기반 판정과 실제 동작을 분리합니다.
  • handoff는 상태 손실을 줄입니다.

하네스는 reasoning enhancement가 아니라 control-loop engineering에 가깝습니다.

sprint contract가 왜 중요한가

builder와 evaluator가 서로 다른 역할을 하려면 둘이 같은 계약을 참조해야 합니다.

sprint_contract:
  objective: "사용자에게 보이는 검색 패널 개선"
  done_when:
    - "모바일/데스크톱 모두 렌더링"
    - "keyboard navigation 동작"
    - "lint/typecheck/build 통과"
  non_goals:
    - "검색 API 구조 개편"
  failure_budget:
    max_fix_loops: 3
  escalation:
    - "접근성 회귀 발견"
    - "데이터 스키마 변경 필요"

이 계약이 있어야 evaluator가 "뭘 더 잘했는가"가 아니라 "무엇이 아직 증명되지 않았는가"를 판정할 수 있습니다.

load-bearing scaffolding을 판정하는 방법

Anthropic 관점에서 planner나 evaluator는 있다는 것 자체가 목적이 아닙니다. 아래 중 하나라도 반복된다면 load-bearing일 가능성이 큽니다.

  • builder가 같은 누락을 계속 반복함
  • 브라우저에서만 드러나는 문제가 자주 있음
  • release 직전 결함 발견 비율이 높음
  • 사람 리뷰가 사실상 마지막 안전장치가 됨

실무 해석

역할을 더 넣는 것이 정답이 아닙니다. builder-only 루프가 자주 놓치는 실패를 줄여주는 단계만 남기는 것이 정답입니다.

retry budget과 handoff 규칙

장시간 작업은 수정 루프가 길어지기 쉽습니다. 그래서 하네스는 보통 무한 반복 대신 제한된 반복 + 명시적 handoff를 둡니다.

type EvaluationResult = {
  status: 'pass' | 'retry' | 'handoff'
  gaps: string[]
}

function nextStep(failCount: number, highRisk: boolean): EvaluationResult['status'] {
  if (highRisk) return 'handoff'
  if (failCount >= 3) return 'handoff'
  return 'retry'
}

사소한 디테일 같지만 중요합니다. retry budget이 없으면 하네스는 품질 시스템이 아니라 토큰 소모 장치가 됩니다.

우리 팀으로 옮길 것

옮길 요소적용 방식
task/sprint contract시작 전에 완료 정의와 비목표 명시
evaluator 분리builder self-check와 독립된 gap report 만들기
retry budget동일 실패 반복 횟수 제한
browser QA handoffUI/실행 검증은 별도 단계로 분리
durable session log장시간 작업의 event log와 handoff 기록을 컨텍스트 창 밖에 남김
brain/hands 분리sandbox, MCP, 외부 도구를 독립 실행 경계로 보고 credential을 분리
classifier approval자동 허용, classifier 검토, 사람 승인, 금지 영역을 분리

그대로 복제하면 안 되는 점

  • planner/evaluator가 많다고 항상 좋은 것은 아닙니다.
  • 작은 작업까지 full pipeline으로 돌리면 비용만 늘어납니다.
  • 모델 성능이 좋아질수록 줄일 수 있는 scaffolding도 생깁니다.
  • auto mode나 Managed Agents가 있다고 고위험 도메인의 HITL이 사라지는 것은 아닙니다.

Anthropic 사례의 진짜 교훈은 "항상 복잡하게 하라"가 아니라 실험으로 load-bearing 구조만 남기고 상태·실행·권한 경계를 분리하라입니다.

참고

  • Anthropic, Harness design for long-running application development, 2026-03-24
  • Anthropic, Claude Code auto mode: a safer way to skip permissions, 2026-03-25
  • Claude Code docs, Choose a permission mode / Configure auto mode, 2026-05-23 열람 기준
  • Anthropic, Scaling Managed Agents: Decoupling the brain from the hands, 2026-04-08
  • Claude Managed Agents docs, Overview / MCP connector, 2026-05-23 열람 기준
  • Anthropic, Agents for financial services, 2026-05-05

관련 문서

검증 리포트

하네스 엔지니어링 핸드북의 링크·정합성·근거 검증 결과

외부 사례 비교

OpenAI, Anthropic, Toss, gstack, revfactory/harness를 입력·상태·검증·배포 기준으로 비교합니다.

Ch1. 플랜 & 환경 설정

Claude Code 고급 활용 · Claude Code를 쓸 수 있는 플랜(Pro·Max·Team Premium·Enterprise·Console)과 네이티브·Homebrew·npm 설치, 모델·effort·퍼미션·managed settings 설정을 정리합니다

Cmd. /permissions

Claude Code 명령어 마스터 · 도구 실행에 대한 allow/ask/deny 권한 규칙을 관리하는 운영 핵심 명령

컨텍스트 팩

Agentic MVP · 에이전트에 반복 주입하는 작은 운영 문서. CLAUDE.md/AGENTS.md 계층, 제품 약속·금지 행동 고정, 세션 간 진행 파일·compact로 맥락을 잃지 않게 만드는 방법을 정리합니다.

사례: OpenAI

OpenAI의 하네스 관점을 repo-readable 시스템, observability, cleanup 중심으로 해부합니다.

사례: Toss

Toss의 frictionless harness와 executable SSOT를 global·domain·local 레이어 관점에서 정리합니다.

On this page

2026년 3~5월 업데이트로 추가된 관점해결하려는 문제기술적 메커니즘Managed Agents: brain, hands, session을 분리한다auto mode: 권한 승인을 classifier로 바꿀 때의 조건왜 이게 엔지니어링인가sprint contract가 왜 중요한가load-bearing scaffolding을 판정하는 방법retry budget과 handoff 규칙우리 팀으로 옮길 것그대로 복제하면 안 되는 점참고