02-구조

02. 구조 — 하네스 안에는 무엇이 들어 있나

WaveSpeedAI와 Anthropic 공식 문서를 종합하면, 일반적인 코딩 에이전트 하네스는 대략 다음 6개 층으로 분해된다.

6. 사용자 인터페이스 (TUI/IDE/Voice)
5. 컨텍스트 관리 (시스템 프롬프트, CLAUDE.md, /compact, 메모리 파일)
4. 에이전트 루프 (gather → act → verify)
3. 도구 디스패치 (tool_use 파싱·검증·실행)
2. 권한 게이트 (canUseTool, 모드, 규칙)
1. 실행 환경 (셸, 파일시스템, 네트워크)

각 층의 역할.

1. 실행 환경

진짜 OS, 진짜 셸, 진짜 파일시스템. 또는 격리된 컨테이너/Devcontainer/원격 VM. OpenHands 논문은 이를 runtime이라 부르고, sandboxing 전략(컨테이너 분리, 시간 제한, 자원 제한)을 핵심 설계 결정으로 든다.

2. 권한 게이트

모든 도구 호출은 권한 검사를 통과해야 한다. Ken Huang의 분석에 따르면 Claude Code는 다섯 가지 모드(default, auto, plan, acceptEdits, bubble)와 canUseTool 함수, ToolPermissionContext로 이를 구현한다. 자세한 것은 04-권한-모델과-sandbox 챕터에서 다룬다.

3. 도구 디스패치

모델이 출력한 tool_use 블록을 받아 (a) 이름으로 도구 핸들러를 찾고, (b) 인자 스키마를 검증하고, (c) 권한 게이트를 통과시키고, (d) 실제 실행한 뒤 결과를 tool_result로 모델에 돌려준다.

“tools provide this bridge … new tools can be added without modifying the harness core, as long as they implement the required interface.”

의역 — 도구가 다리 역할을 한다. 정해진 인터페이스만 구현하면 하네스 코어를 손대지 않고 새 도구를 추가할 수 있다. — Ken Huang

4. 에이전트 루프

Anthropic이 공식적으로 설명하는 3단계 — gather context → take action → verify results — 가 무한히 반복된다. 종료 조건, 무한 루프 회피, 도구 호출 횟수 상한 등은 03-도구-호출-루프에서 본다.

5. 컨텍스트 관리

토큰 예산은 200k지만 전부 쓰면 추론 품질이 무너진다. Robert Matsuoka는 Claude Code가 의도적으로 64~75% 부근에서 auto-compact를 트리거해 “completion buffer”를 유지한다고 관찰한다. 이 층에는 시스템 프롬프트, CLAUDE.md, 대화 히스토리, 메모리 파일, /compact가 모두 포함된다.

6. 사용자 인터페이스

TUI(터미널), IDE 통합, Cowork의 데스크탑/Voice 모드 등. 같은 하네스 코어 위에 다른 UI를 얹을 수 있다.

핵심 통찰

이 6개 층 중 모델 가중치는 단 하나도 들어 있지 않다. 그런데 사용자가 체감하는 “Claude Code가 똑똑해졌다”의 90%는 이 층들에서 일어난다. 그래서 본 파트의 이름이 하네스 엔지니어링이다.