51만 줄의 코드가 보여주는 AI 에이전트의 현재와 미래
분석 대상: Claude Code 소스 스냅샷 (2026-03-31)
분석일: 2026-04-03
규모: 2,041개 파일, 512,664줄, 32MB
—
00장 들어가기 전에
00-1. 분석 배경
2026년 3월 31일, 보안 연구자 Chaofan Shou가 Claude Code의 npm 배포 패키지에 포함된 소스맵(.map) 파일을 통해 원본 TypeScript 소스가 공개적으로 접근 가능한 상태임을 발견했다. Anthropic의 R2 스토리지 버킷에 난독화되지 않은 소스가 참조되어 있었다. 본 보고서는 해당 스냅샷의 아키텍처를 분석한 기술 문서이다.
"소프트웨어 공급망 보안의 중요성을 보여주는 사례이다. 빌드 아티팩트(소스맵)가 프로덕션 배포에 포함되면, 소스코드 전체가 역추적 가능해진다. CI/CD 파이프라인에서 소스맵 제거를 반드시 검증해야 한다."
00-2. 분석 범위
총 파일 수는 2,041개이며, TypeScript 파일이 1,332개, TSX 파일이 552개, 기타가 157개다. 소스 코드는 총 512,664줄이고, 빈 줄과 주석을 제외하면 약 40만 줄로 추정된다. 전체 용량은 32MB이며 텍스트 파일만으로 구성되어 있다. 가장 큰 파일은 REPL.tsx로 896KB에 달하는 메인 대화 화면 전체이다. 빌드 시점 코드 제거를 위한 피처 플래그는 89개, AI가 실행하는 도구는 40종, 사용자 슬래시 명령은 101종이다.
00-3. Claude Code란?
Claude Code는 Anthropic이 개발한 CLI 기반 AI 코딩 에이전트이다. 터미널에서 자연어로 대화하며 파일 편집, 명령 실행, 코드 검색, 웹 검색, 멀티에이전트 병렬 작업을 수행한다. VSCode와 JetBrains IDE 연동, MCP(Model Context Protocol) 서버 지원, 플러그인 시스템을 갖춘 완전한 소프트웨어 플랫폼이다.
단순한 CLI 도구가 아닌 이유는 규모에서 드러난다. 51만 줄이라는 코드 규모는 Linux 커널의 초기 버전이나 중형 웹 프레임워크 전체에 맞먹는다. 이것은 AI가 코딩을 돕는 '도구'가 아니라, AI가 직접 소프트웨어를 개발하는 '플랫폼'으로 설계되었음을 의미한다.
"51만 줄 규모의 에이전트 시스템은 업계에서 공개된 것 중 가장 크다. 이는 AI 에이전트 개발이 단순한 프롬프트 엔지니어링이 아니라, 수백 명이 수년간 작업하는 정통 소프트웨어 엔지니어링임을 증명한다. 에이전트를 만드는 것과 에이전트 플랫폼을 만드는 것은 완전히 다른 차원의 문제이다."
—
01장 기술 스택과 설계 철학
01-1. 기술 스택
런타임은 Bun을 사용한다. Node.js 대비 3~5배 빠른 시작 속도, 내장 번들러, feature flag 지원이 선택 이유다. 언어는 TypeScript의 strict 모드로, 51만 줄 규모의 코드베이스에서 정적 타입으로 안정성을 확보했다.
터미널 UI에는 React와 Ink를 사용한다. 컴포넌트 기반 UI를 터미널에서 렌더링하는 선언적 패러다임이다. CLI 파싱에는 Commander.js의 extra-typings 버전을, 스키마 검증에는 Zod v4를, 코드 검색에는 ripgrep을 사용한다.
프로토콜 층에서는 MCP SDK와 LSP를 통해 외부 도구 서버 및 언어 서버와 표준 연동한다. API는 Anthropic SDK를 사용하며, 인증은 OAuth 2.0, JWT, macOS Keychain의 다중 계층이다. 텔레메트리에 OpenTelemetry와 gRPC를, 피처 플래그에 GrowthBook을 사용하여 A/B 테스트 및 단계적 기능 롤아웃을 지원한다.
01-2. 터미널에서 React를 돌린다
Claude Code의 가장 독특한 설계 결정은 터미널 UI를 React 컴포넌트로 구축한 것이다. Ink 라이브러리가 React의 가상 DOM을 터미널 문자열로 렌더링한다. 흐름으로 보면 React 컴포넌트 트리가 Ink 렌더러를 거쳐 ANSI 이스케이프 시퀀스로 변환되고, 최종적으로 터미널에 출력된다.
이 접근법의 장점은 네 가지다. 389개의 UI 컴포넌트를 선언적으로 관리할 수 있고, 상태 관리에 React 훅을 활용하며(104개 커스텀 훅), 컴포넌트 재사용과 합성이 가능하고, 권한 다이얼로그 등 복잡한 UI를 JSX로 표현할 수 있다.
"터미널에 React를 적용한 것은 관성적 사고를 깬 결정이다. 대부분의 CLI 도구는 문자열 출력에 의존하지만, Claude Code는 웹 프론트엔드 수준의 UI 복잡도를 터미널에서 달성했다. 이는 AI 에이전트의 터미널 인터페이스, 서버 관리 도구, 데이터 파이프라인 모니터링 등 터미널 기반 복잡 UI가 필요한 모든 도메인에 적용 가능한 패턴이다."
01-3. Bun의 빌드 시점 코드 제거
bun:bundle의 feature() 함수로 89개의 피처 플래그가 빌드 시점에 평가된다. 비활성 기능의 코드가 완전히 제거되어 배포 바이너리가 경량화된다. 비활성 코드의 import 체인까지 트리쉐이킹으로 제거되므로, 실험 기능이 프로덕션 바이너리의 크기나 보안에 영향을 주지 않는다.
발견된 89개 피처 플래그 중 주목할 것들을 정리하면 다음과 같다. PROACTIVE는 선제적 에이전트 행동, KAIROS는 백그라운드 에이전트 시스템, KAIROS_DREAM은 메모리 정리/통합(수면 중 꿈)이다. COORDINATOR_MODE는 멀티에이전트 조율, ULTRAPLAN은 고급 계획 모드, ULTRATHINK는 확장된 사고 모드이다. ANTI_DISTILLATION_CC는 모델 증류 방지 메커니즘이고, DAEMON은 데몬(백그라운드) 모드, VOICE_MODE는 음성 입력이다. BRIDGE_MODE는 IDE 브릿지, BUDDY는 동반 스프라이트 캐릭터, AGENT_TRIGGERS는 에이전트 트리거 시스템, WEB_BROWSER_TOOL은 웹 브라우저 도구이다.
01-4. 시작 최적화: 병렬 프리페치
main.tsx(804KB, 전체에서 두 번째로 큰 파일)의 시작 부분에서 무거운 모듈 import보다 먼저 사이드 이펙트를 실행한다. MDM 관리 설정 읽기(startMdmRawRead)와 macOS 키체인 비동기 프리페치(startKeychainPrefetch)가 나머지 약 135ms의 import와 병렬로 실행된다. OpenTelemetry, gRPC, GrowthBook 등 무거운 모듈은 동적 import()로 필요 시점에만 로드한다.
"CLI 도구의 체감 성능에서 시작 시간은 결정적이다. 사용자는 100ms 이상이면 느리다고 느낀다. I/O 작업(키체인, 설정)을 CPU 작업(모듈 로드)과 중첩시키는 전략은 모든 CLI 도구, 마이크로서비스 콜드스타트, 서버리스 함수 최적화에 직접 적용 가능하다."
—
02장 핵심 엔진 상세 분석
02-1. QueryEngine.ts — LLM 호출의 중추 (46,630줄)
Claude Code에서 가장 중요한 단일 파일이다. 모든 LLM API 호출이 이 엔진을 거친다. 주요 책임은 Anthropic API에 메시지 전송 및 스트리밍 응답 처리, 도구 호출(tool use) 루프 관리, thinking 모드 제어, 재시도 로직(Rate limit, 네트워크 오류), 토큰 카운팅 및 비용 추적, 컨텍스트 윈도우 관리, 메모리 프롬프트 로드이다.
핵심 의존성을 보면, query.ts(68KB)가 API 쿼리 파이프라인을, cost-tracker.ts가 토큰 비용 계산을, Tool.ts(29KB)가 도구 타입 정의를, commands.ts(25KB)가 명령어 레지스트리를 담당한다. services/api/claude.ts가 Anthropic API 클라이언트이고, services/compact/가 컨텍스트 압축, memdir/가 영구 메모리를 관리한다.
하나의 파일이 46,000줄이라는 것은 일반적 설계 원칙에서는 권장하지 않는 규모이다. 그러나 스트리밍 응답 도중 도구가 호출되고, 도구 결과가 다시 스트림에 합류하는 복잡한 흐름을 여러 파일로 분리하면 상태 동기화 문제가 발생하기 때문에 현실적으로 유리한 구조이다.
"AI 에이전트에서 LLM 호출 엔진은 단일 거대 파일로 유지하는 것이 실무적으로 유리할 수 있다. 도구 호출 루프, 스트리밍, 재시도, 토큰 관리가 긴밀하게 결합되어 있어, 분리하면 오히려 버그가 증가한다. 이는 트랜잭션 경계 안에서는 모놀리식이 더 안전하다는 원칙과 일맥상통한다."
02-2. Tool.ts — 도구 타입 시스템 (29,516줄)
모든 도구의 베이스 인터페이스를 정의한다. 각 도구가 구현해야 하는 계약을 보면, name과 description으로 도구를 식별하고, inputSchema(Zod 스키마)로 입력을 검증하며, permissionMode로 권한 모델을 정의한다. execute 함수가 실제 실행을 담당하고, renderProgress가 진행 UI를 React로 렌더링하며, validate가 사전 검증을 수행한다.
02-3. 컨텍스트 압축 시스템
대화가 길어지면 컨텍스트 윈도우를 초과한다. services/compact/ 디렉토리가 이를 해결한다. compact.ts(1,705줄)가 메인 압축 로직, sessionMemoryCompact.ts(630줄)가 세션 메모리 압축, microCompact.ts(530줄)가 마이크로 압축(경량), autoCompact.ts(351줄)가 자동 압축 트리거, prompt.ts(374줄)가 압축 프롬프트를 담당한다.
압축은 세 단계로 이루어진다. 첫째, Auto Compact가 토큰 한도 접근 시 자동 트리거된다. 둘째, Micro Compact가 API 레벨에서 경량 압축을 수행한다. 셋째, Full Compact가 전체 대화를 요약으로 교체한다.
"3단계 컨텍스트 압축은 의료 기록 요약, 법률 문서 분석, 장기 프로젝트 관리 등 긴 컨텍스트가 필요한 모든 AI 애플리케이션에 참고할 수 있는 설계 패턴이다."
—
03장 도구 시스템 정밀 분석
03-1. BashTool — 가장 복잡한 도구 (12,411줄, 18개 파일)
셸 명령 실행을 담당하며, 보안이 가장 중요한 도구이다.
파일별로 보면, BashTool.tsx(1,143줄)가 메인 실행 로직이다. bashSecurity.ts(2,592줄)가 보안 검증의 핵심이고, bashPermissions.ts(2,621줄)가 권한 관리를 담당한다. readOnlyValidation.ts(1,990줄)가 읽기 전용 모드 검증, pathValidation.ts(1,303줄)가 경로 보안 검증, sedValidation.ts(684줄)가 sed 명령 별도 검증을 수행한다. 그 외에 destructiveCommandWarning.ts(102줄)가 파괴적 명령 경고, commandSemantics.ts(140줄)가 명령 의미 분석, shouldUseSandbox.ts(153줄)가 샌드박스 결정, prompt.ts(369줄)가 시스템 프롬프트를 담당한다.
bashSecurity.ts의 방어 체계를 자세히 살펴보면, Zsh, Bash, PowerShell의 위험한 패턴을 포괄적으로 차단한다.
명령 치환 차단 목록으로는 $() 명령 치환, ${} 파라미터 치환, <()와 >() 프로세스 치환, =() Zsh 프로세스 치환, =cmd Zsh EQUALS 확장, $[] 레거시 산술 확장, ~[] Zsh 파라미터 확장, <# PowerShell 주석 구문이 있다.
Zsh 위험 명령 블랙리스트도 인상적이다. zmodload는 모듈 로드로 파일 I/O, 네트워크, 의사터미널 우회가 가능하다. emulate는 -c 플래그로 임의 코드를 실행하는 eval 동등 명령이다. sysopen, sysread, syswrite, sysseek는 zsh/system 모듈의 파일 디스크립터 직접 조작 명령이다. zpty는 zsh/zpty 모듈의 의사 터미널 명령 실행이고, ztcp는 zsh/net/tcp 모듈의 TCP 연결로 데이터 유출이 가능하다. zsocket는 zsh/net/socket의 Unix/TCP 소켓 생성이고, mapfile은 zsh/mapfile의 배열 기반 파일 I/O이다. zf_rm, zf_mv, zf_ln, zf_chmod, zf_chown, zf_mkdir, zf_rmdir, zf_chgrp는 zsh/files 모듈의 내장 파일 조작 명령으로 바이너리 검사를 우회한다.
다층 방어 구조의 흐름을 보면, 사용자 입력이 bashSecurity.ts(위험 패턴 탐지)를 거치고, bashPermissions.ts(권한 확인)를 통과하며, readOnlyValidation.ts(읽기 전용 검증)와 pathValidation.ts(경로 보안)를 지나고, sedValidation.ts(sed 명령 별도 검증)를 거친 후, shouldUseSandbox.ts(샌드박스 결정)를 통과해야 비로소 실행된다.
"12,000줄의 Bash 보안 코드는 AI 에이전트 보안의 벤치마크이다. AI가 셸 명령을 실행할 때의 보안은 웹 SQL 인젝션보다 복잡하다. 셸은 여러 계층의 확장(변수/프로세스/글로빙)이 있고, Zsh/Bash/PowerShell 간 동작 차이가 있기 때문이다. 이 수준의 방어 깊이는 자율주행 시스템 안전성, 산업 로봇 명령 검증, 의료 기기 자동화 등 AI가 물리적/디지털 행동을 수행하는 모든 분야에서 참고해야 한다."
03-2. AgentTool — 멀티에이전트의 핵심 (6,072줄, 15개 파일)
서브 에이전트를 생성하는 도구로, Claude Code의 멀티에이전트 능력의 기반이다.
AgentTool.tsx(1,397줄)가 메인 에이전트 로직이고, runAgent.ts(973줄)가 에이전트 실행 엔진, UI.tsx(871줄)가 에이전트 UI를 담당한다. loadAgentsDir.ts(755줄)가 에이전트 디렉토리를 로드하고, agentToolUtils.ts(686줄)가 유틸리티, prompt.ts(287줄)가 에이전트 시스템 프롬프트이다. agentMemory.ts(177줄)와 agentMemorySnapshot.ts(197줄)가 에이전트 메모리를, forkSubagent.ts(210줄)가 서브에이전트 분기를, resumeAgent.ts(265줄)가 에이전트 재개를 담당한다.
에이전트 생성 흐름을 보면, AgentTool.execute()가 호출되면 loadAgentsDir()로 사용자 정의 에이전트를 탐색한다. runAgent()가 에이전트 실행 루프를 시작하며, 이때 QueryEngine으로 독립 LLM 세션을 생성하고 제한된 도구 세트만 할당한다(최소 권한 원칙). 필요시 forkSubagent()로 추가 분기하며, 재귀적 구조를 지원한다. 최종 결과는 agentMemory에 저장된다.
"에이전트가 에이전트를 생성하는 재귀적 구조와, 각 에이전트에 최소 권한만 부여하는 설계는 조직 관리의 위임(delegation) 패턴과 동일하다. 이 패턴은 물류 자동화(주문→배차→배송 에이전트), 금융 분석(전략→섹터→종목 에이전트), 소프트웨어 테스트(총괄→모듈→케이스 에이전트) 등 계층적 작업 분해가 필요한 모든 도메인에 적용 가능하다."
03-3. 전체 도구 목록 (40종)
파일시스템 도구(7종)로는 BashTool, FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool, NotebookEditTool이 있다.
에이전트/멀티에이전트 도구(6종)로는 AgentTool, TeamCreateTool, TeamDeleteTool, SendMessageTool, TaskCreateTool, TaskUpdateTool이 있다.
외부 연동 도구(5종)로는 WebFetchTool, WebSearchTool, MCPTool, LSPTool, ToolSearchTool이 있다.
모드 전환 도구(7종)로는 EnterPlanModeTool, ExitPlanModeTool, EnterWorktreeTool, ExitWorktreeTool, SleepTool, BriefTool, ConfigTool이 있다.
기타 도구(7종)로는 AskUserQuestionTool, REPLTool, SkillTool, SyntheticOutputTool, TodoWriteTool, RemoteTriggerTool, ScheduleCronTool이 있다.
플랫폼 도구(4종 이상)로는 PowerShellTool, McpAuthTool, ReadMcpResourceTool, ListMcpResourcesTool이 있다.
—
04장 명령어 시스템 (101종)
04-1. 명령어 분류
개발 워크플로우(15종)에는 /commit, /review, /diff, /autofix-pr, /pr_comments, /branch, /issue, /compact, /plan, /agents, /tasks, /skills, /hooks, /context, /files가 있다.
세션 관리(8종)에는 /resume, /share, /session, /export, /summary, /copy, /rename, /rewind가 있다.
설정(12종)에는 /config, /permissions, /model, /theme, /vim, /color, /output-style, /keybindings, /effort, /fast, /privacy-settings, /sandbox-toggle가 있다.
연동(7종)에는 /mcp, /plugin, /bridge, /chrome, /desktop, /mobile, /remote-setup이 있다.
진단(8종)에는 /doctor, /cost, /stats, /status, /usage, /extra-usage, /debug-tool-call, /ctx_viz가 있다.
인증(3종)에는 /login, /logout, /oauth-refresh가 있다.
04-2. 주목할 숨겨진 명령어
코드에서 발견되는 피처 플래그 기반 명령어들로, Anthropic의 개발 로드맵을 간접적으로 보여준다.
/bughunter는 자동 버그 탐색 에이전트로, 코드 취약점 발견을 자동화할 것으로 추정된다. /thinkback과 /thinkback-play는 사고 과정의 기록 및 재생 기능으로, AI 추론 디버깅과 감사 도구이다. /teleport는 175KB에 달하는 대규모 기능으로, 로컬↔원격↔IDE 간 작업 세션 이동을 담당할 것으로 보인다. /good-claude는 AI에게 보상 피드백을 보내는 긍정 강화 메커니즘이다. /buddy는 동반 스프라이트 캐릭터로, AI 에이전트의 의인화와 친밀감을 담당한다. /ultraplan은 복잡한 멀티스텝 작업을 위한 고급 계획 모드이다. /btw는 작업 맥락 전환, /stickers는 감정 표현 및 게이미피케이션에 해당한다.
"/thinkback(사고 과정 재생)은 AI 에이전트의 감사(audit) 가능성에 대한 투자를 보여준다. 의료, 금융, 법률 등 규제 산업에서 AI 의사결정의 추적 가능성은 법적 요구사항이다. 이 기능이 상용화되면 규제 산업의 AI 도입 장벽을 크게 낮출 수 있다."
—
05장 멀티에이전트 시스템
05-1. 아키텍처 계층
최상위에 메인 에이전트(REPL.tsx)가 있다. AgentTool로 서브에이전트를 생성하며, 각 서브에이전트는 독립된 QueryEngine을 갖는다. 서브에이전트는 다시 AgentTool을 호출하여 서브-서브에이전트를 만들 수 있고(재귀), SendMessageTool로 에이전트 간 메시지를 전달한다.
TeamCreateTool은 병렬 작업을 위한 팀 에이전트를 생성한다. InProcessTeammateTask와 LocalShellTask가 팀 에이전트의 물리적 실행을 담당한다.
TaskCreateTool은 비동기 작업을 관리하며, DreamTask(메모리 정리), LocalAgentTask, RemoteAgentTask 세 가지 유형이 있다.
coordinator/가 전체를 조율한다.
05-2. Swarm 시스템
팀 에이전트의 물리적 실행을 담당하는 시스템이다. InProcessBackend는 같은 프로세스에서 팀원을 실행하고, TmuxBackend는 tmux 분할 패널에서 팀원을 실행하며, ITermBackend는 iTerm2 탭에서 팀원을 실행한다. PaneBackendExecutor가 터미널 패널 실행의 추상화를 담당한다.
"에이전트 실행을 추상화하여 여러 백엔드(in-process, tmux, iTerm)를 플러그형으로 지원하는 구조는 Kubernetes의 CRI(Container Runtime Interface)와 동일한 패턴이다. AI 에이전트가 로컬/클라우드/엣지 등 다양한 환경에서 실행되어야 하는 스마트팩토리, 자율주행 플릿 관리, 분산 로봇 시스템에 직접 적용 가능한 설계이다."
05-3. DreamTask — AI의 "수면"
KAIROS_DREAM 피처 플래그로 제어되는 백그라운드 메모리 정리 시스템이다. 4단계로 동작한다. orient(현재 메모리 상태 파악) → gather(최근 세션들을 리뷰) → consolidate(중요 기억을 통합) → prune(불필요한 기억 정리).
코드에서 "at least these were touched, not only these were touched"라는 주석이 있다. Dream 에이전트가 파일을 직접 수정할 수 있으며, 그 행동 범위를 완전히 추적하지 못한다는 것은 자율적 메모리 관리의 불확실성을 Anthropic도 인지하고 있다는 의미이다.
05-4. Task 타입 (5종)
DreamTask는 백그라운드 사고와 메모리 정리 작업이다. InProcessTeammateTask는 프로세스 내 팀원 작업, LocalAgentTask는 로컬 에이전트 작업, LocalShellTask는 로컬 셸 작업, RemoteAgentTask는 원격 에이전트 작업이다.
"인간의 수면 중 기억 정리를 모방한 DreamTask는 AI 에이전트의 장기 운영에 필수적인 기능이다. 에이전트가 수주, 수개월 동작하면 메모리가 누적되어 성능이 저하된다. 의료 모니터링 AI(환자 기록 정리), 금융 트레이딩 AI(과거 패턴 압축), 스마트빌딩 관리 AI(센서 이력 정리) 등 장기 운영 에이전트에 필수적인 설계 패턴이다."
—
06장 보안 아키텍처
06-1. 권한 시스템
모든 도구 호출이 hooks/toolPermission/을 거친다. PermissionContext.ts에서 컨텍스트를 수집한 후, 모드별로 세 핸들러가 분기 처리한다. interactiveHandler.ts는 사용자에게 대화형으로 질문하고, coordinatorHandler.ts는 조율 모드에서, swarmWorkerHandler.ts는 스웜 워커에서 동작한다. permissionLogging.ts가 감사 로그를 기록한다.
13종의 권한 다이얼로그가 존재한다. Bash, FileRead, FileWrite, FileEdit, WebFetch, NotebookEdit, PowerShell, SedEdit, Skill, ComputerUse, EnterPlanMode, ExitPlanMode, AskUserQuestion이며, 각각 독립된 React 컴포넌트로 구현되어 도구별 맥락에 맞는 정보를 사용자에게 제공한다.
"AI 에이전트의 권한 시스템은 운영체제의 권한 모델과 같은 중요성을 갖는다. 이 13층 구조는 향후 AI 에이전트 표준 프레임워크에서 필수 요소가 될 것이다. 의료 AI(환자 데이터 접근 제어), 금융 AI(거래 승인), 법률 AI(문서 수정 승인) 등 도메인별 권한 체계 설계에 참고할 수 있다."
06-2. Anti-Distillation (모델 증류 방지)
ANTI_DISTILLATION_CC 피처 플래그로 활성화되는 방어 메커니즘이 발견되었다. CLI 진입점에서만, 그리고 1st party 베타에서만 동작한다. 가짜 도구 정의를 시스템 프롬프트에 주입(fake_tools)하여, Claude의 출력을 캡처하여 다른 모델을 학습시키는 증류 공격의 품질을 저하시킨다.
원리는 이렇다. 증류된 모델이 존재하지 않는 도구를 호출하도록 유도하면, 그 모델은 실제 환경에서 오류를 일으킨다. 가짜 도구가 많을수록 증류된 모델의 신뢰성이 떨어져, 증류의 경제적 가치가 사라진다.
"Anti-Distillation은 AI 시대의 새로운 지적재산 보호 기법이다. 코드 난독화가 소프트웨어를 보호하듯, 가짜 도구 주입이 AI 모델을 보호한다. 이 패턴은 독점 AI 모델을 서비스하는 모든 기업, 특히 API 기반 AI SaaS, 기업용 챗봇, 산업 특화 AI 모델 제공자가 참고해야 할 방어 기법이다."
06-3. 비밀 스캐너 (Secret Scanner)
services/teamMemorySync/secretScanner.ts에 구현된 클라이언트 측 비밀 탐지기이다. gitleaks의 고신뢰도 규칙을 이식하여, 팀 메모리에 업로드되기 전에 GitHub PAT, AWS Access Token, Slack Token 등 고유 접두사가 있는 자격 증명을 탐지한다. 핵심 원칙은 "비밀은 사용자의 머신을 절대 떠나지 않는다"는 것이다.
"클라이언트 측 비밀 탐지는 데이터 유출 방지(DLP)의 핵심이다. AI 에이전트가 코드를 분석하고 공유할 때, API 키나 비밀번호가 포함될 위험이 크다. 이 패턴은 코드 리뷰 자동화, CI/CD 파이프라인, 기업 내 AI 어시스턴트 등 코드를 다루는 모든 AI 시스템에 필수적이다."
—
07장 서비스 계층
07-1. MCP 서비스 (12,238줄, 22개 파일)
Model Context Protocol 연동의 핵심이다. client.ts(3,348줄)가 MCP 서버 연결, auth.ts(2,465줄)가 인증, config.ts(1,578줄)가 설정 관리, useManageMCPConnections.ts(1,141줄)가 React 훅 기반 연결 관리를 담당한다. xaa.ts와 xaaIdpLogin.ts(합계 998줄)가 XAA 인증과 IdP 로그인을 지원하며, channelPermissions.ts(240줄), channelNotification.ts(316줄), utils.ts(575줄), elicitationHandler.ts(313줄) 등이 나머지를 구성한다.
"MCP는 AI 에이전트의 USB 포트와 같다. Claude Code가 12,000줄을 투자하여 MCP 연동을 구현한 것은, 외부 도구 생태계가 AI 에이전트의 핵심 경쟁력임을 보여준다. ERP 연동, CRM 통합, IoT 디바이스 제어 등 기업 시스템과 AI를 연결하는 모든 프로젝트에서 MCP 또는 유사 프로토콜이 표준이 될 것이다."
07-2. Bridge 서비스 (12,613줄, 31개 파일)
IDE(VSCode, JetBrains)와의 양방향 통신 계층이다. IDE 확장과 Claude Code CLI 사이에서 JWT 인증, 세션 관리, 권한 콜백을 중개한다.
bridgeMain.ts(2,999줄)가 브릿지 메인 루프, replBridge.ts(2,406줄)가 REPL 세션 브릿지, remoteBridgeCore.ts(1,008줄)가 원격 브릿지, sessionRunner.ts(550줄)가 세션 실행 관리를 담당한다. bridgeApi.ts(539줄)가 브릿지 API, bridgeUI.ts(530줄)가 브릿지 UI, initReplBridge.ts(569줄)가 REPL 브릿지 초기화, jwtUtils.ts(256줄)가 JWT 인증 유틸리티이다.
07-3. OAuth 서비스 (1,051줄)
표준 OAuth 2.0 플로우를 구현한다. Authorization Code + PKCE 방식이다. client.ts(566줄)가 OAuth 클라이언트, auth-code-listener.ts(211줄)가 인증 코드 리스너, index.ts(198줄)가 모듈 진입점, getOauthProfile.ts(53줄)가 프로필 조회, crypto.ts(23줄)가 PKCE 암호화를 담당한다.
—
08장 메모리 시스템
08-1. 영구 메모리 (memdir/)
CLAUDE.md 파일 기반의 프로젝트/사용자 메모리와, memdir/ 디렉토리 기반의 구조화된 메모리로 구성된다.
memdir.ts(507줄)가 메모리 디렉토리를 관리하고, memoryTypes.ts(271줄)가 메모리 타입을 정의하며, paths.ts(278줄)가 메모리 경로를 해석한다. findRelevantMemories.ts(141줄)가 관련 메모리를 검색하고, memoryScan.ts(94줄)가 메모리를 스캔하며, memoryAge.ts(53줄)가 메모리 수명을 관리한다. teamMemPaths.ts(292줄)가 팀 메모리 경로를, teamMemPrompts.ts(100줄)가 팀 메모리 프롬프트를 담당한다.
08-2. 자동 메모리 추출
services/extractMemories/에서 대화 중 자동으로 기억할 만한 정보를 추출한다. EXTRACT_MEMORIES 피처 플래그로 제어된다.
08-3. 세션 메모리
services/SessionMemory/가 세션 간 기억을 관리하며, 컨텍스트 압축 시에도 핵심 정보를 보존한다.
"3계층 메모리 시스템(영구/세션/자동추출)은 인간의 기억 구조(장기/단기/무의식)를 모방한다. 고객 서비스 AI(고객 이력 기억), 교육 AI(학습자 진도 기억), 연구 보조 AI(논문 분석 이력) 등 장기 관계를 유지해야 하는 AI 에이전트에서 이 패턴이 필수적이다."
—
09장 플러그인 생태계
09-1. 플러그인 아키텍처
각 플러그인은 독립된 디렉토리 구조를 갖는다. .claude-plugin/ 폴더 안에 plugin.json(메타데이터)이 있고, commands/ 폴더에 슬래시 명령어가 Markdown으로 정의된다. skills/ 폴더에 스킬이, hooks/ 폴더에 이벤트 훅이 정의되며, hooks-handlers/ 폴더에 훅 핸들러(셸 스크립트)가 위치한다.
09-2. 공식 플러그인 13종
agent-sdk-dev는 Agent SDK 개발 지원 도구이다. claude-opus-4-5-migration은 Opus 4.5 마이그레이션 가이드이다. code-review는 자동 코드 리뷰이고, commit-commands는 커밋 자동화(commit, push, PR)이다. explanatory-output-style은 설명적 출력 스타일이고, feature-dev는 기능 개발 프로세스 워크플로우이다. frontend-design은 프론트엔드 디자인 지원이고, hookify는 훅 시스템 관리이다. learning-output-style은 학습용 출력 스타일이고, plugin-dev는 플러그인 개발 도구이다. pr-review-toolkit은 PR 리뷰 도구킷이다. 마지막으로 ralph-wiggum은 심슨 캐릭터 스타일 출력을 제공하는 이스터에그이다.
09-3. 훅 시스템
explanatory-output-style 플러그인이 훅 시스템의 사용 예를 보여준다. hooks.json 파일에서 session_start 이벤트에 셸 스크립트 핸들러를 연결하여, 세션 시작 시 출력 스타일을 변경한다.
"Markdown 기반 플러그인 정의는 진입 장벽을 극적으로 낮춘다. 개발자가 아닌 도메인 전문가도 자연어로 도구를 정의할 수 있다. 이 패턴은 교육(교사가 학습 도구 정의), 의료(의사가 진단 프로토콜 정의), 법률(변호사가 계약 검토 규칙 정의) 등 비개발자가 AI 도구를 커스터마이징해야 하는 모든 도메인에 혁신적으로 적용 가능하다."
—
10장 UI/UX 아키텍처
10-1. 화면 구조
REPL.tsx(896KB)는 전체 코드베이스에서 가장 큰 파일이다. 메인 대화 화면의 모든 것, 즉 프롬프트 입력, 메시지 렌더링, 도구 실행 결과 표시, 권한 다이얼로그, 상태 바, 자동완성을 담당한다.
PromptInput.tsx(355KB)는 입력 영역만으로 세 번째로 큰 파일이다. 자동완성, 히스토리, 멀티라인, 파일 첨부, 음성 입력 등을 처리한다.
10-2. 컴포넌트 분류 (389개)
권한 컴포넌트가 13종 있으며 Bash, File(3종), Web, Notebook, PowerShell 등의 권한 다이얼로그를 포함한다. 메시지 컴포넌트는 사용자/어시스턴트/도구 결과 메시지를 렌더링한다. 에이전트 컴포넌트에는 에이전트 생성 위자드와 팀 관리가 포함되며, MCP 컴포넌트 중 ElicitationDialog.tsx(180KB)는 정보 요청 처리를 담당한다. 설정의 Config.tsx(272KB)가 전체 설정 UI를, design-system/이 기본 UI 요소를, LogSelector.tsx(200KB)가 로그 필터링/선택을, Stats.tsx(153KB)가 사용 통계 표시를 담당한다.
10-3. Ink 렌더링 계층
ink/ 디렉토리에 Ink 렌더러의 커스텀 래퍼가 있으며, 자체 레이아웃 엔진(layout/), 이벤트 시스템(events/), 훅(hooks/), 컴포넌트(components/)를 구현하고 있다. ink.tsx(252KB) 자체가 6번째로 큰 파일이다.
—
11장 비공개 기능과 로드맵 추정
11-1. KAIROS 시스템
소스코드에서 가장 많이 참조되는 미출시 시스템이다. 6개의 관련 피처 플래그가 존재한다. KAIROS가 메인 시스템, KAIROS_BRIEF가 간결 모드, KAIROS_CHANNELS가 채널 시스템, KAIROS_DREAM이 수면/메모리 정리, KAIROS_GITHUB_WEBHOOKS가 GitHub 웹훅 반응, KAIROS_PUSH_NOTIFICATION이 푸시 알림이다.
코드 분석 결과, 백그라운드에서 자율적으로 동작하는 에이전트 시스템으로 GitHub 웹훅에 반응하고, 채널을 통해 사용자와 소통하며, 푸시 알림을 보내는 구조이다.
"KAIROS는 AI 에이전트의 다음 패러다임을 보여준다. 현재의 AI 에이전트는 사용자가 명령해야 동작하지만, KAIROS는 이벤트에 자율적으로 반응한다. DevOps 자동화(PR 자동 리뷰), 보안 모니터링(위협 자동
대응), 비즈니스 자동화(이메일 자동 처리) 등 반응형 에이전트가 필요한 모든 분야의 미래를 보여준다."
11-2. ULTRAPLAN / ULTRATHINK
고급 계획 및 사고 모드이다. /plan 명령의 강화 버전으로, 복잡한 멀티스텝 작업을 사전에 계획하고 검증한 후 실행하는 구조로 추정된다. ULTRATHINK는 더 깊은 추론을 위한 확장 사고 모드로, 토큰 예산을 더 많이 사용하여 복잡한 문제를 해결한다.
11-3. DAEMON 모드
백그라운드 프로세스로 실행되는 모드이다. KAIROS와 연동하여 항시 대기하는 에이전트를 구현하는 것으로 추정된다.
11-4. Coordinator Mode
멀티에이전트 조율 전용 모드이다. 일반 모드와 분리되어 팀 에이전트의 작업 분배와 결과 통합을 담당한다. 코드에서 isCoordinatorMode() 함수가 환경 변수와 피처 플래그를 동시에 확인하며, 세션 복원 시 모드 불일치를 자동 감지하고 수정하는 matchSessionMode() 로직이 발견되었다.
11-5. Computer Use / Web Browser Tool
데스크톱 조작 및 웹 브라우저 자동화이다. BUILDING_CLAUDE_APPS와 WEB_BROWSER_TOOL 플래그가 존재하며, ComputerUseApproval 권한 컴포넌트도 발견되었다.
11-6. 기타 미출시 기능
VERIFICATION_AGENT는 검증 전용 에이전트로, 출력 품질 자동 검증을 담당할 것으로 보인다. TORCH는 내부 코드명으로 추정되며 구체적 기능은 미확인이다. LODESTONE은 탐색/네비게이션 관련으로 추정된다. PERFETTO_TRACING은 Perfetto 연동을 통한 성능 프로파일링이고, NATIVE_CLIENT_ATTESTATION은 클라이언트 인증서 검증이다.
—
12장 도메인별 적용 가능 분야
Claude Code 소스코드에서 발견된 설계 패턴과 아키텍처는 다양한 산업 도메인에 직접 적용할 수 있다.
12-1. AI 에이전트 플랫폼 개발
도구 시스템의 경우, Claude Code는 40종의 Tool을 입력 스키마+권한+실행의 표준 구조로 구현했다. 이는 산업별 도구 표준 프레임워크 설계에 적용 가능하다. 멀티에이전트의 경우, AgentTool + coordinator + swarm 구조는 조직 구조를 모방한 에이전트 계층 설계에 적용 가능하다. 메모리의 경우, 3계층(영구/세션/자동) + DreamTask 구조는 장기 운영 에이전트의 지식 관리에 적용 가능하다. 보안의 경우, 13층 권한 + 다층 Bash 보안은 에이전트 행동의 안전 보장 체계 설계에 적용 가능하다.
12-2. 기업용 AI 자동화
플러그인 시스템은 Markdown 기반 도구 정의로 비개발자가 업무 자동화 규칙을 정의할 수 있게 한다. MCP 연동(12,000줄)은 ERP, CRM, ITSM과 AI 에이전트를 연결하는 데 적용 가능하다. Bridge 시스템(CLI↔IDE 양방향 통신)은 기존 업무 도구와 AI를 통합하는 데 적용 가능하다. 비밀 스캐너(클라이언트 측 자격증명 탐지)는 기업 데이터 유출 방지(DLP)에 적용 가능하다.
12-3. 규제 산업 AI 도입
/thinkback의 추론 감사(사고 과정 기록 및 재생)는 의료와 금융 분야에서 AI 의사결정의 추적성 확보에 적용 가능하다. 권한 다이얼로그(도구별 맥락 정보 + 승인/거부)는 의료 처방 승인, 금융 거래 승인 체계에 적용 가능하다. 컨텍스트 압축(핵심 정보 보존 압축)은 환자 기록 요약, 법률 문서 분석에 적용 가능하다. Anti-Distillation(가짜 도구 주입)은 독점 AI 모델의 지적재산 보호에 적용 가능하다.
12-4. 차세대 소프트웨어 엔지니어링
KAIROS 반응형 에이전트(이벤트 기반 자율 행동)는 PR 자동 리뷰, 보안 취약점 자동 탐지에 적용 가능하다. Bun 피처 플래그(89개, 빌드 시점 제거)는 대규모 프로젝트의 단계적 기능 출시에 적용 가능하다. React in Terminal(389개 터미널 UI 컴포넌트)은 서버 관리, 모니터링 도구의 UX 혁신에 적용 가능하다. 병렬 프리페치(시작 시 I/O와 CPU 중첩)는 CLI 시작 시간 최적화에 적용 가능하다.
—
13장 결론
첫째, AI 에이전트 플랫폼은 정통 소프트웨어 엔지니어링이다. 512,664줄의 TypeScript, strict 모드, 13층 권한 시스템, 다층 보안 검증은 프롬프트 엔지니어링만으로는 달성할 수 없는 수준이다. 진정한 AI 에이전트를 만들려면 프롬프트가 아닌 플랫폼을 만들어야 한다.
둘째, 보안은 기능이 아니라 아키텍처이다. BashTool 하나에 12,000줄의 보안 코드, Zsh 전용 공격 벡터까지 방어하는 깊이는 보안을 사후 추가하는 것이 아니라 설계 단계에서 내장해야 함을 보여준다.
셋째, 메모리와 자율성이 에이전트의 다음 경쟁 전선이다. DreamTask(수면 중 기억 정리), KAIROS(이벤트 반응형 자율 행동), 3계층 메모리 시스템은 단순한 질의응답을 넘어 장기적으로 학습하고 자율적으로 행동하는 에이전트를 향한 투자이다.
넷째, 생태계 전략이 핵심이다. MCP 12,000줄, 플러그인 시스템, IDE 브릿지, 스킬 시스템은 Claude Code 자체의 기능보다 외부 생태계와의 연결을 더 중시한다는 것을 보여준다. AI 에이전트의 가치는 혼자 할 수 있는 것이 아니라, 무엇과 연결될 수 있는가로 결정된다.
—
부록 A: 파일 규모 상위 20
1위 screens/REPL.tsx(896KB)는 메인 REPL 화면이다. 2위 main.tsx(804KB)는 진입점이다. 3위 components/PromptInput.tsx(355KB)는 프롬프트 입력이다. 4위 commands/plugin/ManagePlugins.tsx(322KB)는 플러그인 관리이다. 5위 components/Settings/Config.tsx(272KB)는 설정이다. 6위 ink/ink.tsx(252KB)는 Ink 렌더러이다. 7위 tools/AgentTool/AgentTool.tsx(234KB)는 에이전트 도구이다. 8위 utils/ansiToPng.ts(215KB)는 ANSI→PNG 변환이다. 9위 cli/print.ts(213KB)는 CLI 출력이다. 10위 hooks/useTypeahead.tsx(213KB)는 자동완성이다. 11위 components/LogSelector.tsx(200KB)는 로그 선택이다. 12위 utils/messages.ts(193KB)는 메시지 유틸이다. 13위 utils/sessionStorage.ts(181KB)는 세션 저장이다. 14위 components/mcp/ElicitationDialog.tsx(180KB)는 MCP 정보요청이다. 15위 utils/teleport.tsx(176KB)는 텔레포트이다. 16위 tools/BashTool/BashTool.tsx(161KB)는 Bash 도구이다. 17위 utils/hooks.ts(159KB)는 훅 유틸이다. 18위 components/Stats.tsx(153KB)는 통계이다. 19위 components/ScrollKeybindingHandler.tsx(149KB)는 스크롤 키바인딩이다. 20위 context.ts(64KB)는 컨텍스트 수집이다.
부록 B: 디렉토리별 코드 규모
utils/(564개 파일, 180,472줄)가 전체의 35.2%로 가장 크다. components/(389개, 81,546줄)가 15.9%, services/(130개, 53,680줄)가 10.5%, tools/(184개, 50,828줄)가 9.9%, commands/(207개, 26,428줄)가 5.2%를 차지한다. hooks/(104개, 19,204줄)가 3.7%, bridge/(31개, 12,613줄)가 2.5%, screens/(3개, 5,977줄)가 1.2%, tasks/(12개, 3,286줄)가 0.6%, vim/(5개, 1,513줄)가 0.3%이다. 나머지(약 412개, 77,117줄)가 15.0%이다. 합계 2,041개 파일, 512,664줄이다.
부록 C: 피처 플래그 전체 목록 (89개)
빌드 시점에 평가되는 bun:bundle feature() 플래그 전체 목록이다. 각 플래그가 false이면 해당 코드 경로가 바이너리에서 완전히 제거된다.
ABLATION_BASELINE, AGENT_MEMORY_SNAPSHOT, AGENT_TRIGGERS, AGENT_TRIGGERS_REMOTE, ALLOW_TEST_VERSIONS, ANTI_DISTILLATION_CC, AUTO_THEME, AWAY_SUMMARY, BASH_CLASSIFIER, BG_SESSIONS, BREAK_CACHE_COMMAND, BRIDGE_MODE, BUDDY, BUILDING_CLAUDE_APPS, BUILTIN_EXPLORE_PLAN_AGENTS, BYOC_ENVIRONMENT_RUNNER, CACHED_MICROCOMPACT, CCR_AUTO_CONNECT, CCR_MIRROR, CCR_REMOTE_SETUP, CHICAGO_MCP, COMMIT_ATTRIBUTION, COMPACTION_REMINDERS, CONNECTOR_TEXT, CONTEXT_COLLAPSE, COORDINATOR_MODE, COWORKER_TYPE_TELEMETRY, DAEMON, DIRECT_CONNECT, DOWNLOAD_USER_SETTINGS, DUMP_SYSTEM_PROMPT, ENHANCED_TELEMETRY_BETA, EXPERIMENTAL_SKILL_SEARCH, EXTRACT_MEMORIES, FILE_PERSISTENCE, FORK_SUBAGENT, HARD_FAIL, HISTORY_PICKER, HISTORY_SNIP, HOOK_PROMPTS, IS_LIBC_GLIBC, IS_LIBC_MUSL, KAIROS, KAIROS_BRIEF, KAIROS_CHANNELS, KAIROS_DREAM, KAIROS_GITHUB_WEBHOOKS, KAIROS_PUSH_NOTIFICATION, LODESTONE, MCP_RICH_OUTPUT, MCP_SKILLS, MEMORY_SHAPE_TELEMETRY, MESSAGE_ACTIONS, MONITOR_TOOL, NATIVE_CLIENT_ATTESTATION, NATIVE_CLIPBOARD_IMAGE, NEW_INIT, OVERFLOW_TEST_TOOL, PERFETTO_TRACING, POWERSHELL_AUTO_MODE, PROACTIVE, PROMPT_CACHE_BREAK_DETECTION, QUICK_SEARCH, REACTIVE_COMPACT, REVIEW_ARTIFACT, RUN_SKILL_GENERATOR, SELF_HOSTED_RUNNER, SHOT_STATS, SKILL_IMPROVEMENT, SLOW_OPERATION_LOGGING, SSH_REMOTE, STREAMLINED_OUTPUT, TEAMMEM, TEMPLATES, TERMINAL_PANEL, TOKEN_BUDGET, TORCH, TRANSCRIPT_CLASSIFIER, TREE_SITTER_BASH, TREE_SITTER_BASH_SHADOW, UDS_INBOX, ULTRAPLAN, ULTRATHINK, UNATTENDED_RETRY, UPLOAD_USER_SETTINGS, VERIFICATION_AGENT, VOICE_MODE, WEB_BROWSER_TOOL, WORKFLOW_SCRIPTS
—
이상으로 Claude Code 소스코드 아키텍처 분석을 마칩니다.
질의 사항은 arxivgpt@gmail.com 으로 주세요.