Claude Code 아키텍처 심층 분석: 유출된 소스 코드가 밝혀낸 것들

안녕하세요, 저는 Dora입니다. 2026년 3월, 저는 이런 토끼굴에 빠질 생각이 전혀 없었습니다. 그런데 피드에 메시지 하나가 떴습니다: “​Claude Code 소스 코드가 npm 레지스트리의 맵 파일을 통해 유출되었습니다.​”

저는 보고 있던 탭을 닫고 뒤도 돌아보지 않았습니다.

그 뒤로 이어진 오후는 프로덕션 AI 도구가 실제로 어떻게 만들어지는지 공부하면서 보낸 시간 중 가장 흥미로운 시간 중 하나였습니다. 유출 사태 때문이 아니라 — 그건 금방 식상해지니까 — 이 코드가 보기 드문 것이기 때문입니다: 실제로 출시되어 상업적으로 지배적인 에이전틱 CLI를 512,000줄의 세부 사항으로 들여다볼 수 있는 기회였습니다.

제가 발견한 것들을 공유합니다.

유출된 소스 코드가 드문 아키텍처 연구 기회인 이유

Claude Code가 유출된 후, Anthropic의 자체 npm 패키지에 잘못 설정된 .map 파일을 통해 소스가 노출되었으며 — 개발자들은 이것이 단순히 채팅 API를 감싼 래퍼가 아니라는 사실을 금방 알아챘습니다. cybersecuritynews.com의 사건 분석에 따르면, 노출된 내용에는 약 1,900개의 파일과 ​512,000줄 이상의 엄격한 TypeScript​가 포함되어 있으며, 기본 진입점 하나만 해도 785KB에 달합니다.

스택 자체도 흥미롭습니다: 런타임으로는 Node.js가 아닌 Bun을 사용하고, 터미널 UI 렌더링을 위해 Ink와 함께 React를 사용하며, 전반에 걸쳐 스키마 검증을 위한 Zod v4를 사용합니다. CLI에서 React 컴포넌트 패턴을 사용한다는 것은 터미널 내에서 상태 관리, 리렌더링, 그리고 조합 가능한 UI 컴포넌트를 사용한다는 의미입니다. 의도적이고 과감한 선택입니다.

밈을 넘어서 이것이 연구할 가치가 있는 이유: 여기서 보이는 Claude Code 아키텍처 패턴은 진지한 에이전틱 시스템을 구축하는 모든 팀에 적용될 수 있습니다.

툴 시스템 — 40개 이상의 독립적인 권한 게이트 모듈

제가 처음으로 눈에 띈 것은 툴 시스템이 얼마나 깔끔하게 격리되어 있는가였습니다. 모든 툴은 자체적인 입력 스키마, 권한 레벨, 그리고 실행 로직을 — 독립적으로 — 정의합니다. 툴 간에 공유되는 변경 가능한 상태가 없습니다.

BashTool과 FileReadTool은 동일한 레지스트리에 존재하지만 근본적으로 다른 위험 프로필을 가집니다. Bash 실행은 시스템 상태를 변경할 수 있지만, 파일 읽기는 읽기 전용입니다. 아키텍처는 이를 그에 맞게 처리하여, 일괄 정책을 적용하는 대신 각각을 고유한 권한 레벨 뒤에 배치합니다. 이 분리는 프로덕션 에이전틱 시스템에서 매우 중요한데, 툴 간에 권한 모델이 누출되면 보안 및 안정성 문제로 이어지기 때문입니다.

AgentTool이 영리한 부분입니다. 이 툴은 시스템이 하위 에이전트를 또 다른 툴 호출로 생성할 수 있게 해줍니다 — ​별도의 오케스트레이션 레이어도 필요 없고, 별도의 프로세스 모델도 필요 없습니다​. 하위 에이전트는 동일한 툴 레지스트리의 일급 시민입니다. 이 설계 결정은 아키텍처를 평평하고 예측 가능하게 유지합니다.

기본 툴 정의만 해도 약 29,000줄의 TypeScript에 달합니다. 이것은 비대해진 것이 아닙니다 — 이 규모에서 엄격한 스키마 검증, 권한 적용, 그리고 오류 처리가 실제로 어떤 모습인지를 보여주는 것입니다. Anthropic의 공식 Claude Code 문서는 이 툴 중심 철학을 확인해줍니다: 툴이야말로 시스템을 에이전틱하게 만드는 것입니다.

46,000줄의 쿼리 엔진 — Claude Code의 진짜 두뇌

QueryEngine.ts는 46,000줄입니다. 잠시 그 의미를 생각해 보시기 바랍니다.

이 모듈은 모든 LLM API 호출, 스트리밍, 캐싱, 그리고 오케스트레이션을 처리합니다. 단일 파일에서. 이것은 경고 신호처럼 보일 수 있고 — 코드베이스 관례에 따라 의문을 제기하는 것이 당연합니다 — 하지만 그 이유는 일관성이 있습니다: 모델 API를 건드리는 모든 것이 한 곳에 있다는 의미로, 재시도 로직, 속도 제한 처리, 컨텍스트 예산 관리, 스트리밍 오류가 모두 함께 고려됩니다.

자가 치유 쿼리 루프는 예상치 못하게 제 관심을 끈 부분입니다. 컨텍스트 예산이 한계에 가까워지면, 엔진은 충돌하거나 도움을 요청하지 않습니다. 자동으로 압축을 트리거하고, 한계에 도달하기 전에 버퍼를 확보하며 지금까지 논의된 내용의 구조화된 요약을 생성합니다. 이것은 임시방편이 아닙니다 — 의도적인 동작입니다. 장시간 실행되는 에이전트 세션을 구축하는 누구에게나, 이 패턴은 직접적으로 연구할 가치가 있습니다.

멀티 에이전트 오케스트레이션 — 코디네이터, 워커, 그리고 메일박스 패턴

멀티 에이전트 시스템은 유출된 소스에서 위험한 작업을 위한 메일박스 패턴이라고 부르는 것을 사용합니다. 실제로 어떤 의미인지 설명하겠습니다: 작업을 실행하는 워커 에이전트는 고위험 작업을 독립적으로 승인할 수 없습니다. 대신, 코디네이터의 메일박스에 요청을 보내고 기다립니다. 코디네이터가 평가하여 승인하거나 거부합니다.

원자적 클레임 메커니즘은 두 워커가 동시에 같은 승인을 처리하는 것을 방지합니다 — 병렬 실행이 있는 모든 시스템에서 미묘하지만 중요한 세부 사항입니다. 모든 에이전트에 걸친 공유 메모리 공간은 팀이 중복된 재가져오기 없이 일관된 컨텍스트를 유지할 수 있게 합니다.

이것은 모든 에이전트가 완전한 자율성으로 작동하는 단순한 멀티 에이전트 설계와 의미 있는 차이입니다. 승인 게이트가 있는 코디네이터/워커 분리는 혼돈 없이 병렬 처리를 얻는 방법입니다. 자체 에이전틱 시스템을 위한 오케스트레이션 레이어를 구축하는 팀은 자체 설계 전에 Anthropic의 에이전틱 패턴 문서를 꼭 읽어보는 것이 좋습니다.

3계층 컨텍스트 압축 — 장시간 세션을 위한 엔지니어링

이것은 아마도 프로덕션 AI 애플리케이션을 구축하는 누구에게나 전체 코드베이스에서 가장 직접적으로 유용한 엔지니어링 부분일 것입니다.

Claude Code는 각각 다른 시점에 트리거되는 세 가지 뚜렷한 압축 전략을 사용합니다:

MicroCompact는 API 호출 없이 로컬에서 캐시된 콘텐츠를 편집합니다. 오래된 툴 출력이 직접 잘려나갑니다. 빠르고, 저렴하며, 투명합니다.

AutoCompact는 대화가 컨텍스트 윈도우 한계에 가까워지면 실행됩니다. 13,000토큰 버퍼를 예약한 후, 세션의 최대 20,000토큰 구조화된 요약을 생성합니다. 내장된 서킷 브레이커가 있습니다 — 세 번 연속 압축 실패 후에는 재시도를 멈춥니다. 무한 루프가 없습니다.

Full Compact는 전체 대화를 압축한 후, 최근에 접근한 파일(파일당 5,000토큰 제한), 활성 계획, 관련 스킬 스키마를 다시 주입합니다. 압축 후, 작업 예산은 50,000토큰으로 재설정됩니다.

주목할 점은 이 아키텍처가 압축을 완전히 생략하는 툴에 대해 암시하는 것입니다. 컨텍스트 예산을 관리하지 않는 에이전틱 툴은 규모에서 단순히 실패합니다 — 조용히 저하되거나 하드 오류에 부딪힙니다. 3계층 접근 방식은 나중에 덧붙이는 것이 아닌, ​처음부터 세션 지속성을 위해 설계한​ 드문 사례입니다.

아키텍처로서의 피처 플래그 — 프로덕션에 존재하지 않는 108개 모듈

유출된 소스에서 덜 논의된 발견 중 하나: ​108개의 피처 게이트 모듈​이 Bun의 컴파일 타임 데드 코드 제거를 통해 외부 빌드에서 제거됩니다.

KAIROS, VOICE_MODE, DAEMON — 이것들은 여러분이 설치하는 버전에 존재하지 않습니다. 코드는 소스에 있지만, Bun이 피처 플래그 설정에 따라 컴파일 타임에 제거합니다. 프로덕션 번들은 깔끔하게 출시됩니다. 이것이 이미 사용자 손에 있는 것을 건드리지 않고 새로운 기능을 반복하는 방법입니다.

아이러니도 잘 문서화되어 있습니다: git 커밋이나 출력에 내부 코드명이 나타나지 않도록 특별히 설계된 서브시스템인 Undercover Mode가 유출된 소스에 존재했습니다. 유출을 방지하기 위해 구축된 시스템이 유출 자체를 막지 못했습니다. 치명적인 보안 실패는 아니지만, 소프트웨어 전달 파이프라인에서 위험이 실제로 어디에 축적되는지에 대한 교훈적인 사례입니다.

핵심 루프에 내장된 텔레메트리

유출된 소스에서 계속 생각하게 만드는 두 가지 텔레메트리 신호:

좌절 지표는 UX 신호로 욕설 빈도를 추적합니다. 사용자가 툴에 욕을 하고 있다면, 무언가가 무너지고 있는 것입니다 — 후행 지표가 아닌 선행 지표입니다.

“계속” 카운터는 사용자가 세션 중간에 “continue”라는 단어를 얼마나 자주 입력하는지 추적합니다. 에이전틱 CLI에서, 이것은 에이전트가 모멘텀을 잃고 사람이 앞으로 밀어야 했던 순간인 정체의 대리 지표입니다.

어느 것도 허영 지표가 아닙니다. 두 가지 모두 표준 분석이 놓칠 특정 실패 모드를 드러냅니다. 장시간 상호작용 세션을 가진 AI 제품을 구축한다면, 이런 식으로 에이전트 동작을 계측하는 것은 엔지니어링 시간을 투자할 가치가 있습니다.

이것이 빌더에게 스택 결정에 대해 알려주는 것

이 ​claude code 아키텍처​를 연구하면서 얻은 솔직한 교훈: 처음부터 프로덕션 에이전틱 CLI를 구축하는 것은 상당한 엔지니어링 투자가 필요합니다. 툴 시스템, 쿼리 엔진, 멀티 에이전트 오케스트레이션, 컨텍스트 압축, 텔레메트리 — 이것들은 함께 몇 달이 아닌 수년간의 반복을 나타냅니다.

이것은 구축하지 말라는 주장이 아닙니다. 무엇을 떠맡는지 명확히 하라는 주장입니다. 메일박스 승인 시스템과 3계층 압축 같은 패턴은 내보낼 수 있습니다 — 핵심 아이디어를 구현하는 데 512,000줄이 필요하지 않습니다.

빌드 대 구매 계산이 바뀌는 곳은 모델 접근 및 집계에 있습니다. 아키텍처는 단일 모델 제공업체에 대한 직접 접근을 가정합니다. 여러 모델 제공업체에 걸쳐 작업하거나, 모델에 구애받지 않는 상태를 유지해야 하는 제품을 구축하는 팀은 완전히 다른 트레이드오프에 직면합니다.

여기서의 패턴은 빌려올 가치가 있습니다. 복잡성은 복제에 전념하기 전에 이해할 가치가 있습니다.

FAQ

Claude Code의 툴 시스템은 표준 함수 호출과 어떻게 다른가요?

표준 함수 호출은 툴을 평평한 목록으로 처리합니다. Claude Code는 툴별 권한 게이트, 격리된 실행 컨텍스트, 모든 경계에서의 스키마 검증을 추가합니다 — 크로스 툴 상태 누출을 방지하고 최소 권한 접근을 강화하는데, 이는 BashTool이 시스템 상태를 수정할 수 있을 때 중요합니다.

메일박스 패턴이란 무엇이고, 빌더는 언제 사용해야 하나요?

워커 에이전트에서 위험한 작업을 자율적으로 실행하는 대신 승인을 위해 코디네이터로 라우팅합니다. 병렬 에이전트 실행이 있고 고위험 작업에 대한 휴먼 인 더 루프 또는 계층적 승인 메커니즘이 필요할 때마다 사용하세요. ​처리량 비용, 안전성 향상.

Claude Code는 규모에서 컨텍스트 윈도우 제한을 어떻게 처리하나요?

3계층 압축: MicroCompact(로컬 편집, API 비용 없음), AutoCompact(한계 근처에서 트리거, 예약된 토큰 버퍼와 함께 구조화된 요약 생성), Full Compact(선택적 파일 재주입과 함께 전체 대화 압축). 수동 개입 없이 장시간 세션을 위해 설계되었습니다.

컴파일 타임 피처 플래그란 무엇이고, 프로덕션 AI 툴은 왜 사용하나요?

출시되지 않은 기능을 위한 코드가 프로덕션 빌드에 나타나지 않고 소스에 존재할 수 있게 합니다. Bun은 컴파일 타임에 플래그가 꺼진 코드를 제거하므로, 외부 사용자는 준비되지 않은 기능을 절대 만나지 않습니다 — 출시와 준비 상태를 분리합니다.

아키텍처 영감을 위해 유출된 소스를 공부하고 참조하는 것이 합법적인가요?

신중하게 다룰 필요가 있습니다. 유출된 소스는 Anthropic의 지적 재산입니다. 교육적 목적으로 아키텍처 패턴을 공부하는 것은 코드를 직접 복사하는 것과 다른 영역에 있습니다. Anthropic의 공식 문서는 그들의 시스템 위에 구축할 모든 것에 대한 적절한 참고자료입니다. 의심스러운 경우, 자체 법률 고문과 상담하세요.

계속 떠오르는 생각은 이 아키텍처의 얼마나 많은 부분이 실패를 우아하게 관리하는 것에 관한 것인지입니다. 압축의 서킷 브레이커, 위험한 작업을 위한 메일박스 패턴, 툴 간의 권한 격리 — 이것들은 낙관적인 설계가 아닙니다. 무언가가 잘못되는 것을 지켜보고 그것을 엔지니어링으로 해결하기로 결정한 사람들에 의해 만들어졌습니다.

그것은 기능 속도와는 다른 종류의 성숙함입니다.

오늘의 공유는 여기까지입니다. 다음에 또 만나요.

이전 포스트:

• 실제 성능과 비용 측면에서 GPT-5, DeepSeek 및 기타 모델 비교
• DeepSeek V4 컨텍스트 캐싱과 장시간 세션 효율성 개선 방법 이해
• 프로덕션 시스템을 위한 DeepSeek V4 속도 제한 및 확장 제약 사항 알아보기
• 대규모 애플리케이션을 위한 DeepSeek V4 가격 및 백만 토큰당 비용 살펴보기
• 실제 배포에서 DeepSeek V4에 필요한 GPU VRAM 확인