하네스의 기술 메커니즘
왜 하네스가 감각이 아니라 엔지니어링 대상인지, 입력·상태·검증·권한 경계 관점에서 설명합니다.
핵심 요약
- 하네스 엔지니어링은 프롬프트 문구가 아니라 입력·상태·도구 권한·평가·HITL·운영·실행 compute 분리·자동 승인 8가지를 설계해 시스템의 실패 모드를 바꾸는 일입니다.
- 핵심은 모델을 더 똑똑하게 만드는 것이 아니라 모델이 틀려도 시스템이 덜 망가지게(편차·실패 반경 축소) 설계하는 것입니다.
- 상태를 메모리가 아니라 task-contract·plan·qa-report·invariants 같은 파일·아티팩트로 외재화해야 세션 간 handoff와 실패 후 재구성이 가능합니다.
- 자동 승인은 safe allowlist·project-local edits·classifier gate·trust boundary·deny-and-continue·hard human gate로 정책을 나누되, 분류기가 고위험 변경의 사람 리뷰를 대체하지는 못합니다.
- 하네스와 실행 compute를 분리(session·harness·sandbox)하고 credential은 sandbox 밖 vault·MCP proxy 뒤에 두며, load-bearing이 아닌 요소는 계속 제거해야 합니다.
하네스 엔지니어링이 추상적으로 들리는 가장 큰 이유는, "좋은 환경을 만든다"는 말이 실제로 어떤 시스템을 설계한다는 뜻인지 드러나지 않아서입니다.
엔지니어링으로서의 하네스가 다루는 건 결국 아래 여덟 가지입니다.
- 어떤 입력을 작업 시작점으로 줄 것인가
- 작업 상태를 어떤 산출물로 외부화할 것인가
- 어떤 도구를 어떤 권한 경계 안에서 열어줄 것인가
- 어디서 품질을 판정할 것인가
- 언제 사람에게 넘길 것인가
- 시간이 지나며 망가지는 규칙을 어떻게 치울 것인가
- 하네스와 실제 실행 compute를 어떻게 분리할 것인가
- 자동 승인과 자동 차단을 어떤 정책/분류기로 맡길 것인가
왜 "엔지니어링"이라고 부를 수 있는가
하네스는 프롬프트 문구가 아니라 시스템의 실패 모드를 바꿉니다.
| 하네스가 바꾸는 것 | 엔지니어링 대상인 이유 |
|---|---|
| 편차 | 같은 모델을 써도 결과 분산을 줄임 |
| 실패 반경 | 잘못된 실행이 어디까지 번지는지 제한 |
| 관찰 가능성 | 실패 원인을 브라우저/로그/테스트에서 추적 가능하게 만듦 |
| 재현 가능성 | 개인 감각 대신 파일, 명령, 문서, 루프로 재현 |
| 운영 비용 | 반복 실패, 리뷰 누락, 문서 드리프트 비용을 줄임 |
핵심 관점
하네스는 모델에게 더 똑똑해지라고 요구하지 않습니다. 모델이 틀려도 시스템이 덜 망가지게 설계하는 일입니다.
1. 입력 레이어를 설계한다
좋은 하네스는 첫 입력부터 다릅니다.
OpenAI가 AGENTS.md와 구조화된 docs/를 강조하는 이유도,
Anthropic이 sprint contract를 두는 이유도 결국 시작 입력을 압축된 구조로 주기 위해서입니다.
입력 레이어에서 보통 다루는 산출물:
task_contract:
goal: "무엇을 끝낼지"
non_goals:
- "이번 턴에 하지 않을 것"
constraints:
- "깨면 안 되는 규칙"
files_to_read:
- "AGENTS.md"
- "docs/architecture.md"
validation:
- "lint"
- "browser QA"
escalation:
- "schema 변경 발견 시 사람 승인"이건 단순한 문서가 아니라, 이후 단계의 planner, builder, evaluator가 같은 기준을 공유하게 만드는 계약 데이터입니다.
2. 상태를 기억이 아니라 파일과 아티팩트로 남긴다
에이전트 작업이 길어질수록 메모리보다 외부 상태가 중요해집니다. 하네스는 보통 상태를 파일·메시지·테스트 결과로 아래처럼 쪼갭니다.
여기서 중요한 점:
plan.md는 사고 기록이 아니라 범위 고정 장치입니다.qa-report.md는 "됐음"이 아니라 "어떻게 검증했는가"를 남깁니다.invariants.md는 아키텍처 위반을 빠르게 감지하는 기준입니다.
상태를 이렇게 외부화하면 세 가지가 가능해집니다.
- 세션이 바뀌어도 handoff가 됩니다.
- evaluator가 builder의 자기 설명이 아니라 아티팩트를 검증합니다.
- 실패한 뒤에도 어디서 무너졌는지 다시 짚어볼 수 있습니다.
3. 도구를 열어주는 방식이 품질을 바꾼다
OpenAI가 브라우저, 로그, 메트릭 접근을 하네스 일부로 보는 이유는 분명합니다. 텍스트만 읽는 에이전트는 코드의 의도는 검토할 수 있어도, 실제 실행 결과는 잘 못 봅니다.
| 도구 | 없을 때 생기는 문제 | 있을 때 달라지는 점 |
|---|---|---|
| 브라우저 | UI가 깨져도 완료로 착각 | 실제 상호작용과 상태 전환 검증 |
| 로그 | 장애 원인을 추정에 의존 | 실패 지점을 시간 순서대로 재구성 |
| 테스트 | 부분 수정이 회귀를 만듦 | 반복 실패를 자동 감지 |
| 메트릭 | deploy 이후 품질 하락을 늦게 인지 | 작업 결과를 운영 데이터와 연결 |
결국 하네스는 "모델에게 도구를 주는 것"이 아니라 검증 가능한 관측 인터페이스를 여는 것입니다.
4. 평가 루프를 분리해 자기평가 편향을 줄인다
Anthropic이 보여준 핵심은 역할 수가 아니라 편향 분리입니다. builder가 계획, 구현, 자기 평가를 모두 맡으면 속도는 나와도 오판이 늘어납니다.
평가 루프가 엔지니어링이 되는 이유:
- builder와 evaluator의 입력이 다릅니다.
- evaluator는 "무엇을 만들었는가"가 아니라 "무엇이 증명됐는가"를 봅니다.
- QA는 코드 설명이 아니라 실행 상태를 봅니다.
이렇게 나누면 품질 판정이 "느낌"이 아니라 역할별 계약이 됩니다.
5. 권한 경계와 승인 지점을 설계한다
하네스는 단지 생산성 장치가 아닙니다. 어디까지 자동화하고 어디서 사람을 넣을지 결정하는 통제 시스템이기도 합니다.
approval_policy:
auto:
- "docs 수정"
- "로컬 리팩터링"
review_required:
- "사용자 노출 UI 변경"
- "테스트 추가/삭제"
human_gate:
- "production deploy"
- "database migration"
- "권한/과금/정책 변경"이런 정책은 단순 운영 규칙이 아니라, 시스템이 감당할 수 있는 실패 반경을 정의합니다.
Toss의 HITL, gstack의 review/test/ship 분리, revfactory의 validation loop는 모두 이 경계 설계 문제로 읽을 수 있습니다.
6. 자동 승인도 하네스 정책으로 설계한다
권한 프롬프트를 많이 띄운다고 안전해지지는 않습니다. Anthropic의 2026년 Claude Code auto mode 글을 보면, 사용자가 권한 프롬프트 대부분을 승인하는 상황에서는 승인 피로가 쌓이고, 그 와중에 자동화와 안전을 같이 잡으려면 정책화된 분류 경계가 필요합니다.
approval policy를 단순한 UI 설정으로 보면 안 되는 이유가 여기 있습니다.
| 레이어 | 설계 질문 |
|---|---|
| Safe allowlist | 읽기 전용 탐색, 코드 탐색, plan 전환처럼 거의 항상 허용할 도구는 무엇인가 |
| Project-local edits | 버전 관리로 검토 가능한 리포 내부 파일 수정은 어느 범위까지 자동 허용할 것인가 |
| Classifier gate | shell, web fetch, 외부 도구, subagent spawn, 리포 밖 파일 접근을 어떤 기준으로 검사할 것인가 |
| Trust boundary | 어떤 GitHub org, cloud bucket, internal API, 도메인을 내부 인프라로 볼 것인가 |
| Deny-and-continue | 차단되었을 때 멈출지, 더 안전한 대안을 찾게 할지, 몇 번 후 사람에게 넘길지 |
| Hard human gate | production deploy, destructive migration, 보안 posture 변경처럼 자동 판단에 맡기지 않을 영역은 무엇인가 |
중요한 caveat도 있습니다. 자동 분류기는 승인 피로를 줄이는 장치일 뿐, 고위험 인프라 변경의 사람 리뷰를 완전히
대신하지는 못합니다. 그래서 팀 하네스는 자동 허용, 분류기 검토, 사람 승인, 절대 금지를 별도
정책으로 나눠 둡니다.
7. 하네스와 실행 compute를 분리한다
OpenAI Agents SDK의 2026년 업데이트에서 눈에 띄는 변화는, 하네스를 agent loop의 control plane으로 두고 실제 실행은 sandbox compute에 맡기는 흐름입니다. 이렇게 나눈 건 보안만을 위해서가 아닙니다. 장시간 작업이 실패하거나 컨테이너가 바뀌어도 상태를 복원하고, subagent마다 격리된 환경을 배정하고, 민감한 credential을 모델 생성 코드가 실행되는 곳과 떼어 놓으려는 설계입니다.
| 실행 구성 | 하네스 설계 질문 |
|---|---|
| Shell | 어떤 명령 실행을 허용하고, 어디서 승인을 요구할 것인가 |
Filesystem / apply_patch | 어떤 파일을 수정 가능하게 하고, patch 경로를 어떻게 제한할 것인가 |
| Skills | 어떤 지식 묶음을 사전에 주입하지 않고 필요할 때만 로드할 것인가 |
| Memory / Compaction | 장시간 작업의 상태를 어디에 남기고 언제 줄일 것인가 |
| Manifest / mounted data | 입력 데이터, 출력 디렉터리, 의존성을 어떻게 예측 가능한 작업공간으로 제공할 것인가 |
| MCP / tunnel | 사내 도구를 어떤 네트워크 경계 안에서 열 것인가 |
그러니 "도구를 준다"는 말은 너무 약합니다. 진짜 설계 질문은 어떤 환경을 만들고, 무엇을 격리하고, 어떤 상태를 복원 가능하게 만들며, 어떤 도구 호출을 감사 가능한 이벤트로 남길 것인가입니다.
Anthropic Managed Agents는 같은 문제를 session, harness, sandbox 인터페이스 분리로 설명합니다. session은
Claude의 컨텍스트 창이 아니라 append-only event log로 남고, harness는 실패해도 session log에서 다시 깨어나며,
sandbox와 외부 도구는 execute(name, input) -> string 형태의 hand로 다룹니다. 특히 credential은
sandbox 안의 생성 코드가 직접 읽지 못하게 vault나 MCP proxy 뒤에 두는 게 핵심입니다.
8. 운영과 가비지 컬렉션을 내장한다
하네스는 처음 만들 때보다 시간이 지나며 더 많이 망가집니다.
| 망가지는 방식 | 대표 증상 |
|---|---|
| 문서 드리프트 | AGENTS와 실제 구조가 다름 |
| 루프 비대화 | 아무도 안 쓰는 reviewer 단계가 남아 있음 |
| 승인 우회 | 급한 일 때문에 human gate가 관례적으로 무시됨 |
| 도구 노후화 | 브라우저/로그 스크립트가 깨져도 아무도 안 고침 |
그래서 하네스는 처음 띄우는 것보다 정리 루틴이 중요합니다.
이 루프가 없으면 하네스는 문서 더미나 ritual이 됩니다.
무엇이 기술적으로 load-bearing인지 판정하는 질문
실제 팀에서 아래 질문에 예가 많을수록 하네스는 엔지니어링 대상입니다.
- 같은 요청인데 사람마다 결과 편차가 큰가
- 에이전트가 "완료"라고 했는데 브라우저에서 자주 깨지는가
- 배포 직전이나 배포 후에야 결함이 드러나는가
- 아키텍처 규칙이 세션마다 다시 설명돼야 하는가
- 위험한 변경의 승인 기준이 명시적이지 않은가
- 문서와 실제 작업 방식이 자주 어긋나는가
결론
하네스 엔지니어링은 감각 좋은 프롬프트 작성법이 아닙니다. 입력 구조, 상태 아티팩트, 평가 루프, 권한 경계, 운영 정리 루틴을 설계하는 시스템 작업입니다.
이렇게 보면 하네스는 추상론이 아니라, 에이전트 기반 개발의 편차와 실패 반경을 줄이는 실무 아키텍처입니다.
최소 하네스 아키텍처
하네스가 엔지니어링 역할을 한다는 말은, 실제로는 아래처럼 입력, 실행, 검증, 기록이 이어지는 구조를 만든다는 뜻입니다.
| 레이어 | 대표 아티팩트 | 자동화/도구 | 막아주는 실패 |
|---|---|---|---|
| 입력 | AGENTS.md, docs/invariants.md | file search, task contract | 잘못된 시작점, 규칙 누락 |
| 실행 | plan, code diff, command | editor, shell, workflow | 범위 이탈, 무근거 구현 |
| 검증 | test result, browser QA, logs | test runner, browser, observability | "코드는 맞는데 실제로 깨짐" |
| 기록 | qa report, updates, release note | template, bot, PR check | 같은 실패 재발, handoff 실패 |
핵심은 각 레이어를 다음 레이어의 입력으로 이어 붙이는 것입니다. 문서만 있고 검증이 없거나, 검증은 했는데 기록이 안 남으면 하네스가 아니라 부분 최적화에 머뭅니다.
load-bearing과 ritual을 가르는 기준
하네스 구성요소가 정말 필요한지 판단하려면, "그 단계가 없어졌을 때 어떤 실패가 다시 늘어나는가"를 봐야 합니다.
| 항목 | load-bearing인 경우 | ritual인 경우 |
|---|---|---|
| reviewer 분리 | builder가 자주 놓치는 실패 모드를 실제로 잡음 | 결과적으로 같은 내용만 반복 |
| browser QA | UI/상태 전환 결함을 꾸준히 줄임 | 거의 모든 변경에서 의미 없는 확인만 함 |
| task contract | 범위와 금지 조건을 실제로 고정 | 매번 복붙되지만 행동을 안 바꿈 |
| approval gate | 고위험 변경의 실수를 줄임 | 승인자만 바뀌고 판단 기준은 비어 있음 |
| updates 로그 | 해석 변경과 cleanup 근거가 남음 | 일자와 제목만 남고 아무도 안 읽음 |
이 기준이 중요한 이유는 단순합니다. 좋은 하네스는 요소를 많이 추가하는 팀이 아니라, 실패를 줄이는 요소만 남기고 나머지는 계속 제거하는 팀이 만들기 때문입니다.