하네스란 무엇인가
모델을 실제 작업자로 만드는 실행 계층
작성 기준일: 2026-06-24
이 문서의 결론
하네스는 모델을 더 길게 프롬프트하는 기술이 아니다. 하네스는 모델의 출력을 실제 행동으로 바꾸기 전에 검증하고, 제한하고, 실행하고, 관찰하고, 기록하는 런타임 계층이다.
개발자가 만들어야 할 것은 "LLM 호출 코드"가 아니라, 모델이 틀리거나 과감하거나 오염된 정보를 보더라도 side effect를 통제할 수 있는 작업 시스템이다.
독자가 가져갈 것
- 하네스, 모델, scaffold, agent의 차이를 구분한다.
- 무엇이 있어야 하네스라고 부를 수 있는지 판별한다.
- 기존 LLM 앱 구조와 하네스형 agent 구조를 비교한다.
- 개발자가 실제로 설계해야 하는 runtime surface를 안다.
- Claude Code, Deep Agents, Ponytail, Harness-100 사례를 같은 지도 위에 놓는다.
- benchmark와 production readiness를 model-only 관점으로 읽지 않는다.
- 작은 팀이 시작할 수 있는 최소 구현 순서를 얻는다.
왜 이 용어가 중요해졌나
예전 LLM 앱은 답변을 만들었다. 지금의 coding agent와 workflow agent는 파일을 바꾸고, shell을 실행하고, 티켓을 만들고, API를 호출한다.
행동이 생기면 책임도 생긴다. 그래서 질문은 "어떤 모델이 더 똑똑한가"에서 "모델의 행동을 누가 어떻게 통제하는가"로 이동한다.
- 실패 비용이 텍스트 품질에서 실제 side effect로 커졌다.
- 제품 차이가 모델보다 context, tool, permission, verifier에서 많이 난다.
- long-horizon benchmark 점수도 model + harness의 합성 결과로 읽어야 한다.
기존 LLM 앱의 기본형
구조
user input
-> prompt template
-> model call
-> text answer- 중심은 답변 품질이다.
- 출력은 사람이 읽는 텍스트다.
- 실패는 대체로 사용자가 수정한다.
한계
model says "I changed it"
but no file changed- environment state가 없다.
- tool side effect가 없다.
- 검증과 감사가 application 밖에 있다.
하네스형 에이전트의 기본형
flowchart LR
A[User request] --> B[Mode and scope]
B --> C[Context compiler]
C --> D[Model call]
D --> E[Typed action proposal]
E --> F[Validation]
F --> G{Permission}
G -->|deny| H[Stop with reason]
G -->|ask| I[Human approval]
G -->|allow| J[Tool execution]
I --> J
J --> K[Verification]
K --> L[Audit and checkpoint]
L --> M[Next turn or final]
flowchart LR
A[User request] --> B[Mode and scope]
B --> C[Context compiler]
C --> D[Model call]
D --> E[Typed action proposal]
E --> F[Validation]
F --> G{Permission}
G -->|deny| H[Stop with reason]
G -->|ask| I[Human approval]
G -->|allow| J[Tool execution]
I --> J
J --> K[Verification]
K --> L[Audit and checkpoint]
L --> M[Next turn or final]모델 출력은 실행이 아니라 제안이다. 하네스가 그 제안을 실행 가능한 action으로 바꾸거나 멈춘다.
한 줄 정의
하네스는 LLM을 외부 환경에 연결하고, 모델이 제안한 행동을 검증, 제한, 실행, 관찰, 기록하게 만드는 runtime engineering layer다.
짧게 말하면:
Harness = model output -> governed action네 가지 필요조건
What makes a harness a harness는 agent harness를 네 조건으로 판별한다.
| 조건 | 핵심 질문 | 없으면 |
|---|---|---|
| Agent loop | reasoning, action, observation이 반복되는가 | 단발 generator |
| Tool interface | 외부 환경을 읽거나 바꾸는 경로가 있는가 | prompt wrapper |
| Context management | 무엇을 볼지 runtime이 관리하는가 | 긴 transcript |
| Control mechanisms | 제한, 검증, permission, deterministic guard가 있는가 | 말뿐인 guardrail |
하네스 판별 테스트
- 모델을 한 번만 부르고 끝나는가?
- 모델이 외부 환경에 영향을 줄 수 있는가?
- context가 runtime 정책으로 선별되는가?
- tool call이 schema와 policy를 통과하는가?
- 위험 action 앞에서 allow, ask, deny가 갈리는가?
- 실행 결과를 검증하고 다음 context로 되돌리는가?
- 나중에 같은 run을 추적하거나 재현할 수 있는가?
네 조건 중 하나라도 빠지면 "하네스의 재료"일 수는 있어도 완성된 agent harness라고 부르기는 어렵다.
용어 정리: Model, Scaffold, Harness, Agent
Hugging Face Agent Glossary와 Claude Code Glossary의 실무적 구분을 합치면 다음처럼 볼 수 있다.
| 용어 | 역할 | 흔한 오해 |
|---|---|---|
| Model | 입력을 받아 다음 token, 답변, tool call 의도를 만든다 | 모델이 곧 agent라고 생각함 |
| Scaffold | system prompt, tool description, output format, examples | scaffold만으로 side effect가 안전해진다고 생각함 |
| Harness | loop, tool execution, context, permission, verification을 담당한다 | SDK wrapper와 혼동함 |
| Agent | model + scaffold + harness가 환경에서 행동하는 전체 시스템 | 제품 UX와 모델 성능을 분리하지 못함 |
하네스가 아닌 것들
비슷하지만 부족한 것
- 긴 시스템 프롬프트
- tool calling SDK
- 고정 workflow graph
- eval runner
- guardrail 문구
- IDE autocomplete
빠진 핵심
- 실행 중 permission gate
- context compiler
- tool risk model
- verification loop
- checkpoint와 audit
- runtime state transition
하네스는 "도구가 있음"이 아니라, 도구를 안전하게 실행하게 만드는 전체 runtime이다.
개발자가 설계할 표면 지도
- Context: history를 그대로 넣지 않고 task, files, memory, source refs, tool results, trust level을 선별한다.
- Tools: 함수 목록이 아니라 schema, risk, side effect, approval policy가 붙은 capability contract로 정의한다.
- Permission: read, write, shell, network, destructive action을 allow, ask, deny로 판정한다.
- Verification: 모델의 "끝났다"를 믿지 않고 test, lint, build, smoke, screenshot 같은 sensor로 확인한다.
- State: checkpoint, resume, pending approval, compaction, memory를 durable하게 관리한다.
- Observability: input, context, action, decision, result, cost, latency, failure를 replay 가능한 event로 남긴다.
Context는 history가 아니다
좋은 에이전트는 긴 대화 기록을 그대로 넣어서 똑똑해지는 것이 아니다. 좋은 에이전트는 이번 작업에 필요한 정보를 컴파일된 context pack으로 만든다.
Context compiler는 파일, 검색 결과, MCP resource, memory, diagnostics, changed files, pending tasks, tool result를 선별하고, 출처와 신뢰도를 붙이고, token budget 안에 배치한다.
ContextPack 설계 예시
class ContextPack(BaseModel):
task: str
mode: Literal["answer", "plan", "edit", "execute"]
source_refs: list[str]
files: list[FileSnippet]
tool_summaries: list[str]
constraints: list[str]
trust_marks: list[TrustMark]
permission_mode: str핵심은 모델이 본 정보와 시스템이 믿는 상태를 분리하는 것이다. 나중에 실패를 조사하려면 "모델이 무엇을 봤는지"가 재현되어야 한다.
Tool은 함수가 아니라 능력 계약이다
call()만 있는 tool registry는 운영급 하네스가 아니다. tool은 capability, schema, risk metadata, UI behavior, audit serialization을 함께 가져야 한다.
모델이 어떤 tool을 호출했다는 사실보다 더 중요한 것은 그 tool이 읽기인지 쓰기인지, workspace 안에서만 작동하는지, 결과가 untrusted text인지, 사람 승인이 필요한지다.
ToolSpec 설계 예시
class ToolSpec(BaseModel):
name: str
description: str
input_schema: dict
risk_level: Literal["read", "write", "external", "destructive"]
side_effect: bool
requires_approval: bool
result_max_bytes: int
source: Literal["builtin", "mcp", "plugin", "custom"]MCP, plugin, skill, built-in command가 모두 같은 ToolSpec으로 normalize되어야 permission과 audit을 한 지점에서 적용할 수 있다.
Permission은 prompt가 아니라 코드다
def permission_gate(tool: ToolSpec, args: dict, ctx: RunContext) -> Decision:
if tool.risk_level == "destructive":
return Decision("deny", reason="destructive action")
if "path" in args and not path_in_workspace(args["path"], ctx.workspace):
return Decision("deny", reason="outside workspace")
if tool.side_effect and not ctx.scope_confirmed:
return Decision("ask", reason="write action needs approval")
return Decision("allow")모델에게 "위험한 일은 하지 마"라고 말하는 것과, 위험한 action이 실행 전 코드에서 멈추는 것은 완전히 다르다.
Permission state machine
- Default: 읽기와 낮은 위험 action은 허용하고 write는 묻는다.
- Plan: side effect를 막고 계획과 설명만 만든다.
- Auto: 낮은 위험 action은 자동 실행하되 classifier와 protected path를 강화한다.
- Bypass: 고위험 모드이며 session, policy, audit boundary가 필요하다.
- Resume: 승인 대기, 중단, 재개 상태를 같은 thread로 이어간다.
permission은 boolean flag가 아니라 mode transition이다.
Human approval은 팝업이 아니다
| 저장 항목 | 이유 |
|---|---|
| proposed action | 무엇을 실행하려 했는지 보존 |
| target path or endpoint | 위험 범위 추적 |
| diff or command | 사람이 실제로 본 evidence |
| risk classification | 왜 승인 대상인지 설명 |
| reviewer decision | approve, edit, reject, respond |
| timestamp and session | 사고 조사와 replay |
승인 UI만 있고 durable event가 없으면, 나중에 "누가 무엇을 보고 승인했는지"를 설명할 수 없다.
Verification loop
모델 중심 종료
- "수정했습니다"라고 말하면 끝난다.
- 테스트를 실제로 돌렸는지 모른다.
- 실패 로그가 다음 행동으로 연결되지 않는다.
- 재시도와 중단 조건이 흐릿하다.
하네스 중심 종료
- test, lint, build, smoke 결과를 본다.
- 실패 로그를 구조화해 다음 context로 넣는다.
- retry budget과 stop condition이 있다.
- 최종 응답에 검증 결과와 한계를 남긴다.
좋은 하네스는 모델의 완료 선언보다 deterministic sensor를 더 신뢰한다.
Audit event schema
input_received
context_compiled
model_called
action_proposed
schema_validated
permission_decided
approval_requested
tool_executed
result_sanitized
verification_run
checkpoint_saved
final_response_emitted로그는 transcript와 다르다. transcript는 대화 기록이고, audit event는 action, decision, evidence, result를 재현하기 위한 운영 기록이다.
실패가 반복되면 어디를 고칠까
증상
- 잘못된 파일을 계속 고른다.
- 위험한 shell command를 제안한다.
- tool result injection에 속는다.
- 완료했다고 말하지만 테스트를 안 돌린다.
- 승인 요청이 너무 많거나 너무 적다.
하네스 수정 지점
- context compiler와 file ranking
- command policy와 permission gate
- result sanitizer와 untrusted tagging
- verification loop와 stop condition
- risk classifier와 scoped allow rule
프롬프트만 고치면 같은 실패가 다른 모양으로 돌아온다.
Source trust와 tool result injection
tool result는 사실처럼 보이지만 모델에게는 prompt injection이 될 수 있다. 웹 페이지, README, issue comment, MCP resource, 로그 파일은 모두 "증거"이면서 동시에 "모델에게 보이는 텍스트"다.
하네스는 외부 결과를 다음처럼 다뤄야 한다.
- source와 trust level을 붙인다.
- user instruction과 external evidence를 분리한다.
- tool result 안의 명령형 문장을 instruction으로 승격하지 않는다.
- 요약과 원문 ref를 분리한다.
- 민감 정보와 secret 후보를 redaction한다.
Filesystem guard는 보안 subsystem이다
| 위험 | 필요한 방어 |
|---|---|
../ traversal | resolved path 기준 workspace 검사 |
| symlink escape | realpath와 allowed root 비교 |
| Windows ADS | alternate data stream 차단 |
| UNC/long path prefix | OS별 path normalization |
| secret path | .env, .ssh, token, credential deny |
| destructive command | delete, chmod, curl pipe shell 등 별도 deny |
모델이 악의적이지 않아도 repo 내부 텍스트나 외부 문서가 모델을 잘못 유도할 수 있다.
MCP와 plugin은 확장이 아니라 trust boundary다
MCP server, plugin, custom tool은 agent의 능력을 늘린다. 동시에 새로운 tool poisoning, authorization, token storage, context over-sharing 위험을 만든다.
운영 하네스는 외부 capability를 그대로 모델에게 넘기지 않는다. source, owner, auth scope, risk level, allowed operations, output trust mark, audit policy를 붙인 뒤 tool pool에 넣는다.
Claude Code 사례: 제품형 하네스
- Session kernel: turn lifecycle, transcript, usage, permission denial을 관리한다.
- Tool pool: built-in, MCP, plugin tool을 병합하고 노출 여부를 결정한다.
- Context compiler: workspace, memory, skills, diagnostics, MCP resources를 선별한다.
- Permission state machine: default, plan, auto, bypass 같은 mode를 정책으로 다룬다.
- Hook layer: PreToolUse, PostToolUse, Stop 같은 lifecycle point에 정책을 삽입한다.
- Persistence: checkpoint, transcript, audit, metrics를 분리한다.
Claude Code의 교훈은 단순하다. 제품 경험의 상당 부분은 모델 호출 전후의 control surface에서 나온다.
Claude Code류 하네스 아키텍처
flowchart TD U[User / CLI / IDE] --> I[Input processor] I --> C[Attachment and context compiler] C --> Q[Session kernel] Q --> M[Model stream] M --> A[Tool use block] A --> V[Schema validator] V --> P[Permission gate] P -->|allow| T[Tool executor] P -->|ask| H[Human approval] P -->|deny| D[Denied result] H --> T T --> R[Result mapper] R --> C Q --> S[Transcript / checkpoint / usage] X[MCP / plugins / skills] --> C
flowchart TD
U[User / CLI / IDE] --> I[Input processor]
I --> C[Attachment and context compiler]
C --> Q[Session kernel]
Q --> M[Model stream]
M --> A[Tool use block]
A --> V[Schema validator]
V --> P[Permission gate]
P -->|allow| T[Tool executor]
P -->|ask| H[Human approval]
P -->|deny| D[Denied result]
H --> T
T --> R[Result mapper]
R --> C
Q --> S[Transcript / checkpoint / usage]
X[MCP / plugins / skills] --> C이 구조에서 모델 호출부는 핵심이지만 전체는 아니다. tool execution choke point가 실제 하네스의 심장에 가깝다.
Claude Code에서 개발자가 배울 점
- Tool은 UI, permission, validation, result mapping까지 포함하는 계약이다.
- Context는
get all history가 아니라 매 turn 다시 컴파일되는 attachment set이다. - Permission mode는 제품 UX이면서 security state다.
- Hooks는 extension point이지만 failure policy가 필요하다.
- MCP와 plugin은 tool pool에 들어오기 전 source와 risk가 붙어야 한다.
- Transcript, checkpoint, telemetry, audit은 같은 로그가 아니다.
- 제품형 하네스는 CLI, IDE, remote bridge를 하나의 control protocol로 엮는다.
Deep Agents 사례: 라이브러리형 하네스
LangChain Deep Agents는 긴 작업을 위한 open source agent harness 사례다.
| 층 | 기능 | 하네스 역할 |
|---|---|---|
| Execution environment | tools, virtual filesystem, sandbox, permissions | 행동할 세계와 경계 |
| Context management | memory, skills, summarization, offloading | 무엇을 보존하고 압축할지 결정 |
| Delegation | todos, subagents, context isolation | 큰 작업을 나누고 격리 |
| Steering | human-in-the-loop, interrupts, checkpointer | 민감한 행동에 사람 개입 |
Deep Agents 실행 흐름
flowchart TD
A[User task] --> B[create_deep_agent runtime]
B --> C[Input context: prompt, memory, skills]
C --> D[Planning: write_todos]
D --> E[Tool selection]
E --> F{Permission or interrupt}
F -->|deny| G[Return denial]
F -->|interrupt| H[Human review]
F -->|allow| I[File tool / custom tool / sandbox]
H --> E
I --> J[Tool result]
J --> K{Context too large}
K -->|yes| L[Offload, summarize, delegate]
K -->|no| M[Continue]
L --> M
M --> N{Complete}
N -->|no| E
N -->|yes| O[Final artifact]
flowchart TD
A[User task] --> B[create_deep_agent runtime]
B --> C[Input context: prompt, memory, skills]
C --> D[Planning: write_todos]
D --> E[Tool selection]
E --> F{Permission or interrupt}
F -->|deny| G[Return denial]
F -->|interrupt| H[Human review]
F -->|allow| I[File tool / custom tool / sandbox]
H --> E
I --> J[Tool result]
J --> K{Context too large}
K -->|yes| L[Offload, summarize, delegate]
K -->|no| M[Continue]
L --> M
M --> N{Complete}
N -->|no| E
N -->|yes| O[Final artifact]Deep Agents의 장점은 부품을 제공한다는 점이고, 한계는 domain policy와 custom tool guard를 개발자가 채워야 한다는 점이다.
Deep Agents에서 특히 중요한 한계
Deep Agents의 permissions는 built-in filesystem tools에는 유용하지만, 모든 위험을 자동으로 덮지는 않는다.
- custom tools는 별도 input/output guard가 필요하다.
- MCP tools는 source, auth, risk metadata가 필요하다.
- sandbox
execute는 command policy와 network egress policy가 필요하다. - memory write는 별도 validation과 audit 대상이다.
- human-in-the-loop에는 checkpointer와 thread resume 계약이 필요하다.
프레임워크를 쓰는 것은 하네스를 설계하지 않아도 된다는 뜻이 아니다. 하네스 설계의 일부를 빌려오는 것이다.
Ponytail 사례: 행동 정책 하네스
DietrichGebert/ponytail은 독립 runtime harness라기보다 host agent harness 위에 얹는 behavior policy layer다.
Ponytail의 핵심은 agent에게 "더 많이 만들라"가 아니라 "필요한 만큼만 만들라"는 판단 사다리를 주는 것이다. YAGNI, 기존 코드 재사용, 표준 라이브러리, native platform, 최소 diff 순서로 행동을 제한한다.
이 사례는 하네스가 능력을 늘리는 방향뿐 아니라 행동을 줄이는 방향으로도 설계될 수 있음을 보여준다.
Ponytail을 하네스 지도에 놓기
| 조건 | Ponytail 자체 | 판단 |
|---|---|---|
| Agent loop | host agent에 의존 | 독립 runtime은 아님 |
| Tool interface | host agent에 의존 | capability provider는 아님 |
| Context management | AGENTS/rules/skills로 행동 기준 주입 | policy context layer |
| Control mechanisms | YAGNI ladder, review skill, over-engineering 제한 | behavior guard 역할 |
Ponytail의 가치는 "하네스의 모든 조건을 제공한다"가 아니라, host harness 위에서 행동 습관을 바꾸는 정책 패키지라는 점에 있다.
Harness-100 사례: 패키지형 팀 하네스
revfactory/harness-100은 runtime code library보다 Claude Code용 에이전트 팀 패키지 카탈로그에 가깝다.
| 구성 | 역할 |
|---|---|
.claude/CLAUDE.md | 팀 사용법, 산출물 지도, 오케스트레이션 개요 |
.claude/agents/*.md | 전문 역할과 책임 |
.claude/skills/*/SKILL.md | 도메인 절차와 작업 규칙 |
_workspace/ protocol | 입력, 중간 산출물, 최종 결과 공유 |
| meta-skill | 도메인 분석, 팀 생성, 검증, 진화 루프 |
Harness-100이 보여주는 교훈
- 하네스는 폴더 구조부터 설계할 수 있다.
- agents와 skills를 분리하면 역할과 절차가 재사용된다.
- orchestrator는 안내문이 아니라 DAG, 통신 규칙, 에러 처리, 테스트 시나리오를 포함한다.
_workspace/같은 공유 상태는 multi-agent 작업에서 실용적이다.- trigger와 NOT-trigger boundary가 없으면 skill이 과호출된다.
- 패키지형 하네스는 runtime guard를 대체하지 않고 host harness에 의존한다.
Code as Agent Harness: 연구 관점
Code as Agent Harness는 code를 단순 생성물이 아니라 agentic system의 substrate로 본다.
| 속성 | 의미 | 설계 대응 |
|---|---|---|
| Executable | 계획과 의도가 code, tool call, workflow로 실행된다 | typed action, command runner |
| Inspectable | plan, state, provenance, failure cause를 추적한다 | audit, source refs, trace |
| Stateful | 장기 작업과 multi-agent state를 보존한다 | checkpoint, memory, shared artifacts |
| Governed | autonomy가 permission과 verification으로 제한된다 | policy, approval, rollback |
AHE: 하네스는 개선 대상이다
Agentic Harness Engineering은 하네스를 사람이 고정해두는 설정이 아니라 자동 개선 가능한 engineering surface로 다룬다.
논문은 component observability, experience observability, decision observability를 통해 harness mutation을 만들고 평가한다. Terminal-Bench 2 pass@1을 69.7%에서 77.0%로 올렸다고 보고하지만, 이 수치는 특정 benchmark와 preprint 조건 안에서만 해석해야 한다.
중요한 교훈은 수치 자체보다 방향이다. 반복 실패를 보면 prompt만 고치는 것이 아니라 tool, middleware, memory, verifier, permission policy를 고쳐야 한다.
하네스 변경 기록 예시
## Harness Change
- 문제: write_file이 protected path를 ask 없이 통과함
- 변경: protected path list와 path normalization 추가
- 예측: outside_workspace, env_file, ssh_config 케이스가 deny로 바뀜
- 검증: permission regression 12개 실행
- 결과: 12/12 pass
- rollback 기준: generated/ 하위 정상 write가 deny되면 되돌림하네스 개선은 감으로 하는 튜닝이 아니라 예측, 실험, 결과, rollback을 남기는 engineering loop다.
벤치마크를 읽는 법
Model-only 비교
- base model 이름만 본다.
- tool set과 context policy가 숨겨진다.
- retry, checkpoint, verifier가 보이지 않는다.
- 점수 차이의 원인을 분리하기 어렵다.
Model + Harness 비교
- base model과 version
- tool interface와 execution policy
- context construction과 compaction
- permission, verification, checkpoint rule
- eval environment와 timeout/budget
Stop Comparing LLM Agents Without Disclosing the Harness의 요지는 agent 성능이 model + harness의 합성 결과라는 점이다.
Harness disclosure checklist
- Model: base model, version, provider, temperature, tool-call mode
- Tools: available tools, hidden tools, side effect policy, sandbox
- Context: retrieval, file selection, memory, compaction, truncation policy
- Control: permission mode, approval rule, validator, retry, stop condition
- Evaluation: timeout, budget, environment, verifier, pass/fail oracle
- Trace: what was logged, what can be replayed, what is excluded
이 항목이 없으면 리더보드는 model ranking이라기보다 unknown product stack ranking에 가깝다.
보안 위협을 하네스 요구사항으로 바꾸기
| 위협 | 하네스 위치 | 구현 포인트 |
|---|---|---|
| Prompt injection | context gate | external resource trust mark |
| Excessive agency | permission gate | action scope, deny/ask policy |
| Sensitive data leak | tool validator | secret path deny, redaction |
| Tool poisoning | extension registry | MCP/plugin allowlist |
| Command injection | shell guard | parsed args, allowlist, cwd scope |
| Lack of telemetry | audit layer | immutable decision log |
| Context over-sharing | context compiler | per-user/per-task scope |
최소 구현 순서
- Read-only agent: 파일 읽기, 검색, 요약만 허용한다.
- Approval-based write: diff preview와 human approval을 지난 write만 허용한다.
- Limited shell: allowlist, working directory, timeout, output truncation을 둔다.
- External tools: MCP/custom tool마다 source, trust, risk, permission metadata를 붙인다.
- Regression set: workspace escape, prompt injection, unsafe command, missing verifier 케이스를 만든다.
처음부터 full autonomy를 열지 않는다. 하네스의 경계가 먼저이고 능력은 그 다음이다.
Reference backend 흐름
agent_harness_implementation_guide.md의 generic backend는 다음 흐름을 출발점으로 둔다.
request
-> input_guardrail
-> mode_router
-> context_loader
-> prompt_compiler
-> action_planner
-> permission_gate
-> execute_or_ask
-> validators
-> final_response실제 LLM으로 바꿔도 node 계약은 유지해야 한다. 모델은 planned_action을 제안하고, 하네스가 schema, permission, validator를 적용한다.
운영 전환 체크리스트
- Durable state: in-memory checkpointer를 DB-backed checkpointer로 바꾼다.
- Append-only audit: transcript와 별도로 action decision log를 저장한다.
- Tool registry: risk level, side effect, approval policy를 모든 tool에 붙인다.
- Secret policy: env, token, credential path는 기본 block으로 둔다.
- Version lock: LLM provider, MCP, DB, sandbox dependency를 고정한다.
- CI guard: source map, secret, internal prompt 배포물 검사를 추가한다.
최소 테스트 세트
| 테스트 | 목적 |
|---|---|
| invalid action schema rejected | 모델 출력이 schema 밖이면 실행 금지 |
| path traversal denied | ../, symlink, UNC, ADS 방어 |
| write requires approval | write tool이 approval interrupt 없이 실행되지 않음 |
| reject stops side effect | user reject 후 파일/DB/API 변경 없음 |
| approve executes once | resume 중복 호출로 중복 실행 방지 |
| denied tool returns reason | 모델이 대안 경로를 찾을 수 있음 |
| large result summarized | tool result가 context budget을 넘지 않음 |
좋은 하네스의 품질 게이트
- 모델이 임의 JSON을 내면 typed action parser가 거절하는가?
- workspace 밖 파일 write를 path validator가 막는가?
- shell command는 allowlist, timeout, cwd scope를 통과하는가?
- 승인 전 창을 닫아도 pending approval을 재개할 수 있는가?
- MCP server가 새 tool을 추가하면 source/risk/permission이 붙는가?
- context가 커지면 compaction과 source ref가 남는가?
- 운영자가 사고를 조사하면 action, decision, result를 재현할 수 있는가?
- 하네스 변경마다 prediction, eval, rollback 기준이 남는가?
Anti-patterns
하네스처럼 보이지만 운영에서 흔히 깨지는 구현들이다.
- tool을
dict[str, Callable]로만 관리한다. - permission을 prompt instruction으로만 처리한다.
- workspace path를 문자열 prefix로만 검사한다.
- LangGraph checkpoint를 audit log로 착각한다.
- 모든 MCP tool을 그대로 모델에게 노출한다.
- tool result를 그대로 다음 prompt에 넣는다.
- human approval을 UI 이벤트로만 저장한다.
- 실패 원인을 prompt 문장만 고쳐 해결하려 한다.
실무자가 기억할 세 문장
모델은 다음 행동을 제안한다.
하네스는 그 행동이 실행되어도 되는지 결정한다.
좋은 에이전트 제품의 차이는 모델 호출 전후의 control surface에서 나온다.
사례별 위치 정리
| 사례 | 하네스 유형 | 핵심 교훈 |
|---|---|---|
| Claude Code | 제품형 runtime harness | UX와 control plane이 분리되지 않는다 |
| LangChain Deep Agents | 라이브러리형 harness | 실행 환경, context, delegation, steering을 조립한다 |
| Ponytail | behavior policy layer | host harness 위에서 행동을 줄이고 재사용을 강제한다 |
| Harness-100 | 패키지형 team harness | agents, skills, workspace protocol을 파일로 제공한다 |
| Code as Agent Harness | 연구/survey 관점 | code가 executable, inspectable, stateful, governed substrate가 된다 |
| AHE | 자동 개선 관점 | 하네스 자체가 관찰과 mutation의 대상이 된다 |
사용한 내부 정리 자료
claude_code_harness_wiki.md: Claude Code류 제품형 하네스 구조 분석langchain_deep_agents_harness_case_study.md: Deep Agents 라이브러리형 하네스 사례harness_engineering_developer_blog.md: 개발자용 하네스 정의와 구현 체크리스트agent_harness_implementation_guide.md: generic backend 구현 흐름code_as_agent_harness_paper_analysis.md: Code as Agent Harness와 AHE/Meta-Harness/AutoHarness 정리harness_100_case_study.md: 패키지형 team harness 사례raw/AGENT_HARNESS/notes/ponytail_related_case_2026-06-23.md: Ponytail 관련 사례 해석raw/AGENT_HARNESS/notes/harness_definition_sources_2026-06-22.md: 정의/벤치마크 원문 출처 정리
원문 출처
- What makes a harness a harness: https://arxiv.org/abs/2606.10106
- Stop Comparing LLM Agents Without Disclosing the Harness: https://arxiv.org/abs/2605.23950
- Code as Agent Harness: https://arxiv.org/abs/2605.18747
- Agentic Harness Engineering: https://arxiv.org/abs/2604.25850
- Meta-Harness: https://arxiv.org/abs/2603.28052
- AutoHarness: https://arxiv.org/abs/2603.03329
- Claude Code Glossary: https://code.claude.com/docs/en/glossary
- Hugging Face Agent Glossary: https://huggingface.co/blog/agent-glossary
- LangChain Deep Agents overview: https://docs.langchain.com/oss/python/deepagents/overview
- DietrichGebert/ponytail: https://github.com/DietrichGebert/ponytail
- revfactory/harness-100: https://github.com/revfactory/harness-100
- Martin Fowler Harness engineering: https://martinfowler.com/articles/harness-engineering.html
'관심있는 주제 > 용어' 카테고리의 다른 글
| 금융권 차세대 시스템 및 정보계 구조 모아보기 (1) | 2025.06.03 |
|---|---|
| 금융 IT 용어 정리 (0) | 2022.07.21 |