Claude Code 소스 유출이 드러낸 아키텍처 — 1편: 512,000줄의 전체 조감도

들어가며

2026년 3월 31일 새벽, 개발자 커뮤니티가 술렁였습니다. Anthropic이 npm에 배포한 @anthropic-ai/claude-code v2.1.88 패키지에 소스맵 파일이 포함되어 출시된 것입니다. .npmignore 설정 누락이라는 단순한 실수였지만, 그 안에는 약 512,000줄의 원본 TypeScript 소스코드가 고스란히 담겨 있었습니다.

Anthropic은 곧바로 "해킹이 아닌 릴리스 패키징 과정의 인적 오류"라고 공식 확인했습니다. 모델 가중치나 고객 데이터는 포함되지 않았지만, Claude Code라는 제품이 어떤 구조로 설계되었는지가 세상에 드러난 순간이었습니다.

저는 Claude Code의 헤비 유저입니다. 매일 이 도구로 코드를 작성하고, 커스텀 스킬과 에이전트 하네스를 구축해왔습니다. 그래서 이번 유출이 특별히 흥미로웠습니다 — 매일 쓰는 도구의 내부 설계를 들여다볼 수 있는 기회였으니까요.

이 시리즈에서는 유출 이후 공개된 아키텍처 스냅샷과 클린룸 재작성 프로젝트인 claw-code를 기반으로, Claude Code의 설계 패턴을 분석합니다. 코드를 직접 복사하거나 재배포하는 것이 아니라, 아키텍처 수준에서 어떤 설계 결정이 내려졌는지를 살펴보는 것이 목적입니다.

유출 사건의 경위

사건의 전말은 단순합니다. npm 패키지를 빌드할 때 소스맵 파일(번들링된 JavaScript를 원본 TypeScript로 역추적할 수 있는 파일)이 생성됩니다. 보통은 .npmignore에 이 파일을 등록하여 배포에서 제외하는데, 이번에는 그 설정이 누락되었습니다.

블록체인 보안 기업 Fuzzland의 연구원 Chaofan Shou가 이를 발견하고 공개했습니다. 59.8MB 크기의 소스맵 파일 안에는 약 1,900개 파일의 원본 코드가 들어 있었습니다.

한국 개발자 Sigrid Jin은 이 소스를 참조하여 Python으로 클린룸 재작성한 프로젝트 claw-code를 GitHub에 공개했고, 2시간 만에 50,000 스타를 돌파하며 GitHub 역사상 가장 빠른 성장 기록을 세웠습니다. 현재 91,000 스타를 넘었습니다.

이 시리즈에서 참조하는 데이터는 claw-code의 reference_data/ 디렉토리에 보존된 아키텍처 스냅샷(서브시스템 목록, 커맨드/도구 인벤토리)과 Python/Rust 재작성 코드입니다. 유출 시점(v2.1.88)의 스냅샷이므로 현재 버전과 차이가 있을 수 있다는 점을 미리 밝힙니다.

숫자로 보는 Claude Code의 규모

아키텍처를 살펴보기 전에, 먼저 이 프로젝트의 규모감을 짚어보겠습니다.

항목	수치
TypeScript 파일 수	1,902개
총 코드 라인	~512,000줄
최상위 서브시스템	34개
등록된 커맨드	207개
등록된 도구	184개
빌트인 에이전트	6개
번들드 스킬	17개
MCP 트랜스포트 종류	5종
CLI 트랜스포트 종류	3종

솔직히 이 숫자를 처음 봤을 때 놀랐습니다. 터미널에서 실행되는 CLI 도구가 이 정도 규모라니. 하지만 곰곰이 생각해보면, Claude Code가 단순한 "채팅 인터페이스"가 아니라 파일 시스템을 탐색하고, 코드를 작성하고, 테스트를 실행하고, MCP 서버와 통신하고, IDE와 연동하는 풀스택 에이전트라는 것을 감안하면 납득이 됩니다.

34개 서브시스템 지도

Claude Code의 소스코드는 34개의 서브시스템으로 구성되어 있습니다. 각 서브시스템의 모듈 수를 보면 어디에 가장 많은 코드가 집중되어 있는지 알 수 있습니다.

상위 5개 서브시스템 — 코드의 대부분이 여기에

서브시스템	모듈 수	역할
utils	564	유틸리티 (CircularBuffer, Shell, auth 등)
components	389	React(Ink) UI 컴포넌트
services	130	API, OAuth, MCP, analytics 등 서비스
hooks	104	React 훅 + tool permission 핸들러
bridge	31	IDE/데스크톱 연동 브리지

utils가 564개 모듈로 가장 크다는 것이 눈에 띕니다. CLI 도구지만 내부적으로는 CircularBuffer, Shell 관리, 인증, advisor 패턴 등 상당히 정교한 유틸리티 계층을 가지고 있습니다.

components가 389개라는 것도 흥미롭습니다. Claude Code는 터미널 UI를 React + Ink로 렌더링합니다. 웹 프론트엔드를 만들듯이 컴포넌트를 조합해서 터미널 인터페이스를 구성하는 것입니다.

핵심 인프라 서브시스템

서브시스템	모듈 수	역할
skills	20	번들드 스킬 (batch, debug, loop 등)
cli	19	CLI 트랜스포트 (SSE, WebSocket, Hybrid)
keybindings	14	커스터마이저블 키바인딩
types	11	타입 정의
migrations	11	모델/설정 마이그레이션
memdir	8	메모리 디렉토리 (자기 치유 메모리)
entrypoints	8	CLI, MCP, SDK 진입점

나머지 서브시스템

서브시스템	모듈 수	역할
buddy	6	마스코트 캐릭터 UI
state	6	전역 앱 상태 관리
vim	5	Vim 모드
native_ts	4	네이티브 모듈 (color-diff, yoga-layout)
remote	4	원격 세션 관리
screens	3	Doctor, REPL, Resume 화면
server	3	DirectConnect 세션
plugins	2	플러그인 시스템
upstreamproxy	2	프록시 릴레이
voice	1	음성 모드
coordinator	1	에이전트 조율
assistant	1	세션 히스토리
bootstrap	1	부트스트랩 상태
outputStyles	1	출력 스타일
schemas	1	훅 스키마
moreright	1	추가 권한

vim이 독립 서브시스템으로 존재한다는 것이 재미있습니다. motions, operators, textObjects까지 구현되어 있으니 상당히 진지하게 Vim 키바인딩을 지원하고 있습니다. voice 서브시스템의 존재도 흥미롭습니다 — 아직 1개 모듈(활성화 체크)뿐이지만, 음성 입력 기능이 개발 로드맵에 있었다는 것을 시사합니다.

루트 레벨 파일들 — 프로젝트의 뼈대

서브시스템 외에도, 루트 레벨에 위치한 파일들이 프로젝트의 뼈대 역할을 합니다.

QueryEngine.ts      → 핵심: 턴 루프, 스트리밍, 세션, 트랜스크립트
Task.ts             → 태스크 구조 정의
Tool.ts             → 도구 정의 데이터클래스
commands.ts         → 207개 커맨드 메타데이터
tools.ts            → 184개 도구 메타데이터
context.ts          → 워크스페이스 컨텍스트 빌더
cost-tracker.ts     → 비용 추적
costHook.ts         → 매 API 호출마다 비용 기록
main.tsx            → CLI 진입점 (React/Ink 기반)
setup.ts            → 초기 설정
history.ts          → 이벤트 로깅
dialogLaunchers.tsx → 대화형 UI 런처
replLauncher.tsx    → REPL 런처

main.tsx와 replLauncher.tsx의 확장자가 .tsx라는 점을 주목할 만합니다. CLI 도구의 진입점이 React 컴포넌트라는 뜻입니다. Ink 라이브러리를 통해 터미널에서 React를 렌더링하는 구조인 것입니다.

7단계 부트스트랩 — Claude Code는 어떻게 시작되는가

Claude Code를 터미널에서 실행하면, 프롬프트가 나타나기까지 어떤 일이 벌어질까요? claw-code의 Python 포트에서는 이를 7단계 부트스트랩 그래프로 정리하고 있습니다.

단계 1: 프리페치 사이드 이펙트
        ├── MDM(Mobile Device Management) 정책 읽기
        ├── 키체인 프리페치
        └── 프로젝트 디렉토리 스캔

단계 2: 경고 핸들러와 환경 가드
        ├── 환경 변수 검증
        └── 호환성 체크

단계 3: CLI 파서와 신뢰 게이트
        ├── 인자 파싱 (argparse/clap)
        └── 신뢰 검증 (pre-action trust gate)

단계 4: 설정 로딩 + 병렬 초기화
        ├── CLAUDE.md 로딩
        ├── .claude.json 설정 로딩
        ├── 커맨드 레지스트리 구성
        └── 에이전트 정의 로딩

단계 5: 신뢰 후 지연 초기화
        ├── 플러그인 초기화
        ├── 스킬 초기화
        ├── MCP 서버 프리페치
        └── 세션 훅 등록

단계 6: 모드 라우팅
        ├── local (기본)
        ├── remote (원격 서버)
        ├── ssh / teleport
        ├── direct-connect
        └── deep-link

단계 7: 쿼리 엔진 제출 루프 진입
        └── 에이전틱 루프 시작

몇 가지 흥미로운 점이 보입니다.

먼저, 단계 3의 "신뢰 게이트"입니다. CLI를 파싱한 직후, 본격적인 초기화에 들어가기 전에 신뢰 검증을 수행합니다. 이 게이트를 통과해야만 단계 5에서 플러그인, 스킬, MCP 등이 초기화됩니다. 신뢰할 수 없는 환경에서는 이런 확장 기능이 로드되지 않는 구조인 것입니다.

그리고 단계 6의 모드 라우팅입니다. local 외에도 remote, ssh, teleport, direct-connect, deep-link라는 5가지 실행 모드가 정의되어 있습니다. teleport가 무엇인지는 정확히 알 수 없지만, Claude Code가 단순 로컬 CLI를 넘어 다양한 원격 실행 환경을 고려하고 있다는 것을 보여줍니다.

마지막으로, 단계 4에서 CLAUDE.md 로딩이 이루어진다는 점입니다. 사용자가 작성한 프로젝트 지침서가 부트스트랩 과정의 일부로 읽히는 것입니다. 다시 말해, CLAUDE.md는 단순한 참고 문서가 아니라 시스템 초기화의 구성 요소입니다.

커맨드 207개 — 무엇이 가능한가

아키텍처 스냅샷에는 207개의 커맨드가 기록되어 있습니다. 현재 사용자에게 노출된 것은 일부이지만, 내부적으로 이만큼의 명령어 체계가 존재합니다. 카테고리별로 정리하면 다음과 같습니다.

개발 핵심

commit, diff, branch, review, autofix-pr — Git 워크플로우 전반을 커버합니다.

에이전트/자동화

agents, plan, ultraplan, ultrareview, tasks, batch — ultraplan이라는 이름이 눈에 띕니다. 일반 plan보다 한 단계 높은 수준의 계획 기능을 시사합니다.

플러그인 생태계

DiscoverPlugins, ManagePlugins, ManageMarketplaces, install, install-github-app, reload-plugins — 마켓플레이스 기반의 플러그인 설치/관리 시스템이 갖춰져 있습니다.

환경/진단

doctor, ant-trace, cost, usage, stats, insights — ant-trace는 Anthropic의 내부 트레이싱 도구로 추정됩니다.

연동/확장

mcp, oauth, ide, desktop, mobile, chrome, teleport — mobile과 chrome 커맨드의 존재가 흥미롭습니다. 모바일 앱이나 Chrome 확장과의 연동 인터페이스가 준비되어 있었다는 뜻입니다.

메모리/스킬

memory, skills, hooks, theme, vim, voice, keybindings — 사용자 커스터마이징을 위한 진입점들입니다.

마이그레이션이 말해주는 모델 진화

11개의 마이그레이션 파일도 흥미로운 이야기를 들려줍니다. 이 파일들에서 Claude 모델의 내부 코드네임과 진화 경로를 유추할 수 있습니다.

fennec → opus          (Fennec이 Opus의 코드네임이었을 가능성)
opus → opus1m          (1M 컨텍스트 윈도우 확장)
sonnet1m → sonnet45    (Sonnet 4.5로 업그레이드)
sonnet45 → sonnet46    (Sonnet 4.6으로 업그레이드)

fennec이라는 코드네임이 특히 눈길을 끕니다. Fennec은 사막여우를 뜻하는데, Anthropic이 내부적으로 모델에 동물 코드네임을 사용하고 있었던 것으로 보입니다.

1편을 마치며 — 조감도에서 본 것

512,000줄의 코드를 위에서 내려다보면, Claude Code는 세 가지 축으로 이해할 수 있습니다.

첫째, 에이전틱 루프입니다. QueryEngine이라는 핵심 엔진이 모델의 도구 호출을 무한 반복하며 자율적으로 작업을 수행합니다. 이것이 Claude Code의 심장입니다.

둘째, 도구와 권한입니다. 184개의 도구가 에이전트의 손과 발이 되고, 5단계 권한 모델과 훅 시스템이 안전장치 역할을 합니다.

셋째, 연결과 확장입니다. Bridge, MCP, 플러그인, 원격 실행 — Claude Code는 단독으로 동작하는 CLI가 아니라 다양한 환경과 연결되는 허브로 설계되어 있습니다.

다음 편에서는 이 중 첫 번째 축, 에이전틱 루프의 내부 구조를 자세히 들여다보겠습니다. ConversationRuntime의 무한 루프, 184개 도구의 등록과 디스패치, 그리고 "이 도구를 자동 실행할 것인가, 사용자에게 물어볼 것인가"를 결정하는 권한 모델의 설계를 살펴봅니다.

시리즈 안내
1편: 512,000줄의 전체 조감도 (현재 글)
2편: 에이전틱 루프 — 도구, 권한, 훅의 삼중주
3편: 메모리와 컨텍스트 — 잊지 않는 AI의 비밀
4편: Bridge, MCP, 멀티 에이전트 — 단순 CLI를 넘어서