에이전트 시스템 설계 캔버스 — Claude Code 유출이 증명한 12가지 프로덕션 패턴

Claude Code 소스 유출(512K줄 TS)에서 확인된 에이전트 시스템 설계의 6-Layer 캔버스와 8+4 핵심 패턴. 250K/일 API 낭비를 3줄로 해결한 Circuit Breaker부터, 23단계 bash AST 보안까지.

2026년 3월 31일, Anthropic의 npm 패키지에 소스맵이 포함되면서 Claude Code의 전체 소스(약 512,000줄 TypeScript, 1,884개 파일)가 공개되었습니다. 패키징 실수였지만, 그 안에는 프로덕션 에이전트 시스템이 실제로 어떻게 설계되는가에 대한 답이 들어 있었습니다.

이 글에서는 유출 분석을 기반으로, 에이전트 시스템 설계를 6개 레이어로 분해한 프레임워크와 12가지 핵심 패턴을 정리합니다. 이론이 아니라, 수억 건의 실제 요청을 처리하는 시스템에서 검증된 패턴입니다.

왜 “에이전트 설계”가 별도 영역인가

차원	웹 앱	에이전트 시스템
실행 흐름	요청 → 응답 (단일)	요청 → AI 판단 → 도구 실행 → 재판단 → … (루프)
상태 복잡도	DB + 세션	컨텍스트 윈도우 + 메모리 + 도구 상태 + 서브에이전트
안전	입력 검증	입력 + AI 출력 + 도구 실행 검증
비용 구조	컴퓨팅	컴퓨팅 + 토큰 비용 (실패 시 기하급수적 증가)

Claude Code 내부에서 이 차이를 어떻게 다루는지가 이 글의 주제입니다.

6-Layer 설계 캔버스

에이전트 시스템의 6개 레이어입니다. 각 레이어에 Claude Code의 실제 구현을 대응시켜 프로덕션 수준의 기준선을 제시합니다.

graph TB
    subgraph "Agent System Design Canvas"
        direction TB
        T["Tool Layer\n52개 도구, Zod 검증, 크기 제한"]
        S["Safety Layer\n5단계 권한, 23단계 AST 검사"]
        M["Memory Layer\nAuto-Compact, 4타입 영구 메모리"]
        E["Execution Layer\n병렬/순차 분리, 7가지 모드"]
        R["Resilience Layer\nWithhold and Recover, Circuit Breaker"]
        X["Extensibility Layer\nMCP 5 Transport, 44 Feature Flags"]
    end
    T --- S
    S --- M
    M --- E
    E --- R
    R --- X

Layer 1: Tool (도구)

에이전트가 외부 세계와 상호작용하는 모든 수단입니다.

Claude Code의 규모: 52개 빌트인 도구 (41개 활성 + 11개 Feature-gated)

가장 인상적인 것은 도구 등록 파이프라인입니다. getAllBaseTools() → Feature gate 필터 → Deny rules 필터 → Mode 필터 → 이름순 정렬 → assembleToolPool(). 여기서 이름순 정렬이 핵심인데, 도구 순서가 바뀌면 API 프롬프트 캐싱이 깨져서 비용이 급증합니다.

모든 도구는 공통 인터페이스를 준수합니다:

속성	역할
`inputSchema` (Zod)	LLM이 생성한 파라미터를 스키마 검증 — hallucination 방어
`isConcurrencySafe()`	병렬 실행 가능 여부 — Read는 true, Edit는 false
`isReadOnly()`	읽기 전용 여부 — 권한 모드에서 활용
`maxResultSizeChars`	결과 크기 상한 — 초과 시 디스크 저장 후 참조만 반환

이 인터페이스 덕분에 52개 도구가 동일한 10단계 실행 파이프라인을 거칩니다: 이름 조회 → 중단 확인 → 입력 검증 → PreToolUse 훅 → 권한 확인 → 실행 → 결과 매핑 → 크기 검사 → PostToolUse 훅 → 텔레메트리.

Layer 2: Safety (안전 & 권한)

에이전트 시스템에서 가장 과소평가되는 레이어입니다.

Claude Code의 BashTool 보안은 단순한 문자열 필터링이 아닙니다. Tree-sitter AST 파서로 셸 명령을 구문 트리로 분해한 뒤 23단계 검사를 수행합니다. 이 보안 모듈만 888KB, 18개 파일입니다.

검사 대상은 명령 치환($()), 변수 확장(${}), 리디렉션, 파이프라인은 물론이고, Zsh 전용 우회 벡터(=curl 형태)와 유니코드 인젝션(제로폭 문자, 널바이트, 호모글리프)까지 포함합니다.

핵심 설계 원칙: fail-closed. 파싱 자체가 실패하면 실행을 허용하는 게 아니라 차단합니다. 미지의 공격 벡터에 대한 기본 방어입니다.

권한 시스템은 5단계 파이프라인입니다:

flowchart LR
    A["validateInput\nZod 스키마"] --> B["checkPermissions\n도구 자체 권한"]
    B --> C["PreToolUse 훅\n외부 차단 가능"]
    C --> D["규칙 매칭\nallow/deny/ask"]
    D --> E["권한 모드\nDefault/Auto/Plan/Bypass"]

규칙 우선순위는 Local > Project > User > Flags > Policy. 가장 가까운 설정이 이기는 구조입니다.

Layer 3: Memory (메모리 & 컨텍스트)

에이전트 시스템의 숨은 비용 센터입니다. Claude Code의 실제 데이터가 이를 증명합니다.

Auto-Compact Circuit Breaker 도입 전:

1,279개 세션에서 50회 이상 연속 압축 실패
최악의 경우 단일 세션에서 3,272회 연속 실패
하루 약 250,000건의 API 호출이 실패 루프로 낭비

이 문제의 수정은 단 3줄: MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3.

압축 전략은 단순 truncation이 아닙니다:

이미지 제거 (토큰 소모가 큰 콘텐츠 우선)
API 라운드별 그룹화
포크된 서브에이전트로 요약 생성 (메인 컨텍스트와 독립)
이전 메시지를 요약으로 대체
상위 5개 참조 파일 복원 (50K 토큰 예산)
스킬 재주입 (25K 예산, 스킬당 5K)

요약 후에도 가장 많이 참조된 파일과 활성 스킬을 복원한다는 점이 핵심입니다. 맥락을 버리되, 핵심은 보존합니다.

Layer 4: Execution (실행 모델)

Claude Code는 7가지 실행 모드(REPL, Headless, Coordinator, Bridge, Kairos, Daemon, Viewer)를 지원하지만, 핵심 query() 루프는 하나입니다. 모드 차이는 Dependency Injection으로 해결합니다.

도구 실행에서 가장 영리한 부분은 동시성 모델입니다.

안전한 도구(Read, Grep, Glob)는 최대 10개까지 병렬 실행합니다. 위험한 도구(Edit, Bash, Write)가 나오면 새 배치를 시작하고 단독 순차 실행합니다.

[Read, Grep, Glob] -> 병렬 (1 batch, 최대 10)
[Edit]             -> 순차 (새 batch)
[Read, Read]       -> 병렬 (새 batch)
[Bash]             -> 순차 (새 batch)

그리고 StreamingToolExecutor가 API 스트리밍과 도구 실행을 겹칩니다(overlap). 응답이 아직 스트리밍 중인데도, 이미 완성된 tool_use 블록이 있으면 즉시 실행을 시작합니다.

Layer 5: Resilience (안정성)

Withhold & Recover 패턴의 실제 동작:

에러	1차	2차	3차	최종
413 Prompt Too Long	Collapse drain	Reactive compact	—	사용자 표시
Max Output Tokens	8K에서 64K 에스컬레이션	재시도 (최대 3회)	—	잘림 표시
429 Rate Limit	retry-after 확인 후 대기	fast mode off	표준 모델 전환	—
529 Overloaded	재시도	재시도	대체 모델 전환	비포그라운드 포기

특히 Persistent 모드(Anthropic 내부 무인 세션)에서는 최대 6시간까지 지수 백오프로 재시도합니다.

매 API 호출 전에는 트랜스크립트를 디스크에 저장합니다. 프로세스가 죽어도 /resume 한 번으로 마지막 지점부터 재개 가능합니다.

Layer 6: Extensibility (확장성)

Claude Code의 확장 구조는 3계층입니다:

계층	단위	예시
Tool	단일 도구	FileRead, Bash, WebFetch
Skill	마크다운 기반 워크플로우	/commit, /review, /security-review
Plugin	스킬 + 훅 + MCP 묶음	GitHub 통합 = PR 리뷰 스킬 + autofix + GitHub MCP

MCP(Model Context Protocol)는 5가지 Transport(Stdio, SSE/HTTP, WebSocket, SDK, Claude.ai)를 지원하여 사실상 어떤 외부 시스템과도 연결 가능합니다.

44개 Feature Flag 중 20개가 외부 비활성이라는 사실은, 로드맵의 거의 절반이 아직 실험 단계라는 뜻입니다.

8대 핵심 설계 패턴

6개 레이어를 관통하는 설계 패턴 8종입니다.

#	패턴	핵심	CC 근거
1	Generator Streaming	query() yield + overlap 도구 실행	SSE 토큰 스트리밍, Int32Array 이중 버퍼링(50x 성능)
2	Feature Gate Dead Code Removal	빌드 시 비활성 코드 물리적 제거	44 flags, bun:bundle Tree-shaking
3	Memoized Context	세션 불변 컨텍스트 1회 계산+캐싱	14가지 캐시 파손 벡터 추적, 135ms 중 65ms 절약
4	Withhold & Recover	복구 가능 에러 자동 치유 후 표시	413에서 compact, 8K에서 64K 에스컬레이션
5	Lazy Import	호출 시점에만 모듈 로드	800KB 빌드, 피처 게이트 조건부 import
6	Immutable State	DeepImmutable+Zustand로 상태 보호	AppState 전역 불변, 자동 부작용 체인
7	Interruption Resilience	매 호출 전 디스크 저장, /resume 재개	SIGTERM에서 30s grace에서 SIGKILL
8	Dependency Injection	query(deps)로 모드/테스트 전환	7가지 모드가 동일 코어 공유

Generator Streaming이 체감 속도를 바꾸는 이유

단순히 “토큰을 실시간으로 보여준다”가 아닙니다. StreamingToolExecutor가 응답 스트리밍과 도구 실행을 겹칩니다. AI가 아직 텍스트를 생성하고 있는데, 이미 완성된 tool_use 블록의 도구는 실행이 시작됩니다.

렌더링도 최적화되어 있습니다. 커스텀 React reconciler + Yoga(터미널 Flexbox) + 이중 버퍼링(변경된 셀만 갱신) + CharPool/StylePool 인턴 풀. Int32Array 기반 ASCII 버퍼로 50배 캐시 성능 향상을 달성했습니다.

Memoized Context가 비용을 줄이는 메커니즘

getSystemContext()(Git 상태)와 getUserContext()(CLAUDE.md)를 세션 1회만 계산합니다. 매 턴 시스템 프롬프트에 재주입하지만, 값이 동일하므로 API측 프롬프트 캐싱(1시간)의 적중률이 극대화됩니다.

이를 보호하기 위해 promptCacheBreakDetection.ts가 14가지 캐시 파손 벡터를 추적합니다.

Dependency Injection이 7가지 모드를 가능하게 하는 방법

query(messages, deps) — 이 시그니처 하나가 핵심입니다. REPL에서는 React UI 렌더러를, Headless에서는 NDJSON 출력을, Bridge에서는 원격 렌더러를 주입합니다. 코어 로직은 동일하고 deps만 다릅니다.

4가지 인프라 패턴

Tool Concurrency Model

flowchart LR
    subgraph "Batch 1 병렬"
        R1[Read] & G1[Grep] & G2[Glob]
    end
    subgraph "Batch 2 순차"
        E1[Edit]
    end
    subgraph "Batch 3 병렬"
        R2[Read] & R3[Read]
    end
    subgraph "Batch 4 순차"
        B1[Bash]
    end
    R1 & G1 & G2 --> E1 --> R2 & R3 --> B1

isConcurrencySafe()=true인 연속 도구를 배치로 묶어 최대 10개 병렬 실행. 위험 도구가 나오면 새 배치. 배치 내 한 도구가 실패하면 형제 실행도 중단합니다.

Auto-Compact Strategy

Threshold(context_window - 13,000) 초과 시 자동 발동. 서브에이전트 요약 + 참조 파일 복원 + Circuit Breaker(3회 실패 시 중지). 이 Circuit Breaker 3줄이 하루 250,000건의 API 낭비를 해결했습니다.

Permission Pipeline

5단계 검증(입력->도구->훅->규칙->모드) + 4가지 모드(Default/Auto/Plan/Bypass) + 계층적 우선순위(Local > Project > User > Flags > Policy). BashTool의 888KB AST 보안이 심층 방어를 담당합니다.

API Retry Strategy

에러마다 다른 전략: 429는 대기 또는 모델 폴백, 529는 3회 후 대체 모델, 401은 토큰 갱신. 비포그라운드 태스크는 529에서 즉시 포기(리소스 절약). Persistent 모드는 최대 6시간 백오프.

핵심 수치 모음

수치	맥락
512,000줄 / 1,884 파일	CC TypeScript 소스 규모
52개 (11 gated)	빌트인 도구
888KB / 23단계	Bash Security AST 검사
250,000건/일	Circuit Breaker 도입 전 낭비 API 호출
3줄	250K/일 낭비를 해결한 코드량
50K / 25K	압축 후 참조 파일 / 스킬 재주입 토큰 예산
10개	안전 도구 최대 병렬 수
14가지	프롬프트 캐시 파손 벡터
50배	Int32Array 버퍼 렌더링 성능 향상
44개 (20 비활성)	Feature Flag
6시간	Persistent 모드 최대 백오프

마무리: 설계의 3대 원칙

All design decisions follow three principles: safety (blocking dangerous operations), performance (streaming, parallel execution, caching), and extensibility (tools, skills, plugins, MCP).

이 세 원칙이 6개 레이어와 12가지 패턴 전체를 관통합니다. 에이전트 시스템을 설계할 때, 이 세 가지 중 하나라도 빠지면 프로덕션에서 문제가 됩니다.

Sources & Limitations

이 시리즈는 아래 공개 분석 자료를 종합하여 작성했으며, 유출된 소스 코드를 직접 포함하지 않습니다.

Source	URL	특징
ccunpacked.dev	ccunpacked.dev	시각적 아키텍처 가이드, 도구/커맨드 카탈로그
Wikidocs 분석서	wikidocs.net/338204	한국어 상세 기술 분석 (실행 흐름, 상태 관리, 렌더링)
PyTorch KR	discuss.pytorch.kr	GeekNews 기반 커뮤니티 분석 + HN 의견 종합
Claw Code	github.com/ultraworkers/claw-code	클린룸 재구현 (Rust/Python), PARITY.md 패리티 갭 분석

분석 시점: 2026-04-02. Anthropic은 유출 직후 DMCA로 8,100+ 포크를 차단하고 npm 배포를 중단했으므로, 일부 소스의 접근성이 변경되었을 수 있습니다. 또한 Feature Flag 뒤의 미공개 기능은 출시 전 변경되거나 폐기될 수 있습니다.