Claude Code 심층 분석
현재와 미래 AI 에이전트 시스템의 설계 공간

초록#

Claude Code는 사용자를 대신해 셸 명령을 실행하고, 파일을 편집하며, 외부 서비스를 호출할 수 있는 에이전틱 코딩 도구다. 본 연구는 공개된 TypeScript 소스 코드^a를 분석해 그 종합적인 아키텍처를 기술하고, 나아가 서로 다른 배포 맥락에서 유사하거나 심지어 동일한 설계 질문에 답하는 두 개의 독립적인 오픈소스 AI 에이전트 시스템, OpenClaw와 Hermes Agent와 비교한다. 우리의 분석은 이 아키텍처를 추동하는 다섯 가지 인간적 가치·철학·필요를 식별한다: 인간의 결정 권한(human decision authority), 안전·보안·프라이버시(safety, security, and privacy), 신뢰할 수 있는 실행(reliable execution), 능력 증폭(capability amplification), 맥락 적응성(contextual adaptability). 이어서 우리는 이 가치들을 열세 가지 설계 원칙을 거쳐 구체적인 구현 선택으로 추적한다. 시스템의 핵심은 모델을 호출하고, 도구를 실행하고, 반복하는 단순한 while 루프다. 그러나 코드의 대부분은 이 루프를 둘러싼 시스템들에 있다: 일곱 가지 모드와 ML 기반 분류기를 갖춘 권한 시스템, 컨텍스트 관리를 위한 5계층 압축 파이프라인, 네 가지 확장 메커니즘(MCP, 플러그인, 스킬, 훅), 서브에이전트 위임 및 오케스트레이션 메커니즘, 그리고 추가 지향(append-oriented) 세션 저장소. OpenClaw(다채널 개인 비서 게이트웨이) 및 Hermes Agent(단일 프로세스, 다중 표면 비서)와의 비교는 동일한 설계 질문이 세 가지 배포 맥락에 걸쳐 서로 다른 답을 낳는다는 것을 보여준다. Claude Code는 행위 단위(per-action) 안전을 강조하고, OpenClaw는 경계 수준(perimeter-level) 접근을 강조하며, Hermes는 행위 단위 승인을 여러 표면에 걸쳐 렌더링한다. 런타임 계층에서 Claude Code는 단일 CLI 루프를 사용하고, OpenClaw는 게이트웨이 제어 평면(control plane) 안에 런타임을 내장하며, Hermes는 진입점에 의해 역할이 정해지는 하나의 프로세스를 사용한다. 컨텍스트 및 확장 계층에서 Claude Code는 컨텍스트 윈도우를 확장하고, OpenClaw는 게이트웨이 전역 능력(capability)을 등록하며, Hermes는 교체 가능한 메모리 및 모델 백엔드를 제공한다. 마지막으로 우리는 최근의 실증적·아키텍처적·정책적 문헌에 근거해 미래 에이전트 시스템을 위한 여섯 가지 열린 설계 방향을 식별한다.

1서론#

AI 지원 소프트웨어 개발은 GitHub Copilot(Chen et al., 2021) 같은 자동완성 방식 도구에서 출발해, Cursor(Cursor, 2026) 같은 IDE 통합형 어시스턴트를 거쳐, 다단계 수정을 자율적으로 계획하고 셸 명령을 실행하며 파일을 읽고 쓰고 자신의 출력을 반복 개선하는 완전한 에이전틱 시스템으로 진화해 왔다. Claude Code(Anthropic, 2026a)는 Anthropic이 출시한 에이전틱 코딩 도구다(Anthropic, 2026e). 공식 문서는 목표 달성을 향해 행위를 계획하고 실행하며, 도구를 호출하고 결과를 평가하며 작업이 끝날 때까지 계속할 수 있는 "에이전틱 루프(agentic loop)"를 기술한다¹. 제안에서 자율적 행위로의 이러한 전환은 완성(completion) 기반 도구에는 대응물이 없는 아키텍처적 요구사항을 불러온다. 이 요구사항들이 하나의 설계 공간(design space)을 정의한다. 즉 안전, 컨텍스트 관리, 확장성, 위임 같은 주제에 걸쳐 모든 코딩 에이전트가 헤쳐 나가야 하는 되풀이되는 질문들의 집합이다. 본 연구는 Claude Code에 대한 소스 수준 분석을 통해 하나의 프로덕션 시스템이 이 질문들에 어떻게 답하는지를 보인다.

채택이 늘고 있음에도 Anthropic은 Claude Code에 대해 사용자 대상 문서는 발행하지만 상세한 아키텍처 기술은 내놓지 않는다. 본 연구는 소스 코드 분석을 사용해 아키텍처적 설계 결정을 기술한다. Anthropic이 132명의 엔지니어와 연구자를 대상으로 실시한 내부 설문(Huang et al., 2025)은 Claude Code의 도움을 받은 과제 중 약 27%가 그 도구 없이는 시도조차 하지 않았을 작업이었다고 보고하는데, 이는 이 아키텍처가 단순히 기존 작업을 가속하는 것이 아니라 질적으로 새로운 워크플로를 가능하게 함을 시사한다.

본 연구에서 우리는 먼저 아키텍처를 추동하는 다섯 가지 인간적 가치/철학과 열세 가지 설계 원칙을 식별하고(2절), 이어서 분석을 세 부분으로 구성한다:

1. 설계 공간 분석. 우리는 되풀이되는 설계 질문들(추론은 어디에 위치하는가, 반복 루프는 어떻게 구조화되는가, 어떤 안전 태세를 취할 것인가, 확장 표면은 어떻게 분할되는가, 컨텍스트는 어떻게 관리되는가, 작업은 서브에이전트에 어떻게 위임되는가, 세션은 어떻게 지속되는가)을 식별하고, 7개 구성요소로 이루어진 고수준 구조와 5계층 서브시스템 아키텍처를 통해 Claude Code의 답을 분석하며, 각 선택을 구체적인 소스 파일로 추적한다(3절). 이 분석은 시스템 메커니즘에 대한 깊은 이해를 구축하여 더 낫고 강력한 에이전트 시스템의 설계에 정보를 제공하는 것을 목표로 한다.

1. OpenClaw 및 Hermes Agent와의 아키텍처적 대조. Claude Code 자체를 분석하는 것을 넘어, 우리는 그 설계 철학을 두 오픈소스 에이전트 시스템, OpenClaw(Steinberger and OpenClaw Contributors, 2026)(다채널 개인 비서 게이트웨이)와 Hermes Agent(Nous Research, 2026)(단일 프로세스, 다중 표면 비서)의 그것과 여섯 가지 설계 차원에 걸쳐 비교하여, 동일한 되풀이 질문들이 서로 다른 배포 맥락에서 어떻게 다른 답을 낳는지 보인다(10절). 이는 상용 소프트웨어와 오픈소스 소프트웨어 사이의 공통 원칙과 핵심 차이를 모두 부각하기 위함이다. 이 비교는 배포 환경, 제품 목표, 안전 요구사항, 사용자 가정이 아키텍처 선택을 어떻게 서로 다르게 형성하는지를 드러내는 데 도움이 된다. 이 시스템들이 수렴하는 지점과 갈라지는 지점을 살핌으로써, 본 연구는 더 유능한 미래 에이전트 시스템의 설계를 위한 유용한 지침과 실천적 통찰을 제공하고자 한다.

1. 미래 에이전트 시스템을 위한 열린 방향. 설계 공간 분석과 OpenClaw·Hermes 대조를 바탕으로, 13절은 관측가능성-평가 격차, 세션 간 지속성, 하네스 경계 진화, 지평 확장(horizon scaling), 거버넌스, 장기적 개발자 역량에 걸친 여섯 가지 열린 방향을 식별하며, 각각은 실증적·아키텍처적·정책적 문헌에 근거한다. 장기 역량 질문은 또한 하나의 열린 우려를 드러낸다: Claude Code 에이전트 시스템은 프로그래머와 최종 사용자의 단기적 능력을 증폭하지만, 장기적인 인간의 향상, 더 깊은 이해, 지속적인 코드베이스 일관성을 명시적으로 지원하는 메커니즘은 제한적으로만 제공한다.

핵심 에이전트 루프는 상태 관리를 갖춘 while-true 사이클이다. 안전, 확장성, 컨텍스트 관리, 위임, 지속성을 담당하는 주변 서브시스템들이 구현의 대부분을 차지한다. 소스 수준 분석²은 설계 선택, 서브시스템 경계, 구현상의 트레이드오프를 제품 설명에서만 추론하는 것이 아니라 시스템 자체에서 직접 식별할 수 있게 해준다.

러닝 예제. 아키텍처를 구체적으로 유지하기 위해, 우리는 "auth.test.ts의 실패하는 테스트를 고쳐라"라는 하나의 과제를 3절부터 9절까지 관통시킨다. 이 예제는 겉보기에 단순한 사용자 요청이 도구 호출, 권한 검사, 컨텍스트 선택, 반복적 수리, 위임, 세션 지속성을 포함한 여러 아키텍처 계층을 어떻게 활성화하는지를 보여준다.

논문 구성. 2절은 아키텍처를 추동하는 인간적 가치와 설계 원칙을 식별한다. 3절은 고수준 아키텍처와 그것이 답하는 설계 질문들을 소개한다. 4절부터 9절은 각각 주요 서브시스템의 설계 선택을 분석한다. 10절은 분석을 OpenClaw 및 Hermes Agent와 대조하고, 11절은 이 작업을 선행 에이전트 및 소프트웨어 공학 문헌에 견주어 위치시키며, 12절은 논의를 제공하고, 13절은 미래 에이전트 시스템을 위한 열린 질문들을 개관한다. 14절에서 결론을 맺는다. 부록은 증거 기반과 방법론, 패키지 구조 노트, 커뮤니티 재구현물, 그리고 새로운 에이전트 시스템 신호로부터 본 논문의 설계 공간 질문으로 이어지는 참조 지도를 기술한다.

2설계 철학, 설계 원칙, 아키텍처적 동기#

프로덕션 코딩 에이전트는 인간에 의해, 인간을 위해 만들어지며, 그것들이 담고 있는 아키텍처적 결정은 제작자가 무엇이 중요하다고 믿는지를 반영한다. 이 절은 Claude Code의 설계를 추동하는 인간적 가치를 식별하고, 그것을 되풀이되는 설계 원칙을 통해 추적하며, 3절부터 9절의 분석을 조직하는 설계 공간 질문들을 구성한다.

안전한 에이전트에 대한 Anthropic의 프레임워크는 하나의 중심 긴장을 진술한다: "에이전트는 자율적으로 작동할 수 있어야 한다. 그 독립적 작동이야말로 정확히 그것들을 가치 있게 만드는 요소다. 그러나 인간은 자신의 목표가 어떻게 추구되는지에 대한 통제권을 유지해야 한다"(Anthropic, 2025a). Claude's Constitution은 이를 경직된 결정 절차가 아니라 "맥락에 맞게 적용될 수 있는 좋은 판단과 건전한 가치"를 배양함으로써 해소한다(Anthropic, 2026b). 이러한 약속들은, 개발자가 실제로 이 도구를 어떻게 사용하는지에 관한 실증적 발견(Huang et al., 2025; McCain et al., 2026)과 함께, 아키텍처를 형성하는 다섯 가지 인간적 가치를 가리킨다.

2.1다섯 가지 가치와 철학#

인간의 결정 권한(Human Decision Authority). 인간은 시스템이 무엇을 하는지에 대한 궁극적 결정 권한을 유지하며, 이는 누가 무엇에 대한 권한을 갖는지를 형식화하는 주체 위계(Anthropic, 그다음 운영자, 그다음 사용자)를 통해 조직된다(Anthropic, 2026b). 시스템은 인간이 정보에 기반한 통제를 행사할 수 있도록 설계된다. 즉 실시간으로 행위를 관찰하고, 제안된 작업을 승인하거나 거부하고, 진행 중인 호환 작업을 중단시키고, 사후에 감사할 수 있다. Anthropic이 사용자가 권한 프롬프트의 93%를 승인한다는 것을 발견했을 때(Hughes, 2026), 그 대응은 경고를 더 추가하는 것이 아니라 문제를 재구조화하는 것이었다. 즉 사용자가 습관화되면 검토를 멈추게 되는 행위 단위 승인 대신, 에이전트가 자유롭게 작업할 수 있는 정의된 경계(샌드박싱, auto 모드 분류기)를 두는 것이다(Dworken and Weller-Davies, 2025).

안전·보안·프라이버시(Safety, Security, and Privacy). 시스템은 인간이 부주의하거나 실수를 저지를 때조차 인간과 그들의 코드, 데이터, 인프라를 해악으로부터 보호한다. 이는 인간의 결정 권한과는 구별된다. 권한이 인간의 선택할 힘에 관한 것이라면, 안전은 그 힘이 작동하지 않을 때조차 보호해야 하는 시스템의 의무에 관한 것이다. Anthropic의 안전 에이전트 프레임워크는 에이전트 상호작용의 보안 확보와 장기 상호작용에 걸친 프라이버시 보호를 별개의 핵심 약속으로 식별한다(Anthropic, 2025a). auto 모드 위협 모델(Hughes, 2026)은 네 가지 위험 범주를 명시적으로 겨냥한다: 과열된 행동(overeager behavior), 정직한 실수(honest mistakes), 프롬프트 인젝션, 모델 오정렬(misalignment).

신뢰할 수 있는 실행(Reliable Execution). 에이전트는 인간이 실제로 의도한 바를 수행하고, 시간이 지나도 일관성을 유지하며, 성공을 선언하기 전에 자신의 작업을 검증할 수 있게 한다. 이 가치는 단일 턴 정확성(요청을 충실히 해석했는가?)과 장기 지평 신뢰성(컨텍스트 윈도우 경계, 세션 재개, 다중 에이전트 위임을 넘어 일관성을 유지하는가?) 양쪽에 걸쳐 있다. Anthropic의 제품 문서(Anthropic, 2026f)는 에이전트가 과제가 완료될 때까지 반복하는 3단계 루프를 기술한다: 컨텍스트 수집, 행위 수행, 결과 검증. 에이전트 설계 지침(Schluntz and Zhang, 2024)은 나아가 각 단계에서 "환경으로부터의 실측 자료(ground truth)"가 진척을 평가한다고 강조한다. 하네스 설계 지침(Rajasekaran, 2026) 역시 품질이 그저 그럴 때조차 "에이전트는 작업을 자신 있게 칭찬하는 방식으로 반응하는 경향이 있다"고 지적하며, 생성과 평가의 분리를 동기 짓는다.

능력 증폭(Capability Amplification). 시스템은 노력과 비용 단위당 인간이 성취할 수 있는 것을 실질적으로 증가시킨다. 1절에서 논의한 Anthropic의 내부 설문(Huang et al., 2025)은 이 아키텍처가 단지 기존 작업을 더 빠르게 하는 것이 아니라 질적으로 새로운 워크플로를 가능하게 함을 시사한다. 즉 과제의 약 27%가 그렇지 않았다면 시도되지 않았을 작업을 나타냈다. 시스템은 제작자들에 의해 "전통적인 제품이라기보다는 Unix 유틸리티"로, "유용하고, 이해 가능하고, 확장 가능한" 가장 작은 구성 블록들로 만들어진 것으로 기술된다(Cherny and Wu, 2025). 이 아키텍처는 결정 스캐폴딩(명시적 플래너나 상태 그래프)이 아니라 결정론적 인프라(컨텍스트 관리, 도구 라우팅, 복구)에 투자하는데, 이는 갈수록 유능해지는 모델은 자신의 선택을 제약하는 프레임워크보다 풍부한 운영 환경에서 더 많은 이득을 얻는다는 전제에 기반한다.

맥락 적응성(Contextual Adaptability). 시스템은 사용자의 구체적인 맥락(그들의 프로젝트, 도구, 관례, 숙련도)에 맞춰지고, 그 관계는 시간이 지나면서 개선된다. 확장 아키텍처(CLAUDE.md, 스킬, MCP, 훅, 플러그인)는 여러 수준의 컨텍스트 비용에서 설정 가능성을 제공한다(6절과 7절). 종단 데이터(McCain et al., 2026)는 인간-에이전트 관계가 진화함을 보여준다. 자동 승인 비율은 세션 50회 미만에서 약 20%였다가 750세션에 이르면 40%를 넘는다. "모델과 사용자와 제품에 의해 공동 구성되는(co-constructed)" 자율성으로 기술되는 이 패턴은, 시스템이 고정된 신뢰 상태가 아니라 신뢰 궤적(trust trajectories)을 위해 설계되었음을 의미한다. MCP가 Linux Foundation의 Agentic AI Foundation에 기증된 것(The Linux Foundation, 2025)은 이 가치의 생태계적 차원을 반영한다.

2.2설계 원칙#

이 가치들은 열세 가지 설계 원칙을 통해 작동화되며, 각 원칙은 프로덕션 코딩 에이전트가 반드시 해결해야 하는 되풀이 질문 하나에 답한다. 표 1이 원칙들을 요약하며, 이어지는 절들(3절~9절)은 각각을 구체적인 구현 선택으로 추적한다.

표 1 설계 원칙, 그것이 봉사하는 가치, 그리고 각각이 답하는 설계 공간 질문. 원칙들은 여러 가치에 대응되며, 구현은 표시된 절에 등장한다.

이 원칙들은 세 가지 주요 대안 설계 계열에 견주어 읽을 수 있다. 첫째, 규칙 기반 오케스트레이션: LangGraph(LangChain, Inc., 2024) 같은 프레임워크는 결정 논리를 타입 지정 간선을 갖는 명시적 상태 그래프로 인코딩하며, 최소 하네스 대신 스캐폴딩을 선택한다. 둘째, 컨테이너 격리 실행: SWE-Agent와 OpenHands(Yang et al., 2024; Wang et al., 2024b)는 계층화된 정책 집행 대신 Docker 격리에 의존한다. 셋째, 안전장치로서의 버전 관리: Aider(Gauthier, 2024) 같은 도구는 거부 우선 평가 대신 Git 롤백을 주된 안전 메커니즘으로 사용한다. Claude Code의 원칙 집합은 최소 결정 스캐폴딩과 계층화된 정책 집행을, 가치 기반 판단과 거부 우선 기본값을, 점진적 컨텍스트 관리와 조합 가능한 확장성을 결합한다는 점에서 독특하다.

2.3가치에서 아키텍처로#

각 가치는 그 원칙들을 거쳐 구체적인 아키텍처 결정으로 이어진다:

• 인간의 결정 권한은 거부 우선 평가, 점진적 신뢰 스펙트럼, 추가 전용 상태(감사 가능한 이력), 외부화된 프로그래밍 가능 정책, 규칙보다 가치를 동기 짓는다(5절~7절 및 9절).
• 안전·보안·프라이버시는 심층 방어, 거부 우선 기본값, 되돌림 가능성 가중 평가, 외부화된 정책, 격리된 서브에이전트 경계를 동기 짓는다(5절, 8절).
• 신뢰할 수 있는 실행은 희소 자원으로서의 컨텍스트, 추가 전용 지속 상태, 우아한 복구, 격리된 서브에이전트 경계, 심층 방어를 동기 짓는다(4절 및 7절~9절).
• 능력 증폭은 최소 스캐폴딩, 조합 가능한 확장성, 되돌림 가능성 가중 위험, 컨텍스트 관리, 우아한 복구를 동기 짓는다(4절~6절).
• 맥락 적응성은 투명한 파일 기반 메모리, 조합 가능한 확장성, 점진적 신뢰 스펙트럼, 외부화된 프로그래밍 가능 정책을 동기 짓는다(5절~7절).

이 대응 관계는 또한 이 아키텍처가 하지 않는 것도 드러낸다. 그것은 모델의 추론에 명시적 계획 그래프를 부과하지 않으며, 단일한 통합 확장 메커니즘을 제공하지 않고, 재개 시 세션 범위의 신뢰 관련 상태를 모두 복원하지 않는다. 이 부재들은 위의 원칙 집합과 일관된다.

2.4가로지르는 질문: 장기적 개발자 역량#

위의 다섯 가치는 이 아키텍처가 무엇에 봉사하도록 설계되었는지를 기술한다. 본 논문은 여섯 번째 질문도 던진다. 즉 이 아키텍처가 개발자로 하여금 장기적 이해와 역량을 보존하도록 돕는가 하는 것이다. 이 우려는 실재한다. 132명의 엔지니어와 연구자에 대한 Anthropic 자체 연구(Huang et al., 2025)는 AI에 대한 과의존이 그것을 감독하는 데 필요한 기술을 위축시킬 위험이 있다는 "감독의 역설(paradox of supervision)"을 기록하고 있으며, 독립 연구(Shen and Tamkin, 2026)는 AI 지원 조건의 개발자가 이해도 테스트에서 17% 낮은 점수를 받는다는 것을 발견했다. 그러나 이 우려는 아키텍처나 Anthropic이 밝힌 설계 가치에서 설계 동인으로 두드러지게 반영되어 있지 않다. 따라서 우리는 이것을 동등한 가치가 아니라 가로지르는 관심사(cross-cutting concern)로 다룬다. 즉 단기적 증폭이 장기적인 인간의 이해, 코드베이스 일관성, 개발자 파이프라인을 대가로 치르는지를 묻는, 12절에서 다섯 가치 전반에 적용되는 질문이다.

3아키텍처 개요#

프로덕션 코딩 에이전트를 만들려면 몇 가지 되풀이되는 설계 질문에 답해야 한다. 추론은 어디에 있어야 하는가, 실행 엔진은 몇 개가 필요한가, 어떤 안전 태세를 취할 것인가, 어떤 자원을 구속력 있는 제약으로 다룰 것인가. Claude Code의 아키텍처는 이 질문들에 대한 하나의 답 집합으로 읽을 수 있다. 구현 수준에서 시스템은 주된 데이터 흐름으로 연결된 일곱 개의 구성요소를 갖는다. 사용자가 여러 인터페이스 중 하나를 통해 프롬프트를 제출하면, 이것이 공유 에이전트 루프로 들어간다. 에이전트 루프는 컨텍스트를 조립하고, Claude 모델을 호출하고, 도구 사용 요청을 포함할 수 있는 응답을 받고, 그 요청을 권한 시스템을 통해 라우팅하고, 승인된 행위를 실행 환경과 상호작용하는 구체적인 도구로 디스패치한다. 이 과정 내내 상태 및 지속성 메커니즘이 대화 트랜스크립트를 기록하고, 세션 정체성을 관리하며, 재개(resume)·포크(fork)·되감기(rewind) 작업을 지원한다.

그림 1 Claude Code의 고수준 시스템 구조. 시스템은 사용자, 인터페이스, 에이전트 루프, 권한 시스템, 도구, 상태 및 지속성, 실행 환경이라는 일곱 개의 기능 구성요소로 분해된다. 모든 진입 표면은 동일한 에이전트 루프로 수렴한다.

3.1설계 질문과 러닝 예제#

기술은 프로덕션 코딩 에이전트 전반에 되풀이되는 네 가지 설계 질문을 중심으로 조직되며, 각 질문은 표 1에서 식별한 설계 원칙 하나 이상에 근거한다. 각 질문은 여기서 Claude Code의 답, 그럴듯한 대안에 대한 언급과 함께 소개되고, 이후 4절부터 9절을 통해 점진적으로 시연된다.

추론은 어디에 위치하는가? Claude Code에서는 모델이 무엇을 할지 추론하고, 하네스가 행위 실행을 담당한다. 모델은 응답의 일부로 tool_use 블록을 방출하고, 하네스가 이를 파싱하고, 권한을 검사하고, 도구 구현으로 디스패치하고, 결과를 수집한다(query.ts). 모델은 결코 파일시스템에 직접 접근하거나, 셸 명령을 실행하거나, 네트워크 요청을 하지 않는다. 이 분리에는 보안적 귀결이 있다. 추론과 집행이 별개의 코드 경로를 차지하기 때문에, 침해되었거나 적대적으로 조작된 모델이라도 하네스에 구현된 샌드박싱, 권한 검사, 거부 우선 규칙을 무력화할 수 없다. 모델이 외부 세계와 접하는 유일한 인터페이스는 구조화된 tool_use 프로토콜이며, 하네스는 실행 전에 이를 검증한다. 추출된 소스에 대한 커뮤니티 분석은 Claude Code 코드베이스에서 AI 결정 논리에 해당하는 부분이 약 1.6%에 불과하고, 나머지 98.4%가 운영 인프라라고 추정하는데, 이 비율은 핵심 에이전트 추론 계층이 얼마나 얇은지를 보여준다. 대안 설계들은 스캐폴딩 측 추론에 더 많이 투자한다. Devin은 명시적인 계획 및 과제 추적 구조를 유지하고, LangGraph(LangChain, Inc., 2024)는 개발자가 정의한 상태 그래프를 통해 제어 흐름을 라우팅한다.

실행 엔진은 몇 개인가? Claude Code는 사용자가 대화형 터미널, 헤드리스 CLI 호출, Agent SDK, IDE 통합 중 무엇을 통해 상호작용하든 상관없이 실행되는 단일 queryLoop() 함수를 사용한다(query.ts). 렌더링 및 사용자 상호작용 계층만이 달라진다. 다른 시스템들은 모드별 엔진을 사용한다. 예를 들어 IDE 통합이 CLI 도구와 다른 코드 경로를 따를 수 있는데, 이는 균일성을 표면별 최적화와 맞바꾸는 것이다.

기본 안전 태세는 무엇인가? Claude Code의 기본 안전 태세는 인간 에스컬레이션을 동반한 거부 우선이다. 거부(deny) 규칙이 질의(ask) 규칙을 무시하고, 질의 규칙이 허용(allow) 규칙을 무시하며, 인식되지 않은 행위는 조용히 허용되는 대신 사용자에게 에스컬레이션된다(permissions.ts). 복수의 독립적인 안전 계층(권한 규칙, PreToolUse 훅, 활성화된 경우 auto 모드 분류기, 선택적 셸 샌드박싱)이 병렬로 적용되므로, 그중 어느 하나라도 행위를 차단할 수 있다(5절). 이는 표 1의 인간 에스컬레이션을 동반한 거부 우선과 계층화된 메커니즘을 통한 심층 방어 원칙을 결합한다. 대안적 접근들은 신뢰 경계를 다른 곳에 둔다. SWE-Agent와 OpenHands(Yang et al., 2024; Wang et al., 2024b)는 임의 실행을 봉쇄하기 위해 컨테이너 기반 격리에 의존하고, Aider(Gauthier, 2024)는 git 기반 롤백을 주된 안전망으로 사용한다.

구속력 있는 자원 제약은 무엇인가? Claude Code에서는 컨텍스트 윈도우(구형 모델은 200K, Claude 4.6 계열은 1M)가 구속력 있는 자원 제약이다. 모든 모델 호출 전에 다섯 가지 서로 다른 컨텍스트 축소 전략이 실행되며(query.ts), 다른 여러 서브시스템 결정(지시문의 지연 로딩, 지연된 도구 스키마, 요약만 반환하는 서브에이전트)도 컨텍스트 소비를 제한하기 위해 존재한다(7절). 5계층 파이프라인이 존재하는 이유는 단일 압축 전략으로는 모든 유형의 컨텍스트 압력을 다룰 수 없기 때문이다. 예산 축소(budget reduction)는 크기 한도를 넘치는 개별 도구 출력을 겨냥한다. 스닙(snip)은 시간적 깊이를 다룬다. 마이크로컴팩트(microcompact)는 캐시 오버헤드에 반응한다. 컨텍스트 붕괴(context collapse)는 아주 긴 이력을 관리한다. 오토컴팩트(auto-compact)는 최후 수단으로 의미적 압축을 수행한다. 각 계층은 서로 다른 비용-편익 트레이드오프에서 작동하며, 더 이르고 저렴한 계층이 더 비싼 계층보다 먼저 실행된다. 대안 아키텍처들은 다른 자원을 주된 병목으로 취급한다. 예컨대 계산 예산(모델 호출이나 도구 호출 횟수 제한)이나 작업 메모리(대화 이력에 의존하는 대신 명시적 스크래치패드 유지) 같은 것이다.

그림 2 단일 에이전틱 턴의 종단 간 실행을 보여주는 런타임 턴 흐름: 사용자 프롬프트가 컨텍스트 조립을 통해 들어오고, 모델이 호출되고, 도구 요청이 권한 게이트를 통과하고, 도구 결과가 루프로 되먹여지며, 압축이 컨텍스트 압력을 관리한다.

러닝 예제. 이 원칙들을 구체화하기 위해 우리는 3절부터 9절까지 하나의 과제를 관통시킨다: "auth.test.ts의 실패하는 테스트를 고쳐라." 이 절에서 사용자는 Claude Code의 인터페이스 중 하나를 통해 프롬프트를 제출한다. 이어지는 절들은 이 요청을 질의 루프, 권한 게이트, 도구 풀, 컨텍스트 윈도우, 서브에이전트 위임, 세션 지속성을 거쳐 추적한다.

3.2고수준 시스템 구조#

7개 구성요소 모델(그림 1)은 소스 파일에 직접 대응된다:

1. 사용자: 프롬프트를 제출하고, 권한을 승인하며, 출력을 검토한다.
2. 인터페이스: 대화형 CLI, 헤드리스 CLI(claude -p), Agent SDK, IDE/데스크톱/브라우저. 모든 표면이 동일한 루프로 들어간다.
3. 에이전트 루프: 모델 호출, 도구 디스패치, 결과 수집의 반복 사이클로, query.ts의 queryLoop() 비동기 제너레이터로 구현된다.
4. 권한 시스템: 거부 우선 규칙 평가(permissions.ts), auto 모드 ML 분류기, 훅 기반 가로채기(types/hooks.ts).
5. 도구: assembleToolPool()(tools.ts)을 통해 조립되는 최대 54개의 내장 도구(19개는 무조건, 35개는 기능 플래그 및 사용자 유형에 따라 조건부)가 MCP 제공 도구와 병합된다. 플러그인은 MCP 서버 및 스킬/커맨드 레지스트리를 통해 간접적으로 기여한다.
6. 상태 및 지속성: 대체로 추가 전용인 JSONL 세션 트랜스크립트(sessionStorage.ts), 전역 프롬프트 이력(history.ts), 서브에이전트 사이드체인 파일.
7. 실행 환경: 선택적 샌드박싱을 동반한 셸 실행(shouldUseSandbox.ts), 파일시스템 작업, 웹 페치, MCP 서버 연결, 원격 실행.

데이터 흐름은 왼쪽에서 오른쪽으로 가는 척추를 따른다. 사용자가 인터페이스를 통해 요청을 제출하면 그것이 에이전트 루프로 들어간다. 루프는 권한 시스템에 행위를 제안하고, 승인된 행위는 도구에 도달하며, 도구는 실행 환경과 상호작용하고 tool_result 메시지를 루프로 반환한다. 상태 및 지속성은 루프 옆에 위치하여 트랜스크립트를 기록하고 이전 세션 데이터를 로드한다.

애플리케이션 진입점 main()(main.tsx)은 보안 설정(Windows PATH 하이재킹을 방지하기 위한 NoDefaultCurrentDirectoryInExePath 포함)을 초기화하고, 우아한 종료를 위한 시그널 핸들러를 등록하며, 적절한 실행 모드로 디스패치한다.

3.3계층화된 서브시스템 분해#

그림 3 다섯 개 서브시스템 계층을 보여주는 확장된 계층 아키텍처: 표면(대화형 CLI, 헤드리스 CLI, Agent SDK, IDE/데스크톱/브라우저, UI/렌더러), 코어(에이전트 루프, 압축 파이프라인), 안전/행위(auto 모드 분류기를 포함한 권한 시스템, 훅 파이프라인, 확장성, 내장 도구, MCP 도구, 셸 샌드박스, 서브에이전트 스포닝), 상태(컨텍스트 조립, 런타임 상태, 세션 지속성, CLAUDE.md + 메모리, 사이드체인 트랜스크립트), 백엔드(실행 백엔드, 외부 리소스).

5계층 분해(그림 3)는 7개 구성요소 모델을 더 세밀한 관점으로 확장하며, 각 계층을 구체적인 소스 디렉터리에 대응시킨다.

표면 계층(진입점 및 렌더링). src/entrypoints/ 디렉터리는 coreTypes.ts, controlSchemas.ts, coreSchemas.ts를 포함한 SDK 진입점을 비롯한 시작 경로를 담고 있다. src/screens/ 디렉터리는 전체 화면 레이아웃을 구성하고, src/components/는 ink 프레임워크를 통해 터미널 UI 구성 블록을 제공한다. 대화형 CLI는 실시간 스트리밍, 권한 대화상자, 진행 표시기를 갖춘 터미널 UI를 띄운다. 헤드리스 CLI(claude -p)는 단발성 처리를 위해 공유 질의 경로를 감싸는 얇은 대화 래퍼인 QueryEngine 인스턴스를 생성한다(3.4절). Agent SDK는 비동기 제너레이터를 통해 타입이 지정된 이벤트를 방출한다.

코어 계층(에이전트 루프, 압축 파이프라인). queryLoop() 비동기 제너레이터(query.ts)는 반복적 에이전트 루프를 구현하며, 상태 계층에서 조립된 컨텍스트를 소비하고 도구 요청을 안전/행위 계층으로 디스패치한다. 모든 모델 호출 전에 다섯 개의 순차적 셰이퍼로 구성된 압축 파이프라인(query.ts:365-453)이 컨텍스트 압력을 관리한다: 예산 축소, 스닙, 마이크로컴팩트, 컨텍스트 붕괴, 오토컴팩트(4.3절과 7.3절).

안전/행위 계층(권한 시스템, 훅, 확장성, 도구, 샌드박스, 서브에이전트). 권한 시스템(permissions.ts)은 최대 일곱 가지 권한 모드(내부 전용인 bubble과 기능 게이팅된 auto까지 세는 경우)(types/permissions.ts)로 거부 우선 규칙 평가를 구현하며, 도구 안전성에 대한 2단계 고속 필터 및 사고 사슬(chain-of-thought) 평가를 제공하는 통합 auto 모드 ML 분류기(yoloClassifier.ts)를 갖는다(5절). 27개 이벤트 유형에 걸친 훅 파이프라인(coreTypes.ts, 출력 스키마는 types/hooks.ts)이 도구 요청을 차단, 재작성, 주석 처리할 수 있다. 이 중 5개는 안전 관련이고 나머지 22개는 생명주기 및 오케스트레이션 목적에 봉사한다(6절). 확장성 서브시스템은 플러그인과 스킬이 런타임에 도구와 훅을 등록할 수 있게 한다. assembleToolPool()(tools.ts)을 통한 도구 풀 조립은 내장 도구와 MCP 제공 도구를 병합한다. 승인된 셸 명령은 권한 시스템과 독립적으로 파일시스템 및 네트워크 접근을 제한하는 셸 샌드박스(shouldUseSandbox.ts)를 통과한다. AgentTool(AgentTool.tsx, runAgent.ts)을 통한 서브에이전트 스포닝은 다른 모든 도구와 동일한 buildTool() 팩토리를 통해 디스패치되며, 격리된 컨텍스트 윈도우로 queryLoop()에 재진입하여 부모에게 요약만 반환한다(8절).

상태 계층(컨텍스트 조립, 런타임 상태, 지속성, 메모리, 사이드체인). 컨텍스트 조립은 라우팅 허브가 아니라 메모이즈된 상태 로더다. getSystemContext()(context.ts)는 git 상태를 포함한 세션 수준 시스템 컨텍스트를 계산하고, getUserContext()(context.ts)는 CLAUDE.md 계층과 현재 날짜를 로드한다. 둘 다 재사용을 위해 캐시된다. 시스템 컨텍스트는 시스템 프롬프트에 덧붙여지고, 사용자 컨텍스트는 사용자 컨텍스트 메시지로 추가된다. src/state/ 디렉터리는 런타임 애플리케이션 상태를 관리한다. 세션 트랜스크립트는 프로젝트별 경로에 대체로 추가 전용인 JSONL 파일로 저장된다(sessionStorage.ts). CLAUDE.md + 메모리 서브시스템은 관리 설정에서 디렉터리별 파일까지 4단계 지시문 계층(claudemd.ts)과, Claude가 대화 중 작성하는 자동 메모리 항목을 제공한다(7.2절). 사이드체인 트랜스크립트(sessionStorage.ts:247)는 각 서브에이전트의 대화를 별도 파일에 저장하여 서브에이전트 내용이 부모 컨텍스트를 부풀리는 것을 방지한다(8.3절). 전역 프롬프트 이력은 history.jsonl에 유지된다(history.ts). 재개 및 포크 작업은 트랜스크립트로부터 세션 상태를 재구성한다(conversationRecovery.ts).

백엔드 계층(실행 백엔드, 외부 리소스). 선택적 샌드박싱을 동반한 셸 명령 실행(BashTool.tsx, PowerShellTool.tsx), 원격 실행 지원(src/remote/), stdio·SSE·HTTP·WebSocket·SDK 및 IDE 전용 어댑터를 포함한 다중 전송 방식의 MCP 서버 연결(services/mcp/client.ts), 그리고 구체적인 도구 로직을 구현하는 src/tools/의 42개 도구 하위 디렉터리.

3.4QueryEngine: 하나의 명확화#

QueryEngine.ts의 클래스 문서는 다음과 같이 진술한다: "QueryEngine은 하나의 대화에 대한 질의 생명주기와 세션 상태를 소유한다. 이는 ask()의 핵심 로직을 헤드리스/SDK 경로와 (미래 단계에서는) REPL 양쪽이 사용할 수 있는 독립 클래스로 추출한 것이다." 이 클래스는 비대화형 표면을 위한 대화 래퍼이지, 엔진 자체가 아니다. 그 생성자는 초기 메시지, 중단 컨트롤러, 파일 상태 캐시, 기타 대화별 상태를 담은 QueryEngineConfig를 받는다. 그 submitMessage() 메서드는 단일 턴을 조율하는 비동기 제너레이터다. 공유 질의 경로는 내부의 queryLoop()을 감싸는 query()(query.ts)에 있으며, QueryEngine은 query()에 위임한다.

이 구분은 아키텍처적으로 중요하다. 대화형 CLI 역시 query()를 호출하며, QueryEngine을 완전히 우회한다. 공유되는 코드 경로는 엔진 클래스가 아니라 루프 함수다.

3.5권한 및 안전 계층#

기본 안전(safety-by-default) 원칙은 일곱 개의 독립적인 계층을 통해 구현된다. 요청은 적용 가능한 모든 계층을 통과해야 하며, 단 하나의 계층이라도 그것을 차단할 수 있다:

1. 도구 사전 필터링(tools.ts): 전면 거부된 도구는 어떤 호출이 이루어지기도 전에 모델의 시야에서 제거되어, 모델이 그것을 호출하려 시도하는 것을 방지한다.
2. 거부 우선 규칙 평가(permissions.ts): 허용 규칙이 더 구체적일 때조차 거부 규칙이 항상 우선한다.
3. 권한 모드 제약(types/permissions.ts): 활성 모드가 명시적 규칙에 매칭되지 않는 요청의 기본 처리를 결정한다.
4. auto 모드 분류기: ML 기반 분류기가 도구 안전성을 평가하여, 규칙 시스템이 허용할 요청을 거부할 수도 있다.
5. 셸 샌드박싱(shouldUseSandbox.ts): 승인된 셸 명령이라도 파일시스템 및 네트워크 접근을 제한하는 샌드박스 안에서 실행될 수 있다.
6. 재개 시 권한 미복원(conversationRecovery.ts): 세션 범위 권한은 재개나 포크 시 복원되지 않는다.
7. 훅 기반 가로채기(types/hooks.ts): PreToolUse 훅은 권한 결정을 수정할 수 있고, PermissionRequest 훅은 사용자 대화상자와 나란히(또는 coordinator 모드에서는 그보다 먼저) 결정을 비동기적으로 해소할 수 있다.

이 계층들은 5절에서 상세히 기술한다.

3.6병목으로서의 컨텍스트: 압축을 넘어#

5계층 압축 파이프라인(7절에서 상술) 외에도, 여러 서브시스템 결정이 컨텍스트-병목 제약을 반영한다:

• CLAUDE.md 지연 로딩: 기본 CLAUDE.md 계층은 세션 시작 시 로드되지만, 추가적인 중첩 디렉터리 지시문 파일과 조건부 규칙은 에이전트가 해당 디렉터리의 파일을 읽을 때에만 로드되어, 사용되지 않는 지시문이 컨텍스트를 소비하는 것을 방지한다.
• 지연된 도구 스키마: ToolSearch가 활성화되면 일부 도구는 초기 컨텍스트에 이름만 포함하고, 전체 스키마는 필요 시 로드된다.
• 서브에이전트 요약 전용 반환: 서브에이전트는 전체 대화 이력이 아니라 요약 텍스트만 부모에게 반환한다(8절).
• 도구 결과별 예산: 개별 도구 결과는 설정 가능한 크기로 상한이 걸려, 단일한 장황한 출력이 컨텍스트를 불균형하게 소비하는 것을 방지한다.

4턴 실행: 에이전틱 질의 루프#

사용자가 "auth.test.ts의 실패하는 테스트를 고쳐라"를 제출하면, 그 입력은 코딩 에이전트를 위한 여러 가능한 오케스트레이션 패턴 중 하나인 반응형(reactive) 루프로 들어간다. 이 절은 Claude Code의 단순 while 루프 아키텍처 선택을 검토하고 그 루프의 한 턴을 종단 간으로 추적하며, 표 1의 세 가지 설계 원칙을 예시한다: 최소 스캐폴딩, 최대 운영 하네스, 점진적 관리를 동반한 희소 자원으로서의 컨텍스트, 우아한 복구와 회복력.

4.1질의 파이프라인#

각 턴은 고정된 순서를 따른다(그림 2, query.ts):

1. 설정 해소. queryLoop() 함수는 시스템 프롬프트, 사용자 컨텍스트, 권한 콜백, 모델 설정을 포함한 불변 파라미터를 구조 분해한다.
2. 가변 상태 초기화. 하나의 State 객체가 메시지, 도구 컨텍스트, 압축 추적, 복구 카운터를 포함해 반복 전반의 모든 가변 상태를 저장한다. 루프의 일곱 개 continue 지점("continue sites")은 각각 필드를 개별적으로 변경하는 대신 전체 객체 할당 한 번으로 이 객체를 덮어쓴다.
3. 컨텍스트 조립. getMessagesAfterCompactBoundary() 함수가 마지막 컴팩트 경계 이후의 메시지를 가져와, 압축된 내용이 원본 메시지가 아니라 그 요약으로 표현되도록 보장한다.
4. 모델 이전 컨텍스트 셰이퍼. 다섯 개의 셰이퍼가 순차 실행된다(4.3절).
5. 모델 호출. deps.callModel()에 대한 for await 루프가 모델의 응답을 스트리밍하면서, 조립된 메시지(사용자 컨텍스트가 앞에 붙은), 전체 시스템 프롬프트, 사고(thinking) 설정, 사용 가능한 도구 집합, 중단 시그널, 현재 모델 명세, 그리고 fast 모드 설정·effort 값·폴백 모델을 포함한 추가 옵션을 전달한다.
6. 도구 사용 디스패치. 응답에 tool_use 블록이 포함되면 도구 오케스트레이션 계층으로 흘러간다(4.2절).
7. 권한 게이트. 각 도구 요청은 권한 시스템을 통과한다(5절).
8. 도구 실행 및 결과 수집. 도구 결과는 tool_result 메시지로 대화에 추가되고, 루프는 계속된다.
9. 정지 조건. 응답에 tool_use 블록이 없으면(텍스트만) 턴이 완료된다.

queryLoop() 함수는 AsyncGenerator로 정의되어, 진행하면서 StreamEvent, RequestStartEvent, Message, TombstoneMessage, ToolUseSummaryMessage 이벤트를 산출한다. 이 제너레이터 기반 설계는 루프 내에서 단일한 동기적 제어 흐름을 유지하면서도 UI 계층으로의 스트리밍 출력을 가능하게 한다.

Claude Code의 반응형 루프는 ReAct 패턴(Yao et al., 2022)을 따른다. 모델이 추론과 도구 호출을 생성하고, 하네스가 행위를 실행하며, 결과가 다음 반복으로 되먹여진다. 대안적 오케스트레이션 패턴에는 제어 흐름을 타입 지정 간선을 갖는 상태 기계로 정의하는 명시적 그래프 기반 라우팅(LangChain, Inc., 2024)과, 커밋 전에 복수의 행위 궤적을 탐색하는 트리 탐색 방법(Zhou et al., 2023)이 있다. Anthropic 자체 문서(Schluntz and Zhang, 2024)는 다섯 가지 조합 가능한 워크플로 패턴(프롬프트 체이닝, 라우팅, 병렬화, 오케스트레이터-워커, 평가자-최적화자)을 식별하는데, Claude Code는 핵심 루프를 반응형으로 유지하면서 주로 서브에이전트 위임을 위해 오케스트레이터-워커 패턴을 사용한다(8절). 이 반응형 설계는 탐색 완전성을 단순성과 지연시간과 맞바꾼다. 각 턴은 역추적 없이 하나의 행위 시퀀스에 커밋한다.

4.2도구 디스패치와 스트리밍 실행#

모델 응답에 tool_use 블록이 포함되면, 시스템은 두 가지 실행 경로 중에서 선택한다. 주 경로는 StreamingToolExecutor를 사용하는데, 이는 모델 응답에서 도구가 스트리밍되어 들어오는 대로 실행을 시작하여 다중 도구 응답의 지연시간을 줄인다. 폴백 경로는 toolOrchestration.ts의 runTools()를 사용하며, partitionToolCalls()가 생성한 분할을 순회한다. 두 경로 모두 도구를 동시 실행 안전(concurrent-safe) 또는 배타적(exclusive)으로 분류한다. 읽기 전용 작업은 병렬로 실행될 수 있고, 셸 명령 같은 상태 변경 작업은 직렬화된다.

StreamingToolExecutor(StreamingToolExecutor.ts)는 두 가지 조율 메커니즘으로 동시 실행을 관리한다:

• 형제 중단 컨트롤러(Sibling abort controller). 어떤 Bash 도구가 오류를 내면 발동하여, 진행 중인 다른 하위 프로세스를 끝까지 실행되게 두는 대신 즉시 종료한다.
• 진행 가능 신호(Progress-available signal). 새로운 출력이 준비되면 getRemainingResults() 소비자를 깨운다.

결과는 버퍼링되어 도구가 수신된 순서대로 방출되므로, 도구가 병렬로 실행되더라도 출력 순서는 동일하게 유지된다. 이는 모델이 자신의 도구 사용 요청과 동일한 순서로 도구 결과를 기대하기 때문에 중요하다. 이 동시 읽기, 직렬 쓰기 실행 모델은 완전 직렬 디스패치와, 모델이 아직 생성 중일 때 예측된 미래 도구 호출을 투기적으로 미리 실행해 도구 지연시간을 감추는 PASTE(Sui et al., 2026) 같은 더 공격적인 투기적 접근 사이의 중간 지점을 차지한다.

도구 결과 수집 단계는 스트리밍 실행기 또는 배치 방식 runTools() 비동기 제너레이터로부터의 업데이트를 순회한다. 둘 다 동일한 for await 루프가 소비하는 비동기 이터러블이다. 차이는 도구 실행이 모델의 스트리밍 완료 전에 시작되는지(스트리밍), 아니면 동시성 안전 그룹으로 분할한 후에 시작되는지(배치)에 있다. 각 업데이트는 도구 결과, 첨부, 또는 진행 이벤트를 실을 수 있다. 특수 검사가 hook_stopped_continuation 첨부를 탐지한다. PostToolUse 훅이 턴을 계속해서는 안 된다고 신호하면 shouldPreventContinuation 플래그가 설정된다. 결과는 normalizeMessagesForAPI()를 통해 Anthropic API용으로 정규화되며, user 유형 메시지만 남기도록 필터링된다.

4.3모델 이전 컨텍스트 셰이퍼#

query.ts에서 다섯 개의 컨텍스트 셰이퍼가 모든 모델 호출 전에 순차 실행되며, 각각 messagesForQuery 배열을 대상으로 동작한다. 다섯 셰이퍼는 순서대로 실행되어, 앞의 단계가 더 가벼운 축소를 적용한 뒤 뒤의 단계가 더 광범위한 압축을 적용한다.

예산 축소(Budget reduction). (applyToolResultBudget()) 도구 결과에 메시지별 크기 한도를 강제하여, 크기를 초과한 출력을 콘텐츠 참조로 대체한다. 면제 도구(maxResultSizeChars가 유한하지 않은 도구)는 전체 출력을 유지한다. 콘텐츠 대체는 재개 시 재구성을 가능하게 하기 위해 에이전트 및 세션 질의 소스에 대해 지속된다. 예산 축소는 마이크로컴팩트보다 먼저 실행되는데, 마이크로컴팩트는 순전히 tool_use_id로만 동작하고 내용을 결코 검사하지 않기 때문이다. 두 가지는 깔끔하게 조합된다.

스닙(Snip). (snipCompactIfNeeded(), HISTORY_SNIP으로 게이팅) 오래된 이력 구간을 제거하는 가벼운 정리로, {messages, tokensFreed, boundaryMessage}를 반환한다. snipTokensFreed 값은 오토컴팩트로 명시 전달되는데, 주 토큰 카운터가 가장 최근 어시스턴트 메시지의 usage 필드에서 컨텍스트 크기를 도출하고, 그 메시지는 스닙 이전의 input_tokens를 그대로 달고 스닙에서 살아남기 때문이다. 따라서 스닙의 절감분은 명시적으로 전달되지 않으면 카운터에 보이지 않는다.

마이크로컴팩트(Microcompact). 항상 시간 기반 경로를 실행하고 선택적으로 캐시 인지 경로(CACHED_MICROCOMPACT로 게이팅)를 실행하는 세밀한 압축이다. 캐시 경로가 활성화되면 경계 메시지가 API 응답 이후로 지연되어, 추정치가 아니라 실제 cache_deleted_input_tokens를 사용할 수 있게 된다. {messages, compactionInfo}를 반환하며, compactionInfo에는 pendingCacheEdits가 포함될 수 있다.

컨텍스트 붕괴(Context collapse). CONTEXT_COLLAPSE로 게이팅된다. 대화 이력에 대한 읽기 시점 투영(read-time projection)이다. 소스 주석은 이렇게 설명한다: "아무것도 산출되지 않는다. 붕괴된 뷰는 REPL의 전체 이력에 대한 읽기 시점 투영이다. 요약 메시지는 REPL 배열이 아니라 붕괴 저장소에 존재한다. 이것이 붕괴가 턴을 넘어 지속되게 만드는 요소다." 다른 셰이퍼들과 달리 컨텍스트 붕괴는 REPL의 저장된 이력을 변경하지 않는다. applyCollapsesIfNeeded()를 통해 messagesForQuery 배열을 투영된 뷰로 대체하므로, 모델은 붕괴된 버전을 보지만 전체 이력은 재구성을 위해 남아 있다.

오토컴팩트(Auto-compact). 다섯 번째 셰이퍼로, compact.ts의 compactConversation()을 통해 모델이 생성하는 전체 요약을 발동한다. 이 함수는 PreCompact 훅을 실행하고, getCompactPrompt()를 사용해 요약 요청을 생성하며, 모델을 호출해 압축된 요약을 생성한다. 결과는 buildPostCompactMessages()(compact.ts)로 들어간다. 오토컴팩트는 앞의 네 셰이퍼가 모두 실행된 뒤에도 컨텍스트가 여전히 압력 임계값을 초과할 때에만 발동한다.

4.4복구 메커니즘#

질의 루프는 예외 상황을 위한 여러 복구 메커니즘을 구현한다:

• 최대 출력 토큰 에스컬레이션: 응답이 출력 토큰 상한에 도달하면, GrowthBook 플래그와 기존 재정의 또는 환경 변수 상한의 부재를 조건으로, 시스템이 상향된 한도로 재시도할 수 있다. 턴당 최대 세 번의 복구 시도가 허용된다(MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3).
• 반응형 압축(REACTIVE_COMPACT로 게이팅): 컨텍스트가 용량에 가까워지면 반응형 컴팩트가 공간을 확보할 만큼만 요약한다. hasAttemptedReactiveCompact 플래그가 이것이 턴당 최대 한 번만 발동하도록 보장한다.
• 프롬프트 과대 처리: API가 prompt_too_long 오류를 반환하면, 루프는 먼저 컨텍스트 붕괴 오버플로 복구와 반응형 압축을 시도한다. 이것들이 실패한 뒤에야 reason: 'prompt_too_long'으로 종료한다.
• 스트리밍 폴백: onStreamingFallback 콜백이 스트리밍 API 문제를 처리하여, 루프가 다른 전략으로 재시도할 수 있게 한다.
• 폴백 모델: fallbackModel 파라미터는 주 모델이 실패할 경우 대체 모델로 전환할 수 있게 한다.

4.5정지 조건#

여러 조건이 루프를 종료시킬 수 있다:

1. 도구 미사용: 모델이 텍스트 내용만 생성한다(주된 정지 조건).
2. 최대 턴: 설정 가능한 maxTurns 한도에 도달한다.
3. 컨텍스트 오버플로: API가 prompt_too_long을 반환한다.
4. 훅 개입: PostToolUse 훅이 hook_stopped_continuation을 설정한다.
5. 명시적 중단: abortController 시그널이 발동한다.

턴 파이프라인은 도구 요청이 어떻게 조율되고 복구되는지를 결정한다. 다음 절은 각 요청이 애초에 실행이 허가되는지를 결정하는 게이트를 검토한다.

5도구 인가와 통제 경계#

프로덕션 코딩 에이전트들은 서로 다른 안전 아키텍처를 채택한다. 계층화된 정책 집행, OS 수준 샌드박싱, 또는 버전 관리 기반 롤백이다. Claude Code는 앞의 둘을 결합하여, 표 1의 네 가지 설계 원칙을 구현한다: 인간 에스컬레이션을 동반한 거부 우선, 점진적 신뢰 스펙트럼, 계층화된 메커니즘을 통한 심층 방어, 되돌림 가능성 가중 위험 평가.

그림 4 권한 게이트 개요와 설계 원칙.

• 점진적 신뢰(Progressive Trust): 에이전트는 최소한의 자율성으로 시작하고, 사용자가 영구 규칙이 되는 도구 호출을 승인함으로써 그것을 확장한다.
• 거부 우선, 질의 기본(Deny-First, Ask-by-Default): 더 느슨한 모드에서도 거부 규칙이 항상 이긴다. default 및 수동 승인 모드에서, 매칭되지 않은 위험 수반 행위는 조용히 실행되는 대신 사용자에게 묻는다. 선택적 auto 모드는 그러한 검토 다수를 분류기 매개 검사로 라우팅한다.
• 조합 가능한 정책(Composable Policy): 세 가지 메커니즘이 정책을 형성한다. 선언적 규칙, 전역 신뢰 모드, 프로그래밍 가능 훅이며 각각 독립적으로 설정 가능하다.

Claude가 도구를 실행하기로 결정하면(예: auth 테스트 실패를 재현하기 위해 BashTool을 통해 npm test를 실행), 그 요청은 그림 4의 권한 파이프라인으로 들어간다. bypass 모드를 제외하면 도구 호출은 권한 시스템을 통과한다. 기본 대화형 태세에서 읽기 전용 접근을 넘어서는 행위는 조용히 실행되는 대신 승인을 요청하며, 더 허용적인 모드는 일부 프롬프트를 범위 제한된 자동 승인, 거부, 또는 분류기 매개 검토로 대체한다. 이 기본값은 문서화된 행동 패턴에 의해 동기 지어진다. Anthropic의 auto 모드 분석(Hughes, 2026)은 사용자가 권한 프롬프트의 약 93%를 승인한다는 것을 발견했으며, 이는 승인 피로(approval fatigue)로 인해 대화형 확인이 단독 안전 메커니즘으로서 행동적으로 신뢰할 수 없게 됨을 시사한다. 사용자가 습관적으로 신중한 검토 없이 승인하기 때문에, 시스템은 인간의 경계심과 독립적으로 안전을 유지해야 한다. 이것이 사용자의 주의력과 무관하게 작동하는 독립적 계층으로서 거부 우선 평가, 전면 거부 사전 필터링, 샌드박싱에 대한 아키텍처적 헌신을 동기 짓는다.

5.1권한 모드와 규칙 평가#

타입 정의 전반에 걸쳐 일곱 가지 권한 모드가 존재한다(types/permissions.ts의 외부 모드 5개, 조건부로 추가되는 auto, 타입 유니온의 bubble):

1. plan: 모델이 계획을 세워야 하며, 사용자 승인 이후에만 실행이 진행된다.
2. default: 표준 대화형 사용. 대부분의 작업이 사용자 승인을 요구한다.
3. acceptEdits: 작업 디렉터리 내의 편집과 특정 파일시스템 셸 명령(mkdir, rmdir, touch, rm, mv, cp, sed)이 자동 승인되고, 다른 셸 명령은 승인을 요구한다.
4. auto: ML 기반 분류기가 고속 경로 검사를 통과하지 못한 요청을 평가한다(TRANSCRIPT_CLASSIFIER로 게이팅).
5. dontAsk: 프롬프트가 억제되고, 원래라면 물어봤을 행위는 자동 거부된다. 명시적 허용 및 거부 규칙은 여전히 적용된다.
6. bypassPermissions: 대부분의 권한 프롬프트를 건너뛰지만, 안전 필수 검사와 bypass 면역 규칙은 여전히 적용된다.
7. bubble: 부모 터미널로의 서브에이전트 권한 에스컬레이션을 위한 내부 전용 모드.

외부에 보이는 다섯 모드(acceptEdits, bypassPermissions, default, dontAsk, plan)는 EXTERNAL_PERMISSION_MODES 배열에 정의된다. auto 모드는 TRANSCRIPT_CLASSIFIER 기능 플래그가 활성일 때에만 조건부로 포함된다. bubble 모드는 타입 유니온에 존재하지만 어느 모드 배열에도 없으며, 서브에이전트 권한 에스컬레이션에 내부적으로 사용된다(8절).

권한 규칙은 거부 우선 순서로 평가된다(permissions.ts). toolMatchesRule() 함수는 거부 규칙을 먼저 검사한다. 허용 규칙이 더 구체적일 때조차 거부 규칙이 항상 우선한다. 광범위한 거부("모든 셸 명령을 거부")는 좁은 허용("npm test를 허용")으로 무효화될 수 없다. 규칙 시스템은 도구 수준 매칭(도구 이름 기준)과 콘텐츠 수준 매칭(Bash(prefix:npm) 같은 특정 도구 입력 패턴 매칭)을 지원한다.

일곱 모드는 plan(사용자가 실행 전 모든 계획을 승인)에서 default와 acceptEdits를 거쳐 bypassPermissions(최소 프롬프트)에 이르는 점진적 자율성 스펙트럼에 걸쳐 있다. 이 기울기는 되풀이되는 설계 긴장을 반영한다. 자율성이 증가할수록 시스템은 대화형 승인에서 자동화된 안전 검사로 이동해야 한다. 다른 에이전트 시스템들은 이 긴장을 다르게 해소한다. SWE-Agent와 OpenHands(Yang et al., 2024; Wang et al., 2024b)는 Docker 컨테이너 격리를 사용하여, 개별 도구 호출을 평가하는 대신 에이전트의 실행 환경 전체를 샌드박싱한다. Aider(Gauthier, 2024)는 Git을 안전망으로 삼아 모든 변경을 버전 관리를 통해 되돌릴 수 있게 한다. Claude Code의 접근법은 선택적 컨테이너 샌드박싱 위에 복수의 정책 집행 메커니즘을 계층화하여, 단순성을 개별 행위에 대한 세밀한 통제와 맞바꾼다.

5.2인가 파이프라인#

전체 인가 파이프라인은 여러 단계를 거친다:

사전 필터링. 어떤 도구 요청이 런타임 평가에 도달하기 전에, filterToolsByDenyRules()(tools.ts)가 도구 풀 조립 시점에 전면 거부된 도구를 모델의 시야에서 완전히 제거한다. 문서는 이렇게 진술한다: "런타임 권한 검사와 동일한 매처를 사용하므로, mcp__server 같은 MCP 서버 접두사 규칙은 모델이 보기 전에 해당 서버의 모든 도구를 제거한다." 이는 모델이 금지된 도구를 호출하려 시도하는 것을 방지하므로, 모델이 그것들에 호출을 낭비하지 않는다.

PreToolUse 훅. 등록된 훅이 권한 파이프라인의 일부로 발동한다. PreToolUse 훅은 거부 또는 질의를 위한 permissionDecision을 반환하거나, 도구의 입력 파라미터를 수정하는 updatedInput을 반환할 수 있다(types/hooks.ts). 훅의 허용은 이후의 규칙 기반 거부나 안전 검사를 우회하지 않는다. 대화형 경로에서는 사용자 대화상자가 먼저 대기열에 오르고 훅이 비동기적으로 실행된다. coordinator 및 유사한 백그라운드 에이전트 경로는 대화상자를 표시하기 전에 자동화된 검사를 기다린다.

규칙 평가. 거부 우선 규칙 엔진이 요청을 평가한다. MCP 도구는 완전 수식 이름 mcp__server__tool로 매칭되며, 서버 수준 규칙은 해당 서버의 모든 도구에 매칭된다.

권한 핸들러. useCanUseTool.tsx의 핸들러는 런타임 맥락에 따라 네 가지 경로 중 하나로 분기한다:

1. Coordinator: 다중 에이전트 조율 모드용. 사용자 상호작용으로 폴백하기 전에 자동 해소(분류기, 훅, 규칙)를 시도한다.
2. Swarm worker: 자체 해소 로직을 갖는 다중 에이전트 스웜의 워커 에이전트를 처리한다.
3. 투기적 분류기(Speculative classifier): BASH_CLASSIFIER가 활성이고 도구가 BashTool일 때, 투기적 분류기가 미리 시작된 분류 결과를 타임아웃과 경주시킨다. 분류기가 높은 확신으로 반환하면 사용자 상호작용 없이 즉시 승인된다.
4. Interactive: 폴백 경로. 터미널 UI를 통해 표준 사용자 승인 대화상자를 제시한다.

coordinator 및 일부 백그라운드 경로에서는 사용자 상호작용 전에 자동 해소가 시도된다. 표준 대화형 경로에서는 훅이나 분류기 검사가 병렬로 계속되는 동안 대화상자가 먼저 나타날 수 있다. 분류기나 거부 규칙이 행위를 차단할 때, 시스템은 그 거부를 강한 정지가 아니라 라우팅 신호로 취급한다. 모델은 거부 사유를 받고, 접근법을 수정하며, 다음 루프 반복에서 더 안전한 대안을 시도한다. PermissionDenied 훅 이벤트(6절)는 외부 코드가 이러한 거부를 프로그래밍적으로 관찰하고 대응할 수 있게 한다. 이 복구 지향 설계는 권한 집행이 에이전트를 단순히 멈추는 것이 아니라 그 행동을 형성함을 의미한다.

5.3auto 모드 분류기와 훅 생명주기#

auto 모드 분류기(yoloClassifier.ts)는 활성화되었을 때 권한 결정에 참여한다. TRANSCRIPT_CLASSIFIER가 활성화되면 분류기는 세 가지 프롬프트 리소스를 로드한다:

• 기본 시스템 프롬프트.
• 외부 권한 템플릿.
• Anthropic 내부 사용자를 위한 별도의 내부 템플릿.

분류기는 제안된 도구 호출을 대화 트랜스크립트 및 권한 템플릿에 견주어 평가하여 허용, 거부, 또는 수동 승인 요청을 생성한다. isUsingExternalPermissions() 함수는 USER_TYPE과 forceExternalPermissions 설정 플래그를 검사해 적절한 템플릿을 선택한다.

소스에 정의된 27개 훅 이벤트 중 다섯 개가 권한 흐름에 직접 참여하며, 각각 Zod로 검증되는 고유한 출력 스키마를 갖는다(types/hooks.ts):

• PreToolUse: permissionDecision(거부 또는 질의. 단 허용은 이후 검사를 우회하지 않음), permissionDecisionReason, updatedInput(파라미터 수정)을 반환할 수 있다.
• PostToolUse: additionalContext를 주입할 수 있고, MCP 도구의 경우 결과가 컨텍스트에 들어가기 전에 수정하기 위해 updatedMCPToolOutput을 반환할 수 있다.
• PostToolUseFailure: 오류별 안내를 위해 additionalContext를 주입할 수 있다.
• PermissionDenied: auto 모드 거부 이후 재시도 안내를 제공할 수 있다.
• PermissionRequest: 허용 또는 거부 결정을 반환할 수 있다. coordinator 및 유사 경로에서는 사용자 대화상자 이전에 해소될 수 있다. 표준 대화형 경로에서는 대화상자와 나란히 실행될 수도 있다.

비MCP 도구의 경우 tool_result가 PostToolUse 훅 발동 전에 방출된다. MCP 도구의 경우 결과가 사후 훅 실행 이후로 지연되어, updatedMCPToolOutput이 효력을 갖게 한다.

5.4셸 샌드박싱#

셸 샌드박싱은 Bash 및 PowerShell 명령에 추가적인 보호 계층을 제공한다(shouldUseSandbox.ts). shouldUseSandbox() 함수는 샌드박싱이 전역적으로 활성화되어 있는지, 해당 호출이 옵트아웃했는지, 명령이 제외 패턴에 매칭되는지를 검사한다.

활성일 때 샌드박스는 애플리케이션 수준 권한 모델과 독립적으로 파일시스템 및 네트워크 격리를 제공한다.³ 어떤 명령은 권한 승인을 받고도 여전히 샌드박싱될 수 있고, 권한 거부되어 샌드박스 검사에 아예 도달하지 않을 수도 있다. 두 시스템은 서로 다른 축에서 작동한다. 인가(authorization) 대 격리(isolation)다.

계층화된 안전 아키텍처는 독립성 가정에 기반한다. 한 계층이 실패해도 다른 계층들이 위반을 잡아낸다는 것이다. 그러나 여러 계층이 공통의 성능 제약을 공유한다. 보안 연구자들(Adversa.ai, 2026)은 하위 명령이 50개를 넘는 명령이 하위 명령별 거부 규칙 검사를 실행하는 대신 단일한 일반 승인 프롬프트로 폴백한다는 것을 문서화했는데, 이는 하위 명령별 파싱이 UI 정지를 유발했기 때문이다. 이 예는 심층 방어가 그 계층들이 실패 모드를 공유할 때 저하될 수 있음을 보여주며, 이는 12.3절에서 더 분석되는 안전과 성능 사이의 구조적 긴장이다.

권한 파이프라인은 도구 요청이 실행될지를 통제한다. 다음 절은 애초에 어떤 도구가 존재하는지를 결정하는 것, 즉 모델의 행위 표면을 조립하는 확장성 아키텍처를 검토한다.

6확장성: MCP, 플러그인, 스킬, 훅#

코딩 에이전트에 되풀이되는 설계 질문 하나는 확장 표면을 어떻게 구조화할 것인가다. 단일한 통합 메커니즘인가, 소수의 특화된 메커니즘인가, 아니면 서로 다른 컨텍스트 비용을 갖는 계층 스택인가. 여기서의 분석은 표 1의 두 설계 원칙을 예시한다: 조합 가능한 다중 메커니즘 확장성과 외부화된 프로그래밍 가능 정책. 러닝 예제로 돌아가면, Claude가 auth.test.ts를 수리하려 하고 앞선 npm test 요청이 권한 시스템에 의해 매개된 뒤(5절), 다음 질문은 그 수리를 위해 어떤 확장 가능 행위 표면이 이용 가능한가다. Claude Code에서 턴이 시작될 때 모델은 BashTool과 FileReadTool 같은 내장 도구뿐 아니라, MCP 서버의 데이터베이스 질의 도구, .claude/skills/의 커스텀 린트 스킬, 설치된 플러그인이 기여한 도구도 본다. 이것들은 루프의 서로 다른 지점에서 에이전트를 확장하는 네 가지 메커니즘을 통해 도착한다. MCP 서버는 외부 도구 통합을 제공하고, 플러그인은 구성요소 묶음을 패키징하고 배포하며, 스킬은 도메인 특화 지시문을 주입하고, 훅은 도구 실행 생명주기를 가로챈다. Anthropic 문서(Anthropic, 2026f)는 여기서 분석하는 네 메커니즘과 함께 CLAUDE.md(7절)와 서브에이전트(8절)를 포함하는 더 넓은 관점을 제시한다. 우리는 CLAUDE.md와 서브에이전트를 각각 별개의 절에서 다루는데, 이것들이 서로 다른 서브시스템(각각 컨텍스트 구축과 위임)에서 작동하기 때문이다. 다만 컨텍스트 비용 순서는 아키텍처적으로 유의미하다. 그것은 각 확장 지점이 표현력을 제한된 컨텍스트 윈도우와 어떻게 맞바꾸는지를 드러낸다.

그림 5 Claude Code의 확장 메커니즘이 에이전트 루프에 꽂히는 지점. 모든 에이전트 루프에는 세 개의 주입 지점이 있다. ⓐ assemble()은 모델이 무엇을 보는지, ⓑ model()은 모델이 무엇에 도달할 수 있는지, ⓒ execute()는 행위가 실제로 실행되는지와 어떻게 실행되는지를 통제한다.

# Claude Code 에이전트 루프의 한 턴
while not stopped:
    # ⓐ assemble: 모델이 보는 것을 구축
    context = assemble(
        system_prompt,   # 지시문 헤더
        tool_schemas,    # 호출 가능한 도구 시그니처
        history,         # 이전 턴 메시지
        hook_additions,  # 훅이 밀어 넣은 것
    )
    # ⓑ model: 다음 행위를 선택
    action = model(context, tools)  # 평평한 도구 풀
    if action.is_text_only():
        stopped = run_stop_hooks(action)  # 거부권 행사 가능
        continue
    # ⓒ execute: 인가하고 도구 호출을 실행
    action, hook_decision = run_pre_tool_hooks(action)
    if not permitted(action, hook_decision):
        continue
    result = execute(action)              # 여기서 도구 실행
    result = run_post_tool_hooks(result)  # 변형/주석
    history.append(action, result)

ⓐ assemble(): 모델이 보는 것 — CLAUDE.md 파일(컨텍스트로 로드. 작업 디렉터리 상위 파일은 시작 시, 하위 디렉터리 파일은 필요 시 로드), 스킬 설명(모델이 SkillTool을 호출하도록 스킬을 광고), MCP 리소스 및 프롬프트(MCP 서버가 밀어 넣는 비도구 콘텐츠), 출력 스타일(응답 서식 시스템 블록을 대체), UserPromptSubmit 훅(매 사용자 턴마다 컨텍스트를 주입하거나 차단), SessionStart 훅(세션 시작 시 일회성 컨텍스트 주입).

ⓑ model(): 모델이 도달할 수 있는 것 — 내장 도구(Read/Edit/Bash/… CLI에 동봉), MCP 도구(임의의 MCP 서버의 도구, 동일한 평평한 풀 안에), SkillTool(이름으로 스킬을 실행하는 메타 도구), AgentTool(재귀적으로 서브에이전트를 생성하는 메타 도구).

ⓒ execute(): 행위가 실행되는지/어떻게 실행되는지 — 권한 규칙(호출별 선언적 allow/deny/ask), PreToolUse 훅(도구 호출 승인/차단/재작성), PostToolUse 훅(호출 이후 출력 변형 또는 컨텍스트 주입), Stop 훅(모델 정지 시 루프를 계속하게 강제), SubagentStop 훅(AgentTool로 생성된 서브에이전트에 대해 동일), Notification 훅(사용자 알림에 대한 외부 부수 효과).

6.1네 가지 확장 메커니즘#

메커니즘들은 별개의 소스 디렉터리에 구현되어 있으며(그림 5) 서로 다른 통합 패턴에 봉사한다:

MCP 서버. Model Context Protocol은 주된 외부 도구 통합 경로다. MCP 서버는 프로젝트, 사용자, 로컬, 엔터프라이즈라는 여러 범위에서 설정되며, 런타임에 플러그인 및 claude.ai 서버가 추가로 병합된다(services/mcp/config.ts). MCP 클라이언트(services/mcp/client.ts)는 여러 전송 유형을 지원한다: stdio, SSE, HTTP, WebSocket, SDK와 IDE 전용 변형(sse-ide, ws-ide), 그리고 내부 claudeai-proxy. 연결된 각 서버는 MCPTool 객체로 도구 정의를 기여한다. 전용 내장 도구인 ListMcpResourcesTool과 ReadMcpResourceTool이 MCP 리소스 접근을 제공한다.

플러그인. 플러그인은 이중 역할을 한다. 패키징 형식이자 배포 메커니즘이다. PluginManifestSchema(utils/plugins/schemas.ts)는 열 가지 구성요소 유형을 받아들인다: 커맨드, 에이전트, 스킬, 훅, MCP 서버, LSP 서버, 출력 스타일, 채널, 설정, 사용자 설정. 플러그인 로더(utils/plugins/pluginLoader.ts)는 매니페스트를 검증하고 각 구성요소를 해당 레지스트리로 라우팅한다. 커맨드와 스킬은 SkillTool 메타 도구를 통해 표면화되고, 에이전트는 AgentTool이 소비하는 정의에 나타나며, 훅은 훅 레지스트리에 병합되고, MCP 및 LSP 서버는 표준 설정에 접히며, 출력 스타일은 응답 서식을 수정한다. 따라서 단일 플러그인 패키지가 여러 구성요소 유형에 걸쳐 동시에 Claude Code를 확장할 수 있어, 플러그인은 서드파티 확장의 주된 배포 수단이 된다.

스킬. 각 스킬은 YAML 프론트매터를 갖는 SKILL.md 파일로 정의된다. parseSkillFrontmatterFields() 함수(loadSkillsDir.ts)는 표시 이름, 설명, 허용 도구(스킬에 추가 도구 접근 권한 부여), 인자 힌트, 모델 재정의, 실행 컨텍스트(격리 실행을 위한 'fork'), 연관된 에이전트 정의, effort 수준, 셸 설정을 포함해 15개 이상의 필드를 파싱한다. 스킬은 자체 훅을 정의할 수 있으며, 이는 호출 시 동적으로 등록된다. 동봉된 스킬은 시작 시 메모리에 등록된다. 호출되면 SkillTool 메타 도구가 해당 스킬의 지시문을 컨텍스트에 주입한다.

훅. 소스 코드는 27개 훅 이벤트를 정의한다. 도구 인가(PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied), 세션 생명주기(SessionStart, SessionEnd, Setup, Stop, StopFailure), 사용자 상호작용(UserPromptSubmit, Elicitation, ElicitationResult), 서브에이전트 조율(SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted), 컨텍스트 관리(PreCompact, PostCompact, InstructionsLoaded, ConfigChange), 워크스페이스 이벤트(CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove), 알림에 걸쳐 있다(coreTypes.ts, coreSchemas.ts). 이 중 15개는 권한 결정, 컨텍스트 주입, 입력 수정, MCP 결과 변환, 재시도 제어를 지원하는 풍부한 필드를 갖는 이벤트별 출력 스키마를 가진다(types/hooks.ts). 설정과 플러그인을 통해 구성되는 지속 훅 명령은 네 가지 명령 유형을 사용한다: 셸 명령(type: command), LLM 프롬프트 훅(type: prompt), HTTP 훅(type: http), 에이전틱 검증기 훅(type: agent)(schemas/hooks.ts). 런타임은 추가로 SDK와 내부 계측이 사용하는 비지속 콜백 훅(type: callback)을 지원한다(types/hooks.ts). 훅 소스에는 시작 시의 settings.json, 플러그인, 관리 정책이 포함되고, 스킬 훅은 호출 시 동적으로 등록된다(utils/hooks.ts). 다섯 개의 도구 인가 이벤트는 5.3절에서 상술한다.

6.2도구 풀 조립#

tools.ts의 assembleToolPool() 함수는 소스 주석에서 "내장 도구와 MCP 도구를 결합하는 단일 진실 원천"으로 기술된다. 조립은 5단계 파이프라인을 따른다:

1. 기본 도구 열거. getAllBaseTools()(tools.ts)는 최대 54개 도구 배열을 반환한다. 19개는 항상 포함되고(BashTool, FileReadTool, AgentTool, SkillTool 등), 35개는 기능 플래그·환경 변수·사용자 유형에 따라 조건부로 포함된다. Anthropic 내부 사용자는 추가 내부 도구를 받는다. worktree 모드는 EnterWorktreeTool과 ExitWorktreeTool을 활성화한다. 에이전트 스웜은 팀 도구를 활성화한다. Bun 바이너리에 내장 검색 도구가 있으면 전용 GlobTool과 GrepTool은 생략된다.
2. 모드 필터링. getTools()(tools.ts)가 모드별 필터링을 적용한다. CLAUDE_CODE_SIMPLE 모드에서는 Bash, Read, Edit만 사용 가능하다(REPL 분기에서는 REPLTool, 해당되면 coordinator 도구 추가). 각 도구의 isEnabled() 메서드가 런타임 가용성 검사를 위해 호출된다.
3. 거부 규칙 사전 필터링. filterToolsByDenyRules()(tools.ts)가 어떤 호출이 이루어지기 전에 전면 거부된 도구를 모델의 시야에서 제거한다.
4. MCP 도구 통합. appState.mcp.tools의 MCP 도구가 거부 규칙으로 필터링되어 내장 도구와 병합된다.
5. 중복 제거. 도구는 이름으로 중복 제거되며, 내장 도구가 MCP 도구보다 우선한다.

REPL.tsx(useMergedTools 훅을 통해)와 AgentTool.tsx(워커 도구 집합을 구축할 때) 모두 이 함수를 호출하여, 모든 실행 경로에 걸친 일관된 조립을 보장한다. 요청 시점에는 지연 도구가 ToolSearch로 명시적으로 질의될 때까지 모델의 컨텍스트에서 숨겨질 수 있다(tools.ts).

에이전트 기반 확장(.claude/agents/*.md를 통한 커스텀 에이전트 정의와 플러그인이 기여하는 에이전트)은 8절에서 다룬다. 에이전트는 위의 네 메커니즘과 근본적으로 다르기 때문이다. 그것들은 현재 컨텍스트를 확장하는 것이 아니라 새롭고 격리된 컨텍스트 윈도우를 생성한다.

6.3왜 네 가지 메커니즘인가?#

확장 메커니즘이 하나 늘어날 때마다 개발자가 학습해야 하는 표면적이 증가한다는 점을 감안하면, Claude Code가 왜 하나나 둘로 통합하지 않고 네 개의 별개 메커니즘을 사용하는지는 자연스러운 질문이다. 답은 서로 다른 종류의 확장성이 컨텍스트 윈도우에 서로 다른 비용을 부과한다는 관찰에 있다. 단일 메커니즘으로는 확장 작성자에게 불필요한 트레이드오프를 강요하지 않고서 컨텍스트 비용 0인 생명주기 훅부터 스키마가 무거운 도구 서버까지의 전 범위를 아우를 수 없다.

표 2 각 확장 메커니즘이 고유하게 제공하는 것. 컨텍스트 비용은 해당 메커니즘이 활성일 때 제한된 컨텍스트 윈도우를 얼마나 소비하는지를 가리킨다.

표 2가 요약하듯, 각 메커니즘은 배포 복잡성을 서로 다른 종류의 확장성과 맞바꾼다. MCP 서버는 서버 관리 오버헤드와 도구 스키마가 소비하는 컨텍스트 예산을 대가로 런타임 도구 통합(모델이 새로운 호출 가능 도구를 얻음)을 제공한다. 스킬은 최소한의 컨텍스트 비용으로 에이전트가 어떻게 생각하는지(단지 어떤 도구를 갖는지가 아니라)를 형성하는데, 프론트매터 설명만(전체 내용이 아니라) 프롬프트에 남기 때문이다. 훅은 기본적으로 컨텍스트 발자국 없이 가로지르는 생명주기 통제(도구 호출 차단, 재작성, 주석)를 제공하지만, 훅이 추가 컨텍스트 주입을 선택할 수도 있다. 플러그인은 나머지 셋의 임의 조합을 배포 가능한 패키지로 묶어, 별개의 런타임 원시 요소라기보다 패키징·배포 계층 역할을 한다. 점진적 컨텍스트 비용 순서(훅 0, 스킬 낮음, 플러그인 중간, MCP 높음)는 저렴한 확장이 컨텍스트 윈도우를 고갈시키지 않고 널리 확장될 수 있고, 비싼 확장은 진정으로 새로운 도구 표면이 필요한 경우에 유보됨을 의미한다.

일부 에이전트 프레임워크는 단일 확장 메커니즘, 대개 모든 커스터마이징이 추가 호출 가능 도구로 도착하는 도구 전용 API를 제공한다. 다른 것들은 도구를 설정이나 지시문 주입과 분리하는 2계층을 사용한다. Claude Code의 4메커니즘 접근법은 컨텍스트 0인 이벤트 핸들러부터 완전한 외부 서비스 통합까지 더 넓은 범위의 확장 패턴을 수용할 수 있지만, 주어진 통합 과제에 어떤 메커니즘을 사용할지 결정할 때 개발자가 직면하는 학습 곡선을 높인다.

7컨텍스트 구축과 메모리#

에이전트가 컨텍스트 윈도우를 어떻게 관리하고 사용자 지시문을 어떻게 지속시키는지는 중심적인 설계 선택이며, 시스템마다 파일 기반 투명성, 데이터베이스 기반 검색, 불투명한 학습 표현 사이에서 선택한다. 여기서의 설계 선택은 표 1의 두 원칙을 구현한다: 점진적 관리를 동반한 희소 자원으로서의 컨텍스트와 투명한 파일 기반 설정 및 메모리.

러닝 예제에서 이 시점에 이르면 과제는 상태를 축적한 상태다. 원래 요청, npm test 권한 결과, 6절에서 조립된 도구 풀, 그리고 지금까지 수집된 파일 읽기나 명령 출력. 이 절은 그 늘어나는 상태가 다음 모델 호출 전에 Claude Code의 제한된 컨텍스트 윈도우에 어떻게 채워지는지를 묻는다.

모델이 호출되기 전에 에이전트 루프는 도구 풀(6절), CLAUDE.md 파일, 자동 메모리, 대화 이력으로부터 컨텍스트 윈도우를 조립한다. 이어지는 하위 절들은 조립 순서, CLAUDE.md 계층, 다단계 압축 파이프라인을 다룬다.

그림 6 컨텍스트 구축과 메모리 계층. 컨텍스트 윈도우로 수렴하는 소스에는 시스템 프롬프트, 출력 스타일, 환경 정보, CLAUDE.md 계층(managed부터 디렉터리별까지), 자동 메모리, 경로 범위 규칙, MCP 도구 이름, ToolSearch를 통한 지연 도구 정의, 대화 이력, 파일 읽기, 명령 출력, 도구 결과, 서브에이전트 요약, 컴팩트 요약이 포함된다. 계층 구성: (1) 시스템 계층[시작 시, 읽기 전용], (2) 프로젝트 설정[시작 시/지연, 핫리로드], (3) 메모리[시작 시, 시스템 쓰기], (4) 대화[턴마다 누적, 추가], (5) 런타임[실행 중 추가, 모델 트리거], (6) 온디맨드[지연 로드, ToolSearch를 통해].

7.1컨텍스트 윈도우 조립#

컨텍스트 윈도우(그림 6)는 다음 소스들로부터 조립되며, 일부는 최초 조립 시, 일부는 턴 도중 늦게 주입된다:

1. 출력 스타일 수정과 --append-system-prompt 플래그 내용을 반영한 시스템 프롬프트.
2. getSystemContext()(context.ts)를 통한 환경 정보: git 상태(원격 모드이거나 git 지시문이 비활성일 때는 생략)와 내부 빌드용 선택적 캐시 무효화 주입(BREAK_CACHE_COMMAND로 게이팅). 세션당 한 번 메모이즈된다.
3. getUserContext()(context.ts)를 통한 CLAUDE.md 계층: 4단계 지시문 파일 계층(7.2절). 역시 메모이즈된다.
4. 경로 범위 규칙: 에이전트가 매칭되는 디렉터리의 파일을 읽을 때 지연 로드되는 조건부 및 디렉터리 매칭 규칙.
5. 자동 메모리: 비동기적으로 미리 가져온 맥락상 관련된 메모리 항목.
6. 도구 메타데이터: 스킬 설명, MCP 도구 이름, 지연 도구 정의(ToolSearch를 통해 필요 시).
7. 대화 이력: 압축의 대상이 되며 계속 이월된다.
8. 도구 결과: 파일 읽기, 명령 출력, 서브에이전트 요약.
9. 컴팩트 요약: 오래된 이력 구간을 대체한다.

query.ts의 시스템 프롬프트 조립은 asSystemPrompt(appendSystemContext(systemPrompt, systemContext))()를 통해 시스템 컨텍스트를 기본 프롬프트와 결합한다. 사용자 컨텍스트(CLAUDE.md와 날짜)는 prependUserContext()를 통해 메시지 배열 앞에 붙는다. 이 분리는 CLAUDE.md 내용이 API 요청에서 시스템 프롬프트와는 다른 구조적 위치를 차지함을 의미하며, 이는 잠재적으로 모델의 주의(attention) 패턴에 영향을 준다.

여러 컨텍스트 소스는 주 윈도우가 구축된 뒤 늦게 주입된다. 관련 메모리 사전 인출(query.ts), MCP 지시문 델타(신규 또는 변경된 서버 지시문만), 에이전트 목록 델타, 백그라운드 에이전트 과제 알림 등이다. 따라서 컨텍스트 윈도우는 조립 시점에 고정된 것이 아니라 턴 도중 늘어날 수 있다.

7.2CLAUDE.md 계층과 자동 메모리#

하나의 설계 원칙이 메모리 시스템을 형성한다. 저장된 컨텍스트는 사용자가 검사하고 편집할 수 있어야 한다는 것이다. CLAUDE.md 파일은 구조화된 설정이나 불투명한 데이터베이스 항목이 아니라 평문 마크다운이다. 이 투명성 선택은 표현력을 감사 가능성과 맞바꾼다. 사용자는 자신이 통제하는 메모리 파일을 직접 검사하고 편집할 수 있으며, 프로젝트 수준 메모리는 코드베이스와 함께 버전 관리될 수 있다(Anthropic, 2026g; MindStudio Team, 2026). 대안적 메모리 아키텍처들이 이 트레이드오프를 예시한다. 검색 증강(RAG) 접근법은 임베딩 기반 조회로 관련된 이전 컨텍스트를 표면화하여 유연성을 얻지만 검사 가능성을 잃는다. 사용자는 검색 시스템이 무엇을 관련 있다고 여기는지 쉽게 보거나 편집할 수 없다. 데이터베이스 기반 메모리는 구조화된 질의를 제공하지만 추가 인프라를 요구하며 버전 관리에 불투명하다. Claude Code의 파일 기반 접근법은 이 메모리 표면들을 읽고 편집 가능하게 만든다. 다른 컨텍스트 소스들은 여전히 시스템 프롬프트, 도구, 훅, MCP 서버, 런타임 상태를 통해 들어오지만 말이다. 이 시스템은 메모리 검색에 임베딩이나 벡터 유사도 인덱스를 사용하지 않는다. 대신 메모리 파일 헤더에 대한 LLM 기반 스캔으로 필요 시 최대 다섯 개의 관련 파일을 선택하여, 항목 단위가 아니라 파일 단위로 표면화한다. 임베딩 기반 시스템은 개별 항목을 더 선택적으로 검색할 수 있지만, 검사 가능성과 인덱스 유지에 필요한 인프라를 대가로 치른다.

CLAUDE.md 파일은 다단계 로딩 계층을 따른다. 소스 헤더(claudemd.ts)는 네 가지 메모리 유형을 정의한다:

1. 관리 메모리(Managed memory)(예: Linux의 /etc/claude-code/CLAUDE.md): 모든 사용자를 위한 OS 수준 정책.
2. 사용자 메모리(User memory)(~/.claude/CLAUDE.md): 비공개 전역 지시문.
3. 프로젝트 메모리(Project memory)(프로젝트 루트의 CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md): 코드베이스에 체크인된 지시문.
4. 로컬 메모리(Local memory)(프로젝트 루트의 CLAUDE.local.md): gitignore 처리되는, 비공개 프로젝트별 지시문.

파일 탐색은 현재 디렉터리에서 루트까지 거슬러 올라가며 각 디렉터리에서 모든 프로젝트 및 로컬 메모리 파일을 검사한다. 현재 디렉터리에 가까운 파일이 더 높은 우선순위를 갖는다(나중에 로드됨).

파일은 "우선순위의 역순으로" 로드된다. 즉 나중에 로드된 파일이 더 많은 모델 주의를 받는다. 루트에서 CWD까지의 디렉터리에 대해서는 .claude/rules/*.md의 무조건 규칙이 시작 시 즉시 로드된다. CWD 아래의 중첩 디렉터리에 대해서는 무조건 규칙조차도 에이전트가 매칭되는 디렉터리의 파일을 읽을 때 지연 로드된다. 이는 모델의 지시문 집합이 코드베이스의 새로운 부분이 탐색됨에 따라 대화 도중 진화할 수 있음을 의미한다.

CLAUDE.md 내용은 시스템 프롬프트 콘텐츠가 아니라 사용자 컨텍스트(user 메시지)로 전달된다(context.ts). 이 아키텍처적 선택에는 중대한 함의가 있다. CLAUDE.md 내용이 시스템 수준 지시문이 아니라 대화적 컨텍스트로 전달되기 때문에, 이 지시문에 대한 모델 준수는 보장된 것이 아니라 확률적이다. 거부 우선 순서로 평가되는 권한 규칙(5절)이 결정론적 집행 계층을 제공한다. 이는 지침(CLAUDE.md, 확률적)과 집행(권한 규칙, 결정론적) 사이의 의도적 분리를 만든다. 이 함수는 auto 모드 분류기를 위해 로드된 내용을 캐시하도록 setCachedClaudeMdContent()를 호출하는데, 이는 CLAUDE.md 로더와 권한 시스템 사이의 임포트 순환을 피하기 위함이다.

메모리 파일은 모듈식 지시문 집합을 위한 @include 지시자를 지원한다(claudemd.ts의 processMemoryFile()). 문법 변형에는 @path, @./relative, @~/home, @/absolute가 있다. 이 지시자는 리프 텍스트 노드에서만 작동한다(코드 블록 안에서는 작동하지 않음). 구현에서 포함하는 파일이 먼저 푸시되고 포함된 파일들이 그 뒤에 붙으며, 처리된 경로를 추적하여 순환 참조를 방지하고, 존재하지 않는 파일은 조용히 무시된다.

7.3압축 파이프라인#

5계층 압축 파이프라인(4.3절)은 점진적 압축을 통해 "병목으로서의 컨텍스트" 원칙을 구현한다(query.ts). 단일 전략 대신 Claude Code는 다섯 계층을 순서대로 적용하며, 각각 공격성이 증가한다(세 개는 기능 플래그로 게이팅되고, 예산 축소는 항상 활성이며, 오토컴팩트는 사용자가 설정할 수 있다). 이 점진적 접근법은 단일 패스 절단(가장 오래된 메시지 제거)이나 단일 요약 단계 같은 더 단순한 대안과 대조된다. 점진적 설계는 지연 저하(lazy-degradation) 원칙을 반영한다. 가장 덜 파괴적인 압축을 먼저 적용하고, 더 저렴한 전략이 불충분한 것으로 판명될 때에만 강도를 높인다. 이 접근의 비용은 복잡성이다. 여러 개가 기능 플래그로 게이팅된 다섯 개의 상호작용하는 압축 계층은 사용자가 온전히 예측하기 어려운 동작을 만든다. 오토컴팩트는 트랜스크립트에 눈에 보이는 요약을 생성하고 마이크로컴팩트는 경계 표시를 방출하지만, 컨텍스트 붕괴는 사용자에게 보이는 출력 없이 작동한다. 더 단순한 단일 패스 접근법은 정보를 희생하지만 추론하기는 더 쉽다.

1. 예산 축소(항상 활성): 도구 결과별 크기 한도.
2. 스닙(HISTORY_SNIP): 가벼운 오래된 이력 정리.
3. 마이크로컴팩트(CACHED_MICROCOMPACT): 세밀한 캐시 인지 압축.
4. 컨텍스트 붕괴(CONTEXT_COLLAPSE): 이력에 대한 읽기 시점 가상 투영.
5. 오토컴팩트(기본 활성, 비활성화 가능): 모델이 생성하는 전체 요약.

buildPostCompactMessages() 함수(compact.ts)는 다음의 압축 출력 구조를 반환한다: [boundaryMarker, ...summaryMessages, ...messagesToKeep, ...attachments, ...hookResults]. 경계 표시는 annotateBoundaryWithPreservedSegment()를 통해 보존 구간 메타데이터로 주석 처리되며, 읽기 시점 체인 패칭을 가능하게 하기 위해 headUuid, anchorUuid, tailUuid를 기록한다. 이 대체로 추가 전용인 설계는 압축이 이전에 기록된 트랜스크립트 라인을 결코 수정하거나 삭제하지 않음을 의미한다. 새로운 경계 및 요약 이벤트를 추가할 뿐이다.

압축 함수 compactConversation()(compact.ts)에는 여러 설계 선택이 포함되어 있다. 사전 압축 훅이 먼저 발동하여 훅이 주입한 커스텀 지시문을 허용한다. GrowthBook 기능 플래그가 압축 경로가 주 대화의 프롬프트 캐시를 재사용할지 여부를 통제한다(코드 주석은 2026년 1월 실험을 기록한다: "false 경로는 98% 캐시 미스이며 플릿 cache_creation의 약 0.76%를 소비한다"). 압축 후에는 첨부 빌더가 라이브 앱 상태로부터 런타임 상태(계획, 스킬, 비동기 에이전트)를 재공지하는데, 압축이 이전 첨부 메시지는 폐기하지만 그 기저 상태는 폐기하지 않기 때문이다.

시스템이 각자 고유한 제한된 컨텍스트 윈도우에서 작동하는 서브에이전트에 작업을 위임할 때 컨텍스트 격리는 더욱 중요해진다.

8서브에이전트 위임과 오케스트레이션#

다중 에이전트 오케스트레이션은 코딩 에이전트의 핵심 설계 차원이며, 선택지는 부모-자식 위계, 동료 기반 대화 프레임워크(Wu et al., 2024), 그래프 구조 워크플로 엔진(LangChain, Inc., 2024)에 걸쳐 있다. Claude Code의 위임 아키텍처는 표 1의 격리된 서브에이전트 경계 원칙과 함께, 인간 에스컬레이션을 동반한 거부 우선(권한 재정의)과 되돌림 가능성 가중 위험 평가(서브에이전트 도구 제한)의 측면을 구현한다.

Claude가 auth 테스트 수정에 인증 모듈의 구조를 먼저 탐색해야 한다고 판단하면, 이 탐색을 서브에이전트에 위임할 수 있다. 위임 메커니즘은 Agent 도구(AgentTool.tsx)이며, Task는 레거시 별칭으로 유지된다. 모델은 위임 프롬프트, 선택적 서브에이전트 유형, 격리 모드·권한 재정의·작업 디렉터리 설정을 포함하는 구조화된 입력으로 Agent를 호출한다.

그림 7 서브에이전트 격리와 위임 아키텍처. Agent 도구는 내장 서브에이전트(Explore, Plan, general-purpose)나 커스텀 서브에이전트로 디스패치하며, 각각은 재구축된 권한 컨텍스트와 독립적인 도구 집합을 갖는 격리된 컨텍스트에서 실행된다. Agent 도구는 세 축을 따라 디스패치한다: 라우팅(teammate), 격리(remote, worktree), 생명주기(async, sync).

8.1Agent 도구와 위임 기준#

Agent 도구 입력 스키마(그림 7)는 기능 게이팅된 필드를 사용하여, 뒷받침하는 기능이 비활성일 때 선택적 파라미터를 생략한다. isolation 필드는 내부 사용자에게 ['worktree', 'remote']를, 외부 사용자에게 ['worktree']를 제공하며, 빌드 시점에 결정된다. cwd 필드는 기능 플래그로 게이팅된다. run_in_background 필드는 백그라운드 작업이 비활성이거나 fork-subagent 모드가 활성일 때 생략된다.

Claude Code는 기능 플래그와 진입점에 따라 최대 여섯 가지 내장 서브에이전트 유형을 제공한다:

• Explore: 주로 읽기/검색 지향 조사. 쓰기 및 편집 도구는 거부 목록에 있다.
• Plan: 구조화된 계획을 생성한다. 실행은 표준 권한 모델을 통해 진행된다.
• General-purpose: 폭넓게 유능하며, 명시적으로 요청될 때 사용된다(참고: 유형을 생략하면 부모의 대화 컨텍스트를 격리하지 않고 재사용하는 fork-subagent 경로로 라우팅될 수 있다).
• Claude Code Guide: 온보딩 및 문서 지원. 자체 permissionMode 재정의를 갖는다.
• Verification: 검증 검사(테스트 스위트, 린팅)를 실행한다.
• Statusline-setup: 터미널 상태 표시줄 설정에 특화되어 있다.

내장 외에도 사용자는 .claude/agents/*.md 파일로 커스텀 서브에이전트를 정의하고, 플러그인은 loadPluginAgents.ts를 통해 에이전트 정의를 기여한다. 각 파일의 마크다운 본문이 해당 에이전트의 시스템 프롬프트가 되며, YAML 프론트매터가 description, tools(허용목록), disallowedTools, model, effort, permissionMode, mcpServers, hooks, maxTurns, skills, 메모리 범위, 백그라운드 플래그, 격리 모드를 포함한 설정 필드를 지정한다. JSON 형식 에이전트 정의는 동일한 필드에 더해 prompt를 명시 필드로 지원한다(loadAgentsDir.ts). 이는 커스텀 에이전트가 자체 도구, 모델, 권한, 훅, 메모리 범위, 격리 모드를 갖춘 완전히 설정된 격리 하위 시스템일 수 있음을 의미한다. AgentTool은 기본 도구 풀에서 SkillTool과 나란히 이 정의들로 디스패치하는 메타 도구로 자리하지만, 둘은 근본적으로 다르다. SkillTool은 통상 현재 컨텍스트 윈도우에 지시문을 주입하는 반면(동일한 runAgent() 기계를 통해 격리된 서브에이전트를 생성하는 옵트인 context: fork 모드가 있다), AgentTool은 항상 새롭고 격리된 것을 생성한다. 그 트레이드오프는 대부분의 서브에이전트 호출이 자기 완결적 프롬프트를 요구한다는 점인데, 기본 경로가 부모의 대화 이력을 물려받지 않기 때문이다(fork-subagent 경로는 예외다). 전체 트랜스크립트 이력을 공유하는 대화 기반 프레임워크는 이 비용을 피하지만, 에이전트 수가 늘어날수록 컨텍스트 폭발의 위험을 진다.

8.2격리 아키텍처#

서브에이전트 격리는 여러 모드를 지원한다(AgentTool.tsx):

• Worktree: 임시 git worktree를 생성하여, 서브에이전트에게 부모의 작업 트리에 영향을 주지 않고 수정할 수 있는 자체 저장소 사본을 제공한다.
• Remote(내부 전용): Claude Code Remote 환경에서 실행하며, 항상 백그라운드로 동작한다.
• In-process(기본값): 부모와 파일시스템을 공유하지만 격리된 대화 컨텍스트에서 작동한다.

서브에이전트의 권한 재정의 로직(runAgent.ts)에는 몇 가지 구체적 규칙이 있다. 서브에이전트가 permissionMode를 정의하면, 부모가 이미 bypassPermissions, acceptEdits, auto 모드에 있지 않은 한 재정의가 적용된다. 이 모드들은 안전/자율성 트레이드오프에 대한 사용자의 명시적 결정을 나타내므로 항상 우선하기 때문이다. 비동기 에이전트의 경우, 시스템은 다음 연쇄를 통해 프롬프트를 피할지 결정한다. 먼저 명시적 canShowPermissionPrompts, 그다음 bubble 모드(부모 터미널로 에스컬레이션하므로 항상 표시), 그다음 기본값(동기 에이전트는 프롬프트 표시, 비동기 에이전트는 미표시). 프롬프트를 표시할 수 있는 백그라운드 에이전트는 awaitAutomatedChecksBeforeDialog: true를 설정하여, 사용자를 방해하기 전에 분류기와 훅이 해소되도록 보장한다.

이 격리 모드들은 설계 공간의 서로 다른 지점을 차지한다. 컨테이너 기반 격리(SWE-Agent와 OpenHands가 사용, Yang et al., 2024; Wang et al., 2024b)는 더 강한 자원 경계를 제공하지만 컨테이너 인프라를 요구한다. 컨텍스트 전용 격리(AutoGen 같은 대화 기반 프레임워크가 사용, Wu et al., 2024)는 파일시스템을 공유하되 대화 이력을 분리한다. Claude Code의 worktree 기반 격리는 Git의 내장 메커니즘을 활용하여, 컨테이너 오케스트레이션을 도입하지 않고 워크스페이스 수준 파일시스템 분리를 제공한다.

runAgent()에 allowedTools가 명시적으로 제공되면(runAgent.ts) 2계층 권한 범위 모델이 적용된다. --allowedTools로부터의 SDK 수준 권한은 보존된다: "모든 에이전트에 적용되어야 하는 SDK 소비자의 명시적 권한." 그러나 세션 수준 규칙은 서브에이전트가 선언한 allowedTools로 대체된다. allowedTools가 제공되지 않으면(일반적인 AgentTool 경로), 부모의 세션 수준 규칙이 대체 없이 상속된다.

8.3사이드체인 트랜스크립트#

각 서브에이전트는 자신의 트랜스크립트를 별도의 .jsonl 파일과 .meta.json 메타데이터 파일로 기록한다(sessionStorage.ts, runAgent.ts). 이 사이드체인 설계는 서브에이전트 이력이 디버깅과 감사를 위해 보존되면서도 부모의 세션 파일을 부풀리지 않음을 의미한다. 서브에이전트의 최종 응답 텍스트와 메타데이터만이 부모 대화 컨텍스트로 반환되며, 전체 서브에이전트 이력은 결코 부모의 컨텍스트 윈도우에 들어가지 않아 "병목으로서의 컨텍스트" 원칙을 존중한다.

요약 전용 반환 모델은 의도적인 컨텍스트 절약 선택이다. 에이전트 간에 전체 트랜스크립트 이력을 공유하는 대화 기반 프레임워크는 에이전트 수가 늘어날수록 컨텍스트 폭발의 위험을 진다. 격리된 컨텍스트 병렬성조차 상당한 비용을 수반한다. Claude Code의 에이전트 팀은 plan 모드에서 표준 세션의 약 7배 토큰을 소비하며(Anthropic, 2025b), 이는 서브에이전트가 격리된 컨텍스트에 있을 때 요약 전용 반환을 더욱 중요하게 만든다.

에이전트 팀의 다중 인스턴스 조율을 위해 하네스는 메시지 브로커나 분산 조율 서비스가 아니라 파일 잠금을 사용한다(Anthropic, 2025b). 각 팀원은 자체 인박스 JSON 파일을 가지며(utils/teammateMailbox.ts), 과제 할당과 기타 에이전트 간 메시지는 인박스별 잠금 파일(utils/lockfile.ts) 아래에서 수신자의 인박스로 푸시되고, 파일은 예측 가능한 파일시스템 경로에 저장된다. 이는 처리량을 두 가지 속성과 맞바꾼다. 의존성 없는 배포(외부 인프라 불필요)와 완전한 디버그 가능성(어떤 에이전트의 상태든 평문 JSON 파일을 읽어 검사 가능)이다.

9세션 지속성과 복구#

코딩 에이전트의 세션 지속성은 추가 전용 로그, 구조화된 데이터베이스, 체크포인트 기반 스냅샷, 무상태 아키텍처 사이의 설계 선택을 수반하며, 각각 감사 가능성, 질의력, 배포 복잡성에서 다른 트레이드오프를 갖는다. Claude Code의 지속성 설계는 표 1의 추가 전용 지속 상태 원칙을 구현한다. 세션 범위 권한은 메모리에만 존재하고 트랜스크립트에 직렬화되지 않으므로, 재개는 CLI 인자와 디스크 설정으로부터 권한 컨텍스트를 재구축한다. 재구축된 컨텍스트가 인식하지 못하는 요청은 거부 우선 프롬프팅으로 폴백한다.

auth 테스트 과제가 이 절에 이를 때쯤 세션은 원래 프롬프트, 도구 호출과 결과, 컴팩트 경계, 그리고 인증 모듈 탐색에서 얻은 서브에이전트 요약(8절)을 담고 있다. 이 절은 그 산출물 중 어떤 것이 지속적으로 기록되며, 세션의 오래된 권한 부여를 이월하지 않고 나중에 무엇을 복구할 수 있는지를 묻는다.

그림 8 세션 지속성과 컨텍스트 압축. 이 다이어그램은 라이브 세션 상태(컨텍스트 윈도우, 압축)와 지속 저장소(세션 트랜스크립트, history.jsonl, 서브에이전트 사이드체인, 체크포인트)를 분리한다. 재개와 포크는 메시지를 복원하지만 세션 범위 권한은 복원하지 않는다.

• 대화는 컨텍스트보다 오래 산다: 세션의 유효 수명은 모델의 컨텍스트 윈도우에 의해 제한될 수 없다. 디스크의 트랜스크립트가 지속적인 세션 이벤트를 기록하므로, 압축은 대화를 끝내지 않고 라이브 뷰를 재활용할 수 있다.
• 대화는 단일 경로를 넘어선다: 세션은 하나의 선형 궤적에 갇혀서는 안 된다. 추가 전용 트랜스크립트는 사용자가 이전 작업을 잃지 않고 되감고, 재개하고, 새 분기로 포크할 수 있게 한다.

Claude Code의 지속성 메커니즘은 이벤트가 발생하는 대로 대화(메시지, 도구 결과, 컴팩트 경계)를 디스크에 기록한다.

9.1트랜스크립트 모델#

세션 트랜스크립트는 프로젝트별 경로에 대체로 추가 전용인 JSONL 파일로 저장된다(명시적 정리 재작성은 예외)(그림 8). getTranscriptPath() 함수(sessionStorage.ts)는 이를 join(projectDir, ${getSessionId()}.jsonl)로 계산하며, 여기서 projectDir은 먼저 getSessionProjectDir()(재개/분기 중 switchSession()이 설정)을 확인하고 getProjectDir(getOriginalCwd())()로 폴백하여 결정된다.

세 가지 지속성 채널이 독립적으로 작동한다:

1. 세션 트랜스크립트: user, assistant, attachment, system 메시지와 압축 및 기타 메타데이터 이벤트를 포함한 대화 기록. 프로젝트 범위이며 세션당 파일 하나.
2. 전역 프롬프트 이력: 사용자 프롬프트만, Claude 설정 홈 디렉터리의 history.jsonl에 저장된다(history.ts). makeHistoryReader() 제너레이터가 readLinesReverse()를 통해 역순으로 항목을 산출하여 위쪽 화살표와 ctrl+r 탐색을 지원한다.
3. 서브에이전트 사이드체인: 서브에이전트당 별도의 .jsonl + .meta.json 파일(8.3절).

세션 트랜스크립트는 단순 메시지를 넘어 여러 종류의 이벤트를 저장하며, 여기에는 압축 표시, 파일 이력 스냅샷, 귀속(attribution) 스냅샷, 콘텐츠 대체 기록이 포함된다. 추가 전용 JSONL 형식은 질의력보다 감사 가능성과 단순성을 선호하는 의도적 선택이다. 기록된 모든 이벤트는 인간이 읽을 수 있고, 버전 관리 가능하며, 특수 도구 없이 검사 가능하다. 데이터베이스 기반 대안은 세션 이력에 대한 더 풍부한 질의를 가능하게 하겠지만 배포 의존성을 도입하고 투명성을 낮춘다.

세션 정체성 시스템은 sessionId와 sessionProjectDir을 짝지으며, 이는 재개나 분기 중 함께 설정된다. 트랜스크립트 경로는 메시지가 기록될 때 활성이었던 것과 동일한 프로젝트 디렉터리를 사용해야 하며, 그래야 훅이 엉뚱한 디렉터리를 찾는 일을 피할 수 있다.

9.2재개, 포크, 그리고 권한 미복원#

--resume 플래그는 트랜스크립트를 재생하여 대화를 재구축한다(conversationRecovery.ts). 포크는 기존 세션에서 새 세션을 생성한다(commands/branch/branch.ts). 그러나 재개와 포크는 세션 범위 권한을 복원하지 않는다. 사용자는 새 세션에서 다시 부여해야 한다. 이는 의도적으로 안전 보수적인 설계 선택이다. 세션은 격리된 신뢰 도메인으로 취급된다. 재개 시 이전에 부여된 권한을 복원하면 편의는 얻겠지만 변화된 맥락으로 낡은 신뢰 결정을 이월할 위험이 있다. 이 아키텍처는 암묵적 지속 대신 재부여를 택하며, 신뢰는 항상 현재 세션에서 확립된다는 안전 불변식을 유지하는 대가로 사용자 마찰을 감수한다.

compact_boundary 표시는 지속성과 함께 작동하도록 세심하게 설계되었다. annotateBoundaryWithPreservedSegment() 함수(compact.ts)는 경계 이벤트에 headUuid, anchorUuid, tailUuid를 기록한다. 이 UUID들은 세션 로더가 읽기 시점에 메시지 체인을 패치할 수 있게 한다. 보존된 메시지는 디스크에서 원래의 parentUuid를 유지하고, 로더는 경계 메타데이터를 사용해 그것들을 올바르게 연결한다. 이 대체로 추가 전용인 설계는 압축이 통상 이전에 기록된 트랜스크립트 라인을 수정하거나 삭제하지 않음을 의미한다.

Claude Code의 "체크포인트"는 --rewind-files를 위한 파일 이력 체크포인트이며, ~/.claude/file-history/<sessionId>/에 저장된다. 이것들은 파일시스템 변경을 되돌리기 위한 파일 수준 스냅샷이지 범용 체크포인트 저장소가 아니다.

앞선 절들은 되풀이되는 설계 질문에 대한 Claude Code의 답을 문서화했다. 다음 절은 Claude Code의 설계 선택을 아키텍처적으로 독립적인 두 AI 에이전트 시스템의 그것과 대조한다.

10비교 분석: Claude Code, OpenClaw, Hermes Agent#

앞선 절들은 루프 아키텍처, 안전, 확장성, 컨텍스트 관리, 위임, 지속성에 관한 되풀이 설계 질문들에 대한 Claude Code의 답을 문서화했다. 이 발견들을 더 넓은 에이전트 설계 공간 안에 위치시키기 위해, 이 절은 Claude Code를 근본적으로 다른 출발점에서 동일한 설계 질문 다수에 답하는 두 개의 독립적인 오픈소스 AI 에이전트 시스템과 비교한다. OpenClaw는 메시징 표면(WhatsApp, Telegram, Slack, Discord, Signal 등)을 내장 에이전트 런타임에 연결하는 로컬 우선 WebSocket 게이트웨이이며, macOS·iOS·Android용 동반 앱을 갖는다(Steinberger and OpenClaw Contributors, 2026). Hermes Agent는 호출된 진입점에 의해 역할이 정해지는 단일 Python 프로세스로, 하나의 지속성 계층과 하나의 런타임을 마주하는 여러 표면을 갖는다(Nous Research, 2026).⁴ Hermes 배포판은 세 개의 콘솔 스크립트를 노출한다. CLI 및 게이트웨이 컨트롤러를 위한 hermes, 배치 실행을 위한 hermes-agent, 그리고 Hermes 자신의 게이트웨이가 다른 에이전트를 호스팅할 수 있는 방식 그대로 외부 IDE가 Hermes를 호스팅하게 해주는 Agent Client Protocol 어댑터 hermes-acp다. Claude Code가 단일 저장소 세션에 묶인 CLI 코딩 하네스인 반면, OpenClaw는 다채널 개인 지원을 위한 지속적 제어 평면이고, Hermes는 어떤 진입점이 실행했는지에 따라 역할과 표면 집합이 결정되는 하나의 프로세스다. 세 시스템은 에이전트 설계 공간의 서로 다른 영역을 차지한다. 이 비교의 가치는 배포 맥락이 바뀔 때 동일한 되풀이 질문들이 어떻게 서로 다른 아키텍처적 답을 낳는지를 보여주는 데 있다.

10.1여섯 가지 비교 차원#

표 3이 여섯 차원에 걸친 비교를 요약한다. 각 차원은 세 시스템 모두가 답해야 하는 설계 질문 하나에 대응한다. 이 여섯 차원 바깥에 놓이는 Hermes의 기능은 10.2절에서 따로 논의한다.

표 3 아키텍처 비교: 여섯 설계 차원에 걸친 Claude Code 대 OpenClaw 대 Hermes Agent. 각 행은 되풀이되는 설계 질문 하나와 세 시스템이 제공하는 서로 다른 답을 담는다.

세 시스템 전반에 걸쳐 조합적 관계도 존재한다. OpenClaw는 ACP(Agent Client Protocol) 통합을 통해 Claude Code, OpenAI Codex, Gemini CLI를 외부 코딩 하네스로 호스팅할 수 있고, Hermes Agent는 ACP 호스트/게스트 분할의 양쪽에 위치하여 게이트웨이가 플랫폼 어댑터와 도구 서버를 호스팅하는 한편 hermes-acp 어댑터가 외부 IDE로 하여금 Hermes를 호스팅하게 하므로, 이 시스템들은 순전한 대안이 아니라 적층 가능(stackable)하다.

시스템 범위와 배포 모델. Claude Code는 단일 저장소에 묶인 소멸성 CLI 프로세스로 실행된다. 각 세션은 터미널과 함께 시작하고 끝난다. OpenClaw는 모든 메시징 표면 연결을 소유하고 타입 지정 WebSocket 프로토콜로 클라이언트·도구·디바이스 노드를 조율하는 지속 데몬(기본 포트 18789, 루프백 전용)으로 실행된다. Hermes Agent는 실행에 사용된 진입점에 의해 역할이 고정되는 단일 장수명 Python 프로세스로 실행된다. 그 게이트웨이 하위 명령은 2계층 어댑터 시스템(gateway/platforms/ 아래의 인트리 어댑터 + Google Chat·IRC·Teams용 plugins/platforms/ 아래의 플러그인 계층)을 통해 메시징 표면을 구동하며, 세션 및 다중 에이전트 보드 상태를 타입 지정 WebSocket 프로토콜이 아니라 두 개의 온디스크 SQLite 파일(state.db, kanban.db)에 지속시킨다. 이는 Hermes를 신뢰 위상에서는 Claude Code보다 OpenClaw에 가깝게, 프로세스 위상에서는 OpenClaw보다 Claude Code에 가깝게 놓는다. 브로커를 어디에 둘 것인가라는 설계 질문에 Hermes는 브로커를 전혀 두지 않는 것으로 답한다. 이러한 시스템 범위의 차이는 이 비교에서 가장 근본적인 아키텍처적 분기다. 그것들이 다른 모든 설계 질문이 어떻게 구성되는지를 결정한다.

신뢰 모델과 보안 아키텍처. 세 시스템은 서로 다른 위협 모델을 다룬다. Claude Code는 신뢰할 수 있는 개발자의 머신 안에서 작동하는 신뢰할 수 없는 모델을 가정한다. 거부 우선 권한 시스템(5절)이 모든 도구 호출을 평가하고, ML 분류기가 자동화된 안전 평가를 제공하며, 일곱 권한 모드가 점진적 자율성 스펙트럼을 만든다. OpenClaw는 게이트웨이 인스턴스당 단일 신뢰 운영자를 가정한다. 그 보안 아키텍처는 행위 단위 안전 분류가 아니라 신원 및 접근 통제(DM 페어링 코드, 발신자 허용목록, 게이트웨이 인증)에서 출발한다. 도구 정책은 중앙 분류기가 아니라 에이전트별 설정 가능한 allow/deny 목록을 사용한다. 샌드박싱은 다중 백엔드(Docker, SSH, OpenShell)와 설정 가능한 범위(에이전트별, 세션별, 공유)를 갖는 옵트인 기능으로 제공되며, 활성화하면 non-main 모드가 모든 비주(non-main) 세션을 샌드박싱할 수 있으나 샌드박싱이 기본 활성은 아니다. OpenClaw 보안 문서는 공유 게이트웨이에서의 적대적 다중 테넌트 격리가 지원되는 보안 경계가 아님을 명시적으로 진술한다. Hermes Agent는 제3의 입장을 취한다. 도구 인가는 하나의 파일(tools/approval.py)에 중앙화되어 세 모드(manual, smart, off)와, 모드와 무관하게 rm -rf /, mkfs, 블록 디바이스에 대한 원시 dd, 포크 폭탄, 시스템 종료 명령을 차단하는 무조건적 HARDLINE_PATTERNS 바닥을 노출한다Tier B. smart 모드는 보조 LLM 위험 평가를 실행하며, 소스 내 주석은 OpenAI Codex의 smart approvals를 설계 영감으로 지목한다. Hermes가 여러 표면에 걸쳐 실행되기 때문에 동일한 승인 흐름이 네 번 렌더링된다. CLI 프롬프트, Telegram·Discord·QQBot의 게이트웨이 승인 키보드, IDE 클라이언트를 위한 ACP request_permission 왕복, 그리고 무인 실행을 위한 cron 전용 모드다. Claude Code의 일곱 모드 분류 및 ML 분류기 기반 auto 모드와 비교하면, Hermes는 더 작은 모드 분류를 갖지만 동일한 다층 구조를 갖는다. 무조건적 안전 바닥, 기본 대화형 프롬프트, 옵트인 보조 LLM "smart" 경로다. 아키텍처적 답은 동일하고, 표면의 개수가 다르다. 세 시스템의 차이는 신뢰 경계가 어디에 놓이는지를 반영한다. Claude Code는 그것을 모델과 실행 환경 사이에 두고, OpenClaw는 게이트웨이 경계에 두며, Hermes는 Claude Code처럼 행위 단위 승인을 갖되 OpenClaw처럼 여러 표면을 통해 렌더링하며 둘 사이에 위치한다.

에이전트 런타임과 도구 오케스트레이션. 세 시스템 모두 에이전틱 루프를 구현하지만, 그 루프는 각자의 아키텍처에서 서로 다른 위치를 차지한다. Claude Code에서 queryLoop() 비동기 제너레이터(4절)는 시스템의 중심이다. 모든 인터페이스가 그것으로 들어가고, 그것이 직접 컨텍스트 조립, 모델 호출, 도구 디스패치, 복구를 관리한다. OpenClaw에서 에이전트 런타임은 더 큰 게이트웨이 디스패치 계층 안에 자리한 내장 pi-coding-agent 코어(OpenClaw가 통합하는 pi-mono 프로젝트의 외부 SDK)다. 게이트웨이의 에이전트 RPC는 파라미터를 검증하고, 세션을 해소하고, 즉시 반환한다. 그다음 내장 러너가 에이전틱 루프를 실행하면서 생명주기 및 스트림 이벤트를 게이트웨이 프로토콜을 통해 되돌려 방출한다. 실행은 세션별 큐와 선택적 전역 레인을 통해 직렬화되어, 다채널 표면에 걸친 도구 및 세션 경합을 방지한다. Hermes Agent에서 루프는 AIAgent.run_conversation(run_agent.py) 안의 동기 while이며, 반복 횟수(기본 90)와 별도의 반복 예산으로 게이팅된다. 예산이 소진되면 도구를 제거한 요약 호출 하나가 에이전트로 하여금 생각 도중에 종료하는 대신 마무리 메시지를 전달하게 한다Tier B. 각 반복은 model_tools.get_tool_definitions()가 수집한 도구 스키마를 전송하고 도구 호출을 model_tools.handle_function_call로 라우팅하며, tools/*.py의 도구 파일들은 임포트 시점에 자기 등록하므로 도구 추가에 registry.register() 호출 하나만 필요하다. 여러 도구 호출을 반환하는 단일 어시스턴트 메시지는 병렬로 실행되며 순차 폴백을 갖는다. 세 시스템 모두 ReAct 패턴(Yao et al., 2022)을 따르되, OpenClaw의 루프는 제어 평면 자체가 아니라 제어 평면 안의 한 구성요소이고, Hermes의 루프는 런타임 수준에서 Claude Code의 그것과 동급이지만 구현 형태가 다르다. 산출하는 비동기 제너레이터가 아니라 스레드 관리 동시성을 갖는 동기 Python 루프다.

확장 아키텍처. Claude Code의 네 확장 메커니즘(MCP, 플러그인, 스킬, 훅)은 컨텍스트 비용으로 조직된다(6절). 훅은 컨텍스트를 소비하지 않고, 스킬은 적게 소비하며, MCP 서버는 많이 소비한다. 넷 모두 단일 에이전트의 컨텍스트 윈도우와 도구 표면을 확장한다. OpenClaw는 네 아키텍처 계층(발견, 활성화, 런타임 로딩, 표면 소비)과 텍스트 추론, 음성, 미디어 이해, 이미지/음악/비디오 생성, 웹 검색, 메시징 채널을 포함한 열두 가지 능력 유형을 갖는 매니페스트 우선 플러그인 시스템을 사용한다. 플러그인은 중앙 레지스트리에 능력을 등록하고, 게이트웨이는 레지스트리를 읽어 도구, 채널, 제공자 설정, 훅, HTTP 라우트, CLI 명령, 서비스를 노출한다. OpenClaw는 또한 다중 소스(워크스페이스, 프로젝트 수준, 개인, 관리, 동봉, 추가 디렉터리이며 워크스페이스 스킬이 최고 우선순위)를 갖는 별도의 스킬 계층과 공개 레지스트리(ClawHub)를 갖고, 내장 openclaw mcp 명령(서버 및 아웃바운드 클라이언트 레지스트리)을 통해 MCP를 지원한다. Hermes Agent는 Claude Code의 넷에 비해 다섯 개의 확장 표면을 노출한다Tier B. 셋은 Claude Code의 것과 같은 수준에 있고(생명주기 훅을 갖는 plugins/<name>/ 아래의 일반 플러그인, skills/ 아래의 동봉 스킬, config.yaml에 설정되는 MCP 서버), 나머지 둘은 다른 축을 확장한다(plugins/memory/<name>/ 아래의 교체 가능 메모리 제공자와 plugins/model-providers/<name>/ 아래의 교체 가능 모델 제공자). 이는 Hermes로 하여금 이벤트를 가로채는 대신 백엔드를 교체하게 한다. Hermes의 훅은 인프로세스 Python 콜백이거나 설정 기반 외부 셸 명령일 수 있으며, 둘 다 동일한 훅 매니저를 통해 디스패치된다. Hermes가 stdio MCP 서버를 생성할 때 자식의 환경은 실행 전에 소수의 시스템 변수 허용목록으로 제한되고, npx/uvx 패키지 이름은 OSV 악성코드 데이터베이스에 대조 검사된다. 세 시스템의 아키텍처적 차이는 확장이 어디서 작동하는가에 있다. Claude Code의 확장은 한 에이전트의 행위 표면을 수정하고, OpenClaw의 플러그인은 모든 에이전트에 걸쳐 게이트웨이의 능력 표면을 확장하며, Hermes의 확장은 Claude Code 스타일의 에이전트별 표면 위에 두 번째 축을 더해, 이벤트를 그 주위에서 가로채는 대신 메모리 및 모델 제공자 백엔드 전체를 제자리에서 교체한다.

메모리, 컨텍스트, 지식 관리. 세 시스템 모두 불투명한 데이터베이스가 아니라 투명한 파일 기반 메모리를 사용한다. Claude Code는 4단계 CLAUDE.md 계층을 로드하고 5계층 압축 파이프라인으로 컨텍스트 압력을 관리한다(7절). 메모리 검색은 파일 헤더에 대한 LLM 기반 스캔을 사용한다. OpenClaw는 세션 시작 시 워크스페이스 부트스트랩 파일을 시스템 프롬프트에 주입한다. 다섯 개의 핵심 파일(AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md)과 조건부로 BOOTSTRAP.md, HEARTBEAT.md, MEMORY.md이며, 큰 파일은 절단된다. 별도로 메모리 시스템은 세 가지 파일 유형을 관리한다. 장기 지속 사실을 위한 MEMORY.md, 날짜가 찍힌 일일 노트(memory/YYYY-MM-DD.md), 그리고 dreaming 스윕 요약을 위한 선택적 DREAMS.md다. 임베딩 제공자가 설정되면 메모리 검색은 벡터 유사도와 키워드 매칭을 결합한 하이브리드 검색을 사용한다. 실험적 dreaming 시스템은 백그라운드 통합을 수행하여 후보를 채점하고 자격을 갖춘 항목만 단기 회상에서 장기 메모리로 승격시킨다. 압축 전에 OpenClaw는 컨텍스트 손실을 방지하기 위해 중요한 노트를 메모리 파일에 저장하라고 에이전트에 자동으로 상기시킨다. Hermes의 압축은 토큰 예산 꼬리 보호를 갖는 하나의 보조 LLM 요약기이며, 그에 앞서 도구 출력 가지치기 패스가 실행된다. 요약에는 이 압축이 새로운 지시가 아니라 배경 컨텍스트이며 지속 메모리(MEMORY.md, USER.md)가 여전히 권위를 갖는다고 에이전트에 알리는 긴 "참조 전용" 서문이 접두된다Tier B. Claude Code의 CLAUDE.md 계층이 고정되어 있고 압축이 다섯 계층인 반면, Hermes는 압축 계층은 더 적지만 컨텍스트 파일 사전 주입 스캔을 추가한다. AGENTS.md, .cursorrules, SOUL.md 같은 파일이 주입 패턴 및 비가시 유니코드 문자 목록에 대조 검사되고, 하나라도 걸리면 해당 파일의 내용이 [BLOCKED: ...] 표시로 대체된다. 세 시스템 모두 사용자에게 보이고 편집 가능한 메모리라는 설계 헌신을 공유하지만, 동일한 컨텍스트 관리 질문에 서로 다른 답을 낸다. Claude Code는 점진적 컨텍스트 압축(캐시 인지를 갖춘 다섯 계층)에 투자하고, OpenClaw는 구조화된 장기 메모리 승격(dreaming, 일일 노트, 메모리 검색)과 교체 가능한 압축 제공자 및 세션 가지치기에 투자하되 그 압축 파이프라인은 Claude Code의 5계층 시스템보다 덜 점진적이며, Hermes는 더 깊은 압축 스택이 아니라 사전 주입 콘텐츠 스캔과 압축된 이력으로부터 지속 메모리를 프롬프트 수준에서 격리하는 데 투자한다.

다중 에이전트 아키텍처와 라우팅. 이 차원이 가장 두드러진 아키텍처적 차이를 드러낸다. Claude Code의 다중 에이전트 모델은 과제 위임이다. 부모가 서브에이전트(Explore, Plan, general-purpose 및 커스텀 유형)를 생성하고, 이들은 제한된 도구 집합을 갖고 격리된 컨텍스트 윈도우에서 작동하며 요약만 반환한다(8절). worktree 격리가 파일시스템 수준 분리를 제공한다. OpenClaw는 두 개의 별개 관심사를 분리한다. 첫째, 다중 에이전트 라우팅: 하나의 게이트웨이가 각자 고유한 워크스페이스, 인증 프로필, 세션 저장소, 모델 설정을 갖는 완전히 격리된 복수의 에이전트를 호스팅할 수 있고, 결정론적 바인딩 규칙을 통해 특정 채널이나 발신자로 라우팅된다. 둘째, 서브에이전트 위임: 단일 에이전트 내에서 설정 가능한 중첩 깊이(최대 5, 기본 1, 권장 2), 지원 채널에서의 스레드 바인딩 세션, 깊이별 설정 가능한 도구 정책으로 백그라운드 실행을 생성할 수 있다. OpenClaw의 프로젝트 비전은 에이전트 위계 프레임워크를 기본 아키텍처로 삼는 것을 명시적으로 거부한다. Hermes Agent는 또 다른 이음매를 따라 이 질문을 나눈다. 턴별 위임은 delegate_task 도구를 통해 이루어지며, 이는 스레드 풀에서 자식 AIAgent 인스턴스를 생성한다. 부모는 자식이 요약을 반환할 때까지 블록되고, 동시성은 기본 세 자식으로 상한이 걸리며 깊이는 1로 상한이 걸린다(범위 [1, 3]으로 클램프). 리프 자식은 기본적으로 스스로 위임할 수 없으며(중첩 위임은 오케스트레이터 자식과 더 높은 spawn-depth 설정을 통해 옵트인), 자식은 항상 지속 메모리가 비활성화된 상태로 실행되어 부모의 노트를 읽거나 쓸 수 없다Tier B. 턴별 위임을 넘어, v0.13의 Kanban 서브시스템은 복수의 Hermes 워커 프로필이 과제를 클레임하고 하트비트를 보내고 완료하는 SQLite 기반 작업 큐이며, 오래된 클레임 회수와 두 번 연속 실패 시 자동 차단 기능을 갖는다(hermes_cli/kanban_db.py:2703). 세 시스템의 구분이 중요한 이유는, Claude Code의 서브에이전트가 한 사용자의 코딩 세션 안의 종속 워커인 반면, OpenClaw의 다중 에이전트 라우팅은 서로 다른 채널을 통해 서로 다른 사용자나 목적에 봉사하는 진정으로 독립적인 에이전트 인스턴스를 만들고, Hermes는 엄격한 턴별 위임 기본값과, 복수의 에이전트 프로세스가 지속적인 공유 보드를 두고 조율하게 하는 별도의 Kanban 계층을 결합하기 때문이다. 이는 Claude Code와 OpenClaw가 동일한 형태로는 던지지 않는 질문이다.

10.2Hermes Agent: 비교 표 바깥의 기능들#

Hermes의 세션 지속성은 모든 세션 메시지에 걸친 전문 검색과 압축으로 촉발된 분할을 기록하는 부모 세션 체인을 갖는 하나의 WAL 모드 SQLite 데이터베이스를 사용한다Tier B. Claude Code가 세션을 프로젝트별 JSONL 파일로 지속시키는 반면(9절), Hermes의 선택은 교차 세션 검색과 동시 판독기 지원을 기본 제공한다. 게이트웨이가 대화 도중 재시작되면, 트랜스크립트 타임스탬프 신선도 로직(기본 1시간 윈도우)에 따라 다음 메시지 도착 시 세션이 자동 재개된다. 내장 cron 스케줄러와 웹훅 구독 시스템은 에이전트가 스케줄 표현식이나 외부 HTTP 이벤트에 따라 무인으로 실행되게 한다. cron 세션은 지속 메모리가 비활성화되고 설정 가능한 비활동 타임아웃(기본 600초)을 갖는다. 배포판에는 에이전트가 생성한 스킬을 검토하고 오래된 것을 보관하되 결코 삭제하지 않는 백그라운드 "큐레이터" 루프도 포함되며, 이는 에이전트 출처를 갖는 스킬로 한정되어 동봉 및 허브 설치 스킬은 대상 밖이다. 이 기능들 중 어느 것도 주 표에 사용된 여섯 비교 차원에 깔끔하게 대응되지 않으며, 그래서 표 3의 칸이 아니라 여기 Hermes 특화 부록으로 등장한다. OpenClaw의 독특한 기능들(확장 아키텍처 아래의 ClawHub 플러그인 레지스트리와 메모리·컨텍스트 아래의 dreaming 메모리 서브시스템)은 이미 그 여섯 차원의 칸을 차지하고 있으므로 별도의 부록이 필요하지 않다. 이 하위 절의 Hermes 추가 사항들은 그 지속 프로세스 범위에서 비롯되는데, 이는 Hermes가 OpenClaw와 공유하지만 Claude Code의 세션당 CLI 모델은 제공하지 않는 배포 맥락 속성이다.

10.3이 대조가 드러내는 것#

이 비교는 AI 에이전트 시스템의 설계 공간에 대해 세 가지 관찰을 표면화한다.

첫째, 3.1절에서 식별한 되풀이 설계 질문들(추론은 어디에 있는가, 어떤 안전 태세를 취할 것인가, 컨텍스트를 어떻게 관리할 것인가, 확장성을 어떻게 구조화할 것인가)은 코딩 에이전트를 넘어 적용된다. OpenClaw는 저장소에 묶인 코딩 도구가 아니라 다채널 개인 비서라는 출발점에서 이 모든 질문에 답하고, Hermes Agent는 CLI 하네스나 다채널 게이트웨이가 아니라 단일 프로세스, 다중 표면 배포에서 그것들에 답한다. 질문은 안정적이고, 답은 세 시스템에 걸쳐 배포 맥락에 따라 달라진다.

둘째, 이 시스템들은 여러 차원을 따라 서로 다른 베팅을 한다. Claude Code는 점진적 행위 단위 안전 평가에 투자하고, OpenClaw는 경계 수준 신원 및 접근 통제에 투자하며, Hermes는 Claude Code처럼 행위 단위 승인을 갖되 OpenClaw처럼 여러 표면을 통해 렌더링하며 둘 사이에 위치한다. Claude Code는 에이전트 루프를 아키텍처의 중심으로 다루고, OpenClaw는 게이트웨이 제어 평면을 중심으로 다루며 에이전트 루프를 한 구성요소로 내장하고, Hermes의 루프는 런타임 수준에서 Claude Code의 것과 동급이어서 게이트웨이 디스패치 계층 안에 앉기보다 동일한 아키텍처적 위치를 차지한다. Claude Code의 확장은 단일 컨텍스트 윈도우를 수정하고, OpenClaw의 플러그인은 공유 게이트웨이 표면을 확장하며, Hermes는 Claude Code 스타일의 에이전트별 표면 위에 두 번째 축을 더해 이벤트를 가로채는 대신 메모리와 모델 백엔드를 제자리에서 교체한다. 이 차이들은 자의적이지 않다. 세 시스템의 서로 다른 신뢰 모델과 배포 위상에서 따라 나온다.

셋째, 세 시스템 전반의 조합적 관계가 아키텍처적으로 유의미하다. OpenClaw는 ACP를 통해 Claude Code를 외부 코딩 하네스로 호스팅할 수 있고, Hermes Agent는 호스트/게스트 분할의 양쪽에 위치한다. 그 게이트웨이는 플랫폼 어댑터와 도구 서버를 호스팅하고, hermes-acp 어댑터는 외부 IDE가 Hermes를 호스팅하게 한다. 이 시스템들은 배타적 대안이 아니라 조합 가능하며, 이는 AI 에이전트의 설계 공간이 평평한 분류학이 아니라 게이트웨이 수준 시스템과 과제 수준 하네스가 여러 위치에서 조합될 수 있는 계층적 분류학임을 시사한다.

11관련 연구#

11.1코딩 에이전트 분류#

표 4 자율적 행위의 정도에 따른 AI 코딩 도구 범주.

AI 코딩 도구는 그것이 지원하는 자율적 행위의 정도에 따라 조직될 수 있다(표 4). GitHub Copilot(Chen et al., 2021) 같은 인라인 완성 도구는 자율적 행위 없이 에디터 안에서 코드 조각을 제안한다. Cursor와 Windsurf를 포함한 채팅 통합 제품은 대화형 상호작용과 다중 파일 편집을 추가하지만 IDE 환경에 결합된 채로 남는다. Claude Code, OpenAI의 Codex CLI, Aider(Gauthier, 2024)를 포함한 에이전틱 CLI 도구는 명령줄에서 작동하며 단일 요청 안에서 자율적으로 셸 명령을 실행하고, 파일을 읽고 쓰고, 출력을 반복 개선할 수 있다. Devin, SWE-Agent(Yang et al., 2024), OpenHands(Wang et al., 2024b) 같은 완전 자율 시스템은 종종 샌드박싱된 클라우드 환경에서 최소한의 인간 감독을 목표로 한다.

Claude Code는 더 높은 자율성의 에이전트와 특징을 공유하지만(auto 모드 분류기, 백그라운드 에이전트 실행, 원격 환경) 기본적으로 대화형 승인을 유지한다. SWE-Bench(Jimenez et al., 2023)와 HumanEval(Chen et al., 2021) 같은 평가 벤치마크가 코딩 에이전트에 대한 학계의 관심 상당 부분을 이끌어 왔다. 본 논문은 Claude Code의 내부 아키텍처를 소스 코드로부터 검토한다.

11.2에이전트 아키텍처 패턴#

Claude Code의 핵심 루프는 ReAct 패턴(Yao et al., 2022)을 따른다. 모델이 추론과 도구 호출을 생성하고, 하네스가 행위를 실행하며, 결과가 다음 반복으로 되먹여진다. Toolformer(Schick et al., 2023)는 언어 모델이 도구 사용을 학습할 수 있음을 보였다. Claude Code는 최대 54개의 내장 도구와 계층화된 권한 시스템을 사용한다. 더 넓은 설계 공간은 여러 서베이가 지도화해 왔다. Weng(2023)은 이제 표준이 된 계획·메모리·도구 사용의 분해를 제시했고, Wang et al.(2024a)은 초기 자율 에이전트 연구를 정리했다. Xu(2026)는 이 분야를 우리 분석 전반에 되풀이되는 세 가지 트레이드오프(자율성 대 통제 가능성, 지연시간 대 정확성, 능력 대 신뢰성)를 중심으로 구성하며, Hu et al.(2024)은 에이전트 설계 자체를 구성요소·알고리즘·평가 함수에 대한 탐색 문제로 규정한다. 본 논문은 그 공간의 한 특정 지점을 특징짓는다.

에이전트 하네스로서의 코드에 관한 최근 서베이는 코드를 모델 출력일 뿐 아니라 추론, 행위, 환경 모델링, 실행 기반 검증의 기질(substrate)로 규정한다(Ning et al., 2026). 그 규정은 벤치마크 점수만이 아니라 모델을 둘러싼 하네스에 초점을 맞추는 본 논문의 관점과 부합한다.

AutoGen(Wu et al., 2024), LangChain, CrewAI 같은 다중 에이전트 오케스트레이션 프레임워크는 대화 기반 에이전트 조율을 제공한다. Claude Code의 서브에이전트 위임(8절)은 권한 재정의 우선순위, 2단계 권한 범위, 서브에이전트별 별도 트랜스크립트 파일을 포함한다. LATS(Zhou et al., 2023)는 추론·행위·계획을 트리 탐색 프레임워크로 통합한다. Claude Code의 plan 권한 모드는 더 단순한 계획-후-실행 접근을 구현한다.

실무자들의 글은 Claude Code의 아키텍처가 구현하는 몇 가지 되풀이 패턴으로 수렴해 왔다. Anthropic 자신의 "Building Effective Agents"(Schluntz and Zhang, 2024)는 에이전트를 워크플로와 구별하고 무거운 프레임워크보다 단순하고 조합 가능한 패턴을 옹호한다. Martin(2026)은 프로덕션 시스템에서 관찰된 일곱 가지 패턴을 종합하는데, 여기에는 범용 행위 계층으로서 에이전트에 파일시스템과 셸 접근을 부여하는 것과, 모든 도구 스키마를 사전에 로드하는 대신 필요 시 행위를 발견하는 것이 포함된다. Chase(2025)는 Claude Code의 계획 도구가 "기본적으로 무동작(no-op)"이며 그 가치는 어떤 외부 계산을 수행하는 데 있는 것이 아니라 에이전트를 궤도에 유지하는 데 있다고 관찰한다. Wang(2025)은 학계 프레임워크가 가장 자주 빠뜨리는 요소가 권한(authority)이라고 주장하며, 신뢰를 프로덕션 에이전트 설계에서 "가장 간과된 요소"라고 부르는데, 이는 5절의 권한 분석이 메우고자 하는 간극이다. Huyen(2025)은 복합 오류 우려를 구체화한다. 단계당 95% 정확도에서 100단계 과제는 0.6%의 확률로만 성공하며, 이는 우리가 4절과 5절에서 추적하는 단계별 검증 패턴을 동기 짓는다. OpenAI도 하네스 엔지니어링에 관한 자체 글에서 하네스 자체의 설계를 중심적인 엔지니어링 과제로 다루며 유사한 지적을 한다(OpenAI, 2026a). 최근에는 루프 엔지니어링(loop engineering)이라는 새로운 개념도 등장했다. 매 턴 에이전트에 프롬프트를 주는 대신, 개발자가 작업을 찾고, 할당하고, 결과를 확인하고, 다음에 무엇이 올지 결정하는 루프를 구축하는 것으로, 이는 본 논문이 문서화하는 것과 동일한 원시 요소들(스킬, MCP 서버, 서브에이전트)로 조립된다(Osmani, 2026). 이는 한 명의 개발자가 훨씬 더 많은 작업을 자율적으로 지휘할 수 있게 하며 Claude Code 팀 자신을 포함해 관심을 끌었으나, 사람의 턴별 관여를 줄이는 것은 14절이 되돌아가는 장기적 개발자 역량 우려를 더 날카롭게 만들기도 한다.

컨텍스트 관리. 표 5는 컨텍스트 관리 접근법의 설계 공간 분류를 제시한다.

표 5 LLM 기반 도구의 컨텍스트 관리 접근법 설계 공간.

Claude Code의 5계층 압축 파이프라인은 강도를 높이기 전에 서로 다른 세밀도에서 복수의 전략을 적용하며, 캐시 인지 압축과 읽기 시점 가상 뷰 의미론을 갖는다. Zhang et al.(2025a)은 이 설계가 완화하는 두 가지 실패 모드(도메인 세부를 떨어뜨리는 요약과 반복적 컨텍스트 재작성으로 인한 세부 손실)를 특징짓고, 대신 컨텍스트를 시간이 지나며 전략을 축적하는 "진화하는 플레이북(evolving playbook)"으로 다룰 것을 제안한다. Claude Code의 접근법은 그 규정과 일관되는데, CLAUDE.md 계층이 지시문을 반복적으로 요약하는 대신 구조화된 형태로 축적하기 때문이다. Hu et al.(2025)은 컨텍스트 엔지니어링과 에이전트 메모리를 구별한다. 컨텍스트 엔지니어링은 일시적 조립을 다루고, 메모리는 지속적인 사실 지식과 경험적 흔적을 다룬다. Claude Code의 아키텍처는 압축 파이프라인과 파일 기반 메모리 계층을 짝지음으로써 둘을 같은 방식으로 분리한다.

안전과 권한. 프로덕션 코딩 에이전트는 세 축을 따라 달라지는 안전 아키텍처를 채택한다. 승인 모델(행위 단위 프롬프팅, 분류기 매개 자동화, 프롬프트 없이 사후 검토), 격리 경계(OS 수준 컨테이너, 파일시스템 샌드박스, 권한 범위 도구 풀, 또는 없음), 복구 메커니즘(버전 관리 롤백, 세션 범위 권한 초기화, 체크포인트 기반 되감기)이다. SWE-Agent와 OpenHands(Yang et al., 2024; Wang et al., 2024b)는 주로 Docker 컨테이너 격리에 의존하여 모든 에이전트 행위를 제약하는 환경 수준 샌드박싱을 제공한다. Codex CLI는 셸 명령에 대한 샌드박스 모드와 승인 정책을 지원한다. Aider(Gauthier, 2024)는 Git을 주된 안전 메커니즘으로 사용해 모든 변경을 버전 관리로 되돌릴 수 있게 한다. Claude Code는 행위 단위 거부 우선 규칙, 자동 승인을 위한 ML 기반 분류기, 선택적 셸 샌드박싱, 세션 범위 권한 미복원을 결합하여, 단일 격리 경계에 의존하는 대신 복수의 메커니즘을 계층화한다.

샌드박싱 보고서들이 이 경계를 구체화한다. OpenAI의 Windows 샌드박스 논의는 작업 디렉터리와 설정된 쓰기 가능 루트로 범위가 제한된 쓰기 접근을, 그 루트 안의 선택된 읽기 전용 경로에 대한 명시적 거부 규칙과 함께 기술한다(OpenAI, 2026b). Cursor의 클라우드 에이전트 보고서는 동일 문제의 클라우드 측면을 더한다. 네트워크 정책, 비밀 정보 마스킹, 자격 증명 관리가 에이전트 환경의 일부가 된다(Ma, 2026). 이 세부 사항들은 안전 경계를 승인 프롬프트만이 아니라 실행 경계로 만든다.

프로토콜과 확장성. Claude Code가 주된 외부 도구 통합으로 사용하는 Model Context Protocol은 상당한 생태계와 그에 상응하는 공격 표면을 갖는 사실상의 표준이 되었다. Hou et al.(2025)은 26개 주요 디렉터리에 걸친 수천 개의 커뮤니티 개발 MCP 서버를 정리하고, MCP 특화 위협을 도구 오염(tool poisoning), 러그 풀(rug pull), 교차 서버 섀도잉을 포함한 네 개의 공격자 범주와 열여섯 개의 시나리오로 조직한다. 5절에서 분석한 권한 및 거부 규칙 기계와 6.2절의 사전 필터링 단계는 그 서베이가 요청하는 완화책의 런타임 측면으로 읽을 수 있다.

같은 지적이 더 높은 수준의 도구 설계에도 적용된다. NSA 지침은 MCP 보안을 프로토콜 설계, 런타임 스케줄링, 외부 서비스와의 통합, 장기 모니터링에 걸친 생명주기 이슈로 다룬다(National Security Agency, 2026). 에이전트 우선 도구 설계 제안은 에이전트 대상 API가 인간 지향 CRUD 엔드포인트만이 아니라 search, resolve, preview, execute, verify, recover 단계를 제공해야 한다고 주장한다(Pan, 2026). 이렇게 읽으면 MCP 서버, 플러그인, 스킬, SDK, 에이전트 간 프로토콜은 하나의 도구 공급망을 이룬다. 그것들은 에이전트가 할 수 있는 일을 확장하지만, 신원, 허용목록, 버전 관리, 감사 로그, 폐기도 필요로 한다.

소프트웨어 아키텍처. 계층 아키텍처 패턴(Garlan et al., 1993)이 우리의 5계층 분해에 정보를 준다. 역할 기반 접근 통제 모델(Sandhu et al., 2002)은 권한 모드 시스템에 대한 이론을 제공한다. 브라우저 샌드박싱(Reis and Gribble, 2009)은 유사한 프로세스별 격리 접근법이다. 다중 에이전트 시스템 이론(Wooldridge, 2009)은 서브에이전트 위임을 설명하는 데 도움이 된다.

위치 짓기. 코딩 에이전트에 대한 선행 연구는 벤치마크(에이전트가 과제를 얼마나 잘 푸는가), 프레임워크(에이전트를 어떻게 조합하는가), 제품(사용자가 무엇을 할 수 있는가)에 초점을 맞춰 왔다. 본 논문은 프로덕션 코딩 에이전트에 대한 소스 기반 설계 공간 분석을 기여하며, 소스 수준 분석과 아키텍처 비교를 사용해 설계 선택과 트레이드오프를 표면화한다. 이는 소프트웨어 아키텍처 사례 연구 전통(Garlan et al., 1993)에 기대되, 설계 질문을 체계적으로 식별하고, 대안을 지도화하고, Claude Code의 선택을 서로 다른 배포 맥락에서 작동하는 두 독립 AI 에이전트 시스템인 OpenClaw 및 Hermes Agent의 그것과 대조함으로써 LLM 기반 에이전트에 적용한다.

12논의#

앞선 절들의 분석은 Claude Code가 루프 아키텍처, 안전 태세, 확장성, 컨텍스트 관리, 위임, 지속성에 관한 되풀이 설계 질문에 어떻게 답하는지를 문서화했다. 각 답은 실재하는 대안과 측정 가능한 트레이드오프를 갖는 설계 공간에서의 한 위치를 반영한다. 이 절은 그 답들을 함께 읽을 때 무엇이 드러나는지를 검토한다. 그것들이 반영하는 설계 철학(12.1절), 그것들이 만드는 가치 긴장(12.2절), 그것들이 수반하는 아키텍처적 트레이드오프(12.3절), 그것들이 낳는 실증적 예측(12.4절), 그리고 서브시스템 전반에 되풀이되는 가로지르는 헌신(12.7절)이다. 2.1절의 5가치 프레임워크가 이 절을 조직한다.

12.1설계 철학#

2절에서 소개한 가치와 설계 원칙은 결정 스캐폴딩이 아니라 운영 인프라에 투자하는 아키텍처를 예측한다. 구현은 이를 확증한다. 3절부터 9절까지 문서화한 아키텍처는 압도적으로 결정론적 인프라(권한 게이트, 도구 라우팅, 컨텍스트 관리, 복구 로직)이며, LLM은 무상태 완성 엔드포인트로 호출된다. 코드베이스의 약 1.6%가 결정 논리를 구성하고 나머지 98.4%는 운영 하네스로 추정된다. 이 비율은 우연이 아니다.

2.2절에서 문서화한 설계 원칙들이 이 접근법을 뒷받침한다. 하네스는 모델의 선택을 제약하는 것이 아니라 모델이 잘 결정할 수 있는 조건을 만든다.

이 설계는 에이전트 엔지니어링의 지배적 패턴과 상반된다. 그쪽에서는 LangGraph 같은 프레임워크가 모델 출력을 타입 지정 간선을 갖는 명시적 그래프 노드를 통해 라우팅하고, Devin 같은 시스템은 다단계 플래너를 무거운 운영 인프라와 짝짓는다. Claude Code는 대신 풍부한 운영 하네스 안에서 모델에 최대한의 결정 여지를 준다. 엔지니어링 복잡성은 모델의 결정을 제약하기 위해서가 아니라 그것을 가능하게 하기 위해 존재한다. 모델이 추론하고 하네스가 집행하는 이 계층 아키텍처는, 에이전틱 코딩 도구가 핵심 루프가 커널 역할을 하고 나머지 전부가 OS를 구성하는 운영체제 같은 추상으로 수렴하고 있는지를 묻게 만든다.

프론티어 모델들이 코딩 과제에서 실용적 능력 면에서 수렴함에 따라 이 설계는 추가적 의미를 얻는다. 주변 운영 하네스의 품질이 주된 차별화 요소가 되며, 이는 결정 스캐폴딩보다 인프라에 투자하는 아키텍처를 정당화한다. 에이전트 제작자에게 그 함의는, 컨텍스트 관리·안전 계층화·복구 메커니즘 같은 결정론적 인프라에 투자하는 것이 갈수록 유능해지는 모델 주위에 계획 스캐폴딩을 추가하는 것보다 더 큰 신뢰성 이득을 낼 수 있다는 것이다. 최근의 네이티브 런타임 벤치마킹은 이 논증적 주장에 직접적인 실증 근거를 준다. 모델을 고정하고 주변 하네스만 바꾸었을 때, 장기 지평 과제에서 단일 모델의 점수가 최대 18점까지 이동했으며, 테스트된 하네스에는 Claude Code와 OpenClaw가 포함되었다(Ding et al., 2026).

Tier C 모델 능력이 강해질수록, 코드베이스를 읽고 스스로 고칠 수 있는 Fable 5 같은 모델에도 여전히 하네스가 필요한가? 하네스는 2.1절의 다섯 가치에 봉사하며, 그중 오직 하나, 능력 증폭만이 주로 모델이 얼마나 유능한지에 관한 것이다. 그 안에서도 더 강한 모델이 영향을 주는 부분은 결정 스캐폴딩, 즉 일부 프레임워크가 모델을 해법으로 인도하고 제약하기 위해 그 주위에 두르는 계획 및 통제 논리다. 코드와 수학처럼 모델이 이미 강한 영역에서는 스스로 성공적인 해법에 도달하므로 그런 인도와 제약이 덜 필요하다. 나머지 네 가치는 주로 모델이 얼마나 유능한지에 관한 것이 아니므로, 그것들에 봉사하는 하네스는 남는다. 신뢰할 수 있는 실행이 부분적 예외다. 더 강한 모델은 요청을 더 정확히 읽고 자신의 실수를 조금 더 잘 고친다. 그러나 컨텍스트 윈도우는 여전히 유한하고, 세션은 여전히 재개되며, 모델은 여전히 매 실행마다 같은 것을 다른 방식으로 다시 만드는 경향이 있으므로 컨텍스트 관리와 복구는 여전히 필요하다. 안전·보안·프라이버시는 능력에 전혀 의존하지 않는다. 거부 우선 규칙, 샌드박싱, auto 모드 분류기, 감사 로그는 이전만큼 중요하며, 더 강한 모델은 더 안전한 것이 아니라 더 위험하다. Fable 5 자체도 고위험 영역에서 안전 분류기에 의해 제어된다(Anthropic, 2026c). 인간의 결정 권한은 모델의 능력이 아니라 사람의 결정할 권리에 관한 것이므로, 승인, 중단, 트랜스크립트는 그 역할을 유지한다. 맥락 적응성도 마찬가지다. 강한 모델도 여전히 당신의 코드를 본 적 없는 범용 모델이므로, CLAUDE.md, 스킬, MCP가 여전히 그것을 당신의 프로젝트에 맞춘다. 다섯 가치 전부를 구속하는 토큰 경제학도 완화되지 않는다. 더 나은 모델이 토큰을 공짜로 만들어 주지는 않기 때문이다.

연구는 가장 강한 모델에 대해서도 이를 뒷받침한다. 하네스 선택만으로 Fable 5의 기능적 통과율과 보안 통과율이 10점 이상 움직인다(Compagna, 2026). 하네스는 모델 능력이 커진다고 무용해지지 않는다. 변하는 것은 결정 스캐폴딩뿐이며, 그것도 모델이 이미 강한 영역에서만 그러하고, 하네스가 하는 나머지 모든 일은 이전만큼 중요하게 남는다.

종합하면, 앞선 절들은 프로덕션 코딩 에이전트가 되풀이되는 설계 선택에 직면함을 보여준다. 추론이 하네스에 대해 어디에 위치하는가, 반복 루프가 어떻게 구조화되는가, 기본적으로 어떤 안전 태세를 취하는가, 확장 표면이 어떻게 분할되는가, 컨텍스트가 어떻게 조립되고 압축되는가, 서브에이전트가 어떻게 위임되고 조율되는가, 세션이 경계를 넘어 어떻게 지속되는가. 이 질문들에 대한 Claude Code의 답은 풍부한 운영 하네스 안에서 모델 자율성을 우대하는 하나의 정합적인 설계 지점을 이룬다. 이 철학은 풍부한 결정론적 인프라가 제약 없는 모델 판단을 충분히 뒷받침할 수 있다고 가정한다. 이어지는 하위 절들은 이 가정이 시험받는 지점을 검토한다.

12.2가치 긴장#

2.1절에서 식별한 다섯 가치는 하나를 추구하는 것이 다른 하나를 제약하는 긴장을 낳는다(표 6). 이 긴장들은 설계 실패가 아니다. 복수의 가치를 동시에 추구하는 데서 오는 구조적 귀결이다. 우리는 전체 조합 집합이 아니라 뒷받침 근거가 가장 강한 긴장들을 보고한다.

표 6 가치 간 긴장과 뒷받침 근거. 각 긴장은 두 가치가 진정으로 구별되는 관심사를 포착함을 보여준다.

단기 이득이 장기적 개발자 역량을 약화시키는지는 별개의 질문이다(2.4절). 246개 과제에 걸친 숙련 개발자 16명 무작위 대조 시험(Becker et al., 2025)은 AI 도구가 20% 개선되었다는 인식에도 불구하고 개발자를 19% 더 느리게 만들었음을 발견했다. 807개 저장소에 걸친 Cursor 도입의 인과 분석(He et al., 2025)은 코드 복잡도가 40.7% 증가했음을 발견했다. 54명 참가자에 대한 EEG 연구(Kosmyna et al., 2025)는 LLM 사용자가 AI를 제거한 뒤에도 지속되는 약화된 신경 연결성을 보였음을 발견했다. 연구자들은 AI 프로그래밍에서 인지 오프로딩(cognitive offloading)을 측정하기 위한 프로토콜을 제안했는데, 이는 AI를 사용하는 학생들이 기저 논리를 이해하지 못한 채 애플리케이션을 생산한다는 우려에서 동기 지어졌다(Aiersilan, 2026). 이 발견들은 2023년에서 2024년 사이 신입 기술직 채용의 25% 감소(Rak, 2025)와 결합되어, 능력 증폭과 장기적 지속가능성 사이의 긴장이 개인 생산성을 넘어 더 넓은 개발자 파이프라인으로 확장됨을 시사한다. 이 근거는 그 질문을 동기 짓지만 Claude Code의 아키텍처를 구체적으로 겨냥하지는 않는다. 이는 제한된 컨텍스트, 도구 사용 루프, 국소적 생성 결정에 의존하는 에이전트 시스템에 가장 관련이 깊다.

12.3아키텍처적 트레이드오프#

표 6의 긴장은 네 영역에서 구체적인 아키텍처적 트레이드오프로 나타난다. 위에서 문서화한 장기 지속가능성 우려는 12.4절의 실증적 예측에서 표면화된다.

안전 대 자율성. 권한 모드(항상 존재하는 다섯 개, 분류기 기능 플래그가 활성일 때의 auto, 그리고 내부 bubble 모드)는 plan(사용자가 모든 계획을 승인)에서 default, acceptEdits, auto(ML 분류기)를 거쳐 bypassPermissions(대부분의 프롬프트를 건너뛰되 안전 필수 검사는 남음)에 이르는 기울기를 만든다. 이 진행은 자율성이 증가함에 따라 단조 감소하는 안전 기울기를 나타낸다. 재개 시 권한을 복원하지 않는 것은 안전 쪽으로 기우는 의도적 선택을 반영한다. 보안 상태는 세션 경계를 넘어 암묵적으로 지속되지 않는다.

안전-자율성 기울기는 아키텍처 설계뿐 아니라 사용자 행동에 의해서도 형성된다. Anthropic의 auto 모드 분석(Hughes, 2026)은 사용자가 권한 프롬프트의 약 93%를 승인함을 발견했으며, 이는 승인 피로가 대화형 확인을 행동적으로 신뢰할 수 없게 만듦을 시사한다. 종단 사용 데이터(McCain et al., 2026)는 자동 승인 비율이 세션 50회 미만에서 약 20%였다가 750세션에 이르면 40%를 넘고, 세션 지속 시간도 상당히 증가함을 보여준다. 이 패턴들은 그 기울기가 의도적인 모드 선택이 아니라 점진적 습관화에 의해 항해됨을 시사한다. 샌드박싱은 권한 프롬프트 빈도를 약 84% 줄인 것으로 추정되며(Dworken and Weller-Davies, 2025), 이는 문제를 인간 요인(human-factors) 관심사로 재구성한다. 신뢰할 수 없는 인간 승인에 대한 아키텍처적 대응은 인간이 내려야 하는 결정의 수를 줄이는 것이다.

더 근본적으로, 5절에서 기술한 심층 방어 아키텍처는 독립성 가정에 기반한다. 한 안전 계층이 실패하면 다른 계층들이 위반을 잡아낸다는 것이다. 그러나 Claude Code의 안전 계층들은 공통의 성능 및 경제적 제약을 공유한다. auto 모드 분류기는 직접적인 토큰 비용을 갖는 별도의 LLM 호출이다. bashSecurity.ts 모듈은 파싱 지연을 동반한 순차적 AST 기반 검사를 수행한다. 거부 우선 규칙 평가는 명령 구조를 대상으로 작동한다. 성능 압력이 이 비용들을 줄이는 쪽으로 밀어붙이면 계층들이 동시에 저하될 수 있다. 보안 연구자들(Adversa.ai, 2026)은 하위 명령이 50개를 넘는 명령이 하위 명령별 거부 규칙 검사를 실행하는 대신 단일한 일반 승인 프롬프트로 폴백함을 문서화했는데, 이는 하위 명령별 파싱이 UI 정지를 유발했기 때문이며, 독립성 가정이 위반될 때 심층 방어가 실패함을 보여준다.

이 긴장은 구조적이다. 안전 평가에 모델 자체를 사용하는 모든 LLM 기반 에이전트 시스템이 이에 직면한다. 관련된 평가 기준은 개별 계층이 우회될 수 있는지가 아니라, 얼마나 많은 독립 계층이 동시에 실패해야 하는지, 그리고 그것들이 실패 모드를 공유하는지다.

적대적 조건 하의 권한 모델. 독립 보안 연구는 권한 아키텍처에 대한 실증적 검증을 제공하는데, 구체적으로는 그림 4가 포착하지 못한 시간적 순서 속성을 드러냄으로써 그렇게 한다. 독립적으로 검증된 두 취약점은 사전 신뢰 초기화 순서에 공통 근본 원인을 갖는다. 프로젝트 초기화 중 실행되는 코드(훅, MCP 서버 연결, 설정 파일 해소)가 대화형 신뢰 대화상자가 사용자에게 제시되기 전에 실행된다는 것이다.⁵ 이 사전 신뢰 실행 창은 거부 우선 평가 파이프라인(permissions.ts) 바깥에 놓여, 5절에서 문서화한 안전 보장이 아직 적용되지 않는 구조적으로 특권적인 국면을 만든다.

이 패턴은 권한 파이프라인이 안전 검사의 공간적 순서는 묘사하지만 시간적 차원, 구체적으로 세션 초기화 중 각 메커니즘이 언제 활성화되는지는 포착하지 못함을 드러낸다. 초기화 순서(확장 로딩, 그다음 신뢰 대화상자, 그다음 권한 집행)는 확장성 아키텍처(6절)가 안전 아키텍처(5절)가 완전히 가동되기 전에 작동하는 창을 만든다. 이 발견은 확장성 대 단순성 긴장에 보안 차원을 더해 정교화한다. 확장성은 조합적 복잡성을 통해서만이 아니라 초기화 순서를 통해서도 공격 표면을 만든다.

컨텍스트 효율 대 투명성. 5계층 압축 파이프라인은 효과적인 컨텍스트 관리를 달성하지만, 압축은 사용자에게 대체로 보이지 않는다. 예산 축소가 긴 도구 출력을 참조로 대체할 때, 컨텍스트 붕괴가 메시지를 요약으로 대체할 때(소스에서 "REPL의 전체 이력에 대한 읽기 시점 투영"으로 기술됨), 또는 스닙이 오래된 이력을 정리할 때, 사용자는 무엇이 손실되었는지 검사할 쉬운 방법이 없다. 마이크로컴팩트의 캐시 인지 동작은 불투명성을 더한다. 압축 결정이 사용자에게 보이지 않는 방식으로 프롬프트 캐싱의 영향을 받기 때문이다. 요약 기반 압축에 관한 외부 연구는 소스 수준 관점이 드러내지 못하는 두 가지 비용을 불투명성 외에 문서화한다. 요약 단계는 블로킹 추론 지연이며, 비결정론적이어서 동일한 입력에 대해서도 실행마다 보존되는 내용이 요동친다(Cim et al., 2026).

단순성 대 확장성. 네 확장 메커니즘은 풍부한 커스터마이징을 가능하게 하지만 조합적 상호작용을 만든다. 플러그인이 도구 입력을 수정하는 PreToolUse 훅을 기여한다. auto 모드 분류기가 캐시된 CLAUDE.md 내용을 읽는다. 경로 범위 규칙이 새 디렉터리를 읽을 때 지연 로드되어, 잠재적으로 대화 도중 분류기 동작을 바꾼다. 권한 핸들러의 네 분기가 훅 파이프라인과 여러 지점에서 상호작용한다. 이 가로지르는 관심사들은 어떤 단일 설정 파일로부터도 예측하기 어려운 창발적 동작을 만든다.

12.4실증적 예측과 초기 신호#

본 논문이 문서화한 아키텍처적 속성들은 소스 코드만으로는 도출할 수 없는 코드 품질 결과에 관한 검증 가능한 예측을 낳는다. 제한된 컨텍스트 윈도우(7절)는 에이전트가 전체 코드베이스에 대한 동시적 인식을 유지하는 것을 막는다. 5계층 압축 파이프라인은 유용한 정보를 보존하지만 각 단계에서 손실 압축을 도입한다. 이는 에이전트가 생성한 코드가 전체 코드베이스 가시성을 갖고 생산된 코드보다 패턴 중복과 관례 위반 비율이 더 높을 것이라는 아키텍처적 예측을 낳는다. 각 서브에이전트가 독립적으로 조립된 도구 풀을 갖고 자신의 컨텍스트 윈도우에서 작동하는 서브에이전트 격리(8절)는 이 효과를 가중한다. 병렬 에이전트들이 다른 곳에 이미 존재하는 해법을 독립적으로 재구현할 수 있다. 12.1절의 설계 철학은 모델이 좋은 국소적 결정을 내리리라 신뢰하지만, 모델이 전역 컨텍스트를 결여할 때 좋은 국소적 결정이 나쁜 전역적 결과를 낳을 수 있다.

아키텍처적으로 유사한 도구들에 대해 발표된 실증 연구는 이 예측들과 일관된 데이터를 제공한다. 807개 저장소에 걸친 Cursor 도입의 인과 분석(He et al., 2025)은 통계적으로 유의미한 코드 복잡도 증가를 발견했으며, 초기 속도 급등은 3개월 차에 기준선으로 소멸했다. 증가하는 복잡도는 미래 개발 속도의 비례적 감소와 연관되었는데, 이는 단기 이득이 나중의 유지보수 비용으로 상쇄될 수 있음을 시사한다.⁶ 6,275개 저장소에 걸친 304,000개의 AI 작성 커밋에 대한 대규모 감사(Liu et al., 2026)는 측정 가능한 기술 부채를 발견했으며, AI가 도입한 이슈의 약 4분의 1이 최신 리비전까지 지속되고 보안 관련 이슈는 상당히 더 높은 비율로 지속되었다. 이 연구들이 인접 시스템을 겨냥하고 있긴 하지만, 아키텍처적 유사성(제한된 컨텍스트, 도구 사용 루프, 국소적 생성 결정)은 그것들을 여기서 분석한 설계에 대한 관련 있는 비교 지점으로 만든다. Claude Code 자체에서 수행된 통제된 최소 대조쌍(minimal-pair) 연구는 이 효과들이 측정 가능한 지점을 더 날카롭게 한다. 코드 청결도는 과제 통과율을 바꾸지 않았지만, 더 깨끗한 입력은 토큰 사용을 7~8% 줄이고 파일 재방문을 34% 줄였으며(Trivedi and Schmitt, 2026), 이는 하네스의 컨텍스트 처리가 가장 뚜렷이 드러나는 곳이 원시 성공률이 아니라 운영 발자국(비용과 탐색)임을 나타낸다.

Claude Code의 컨텍스트 관리 파이프라인은 이 효과들을 완화하도록 특별히 설계되었다. 점진적 압축은 가장 최근이고 가장 관련성 높은 컨텍스트를 보존하고, 캐시 인지 압축은 압축 중 프롬프트 캐시 무효화를 피하며, 읽기 시점 투영은 모델에 압축된 뷰를 제시하면서도 재구성을 위해 전체 이력을 유지하고, 서브에이전트 요약 격리는 탐색 노이즈가 부모 컨텍스트에 누적되는 것을 방지한다. 이 메커니즘들이 제한된 컨텍스트의 구조적 한계를 극복하기에 충분한지는 본 논문의 소스 수준 분석이 해소할 수 없는, 직접 측정 가능한 실증적 질문이다.

12.5한계#

부록에 기술한 방법론적 한계 외에도 몇 가지 분석적 제약이 적용된다. 메모이즈된 컨텍스트 조립 함수들(getSystemContext()와 getUserContext() 둘 다 context.ts에서 lodash memoize 사용)은 git 상태와 CLAUDE.md 내용이 매 턴 재계산되는 대신 캐시됨을 의미한다. 대화 중의 동적 변화가 즉시 반영되지 않을 수 있지만, 압축이 캐시를 비울 수 있고 지연 로드되는 경로 범위 규칙이 부분적인 대응 메커니즘을 제공한다.

기능 플래그는 빌드 시점 가변성을 만든다. TRANSCRIPT_CLASSIFIER가 false인 빌드에서는 auto 모드 분류기 전체가 제거된다. 기능 게이팅된 모듈은 정적 import가 아니라 동적 require()를 사용하는데(예: 컨텍스트 붕괴를 위한 query.ts), 이는 bun:bundle 트리 셰이킹 제약으로 인해 feature()가 if/삼항 조건에서만 작동하기 때문이다. 서로 다른 빌드 타깃이 기능적으로 다른 애플리케이션을 산출할 수 있다.

12.6부상하는 방향#

구현의 여러 측면이 더 넓은 설계 질문과 관련된다. 더 긴 컨텍스트 윈도우는 압축 압력을 줄여 점진적 파이프라인을 단순화할 잠재력이 있다. 다중 모달 도구(스크린샷, 다이어그램, UI 미리보기)는 도구 표면을 확장하고 새로운 컨텍스트 과제를 만들 것이다. 권한 속성의 형식 검증(예를 들어 거부 규칙이 항상 우선함, 샌드박싱된 명령이 격리를 탈출할 수 없음, 재개된 세션이 낡은 권한을 물려받을 수 없음을 증명하는 것)은 더 강한 안전 보장을 제공할 것이다.

아키텍처적 탈결합. 여기서 분석한 긴밀히 결합된 로컬 아키텍처는 이미 진화 중인 스펙트럼의 한 지점이다. Anthropic 자신의 Managed Agents 작업(Martin et al., 2026)은 에이전트의 구성요소(세션, 하네스, 샌드박스)를 가상화하여 "각각이 다른 것들에 대해 거의 가정하지 않는 인터페이스가 되고, 각각이 독립적으로 실패하거나 교체될 수 있게" 하는 것을 기술하며, 운영체제가 하드웨어를 프로세스와 파일로 가상화한 방식에 명시적으로 비유한다. Harness Design 에세이(Rajasekaran, 2026)는 더 나은 모델이 유용한 하네스 조합의 공간을 제거하는 것이 아니라 이동시킨다고 주장하며 다른 각도에서 유사한 지적을 한다. 따라서 본 논문이 문서화한 아키텍처는 고정된 최적점이 아니라 공진화하는 시스템의 스냅샷으로 읽혀야 한다.

클라우드 에이전트 보고서들은 운영체제 비유에 의존하지 않고 이를 구체화한다. Cursor는 에이전트 루프, 머신 상태, 대화 상태를 분리하고 VM 체크포인팅, 네트워크 정책, 비밀 정보 처리, 자격 증명 관리를 에이전트 제품의 일부로 다룬다(Ma, 2026). LangChain의 Managed Deep Agents는 지속 스레드, 체크포인팅, 스트리밍, 컨텍스트, 관측가능성, 인간 개입 워크플로를 관리 런타임에 두는 유사한 수를 둔다(LangChain, 2026b). Google의 Antigravity는 사람들에게 에이전트의 작업을 확인할 수 있는 계획, 스크린샷, 녹화 같은 산출물을 제공한다(Google, 2025). 따라서 유용한 설계 질문은 런타임 소유권이다. 어느 계층이 루프, 상태, 샌드박스, 정책, 복구 경로를 소유하는가?

일급 서브시스템으로서의 메모리. Hu et al.(2025)의 메모리 서베이는 에이전트 메모리가 컨텍스트 윈도우 관리의 부수 효과가 아니라 별개의 인지 기질이 되어 가고 있다고 주장하며, 자동화된 메모리 관리, RL 기반 메모리, 신뢰할 수 있는 메모리(프라이버시, 설명 가능성, 환각 강건성)를 열린 최전선으로 식별한다. 오늘날 Claude Code는 사실 계층(CLAUDE.md, 자동 메모리)과 작업 계층(대화 윈도우)을 노출한다. 경험 계층(과거 세션에서 학습한 전략의 축적되고 자동으로 큐레이션되는 플레이북)이 자연스러운 다음 단계이며, 컨텍스트 엔지니어링 문헌(Zhang et al., 2025a)이 그 축적을 위한 메커니즘을 제공하기 시작했다.

Context Hub는 그 경계를 가시화한다. LangSmith Context Hub는 AGENTS.md 파일, 스킬, 정책, 예제 및 관련 번들을 버전 관리되고 검토 가능한 산출물로 다루며, 환경 간 배포를 위한 태그를 제공한다(LangChain, 2026a). 이는 Claude Code의 파일 계층과는 다른 설계 지점이지만, 동일한 문제를 지목한다. 컨텍스트에는 토큰 예산뿐 아니라 생명주기가 필요하다.

관측가능성과 조용한 실패. 업계 서베이는 배포된 에이전트의 지배적 실패 모드가 충돌이 아니라 조용한 실수임을 시사한다. Bessemer의 2026년 인프라 보고서(Wade et al., 2026)는 "AI 실패의 78%가 보이지 않는다"고 추정하며, LangChain의 1,340명 응답 에이전트 엔지니어링 현황 조사(LangChain, 2026c)는 비용이 아니라 품질을 프로덕션 사용의 최대 장벽으로 식별하고 관측가능성(거의 89% 채택)과 오프라인 평가(52.4%) 사이의 넓은 격차를 발견한다. 여기서 분석한 아키텍처는 운영자에게 도구 호출, 훅, 세션 트랜스크립트에 대한 가시성을 제공한다. 평가 격차를 메우는 데는 모델 개선만으로는 부족하고 추가 스캐폴딩(생성자-평가자 분리, 스프린트 계약, Rajasekaran(2026)에서 논의된 종류의 사후 검사)이 필요할 가능성이 높다.

OpenAI의 에이전트 개선 루프는 이를 실행 가능하게 만든다. 트레이스와 피드백이 평가(eval)가 되고, 그 결과인 증거가 하네스 변경을 위한 Codex 핸드오프가 된다(Pasfield, 2026). 그 루프에서 텔레메트리가 중요한 이유는 그것이 재사용 가능한 테스트나 구체적인 변경 요청으로 전환되기 때문이다.

거버넌스. 에이전트가 더 자율적이 됨에 따라 더 넓은 거버넌스 흐름이 설계 공간을 제약할 것이다. International AI Safety Report(Bengio et al., 2026)는 "AI 에이전트는 자율적으로 행동하므로 실패가 해를 끼치기 전에 인간이 개입하기 더 어렵게 만들어 높아진 위험을 제기한다"고 경고하며, MIT AI Agent Index(Staufer et al., 2026)는 색인된 에이전틱 시스템 중 13.3%만이 에이전트 특화 안전 카드를 발행함을 발견한다. EU AI Act와 AI 생성 코드를 둘러싼 진화하는 저작권 논쟁을 포함한 부상하는 규제 노력은 로깅, 투명성, 위험 관리, 인간 감독에 대한 외부 제약을 부과하여 코딩 에이전트 아키텍처의 진화 방향을 형성할 수 있다.

능동적 아키텍처. 기능 게이팅된 KAIROS 시스템은 이 아키텍처가 반응형 도구 사용을 넘어 어떻게 진화할 수 있는지를 예시한다. KAIROS는 틱 기반 하트비트를 갖는 지속적 백그라운드 에이전트를 구현한다. 대기 중인 사용자 메시지가 없으면 시스템이 주기적인 <tick> 프롬프트를 주입하고, 모델이 행동할지 잠들지를 결정한다. 이 설계는 능동적 AI 어시스턴트에 관한 한 연구에서 문서화된 긴장을 다룬다. 과제 완료가 12~18% 증가한 반면 높은 빈도에서는 사용자 선호도가 하락했다(Chen et al., 2025). KAIROS는 이를 터미널 포커스 인지(사용자가 자리를 비웠을 때 자율 행동을 최대화하고, 있을 때 협업을 늘림)와 SleepTool을 통한 경제적 조절(각 깨어남은 API 호출 비용이 든다. 프롬프트 캐시는 5분간 비활동 후 만료되므로 수면/기상이 명시적인 비용 최적화가 된다)로 해소하려 한다. 능동성을 사용자 현존과 토큰 경제학 양쪽에 결부시키는 것은 주목할 만하지만, KAIROS가 프로덕션 빌드에서 활성인지는 확인할 수 없다.

12.7되풀이되는 설계 선택#

여섯 서브시스템 분석을 함께 읽으면, 그 밖으로는 독립적인 구성요소들에 걸쳐 되풀이되는 세 가지 가로지르는 설계 헌신이 드러난다.

단일 메커니즘 대신 점진적 계층화. 안전, 컨텍스트 관리, 확장성 모두 단일한 통합 해법이 아니라 독립적 메커니즘의 점진적 스택을 사용한다. 권한 아키텍처는 3.5절에 열거한 일곱 개의 독립 단계를 계층화한다. 도구 사전 필터링, 거부 우선 규칙 평가, 권한 모드 제약, auto 모드 분류기, 셸 샌드박싱, 재개 시 세션 권한 미복원, 훅 가로채기다. 컨텍스트 관리는 다섯 압축 단계, 지연 로드되는 CLAUDE.md 파일, 지연 도구 스키마, 요약 전용 서브에이전트 반환을 계층화한다. 확장성은 서로 다른 컨텍스트 비용에서 네 메커니즘(MCP 서버, 플러그인, 스킬, 훅)을 계층화한다(6절). 각 경우에 설계는 단순성과 디버그 가능성을 심층 방어와 맞바꾸며, 계층 간 상호작용이 어떤 단일 설정 파일로부터도 예측하기 어려운 창발적 동작을 낳을 수 있음을 감수한다. 10절의 OpenClaw 및 Hermes Agent 대조는 점진적 계층화가 매우 다른 배포 맥락을 갖는 시스템들에 걸쳐 되풀이됨을 보여주며, 이는 계층화 패턴이 Claude Code 특유의 구현 선택이 아니라 공유된 설계 질문을 반영함을 시사한다.

질의력보다 감사 가능성을 선호하는 추가 전용 설계. 세션 트랜스크립트는 읽기 시점 체인 패칭을 갖는 추가 전용 JSONL 파일이다. 권한은 세션 경계를 넘어 복원되지 않는다. 컨텍스트 압축은 파괴적 편집이 아니라 전체 이력에 대한 읽기 시점 투영을 적용한다. 이 헌신이 되풀이되는 이유는 그것이 이전에 기록된 상태를 수정하지 않고도 세션을 재개하고, 포크하고, 감사하는 능력을 보존하기 때문이다. 그 비용은 더 풍부한 구조화 질의("여러 세션에 걸쳐 파일 X를 수정한 모든 도구 호출을 보여줘")가 직접 조회가 아니라 사후 재구성을 요구한다는 점이다.

결정론적 하네스 안의 모델 판단. 모든 서브시스템에 걸쳐, 이 아키텍처는 모델의 선택을 제약하는 대신 풍부한 결정론적 하네스 안에서 모델의 판단을 신뢰한다. 추정된 1.6% 결정 논리 비율이 이를 정량적으로 포착한다. 하네스는 모델이 잘 결정할 수 있는 조건(도구 라우팅, 권한 집행, 컨텍스트 조립, 복구 로직)을 만든다. 위계적 권한이 에이전트 경계를 넘어 안전 불변식을 보존하고, assembleToolPool()이 내장 도구와 MCP 도구를 단일한 통합 인터페이스로 병합하지만, 어떤 도구를 어떤 순서로 호출할지에 대한 완전한 여지는 모델이 유지한다. 그 트레이드오프는 제한된 컨텍스트가 전역적 인식을 막을 때 좋은 국소적 결정이 나쁜 전역적 결과를 낳을 수 있다는 것이며, 이는 12.4절의 실증적 예측이 문서화하는 바다.

13향후 방향#

12절은 3절부터 9절까지 문서화한 아키텍처를 하나의 정합적인 설계 지점으로 읽고, 그 설계 지점이 함의하는 긴장, 트레이드오프, 근거리 방향을 표면화했다. 이 절은 아키텍처 자체를 넘어, 12.6절이 부분적으로 지목하고 성장하는 외부 문헌이 구체적으로 진술할 만큼 날카롭게 만든 여섯 가지 열린 질문을 기록한다. 이 질문들은 본 논문의 5가치 프레임워크(2.1절)와 2.4절에서 도입한 장기적 개발자 역량 질문을 아우른다. 그것들은 권한 위계에 대한 거버넌스 제약(13.5절), 안전 측면의 관측가능성-평가 격차(13.1절), 신뢰성 측면의 세션 간 지속성(13.2절), 능력 최전선의 네 가지 확장(13.3절), 신뢰할 수 있는 실행의 별개 축으로서의 지평 확장(13.4절), 그리고 설계 질문으로 재구성된 장기적 개발자 역량(13.6절)에 관한 것이다. 12.6절의 구성과 일관되게, 각 질문은 ~인지/어떻게/어느 것 형태로 제기된다. 인용된 출처가 구체적인 메커니즘 선택을 지목할 때는 그것을 명시하고, 그렇지 않으면 열어 둔다.

13.1조용한 실패와 관측가능성-평가 격차#

12.6절에서 보고한 관측가능성-평가 격차는 누락된 도구 계층을, 하네스 내부의 누락된 평가 인터페이스를, 또는 모델 능력 천장을 반영하는 것일 수 있다. 그곳의 출처들은 이를 판정하지 않는다. 따라서 그 문단이 언급한 조용한 실수 실패 모드를 어떻게 표면화해야 하는지는 모델에 대한 능력 질문이 아니라 하네스에 대한 아키텍처 질문이다. 최근의 실증 연구는 이 격차를 여러 해상도에서 특징짓는다. Cemri et al.(2025)은 시스템 설계 문제, 에이전트 간 오정렬, 과제 검증에 걸친 열네 가지 실패 모드를 정리한다. Pathak et al.(2025)은 트레이스의 이상 탐지를 위해 특별히 에이전트 궤적 벤치마크를 구축한다. Yao et al.(2024)은 k회의 독립 시행이 모두 성공할 확률인 pass^k 지표를 통해 일관성 격차를 드러낸다. Kapoor et al.(2024)은 현재의 에이전트 벤치마크가 홀드아웃과 비용 통제를 결여하여 관측가능성이 실제로 진단할 수 있는 바를 제한한다고 주장한다.

4절과 5절에서 분석한 권한 파이프라인 및 도구 오케스트레이션 계층에 견주면 두 가지 아키텍처 질문이 열린 채로 남는다. 첫째, 본 논문이 Rajasekaran(2026)으로부터 인용한 스캐폴딩(생성자-평가자 분리, 스프린트 계약, 사후 검사이며 Madaan et al.(2023)의 self-refine 패턴에 기반)이 하네스 안에(예: 6절에서 문서화한 27개와 나란한 추가 훅 이벤트로) 속하는지 아니면 별도의 평가 계층으로 그 바깥에 속하는지는 인용된 출처들로 해결되지 않는다. 둘째, 6절의 기존 훅 파이프라인이 현재의 컨텍스트 비용 한도 안에서 그러한 스캐폴딩을 수용할 수 있는지는 또 다른 열린 질문이다. 이 격차를 메우는 데 "모델 개선만이 아니라 추가 스캐폴딩이 필요할 가능성이 높다"(12.6절)는 관찰은 열린 작업을 하네스 계층에 위치시킨다.

13.2지속성: 메모리와 종단적 동료 관계#

에이전트 상태와 인간-에이전트 작업 관계가 세션을 넘어 지속되어야 하는지, 그리고 어떤 형태로 그래야 하는지는 오늘날 본 논문에서 두 개의 구별되는 계층에서 다뤄진다. 7절은 4단계 CLAUDE.md 계층과 자동 메모리를 문서화한다. 9절은 재개가 세션 범위 권한을 복원하지 않는, 대체로 추가 전용인 JSONL 트랜스크립트를 문서화한다(명시적 정리 재작성은 예외). 이 두 계층 사이에 무엇이 속하는지는 열린 설계 질문이다. 즉 정적 지시문도 아니고 단일 세션의 트랜스크립트도 아닌 지속 상태 말이다. 12.6절에서 이미 인용한 Hu et al.(2025)과 Zhang et al.(2025a)은 축적 계층을 동기 짓는다. Packer et al.(2023)은 LLM을 페이징된 메모리를 갖는 운영체제로 재규정한다. Chhikara et al.(2025)은 재시작을 견디는 프로덕션 지향 메모리 저장소를 구축하고, Xu et al.(2025)은 연구용 에이전틱 메모리 설계를 제안한다. Wang et al.(2024c)은 재사용 가능한 절차적 흔적을 포착한다. Shinn et al.(2023)은 시도를 거듭하며 언어적 강화를 통해 자기 성찰 흔적을 축적한다. Zhang et al.(2025b)과 Huang et al.(2026)의 서베이가 후보 메커니즘들을 지도화한다.

MemGym은 메모리 질문을 더 구체적으로 만든다. 그것은 채팅에서 개인적 사실의 보유만이 아니라 도구 사용 대화, 심층 연구, 코딩, 컴퓨터 사용에 걸친 동적 메모리 형성을 평가한다(Xu et al., 2026). 이는 질문을 "노트를 어디에 저장해야 하는가?"에서 "어떤 기억된 상태가 에이전트가 계속 올바르게 작업하도록 돕는가?"로 옮긴다.

동일한 지속성 질문이 인간 쪽에서도 되풀이된다. 12.6절은 이미 Huang et al.(2025)과 McCain et al.(2026)의 종단적 자율성 근거를 인용한다. Dell'Acqua et al.(2025)의 Procter & Gamble 전문가 776명 현장 실험은, Copilot 도입에 대한 종단적·조직적 연구(Stray et al., 2025) 및 AI 팀워크 궤적 연구(Xiao et al., 2025)와 함께, 협업이 축적됨에 따라 인간-AI 작업 역학에 변화가 있음을 보고한다. Wang et al.(2023)은 과제를 넘어 스킬 라이브러리를 축적하는 체화된 에이전트를 예시한다. Mollick(2024)은 인간-AI 작업 관계를 공동 지능(co-intelligence)으로 규정한다.

단일한 기질이 사용자의 개인 지시문 계층과 공유된 조직 컨텍스트를 모두 담으면서 7절이 문서화한 CLAUDE.md의 파일 기반 투명성을 보존할 수 있는지는 열린 아키텍처 질문이다. 세션 범위 권한이 그러한 기질과 어떻게 상호작용하되 9절이 의도적 안전 선택으로 닫아 둔 재개-복원 우려를 재도입하지 않을지는 또 다른 열린 질문이다. 10절과 10.2절에서 문서화한 OpenClaw의 메모리 서브시스템(dreaming, 일일 노트, 하이브리드 검색)과 Hermes Agent의 전문 검색을 갖는 WAL 모드 SQLite 세션 저장소는, 지속 기질이 정적 지시문 계층과 단일 세션 트랜스크립트 사이에 어떻게 놓일 수 있는지에 대한 두 가지 구체적 참조점을 제공한다.

13.3하네스 경계 진화: 에이전트가 어디서, 언제, 무엇에, 누구와 함께 행동하는가#

12.6절은 더 나은 모델이 유용한 하네스 조합의 공간을 제거하는 것이 아니라 이동시킨다는 Rajasekaran(2026)의 주장을 인용한다. 그 이동이 하네스가 어디서 실행되는지, 언제 행동하는지, 무엇에 대해 행동하는지, 누구와 조율하는지 중 어디에서 가장 두드러질지는 3절부터 9절의 소스 수준 분석으로 해결되지 않는다. 넷 각각에는 본 논문이 지나가듯 언급할 뿐인 활발한 연구 문헌이 있다.

어디서. Martin et al.(2026)의 Managed Agents 설계는 세션, 하네스, 샌드박스를 독립적으로 교체 가능한 인터페이스로 가상화한다. 이는 Packer et al.(2023)이 컨텍스트 윈도우 관리에 적용하고 Karpathy(2023)가 더 넓게 대중화한 가상 메모리 비유를 확장한다. Khattab et al.(2023)은 하네스 자체를 컴파일 대상으로 다룬다.

언제. 12.6절은 이미 KAIROS를 기능 게이팅된 예시로 소개했으며, 이는 Chen et al.(2025)이 보고한 +12%~+18% 과제 통과 이득과 고빈도 Persistent Suggest 변형에 한정된 급격한 선호도 페널티(47% 대 80~90%)에서 동기 지어진다. Liu et al.(2025), Pu et al.(2025), Lee et al.(2025)은 프로그래밍 및 앰비언트 인터페이스 환경에 걸쳐 능동성 설계 공간을 확장한다. Pasternak et al.(2025)과 Sun et al.(2025)은 그것을 날카롭게 하기 위한 벤치마크와 훈련 체제를 도입하고, Deng et al.(2025)은 더 넓은 문헌을 개관한다.

무엇에. 비전-언어-행동(VLA) 연구는 하네스를 텍스트 도구 반환값 너머로 확장한다. Brohan et al.(2023)과 Black et al.(2024)은 물리적 행위를 실행하는 VLA 정책을 훈련하고, Ahn et al.(2022)은 계획을 로봇 어포던스에 근거시킨다. Figure AI(2025)와 Bjorck et al.(2025) 같은 산업 시스템은 유사한 아이디어를 휴머노이드 제어로 밀어붙인다. 이 시스템들은 표 1의 되돌림 가능성 가중 위험 원칙을, 그 원칙이 명명하되 비텍스트 행위에 대해서는 정량화하지 않은 비용 비대칭 하에서 마주한다.

누구와. 역할 분화된 다중 에이전트 시스템(Hong et al.(2023), Li et al.(2023), Chen et al.(2023), Qian et al.(2024))은 별개의 책임을 갖는 에이전트를 조합한다. 다중 에이전트 토론(Du et al., 2024; Liang et al., 2024)과 그래프 구조 워크플로(Zhuge et al., 2024)는 8절의 부모/서브에이전트 패턴에 대한 대안을 탐색한다. Guo et al.(2024)이 이 공간을 개관한다.

단일 하네스 아키텍처가 이 네 확장을 모두 아우를 수 있는지, 아니면 Rajasekaran(2026)이 기술하는 "하네스 조합"이 특화된 스택들로 파편화될지는 열린 설계 질문이다. 언제 확장은 표 6의 능력 대 적응성 긴장을 직접 이어간다. 누구와 확장은 부분적으로 능력 대 신뢰성에 대응되지만 표 6 자체가 다루지 않는 에이전트 간 일관성 우려를 제기한다. 어디서와 무엇에 확장은 본 논문의 현재 서브시스템 경계가 다루지 않는 추가 질문을 제기한다. 하네스 구성요소가 호스팅 서비스가 될 때 어떤 거버넌스 의무가 부착되는지(13.5절), 그리고 되돌림 가능성 가중 위험(표 1)이 텍스트가 아닌 물리적 효과로 어떻게 확장되는지다. 이 확장들이 어느 한 축 안에서가 아니라 축들에 걸쳐 어떻게 조합되는지는 본 논문의 단일 서브시스템 분석으로 해결할 수 있는 것이 아니다.

13.4지평 확장: 세션에서 과학 프로그램으로#

2.1절은 신뢰할 수 있는 실행을 "단일 턴 정확성과 장기 지평 신뢰성" 양쪽에 걸치는 것으로 정의한다. 자율 작업이 단일 세션을 넘어 확장될 때 3절, 4절, 7절~9절에서 문서화한 아키텍처가 장기 지평 신뢰성을 계속 뒷받침할 수 있는지는 열린 질문이다. 그 주된 단위는 턴, 세션, 서브에이전트다. 성장하는 문헌이 이 영역을 겨냥한다. Lu et al.(2024)은 초안 원고를 생산하는 종단 간 자율 연구 파이프라인을 제시한다. Beel et al.(2025)은 그 파이프라인에 대한 독립적인 SIGIR Forum 평가를 제공하여, "자율 연구"가 현재 무엇을 내놓고 어디서 미치지 못하는지를 특징짓는다. Gottweis et al.(2025)은 턴이 아니라 며칠에 걸쳐 실행되는 다중 에이전트 가설 생성 시스템을 개발하고, Novikov et al.(2025)은 이전에는 인간 전문가가 몇 주를 들이던 시간 규모에서 알고리즘 발견을 추구한다. Kwa et al.의 METR 연구는 프론티어 에이전트가 고정된 신뢰도로 성공하는 과제 지속 시간을 측정하여 이 확장 질문에 실증적 틀을 제공한다.

Quantitative Goal Persistence 벤치마크는 더 좁은 실패 모드를 지목한다. 에이전트가 합리적인 국소 도구 호출을 하면서도 검증자가 충분한 유효 작업 단위를 확인하기 전에 멈출 수 있다는 것이다(Cai et al., 2026). 장기 지평 코딩 에이전트에게 진척은 유창한 최종 메시지만이 아니라 외부적인 완료(done) 개념을 필요로 한다.

본 논문의 분석에 견주면, 장기 지평 배포는 7절의 컨텍스트 관리 파이프라인, 8절의 마지막 어시스턴트 텍스트 반환 정책, 9절의 추가 전용 지속성이 세션들이 다중 세션 프로그램으로 조합될 때에도 여전히 충분한지를 시험한다. 12.4절은 이미 이를 소스 수준 분석이 해소할 수 없는 "직접 측정 가능한 실증적 질문"으로 규정한다. 지평 확장은 그 질문을 주 단위 규모에서 다시 진술한다. 하네스 계층만으로 그 격차를 메울 수 있는지, 세션 간 메모리 기질(13.2절)이 필요한지, 아니면 지평 규모의 작업이 세션·서브에이전트·메모리를 넘어서는 조율 원시 요소를 요구하는지는 본 논문의 세션 범위 분석이 결론지을 수 있는 바가 아니다.

Tier A 여기서 분석한 v2.1.88 스냅샷 이후의 한 발전이 이 질문을 구체화한다. Claude Code v2.1.154는 동적 워크플로(dynamic workflows)를 도입했는데, 여기서 모델은 백그라운드 런타임이 실행하는 JavaScript 오케스트레이션 스크립트를 작성하여 다수의 서브에이전트로 팬아웃하고(실행당 최대 1,000개로 제한), 중간 결과는 모델의 컨텍스트 윈도우를 거치는 대신 스크립트 변수 안에 바깥에 존재한다(Anthropic, 2026i). Claude Opus 4.8(Anthropic, 2026h)과 함께 출시된 이것은 정확히 여기서 분석한 세션·서브에이전트·메모리 단위를 넘어서는 조율 원시 요소다. 그것은 오케스트레이션 로직 자체를 대화 바깥으로 옮겨, 희소 자원으로서의 컨텍스트와 격리된 서브에이전트 경계 원칙(표 1)을 개별 서브에이전트에서 오케스트레이션 계층으로 확장한다. 코드로서의 오케스트레이션(orchestration-as-code)이 지배적인 장기 지평 원시 요소가 될지, 그리고 그 토큰 비용과 줄어든 실행 중 인간 감독이 그 신뢰성 이득과 어떻게 견주어지는지는 여기서의 세션 범위 분석이 해결할 수 없는 열린 질문이다.

13.5대규모 거버넌스와 감독#

부상하는 AI 규제는 2.1절에서 문서화한 Anthropic, 운영자, 사용자의 권한 위계를 구현하는 아키텍처에 외부 제약을 더한다. 그 외부 제약 아래에서 코딩 에이전트 아키텍처가 어떤 로깅, 투명성, 인간 감독 어포던스를 노출해야 하는지는 열린 설계 질문으로 남는다. 유럽 집행위원회의 GPAI Code of Practice(European Commission, 2025a)와 이행 지침(European Commission, 2025b)은 범용 AI 거버넌스가 문서화, 위험 관리, 투명성, 감독에 대한 더 명시적인 기대로 나아가고 있음을 예시한다. MIT AI Agent Index(Staufer et al., 2026)와 International AI Safety Report(Bengio et al., 2026)는 12.6절에서 이미 인용했으며, 이 제약의 공개 및 감독 측면을 동기 짓는다. Bartz 대 Anthropic 판결(bar, 2025)은 훈련 데이터 조달에 대한 입력 측 제약을 더하는데, 이는 별도의 사건들이 다루는 AI 생성 코드에 관한 출력 측 저작권 질문과 구별된다. AI 거버넌스 프레임워크에 관한 OECD 보고서(OECD, 2025)와 에이전트 제공자의 준수 의무에 대한 Nannini et al.(2026)의 초기 분석은 구체적 사항을 규정하지 않으면서 규제 대상 인터페이스가 어떤 모습일 수 있는지를 스케치한다.

Tier A 규제는 아키텍처가 무엇을 공개해야 하는지뿐 아니라 모델의 가용성에도 작용할 수 있다. 2026년 6월 미국 수출 통제 명령이 외국 국적자의 Anthropic Fable 5 및 Mythos 5 모델 접근을 금지했고, 출시 후 며칠 내에 Anthropic은 전 세계 모든 사용자에 대해 두 모델을 비활성화했다(Anthropic, 2026d). 이런 종류의 정부 정책은 그러한 모델이 배포된 상태로 남을지 여부를 직접 결정할 수 있다.

에이전틱 안전 벤치마크도 안전의 대상을 텍스트에서 환경 상태로 옮긴다. Boiling the Frog는 다중 턴 워크스페이스 편집이 점진적 공격 하에서 안전하지 않게 되는지를 평가한다(Bisconti et al., 2026). 이는 코딩 에이전트에 중요한데, 위험한 대상이 최종 답변 텍스트가 아니라 수정된 저장소일 수 있기 때문이다.

5절에서 분석한 권한 파이프라인에 견주어 읽으면, 현 아키텍처의 두 속성이 이 제약 아래 열려 있다. 첫째, 본 논문이 문서화한 거부 우선 평가는 세션 트랜스크립트(9절)를 통해 내부적으로 감사 가능하지만, GPAI Code of Practice(European Commission, 2025a) 같은 부상하는 프레임워크가 상정하는 형태로 외부적으로 감사 가능하지는 아직 않다. 둘째, 본 논문이 결정론적 가드레일과 짝짓는 규칙보다 가치 원칙이 준수 검토가 요구할 수 있는 종류의 명시적 규칙 표명을 허용하는지는 또 다른 열린 질문이다. 두 속성 모두 모델이 아니라 하네스 안에 놓이며, 그곳이 미래 아키텍처가 새로운 인터페이스를 노출해야 할 수 있는 지점이다.

13.6장기적 개발자 역량#

2.4절은 장기적 개발자 역량을 동등한 설계 가치가 아니라 가로지르는 질문으로 도입한다. 12.2절과 12.4절은 인식된 생산성 대 측정된 생산성, 이해도 손실, 복잡도 누적, 기술 부채 지속, 신경 연결성 지속, 초기 경력 채용 감소를 포함한 외부 근거로 이 질문을 확장한다. 실무자들도 같은 말을 한다. 에이전트 주도 코딩으로의 자신의 이동을 성찰하며 Karpathy(2026)는 "당신은 사고를 외주화할 수는 있어도 이해를 외주화할 수는 없다"고 경고한다. 이어 14절은 방향을 바꾼다: "미래 시스템은 그 지속가능성 격차를 하류의 평가 지표가 아니라 일급 설계 문제로 다룰 수 있을 것이다." 그 전환이 가능한지, 그리고 일급 취급이 어떤 아키텍처적 메커니즘을 요구할지가 이 절이 기록하는 마지막 열린 질문이다.

이는 과정 감독(process supervision)과도 연결된다. 인간-LLM 협업 계획 연구는 사용자가 결과 수준 검토만이 아니라 과정 수준 통제를 필요로 한다고 주장하며, 조종(steering)을 모드, 범위, 편집 수준으로 조직한다(He et al., 2026). 코딩 에이전트에 대해 이에 상응하는 질문은, 작업이 아직 펼쳐지는 동안 사용자가 무엇을 검사하고 바꿀 수 있는가다.

두 개의 하위 질문이 측정 격차와 설계 격차를 분리한다. 첫째, 이 질문을 동기 짓는 실증적 주장들이 세션 세밀도에서 측정 가능한가. 기존 인용들은 세션에서 수개월 규모에 걸쳐 작동하지만(Becker et al.(2025)의 개발자 16명 RCT, Shen and Tamkin(2026)의 이해도 테스트 비교, Kosmyna et al.(2025)의 EEG 연구, He et al.(2025)의 807개 저장소 인과 분석, Liu et al.(2026)의 304,000 커밋 감사, Rak(2025)의 채용 시계열), 3절, 4절, 7절에서 문서화한 하네스는 이해도나 관례 표류에 대한 세션별 신호를 전혀 노출하지 않는다. 프로그래머 상호작용 양식(Barke et al., 2023)과 AI로 유발된 코드 보안 퇴행(Perry et al., 2023)에 관한 관련 연구가 세션 세밀도 측정을 스케치하며, Aiersilan(2026)은 세션 수준 인지 오프로딩 탐침을 위한 프로토콜을 제안한다. 둘째, 그러한 측정이 존재하게 되었을 때 아키텍처가 그에 반응할 수 있는가(생성자-평가자 분리(Rajasekaran, 2026)를 인간 루프에 적용한 유사물, 이해 보존적 표면, 또는 아직 명명되지 않은 메커니즘)가 14절이 제기하는 설계 격차 질문이다. 본 논문은 어느 메커니즘 부류가 적절한지에 대해 입장을 취하지 않는다. 또한 여기서 문서화한 하네스가 IDE나 조직이나 인간 개발 루프가 아니라 그 행동의 올바른 위치인지도 결론짓지 않는다. 11절에서 개관한 관련 연구와 14절의 지속가능성 전환이 본 논문이 이 질문을 남겨 두는 지점을 표시한다.

14결론#

본 논문은 프로덕션 코딩 에이전트가 되풀이되는 설계 질문 집합에 대한 답으로 이해될 수 있음을 보인다. 추론이 하네스에 대해 어디에 위치하는가, 실행·안전·확장성·컨텍스트·위임·지속성이 어떻게 조직되는가, 그리고 그 선택들이 어떤 트레이드오프를 인코딩하는가. Claude Code는 그 공간 안에서 뚜렷한 설계 지점을 차지한다. 그것은 모델에 폭넓은 국소적 자율성을 부여하는 한편, 권한 부여, 도구 라우팅, 컨텍스트 압축, 확장성, 세션 복구를 위한 조밀한 결정론적 하네스로 그것을 둘러싼다. 2절에서 식별한 다섯 가치와 열세 설계 원칙을 통해 읽으면, 이 선택들은 임시방편적이 아니라 정합적이다. 시스템은 일관되게 인간의 결정 권한, 안전, 신뢰할 수 있는 실행, 능력 증폭, 맥락 적응성을 우선한다.

OpenClaw 및 Hermes Agent 비교는 동일한 설계 질문이 서로 다른 에이전트 시스템에서 되풀이되지만 서로 다른 답을 낳음을 보여준다. Claude Code가 CLI 하네스 안에서 행위 단위 안전 분류와 점진적 컨텍스트 압축에 투자하는 반면, OpenClaw는 다채널 게이트웨이 안에서 경계 수준 접근 통제와 구조화된 장기 메모리에 투자하고, Hermes Agent는 하나의 프로세스에서 교체 가능한 메모리 및 모델 백엔드와 함께 행위 단위 승인을 여러 표면에 걸쳐 렌더링한다. 세 시스템은 여러 위치에서 ACP를 통해 조합된다. OpenClaw는 ACP를 통해 Claude Code를 외부 하네스로 호스팅할 수 있고, Hermes Agent는 호스트/게스트 분할의 양쪽에 위치한다. 따라서 에이전트 제작자에게 가장 중대한 열린 질문은 어떻게 더 많은 자율성을 더할 것인가가 아니라, 어떻게 시간이 지나도 인간의 역량을 보존할 것인가다. 2.4절에서 도입한 장기 역량 질문, 12절의 분석, 13절에서 개관한 열린 질문들을 종합하면, 이 아키텍처가 장기적인 인간의 이해, 코드베이스 일관성, 개발자 파이프라인을 명시적으로 보존하는 메커니즘을 제한적으로만 제공함을 보여준다. 미래 시스템은 그 지속가능성 격차를 하류의 평가 지표가 아니라 일급 설계 문제로 다룰 수 있을 것이다.

부록#

증거 기반과 방법론#

이 부록은 본 연구의 증거 출처, 분석 절차, 한계를 기록한다.

증거 기반과 증거 등급#

본 논문의 주장은 세 가지 증거 등급에 근거한다:

• Tier A(제품 문서화됨): 공식 Anthropic 문서와 엔지니어링 발행물에서 도출한 주장. 제품 의도를 확립하지만 내부 구현을 반영하지 않을 수 있다.
• Tier B(코드 검증됨): 추출된 TypeScript 코드베이스(v2.1.88, 공개적으로 이용 가능한 npm 패키지 추출에서 얻음)의 특정 파일과 함수를 인용하는 주장. 가장 강한 증거 등급이다.
• Tier C(재구성됨): 커뮤니티 분석, OpenClaw 또는 Hermes Agent 구조 비교, 또는 코드 패턴으로부터의 추론에서 도출한 주장. 유보적 표현과 함께 진술된다.

소스 코퍼스는 약 1,884개 파일, 대략 512K 줄의 TypeScript로 구성된다. OpenClaw와 Hermes Agent는 실측 기준이 아니라 비교 참조점으로 사용된다.

설계 공간 분석 절차#

설계 질문은 각 서브시스템에서 다른 프로덕션 에이전트에 대안 설계가 존재하는 되풀이 선택 지점을 조사하여 식별했다. 각 질문에 대한 Claude Code의 답은 구체적인 소스 파일과 함수 구현을 통해 추적했다(Tier B 증거). 5가치 프레임워크(인간의 결정 권한, 안전·보안·프라이버시, 신뢰할 수 있는 실행, 능력 증폭, 맥락 적응성)는 공식 문서와 제작자 진술에서 식별했고Tier A, 이어 열세 설계 원칙을 거쳐 아키텍처 결정으로 추적했다. 장기 역량 보존은 설계 가치가 아니라 가로지르는 질문으로 별도 취급했는데, 이는 그것이 아키텍처나 Anthropic이 밝힌 가치에서 설계 동인으로 두드러지게 반영되어 있지 않기 때문이다(2.4절). 토큰 경제학은 다섯 가치 전부를 동시에 구속하는 가로지르는 제약으로 기능하며, 개별 서브시스템 선택이 공유 자원 압력 하에서 어떻게 상호작용하는지를 드러낸다.

한계#

• 정적 스냅샷. 분석은 하나의 버전(v2.1.88)을 반영한다. 기능 플래그(예: TRANSCRIPT_CLASSIFIER, CONTEXT_COLLAPSE)는 빌드 시점 가변성을 만든다. 서로 다른 빌드 타깃이 기능적으로 다른 애플리케이션을 산출할 수 있다.
• 역공학 인식론. 소스 코드는 구현된 구조, 제어 흐름, 의존성, 기능 게이트를 드러낸다. 그것은 설계 의도, 프로덕션에서 활성화된 플래그, 런타임 보급률, 출시되지 않은 동작을 확인해 줄 수 없다.
• 단일 시스템 분석. 발견은 Claude Code의 설계 공간을 기술하는 것이지 코딩 에이전트의 설계 공간 전체를 기술하는 것이 아니다. 일반화는 제한된다.
• 비교 시스템 스냅샷. OpenClaw와 Hermes Agent 분석은 각각 특정 개발 상태를 반영하며 현재 능력을 대표하지 않을 수 있다.

패키지 구조#

이 부분은 주 TypeScript 패키지를 런타임 책임에 대응시킨다.

디렉터리-책임 대응 지도#

패키지(그림 9)는 src/ 디렉터리를 중심으로 조직된다. 표 7은 주요 서브시스템을 이루는 핵심 파일을 나열한다.

표 7 대략적 크기와 런타임 책임에 따른 주요 파일.

표 8 조건부 도구 가용성 범주.

tools/ 디렉터리는 대응하는 스키마, 설명, 권한 요구사항, 실행 로직과 함께 도구를 구현하는 약 42개의 하위 디렉터리를 담고 있다. commands/ 디렉터리는 약 86개의 슬래시 커맨드 하위 디렉터리를 담고 있다.

핵심 서비스 디렉터리에는 services/tools/(StreamingToolExecutor, toolOrchestration, toolExecution), services/compact/(압축 엔진), services/mcp/(MCP 클라이언트 및 설정)가 포함된다. 권한 인프라는 utils/permissions/(규칙 평가, 분류기), hooks/useCanUseTool.tsx(권한 핸들러), types/permissions.ts(모드 정의), types/hooks.ts(이벤트 스키마)에 걸쳐 있다.

구조적 특이점 하나: query.ts(파일)와 query/(디렉터리)가 공존한다. 파일은 주 질의 루프를 담고, 디렉터리는 루프 설정 및 컨텍스트 조립을 위한 헬퍼 모듈을 수용한다.

조건부 도구 가용성#

getAllBaseTools() 함수(tools.ts)는 모드, 빌드, 환경, 기능 플래그에 따라 서로 다른 도구 집합을 구성한다(표 8). 모델은 simple 모드에서는 3개 도구(Bash, Read, Edit)만큼 적게 볼 수도 있고, 모든 기능이 활성화된 완전한 내부 빌드에서는 최대 54개 도구(무조건 19개 + 조건부 35개)를 볼 수도 있다.

교차 파일 의존성#

임포트 그래프는 다음 의존 구조를 포함한다. QueryEngine.ts는 턴 실행을 query.ts에 위임한다. query.ts는 services/tools/(StreamingToolExecutor, runTools)와 services/compact/(autoCompact, buildPostCompactMessages)에서 임포트한다. QueryEngine.ts는 메모리 및 프롬프트 조립을 위해 memdir/에서 임포트한다. 코드는 순환 임포트를 명시적으로 피한다. types/permissions.ts는 임포트 순환을 끊기 위해 추출되었고, context.ts의 setCachedClaudeMdContent()는 permissions/filesystem 경로를 통한 순환을 피한다.

커뮤니티 재구현물#

Claude Code TypeScript 소스가 공개적으로 읽을 수 있게 된 후, 여러 커뮤니티 프로젝트가 독립적인 재구현물을 발행했다. 이 부록은 몇 가지 대표적 예를 나열한다.

표 9 Claude Code의 대표적 커뮤니티 재구현물(2026년 기준).

표 9는 2026년 기준 공개 생태계에서 식별된 다섯 개의 재구현물을 나열한다. 각 프로젝트는 수동적인 소스 덤프나 주석 작업이 아니라 작동하는 CLI 에이전트다. 이 집합은 네 가지 런타임 타깃(Python, Rust, Bun을 사용한 TypeScript, npm을 통한 JavaScript)과 세 가지 재구축 방법론(관찰된 동작으로부터의 독립적 재작성, 재구성된 빌드를 갖는 TypeScript 스냅샷으로부터의 포크, 자동화된 역컴파일 파이프라인)에 걸쳐 있다.

동반 설계 공간 자료#

프로젝트 저장소는 새로운 에이전트 시스템 발전이 나타나는 대로 추적하는 동반 노트를 유지한다. 이것들은 Claude Code 구현에 대한 증거가 아니며, 그 증거는 위의 증거 등급에 근거한 채로 남는다(VILA Lab, 2026).

그림 9 런타임 책임에 대응된 추출 패키지 구조. 왼쪽 열: TypeScript 소스 디렉터리와 핵심 파일. 오른쪽 열: 추론된 런타임 역할. 이 부록은 공식 Anthropic 문서가 아니라 재구성된 분석(Tier C 증거)을 나타낸다.

진입 및 시작 — main.tsx(애플리케이션 진입점, 모드 디스패치, 시그널 핸들러), replLauncher.tsx(대화형 REPL 구성), entrypoints/(SDK 및 헤드리스 시작), cli/(CLI 인자 핸들러: agents, auth, mcp, plugins) UI 계층 — components/, screens/(ink 프레임워크 터미널 UI 구성 블록, 화면 구성), outputStyles/(시스템 프롬프트 출력 스타일 로직) 핵심 루프 — query.ts(에이전틱 질의 루프, 5개 셰이퍼), query/(루프 설정 헬퍼), QueryEngine.ts(헤드리스/SDK 대화 래퍼), context.ts(컨텍스트 조립) 도구 및 커맨드 — Tool.ts(도구 인터페이스와 타입), tools/(42개 구체적 도구 구현), services/tools/(도구 실행 및 오케스트레이션), commands/(86개 슬래시 커맨드 구현) 안전 및 권한 — utils/permissions/(거부 우선 규칙 평가, yoloClassifier), types/permissions.ts(7개 권한 모드 정의), hooks/useCanUseTool.tsx(권한 핸들러), components/permissions/(권한 대화상자 UI) 확장성 — plugins/(플러그인 로더, 매니페스트 검증, 구성요소 등록), skills/(스킬 로더, SKILL.md 프론트매터 파싱), utils/hooks.ts(훅 레지스트리, 27개 이벤트 유형에 걸친 생명주기 디스패치), types/hooks.ts + schemas/hooks.ts(Zod 훅 스키마 및 타입) 컨텍스트 및 메모리 — services/compact/(5계층 압축), memdir/(자동 메모리 로딩, 항목 상한 집행), utils/claudemd.ts(CLAUDE.md 4단계 계층, @include 처리), state/(런타임 애플리케이션 상태) 지속성 — history.ts(전역 프롬프트 이력), utils/sessionStorage.ts(세션별 JSONL 트랜스크립트, 사이드체인, 파일 이력) 서비스 및 통합 — services/(MCP 클라이언트 8개 이상 전송, API 어댑터, LSP, 분석), remote/(원격 실행 백엔드 지원), coordinator/(다중 에이전트 조율 모드, 워커 관리) 추가 인프라 — bootstrap/, bridge/, constants/, server/(앱 초기화, WebSocket 통신, API 설정), ink/, keybindings/, vim/, buddy/ 등(터미널 렌더링, 입력 처리, 선택적 기능)

참고문헌#

원문의 참고문헌 목록(약 8페이지, 250개 이상 항목)은 서지 정보이므로 번역하지 않았다. 전체 목록은 원문 PDF의 42–50페이지를 참조하라: https://arxiv.org/abs/2604.14228