Claude Code 에이전트 하네스: 아키텍처 분석

나만의 도구 호출 설정을 구축하면서 같은 질문을 계속 마주쳤다: 왜 연결하는 것이 프롬프트 작성보다 훨씬 어렵게 느껴질까?

모델 부분은 금방 이해됐다. 하지만 모델이 실제로 무언가를 해야 하는 순간 — 파일 읽기, 셸 명령 실행, 외부 서비스와 통신 — 모든 결정이 무언가를 망가뜨릴 수 있을 것처럼 느껴졌다. 권한 경계. 컨텍스트 한계. 도구 디스패치.

그러다 2026년 3월 말, Claude Code의 소스 코드가 버전 2.1.88의 npm 소스 맵을 통해 우연히 노출됐다. 50만 줄 이상의 TypeScript 코드가 몇 시간 만에 미러링됐다. Anthropic은 패키징 오류였음을 확인했고 — 고객 데이터는 포함되지 않았다 — DMCA 삭제 요청을 시작했다.

하지만 아키텍처는 공개 지식이 됐다. 그리고 드러난 것은 모델이 아니었다. 바로 하네스였다.

출처에 대한 참고: 여기서 다루는 세부 사항은 커뮤니티 분석, 오픈소스 재현, Anthropic의 공개 문서 및 엔지니어링 블로그에서 나온 것이며 — 유출된 코드 자체에서 나온 것이 아니다. 불확실한 세부 사항은 표시되어 있다.

에이전트 하네스란 무엇인가?

정의와 에이전틱 시스템에서의 역할

에이전트 하네스는 언어 모델과 실제 세계 사이의 모든 것이다. 모델은 텍스트를 생성한다. 하네스는 그 텍스트가 무엇에 접근할 수 있는지 결정한다.

Claude Code에 대한 Anthropic의 문서는 이를 직접적으로 설명한다: Claude Code는 “언어 모델을 유능한 코딩 에이전트로 전환하는 도구, 컨텍스트 관리, 실행 환경을 제공한다.” 모델은 추론한다. 하네스는 행동한다.

에이전트가 파일을 읽을 때, 하네스는 읽기가 허용되는지, 결과에 어떤 일이 일어나는지, 응답의 얼마만큼이 다음 프롬프트에 맞는지를 결정한다. 모델은 파일 시스템에 직접 접근하지 않는다.

프로덕션에서 하네스 설계가 중요한 이유

대부분의 에이전트 데모는 이 부분을 건너뛴다. 모델이 함수를 호출하고, 결과를 받고, 또 다른 함수를 호출하는 것을 볼 수 있다. 깔끔해 보인다. 그런 다음 실제 코드베이스에서 45분 동안 실행하면 조용히 무너지기 시작한다 — 컨텍스트 오버플로우, 너무 느슨하거나 너무 성가신 권한, 모델이 알지 못한 채 잘린 도구 결과.

Anthropic의 엔지니어링 팀은 이에 대해 작성했다: 여러 컨텍스트 창에 걸쳐 루프로 실행되는 최전선 모델도 잘 설계된 하네스 없이는 성능이 떨어진다. 에이전트는 한 번에 너무 많은 것을 시도하거나, 조기에 작업 완료를 선언한다. 하네스는 그 경향에 구조를 부과한다.

Claude Code의 도구 표면

핵심 도구 카테고리

공식 Claude Code 문서와 공개 분석을 기반으로, Claude Code는 대략 19개의 권한 게이트 도구를 노출한다. 주요 카테고리: 파일 읽기 및 편집, 셸 실행(Bash), Git 작업, 웹 가져오기, 노트북 편집, MCP 도구 호출. 커뮤니티 분석에 따르면 LSP 통합, 서브에이전트 생성, 내부 조정 도구를 포함하면 약 40개에 달할 수 있다.

각 도구는 독립적으로 샌드박스화되어 있다. “에이전트가 파일 시스템 접근 권한을 갖는다”가 아니라 “에이전트가 Read 도구를 사용할 수 있으며, Read는 실행 전에 규칙 파이프라인을 확인하는 자체 권한 게이트를 갖는다”는 것이다.

도구 등록 및 디스패치 방법

모델은 무엇을 시도할지 결정한다. 도구 시스템은 무엇이 허용되는지 결정한다. 아키텍처적으로 분리되어 있다.

모든 도구 호출은 실행 전에 권한 검사를 거친다. 커뮤니티 심층 분석에서는 거부/질문/허용 규칙을 그 순서로 평가하는 핵심 함수를 설명한다 — 거부는 항상 이긴다. 세 가지 가능한 결과: 조용히 진행, 사용자에게 확인 요청, 또는 차단.

손상된 모델은 설득력 있는 주장으로 안전 검사를 우회할 수 없다. 하네스는 모델의 주장에 신경 쓰지 않는다. 규칙은 규칙이다.

권한 등급

Claude Code의 권한 모델은 여러 커뮤니티 분석가들에 의해 대략 세 단계로 설명됐다:

1단계 — 자동 승인: 읽기 전용 또는 본질적으로 안전한 작업. 파일 읽기, 텍스트 검색, 코드 탐색. 이것들은 상태를 변경하지 않으므로 중단 없이 실행된다.

2단계 — 확인 요청: 제어된 방식으로 상태를 수정하는 작업. 파일 편집, 특정 셸 명령. 자동 모드(2026년 3월 도입)에서는 Sonnet 4.6에서 실행되는 백그라운드 분류기가 물어보지 않고 진행할 수 있는지 평가한다. 분류기는 사용자의 요청과 도구 호출을 보지만, 모델의 산문은 보지 않는다 — 모델이 게이트를 달콤하게 설득하는 것을 방지하기 위한 의도적인 설계 선택이다. 3단계 — 명시적 승인 필요 또는 차단: 고위험 작업. 예측할 수 없는 방식으로 시스템 상태를 수정할 수 있는 셸 명령, 작업 디렉터리 외부 작업, 데이터 유출처럼 보이는 모든 것.

한 가지 주의사항: 세 단계 프레임은 Anthropic의 공식 문서가 아닌 커뮤니티 분석에서 나온 것이다. 공식 시스템은 허용/질문/거부 규칙과 여섯 가지 권한 모드(default, acceptEdits, plan, auto, dontAsk, bypassPermissions)를 사용한다. “세 단계”는 유용한 멘탈 모델이지만 단순화다.

세션 및 컨텍스트 관리

Claude Code가 세션 상태를 추적하는 방법

Claude Code는 세션 전반에 걸쳐 컨텍스트를 누적한다 — 읽은 파일, 실행한 명령, grep 결과, diff, 오류 출력. 이 모든 것이 하나의 증가하는 프롬프트로 쌓인다. 각 메시지가 다소 독립적인 채팅 인터페이스와 달리, Claude Code 세션은 연속적인 작업 메모리다.

세션은 로컬에 저장된다. 각 메시지, 도구 사용, 결과가 저장되어 되감기, 재개, 포크를 가능하게 한다. 코드 변경 전에 하네스는 영향받는 파일의 스냅샷을 찍어 되돌릴 수 있게 한다.

출력 잘림 및 토큰 비용 처리

큰 도구 출력은 실제 문제다. Claude Code는 MCP 도구 출력에 대해 기본 최대 25,000 토큰을 설정하고, 10,000 토큰에서 경고를 표시한다. 서버 작성자는 더 큰 결과(최대 500,000자)를 허용하도록 도구에 주석을 달 수 있으며, 이는 컨텍스트에 유지되는 대신 디스크에 저장된다.

이것은 도구 결과가 잘려서 에이전트가 조용히 정보를 놓칠 때까지 생각하지 않는 종류의 것이다. 디스크 기반 폴백이 있는 명시적이고 구성 가능한 한계 — 가져올 만한 가치가 있다.

압축 동작

이것은 이해하기 전에 나를 물어뜯었다. 토큰 사용량이 컨텍스트 창의 약 98%에 도달하면, Claude Code는 자동 압축한다: 공간을 확보하기 위해 이전 기록을 요약한다. 중요한 메타데이터는 보존된다. 이미지와 PDF는 제거된다.

까다로운 부분: 압축은 중요한 세부 사항을 잃을 수 있다. 실용적인 해결책: 모든 중요한 것을 CLAUDE.md에 넣어라, 하네스가 매 턴마다 다시 읽는다.

Anthropic의 하네스 설계 연구에 따르면 새 에이전트 인스턴스가 핸드오프 아티팩트에서 이어받는 전체 컨텍스트 재설정이 — 장시간 세션에서 압축보다 더 잘 작동하는 경우도 있다. 더 많은 오케스트레이션 복잡성이지만, 더 나은 컨텍스트 충실도를 제공한다.

MCP 통합 레이어

Claude Code가 MCP 서버에 연결하는 방법

MCP (Model Context Protocol)는 AI 도구를 외부 서비스에 연결하기 위한 개방형 표준이다. Claude Code는 세 가지 전송 모드를 지원한다: HTTP(원격 서버에 권장), stdio(로컬 프로세스용), SSE.

서버 추가는 하나의 명령이다: claude mcp add server-name --transport http "URL". 그 후 서버의 도구가 세션에서 호출 가능한 도구로 표시되며, 내장 도구와 동일한 권한 파이프라인의 적용을 받는다.

도구 발견 및 인증 흐름

나를 인상시킨 한 가지 세부 사항: 도구 검색. MCP 서버를 연결할 때, Claude Code는 모든 도구 스키마를 처음부터 컨텍스트에 로드하지 않는다. 세션 시작 시 도구 이름만 로드한 다음, 작업이 실제로 필요할 때 검색 메커니즘을 사용하여 관련 도구를 발견한다. Claude가 사용하는 도구만 컨텍스트에 들어간다.

이는 MCP 오버헤드를 낮게 유지한다. 인증 흐름은 서버에 따라 다르다 — OAuth, API 키, 헤더. Claude Code는 새 MCP 서버에 대한 명시적인 사용자 승인을 요구한다.

프로덕션 준비 완료 vs. 여전히 진화 중

MCP 통합은 기능적이고 활발하게 사용된다. 하지만 알아둘 몇 가지 실용적인 한계:

각각이 서브프로세스를 시작하기 때문에 권장 상한은 약 5~6개의 활성 MCP 서버다. 도구 검색은 컨텍스트 오버헤드에 도움이 되지만, 그 이상에서는 지연이 여전히 발생한다. 큰 MCP 응답은 신중한 처리가 필요하다. 25K 토큰 기본 한계는 대부분의 사용 사례에서 잘 작동하지만 데이터베이스 스키마에는 빠듯해진다. 디스크 저장 폴백이 도움이 되지만, 모델은 컨텍스트에서 전체 결과 대신 참조만 받는다.

그리고 커뮤니티가 만든 MCP 서버는 품질이 다양하다. Anthropic의 문서는 서드파티 서버가 프롬프트 인젝션 벡터가 될 수 있다고 명시적으로 언급한다. 권한 시스템이 도움이 되지만, 신뢰는 여전히 당신에게 달려 있다.

빌더를 위한 교훈

이 아키텍처가 프로덕션 수준의 에이전틱 시스템에 대해 드러내는 것

Claude Code 설계에서 일반화될 수 있다고 생각하는 몇 가지 패턴:

추론과 권한 집행을 분리하라. 모델은 무엇을 하고 싶은지 결정한다. 다른 시스템이 그것이 허용되는지 결정한다. 탈옥된 모델은 안전 검사를 우회할 수 없는데, 이는 문자 그대로 다른 코드 경로이기 때문이다.

컨텍스트 관리를 명시적으로 만들어라. 압축, 잘림 한계, 도구 검색, 디스크 지속성 — 이것들은 모두 모델이 보는 것을 적극적으로 관리하기 위한 메커니즘이다. 대부분의 취미 에이전트 빌드는 컨텍스트를 바닥 없는 가방으로 취급한다. 그렇지 않다.

세션 연속성을 위해 설계하라. 스냅샷, 되돌릴 수 있는 파일 변경, 지속적인 앵커로서의 CLAUDE.md. 장시간 실행 에이전트는 컨텍스트 압축에서 살아남는 메모리가 필요하다.

권한 세분화는 보상을 준다. 거부 우선 평가와 함께 도구별, 패턴별, 디렉터리별 규칙. “모든 것을 허용”하는 플래그보다 더 많은 작업이지만, 이것이 데모와 배포 가능한 시스템의 차이다.

자신만의 하네스를 구축할 때 vs. 관리 레이어를 사용할 때

좁고 잘 정의된 작업 — 테스트를 실행하고 결과를 게시하는 CI 봇 — 은 직접 최소한의 하네스를 연결할 수 있다. 몇 가지 도구, 간단한 권한 검사, 고정 컨텍스트 창.

확장 세션, 컨텍스트 재설정에 걸친 상태, 신뢰할 수 없는 도구 출력, 수십 개의 도구 — 기존 하네스 위에 구축하거나 하나를 면밀히 연구하라. Claude Agent SDK, OpenAI의 Codex 아키텍처, LangGraph는 모두 결국 부딪히게 될 문제들을 해결했다.

대부분의 팀은 하네스 복잡성을 과소평가한다. 나도 확실히 그랬다. 모델은 쉬운 부분이다.

FAQ

Claude Code의 에이전트 하네스란 무엇인가?

Claude 모델과 실제 세계 사이의 인프라 레이어 — 도구 디스패치, 권한, 컨텍스트 관리, 세션 상태, MCP 연결. Anthropic은 이를 “언어 모델을 유능한 코딩 에이전트로 전환하는” 것으로 설명한다.

Claude Code는 도구 권한을 어떻게 처리하는가?

규칙 기반 파이프라인이 모든 도구 호출을 평가한다: 허용, 질문, 또는 거부, 거부는 항상 이긴다. 자동 모드에서는 별도의 모델 인스턴스의 백그라운드 분류기가 모호한 경우를 평가한다 — 그리고 프롬프트 인젝션을 방지하기 위해 의도적으로 에이전트의 산문 출력을 보지 않는다.

Claude Code의 MCP 통합은 프로덕션 준비가 됐는가?

기능적이고 활발하게 사용되지만, 서버 수, 응답 크기, 서드파티 신뢰에 관한 실용적인 한계가 있다. 빠르게 발전하고 있다.

동일한 패턴을 사용하여 자체 하네스를 구축할 수 있는가?

그렇다. Claude Agent SDK는 동일한 권한 모드, 훅, 컨텍스트 관리를 노출한다. Everything Claude Code 같은 커뮤니티 프로젝트도 재사용 가능한 패턴을 문서화했다.

스펙 패리티와 동작 패리티의 차이는 무엇인가?

스펙 패리티는 동일한 도구와 구성을 지원하는 것을 의미한다. 동작 패리티는 엣지 케이스를 동일하게 처리하는 것을 의미한다 — 압축이 중요한 규칙을 삭제하거나, 도구가 100K 토큰을 반환하거나, 모델이 권한을 우회하려고 시도하는 경우. 스펙을 맞추는 것은 간단하다. 동작을 맞추는 데는 몇 달이 걸린다.

내 마음에 남아 있는 것: 하네스가 어려운 부분이다. 모든 사람이 모델이 경쟁 우위라고 가정한다. 그리고 그렇다 — 5분 이상 안정적으로 무언가를 하게 만들려고 할 때까지는. 그게 엔지니어링이 사는 곳이다.

이전 게시물: