Claude Code의 아키텍처, 시각적 설명:

Claude Code의 아키텍처, 시각적 설명:

(이 게시물을 북마크하세요)

Claude Code는 단순히 Claude 모델을 호출하는 CLI (Command Line Interface) 그 이상입니다.

실제 시스템은 6개의 레이어(layer)로 구성되어 있으며, 모델은 루프 내부의 단 하나의 노드(node)일 뿐입니다.

아래 다이어그램은 모든 구성 요소를 설명합니다:

1. 입력 레이어 (Input layer)는 어떤 정보가 모델에 도달하기 전에 세션 관리 (session management), 권한 게이팅 (permission gating), 그리고 YAML 기반의 신뢰 계층 (trust tiers)을 처리합니다.

2. 지식 레이어 (Knowledge layer)는 기술 레지스트리 (skill registry), 컨텍스트 압축기 (context compressor), 태스크 그래프 (task graph), 그리고 교차 세션 메모리 저장소 (cross-session memory store)를 보유합니다. 이곳은 가중치 (weights) 외부에서 하네스 지능 (harness intelligence)이 거주하는 곳입니다.

컨텍스트 압축기 (context compressor)는 컨텍스트 윈도우 (context window)가 약 95% 용량에 도달했을 때 작동하는 5개 레이어의 캐스케이드 (cascade)입니다. 이는 ChatGPT가 하는 방식처럼 대화를 요약하지 않습니다. 대신, 파일 경로 (file paths), 코드 스니펫 (code snippets), 에러 히스토리 (error histories)에 대해 구조화된 추출 (structured extraction)을 수행하는 동시에 중복된 도구 출력 (tool outputs)을 가지치기 (pruning)합니다. 목표는 컨텍스트를 단순히 작게 만드는 것이 아니라, 사용 가능한 상태로 유지하는 것입니다.

3. 실행 레이어 (Execution layer)는 bash, read, write, grep, glob, revert와 같이 도구당 하나의 핸들러 (handler)를 가진 타입 지정 레지스트리 (typed registry)를 통해 도구 디스패치 (tool dispatch)를 실행합니다.

스트리밍 런타임 (streaming runtime)은 병렬 실행 (parallel execution)을 처리하며, 프롬프트 캐시 (prompt cache)는 원래 비용의 약 10%로 안정적인 접두사 (stable prefixes)를 재사용합니다.

4. 통합 레이어 (Integration layer)는 MCP 런타임을 외부 서버 (filesystem, git, custom)에 연결합니다. 도구들은 내부로 등록되며, 메모리 쓰기 (memory writes)는 세션 전반에 걸쳐 지속되는 마크다운 파일 (agent_memory.md)로 외부로 전달됩니다.

5. 멀티 에이전트 레이어 (Multi-agent layer)는 가장 과소평가된 부분이며, 대부분의 사람들이 가정하는 것과는 매우 다르게 작동합니다.

Claude Code는 두 가지 수준의 병렬성 (parallelism)을 지원합니다:

• 서브에이전트 (Subagents)는 사용자의 세션 내부에서 실행되는 경량 워커 (lightweight workers)입니다. 이들은 자신만의 컨텍스트 윈도우 (context window)를 가지며, 집중된 작업 (코드베이스 검색, 파일 트리 탐색 등)을 수행하고 결과를 부모 (parent)에게 반환합니다. 이들은 서로 대화할 수 없으며, 자신만의 서브에이전트를 생성할 수도 없습니다. 이는 엄격한 부모-자식 계층 구조 (parent-child hierarchy)입니다.

• 에이전트 팀 (Agent teams)은 한 단계 더 나아갑니다. 하나의 세션이 팀 리더 (team lead) 역할을 수행하며, 독립적인 팀원 (teammates)들을 생성합니다. 각 팀원은 자신만의 컨텍스트 윈도우 (context window)를 가진 완전한 Claude Code 인스턴스로 실행됩니다. 팀 리더는 작업을 하위 작업 (subtasks)으로 분할하고, 이를 할당하며, 진행 상황을 모니터링합니다.

조율은 두 가지 메커니즘을 통해 이루어집니다 → 공유된 작업 목록 (디스크 상의 JSON 파일)과 피어 투 피어 (peer-to-peer) 메시징을 위한 메일박스 (mailbox) 시스템입니다.

각 팀원은 git 워크트리 (worktree) 격리를 제공받습니다. 이는 동일한 저장소 히스토리를 공유하면서도 자신만의 브랜치를 가진 별도의 작업 디렉토리입니다.

이는 에이전트들이 파일 충돌 없이 코드베이스의 중첩된 부분에 내용을 작성할 수 있음을 의미합니다. 작업이 완료되면 변경 사항이 없는 워크트리는 자동으로 정리됩니다. 변경 사항이 있는 워크트리는 병합 (merging) 전 인간의 검토를 위해 유지됩니다.

6. 관찰 가능성 계층 (Observability layer)이 모든 것을 감쌉니다. 라이프사이클 훅 (lifecycle hooks)이 포함된 이벤트 버스 (event bus)는 모든 도구 호출 (tool calls)과 메시지를 기록하여, 에이전트의 행동과 결정에 대한 완전한 감사 추적 (audit trail)을 생성합니다.

백그라운드 실행기 (Background executors)는 데몬 스레드 (daemon threads)로 비차단 (non-blocking) 방식으로 실행되므로, 관찰 가능성이 메인 루프를 지연시키지 않습니다.

마지막으로, 마스터 에이전트 루프 (master agent loop)가 6개 계층 모두의 중심에 위치합니다. 이 루프는 컨텍스트를 조립하고, 모델을 호출하며, 도구 요청을 받고, 이를 실행하고, 결과를 다시 입력으로 피드백하며 이 과정을 반복합니다. 모든 반복 (iteration)은 하나의 턴 (turn)입니다.

한 턴 내에서 모델은 도구 호출 (tool call)을 요청할 수 있습니다. 해당 요청은 권한 시스템 (permission system)을 거쳐 실행되며, 그 출력은 다음 입력으로서 루프에 다시 피드백됩니다.

루프 자체는 의도적으로 싱글 스레드 (single-threaded)로 설계되었습니다. 모든 지능은 루프 로직이 아니라 루프를 둘러싼 계층들에 존재합니다. Anthropic은 모델이 추론하고 하네스 (harness)가 중재하기 때문에 이를 '멍청한 루프 (dumb loop)'라고 부릅니다.

이것이 Claude Code의 배후에 있는 아키텍처입니다.

Claude 하위 에이전트 (sub-agents)와 에이전트 팀 (agent teams)에 대해 더 깊이 알고 싶다면, 최근에 이들에 대해 작성한 글이 있습니다.

그 글은 Claude 하위 에이전트 (격리되어 실행 후 종료되는 작업자)와 에이전트 팀 (공유된 작업 목록을 가진 지속적이고 피어 간 통신이 가능한 인스턴스)의 차이점, 그리고 각각을 언제 사용해야 하는지를 설명합니다.

아래에서 확인해 보세요.