Claude Code 개요와 소스 구조

Claude Code란 무엇인가

Claude Code는 Anthropic이 공식 제공하는 CLI 기반 AI 코딩 에이전트입니다. 터미널에서 직접 실행되며, 파일 읽기·쓰기·편집, 셸 명령 실행, 웹 검색 등 실제 개발 작업을 수행할 수 있습니다.

v2.1.88 기준으로 약 1,900개 소스 파일, 512,000줄 이상 의 TypeScript 코드로 구성되어 있습니다. 런타임은 Bun 을 사용하며, CLI 파싱에 Commander.js, 터미널 UI에 React/Ink, 스키마 검증에 Zod v4 를 채택했습니다.

핵심 파일 규모

파일	크기	역할
`QueryEngine.ts`	~46,000줄	LLM API 호출, 스트리밍, 도구 루프, 토큰 카운팅
`Tool.ts`	~29,000줄	도구 기본 타입 정의 및 인터페이스
`commands.ts`	~25,000줄	명령어 등록, 환경별 조건부 임포트
`main.tsx`	진입점	Commander.js CLI 파서 + React/Ink UI

로컬 실행 원칙

Claude Code의 핵심 설계 철학은 다음 한 문장으로 요약됩니다.

“The loop runs entirely in your terminal process. There is no remote execution server.”

이것이 의미하는 바는 다음과 같습니다.

파일 시스템 — 모든 파일 접근은 로컬 디스크에서 직접 이루어집니다
셸 명령 — Bash 도구는 사용자의 로컬 터미널 프로세스에서 실행됩니다
자격 증명 — API 키, SSH 키 등 모든 자격 증명은 로컬에 유지됩니다
에이전트 루프 — 추론과 도구 실행 사이클이 원격 서버 없이 로컬에서 동작합니다

클라우드로 전송되는 것은 오직 Anthropic API 호출 (텍스트 메시지) 뿐입니다.

8대 서브시스템

Claude Code의 소스 코드는 목적에 따라 8개의 서브시스템으로 분류됩니다.

#	서브시스템	주요 디렉토리	역할
1	Core Architecture	`src/core/`	에이전틱 루프, 쿼리 엔진, 상태 관리
2	Tool System	`src/tools/`	~40개 도구 — 파일·셸·검색·웹·에이전트
3	Agent Intelligence	`src/agents/`	서브에이전트 스폰, 코디네이터, 스웜
4	Interface	`src/ui/`	React/Ink 터미널 UI, ~50개 슬래시 명령어
5	Infrastructure	`src/infra/`	설정, 훅, 스킬, 권한, 텔레메트리
6	Connectivity	`src/bridge/`, `src/mcp/`	브릿지(IDE 통신), MCP, OAuth
7	SDK	`src/sdk/`	JSON 스트림 통신, TypeScript API
8	Unreleased Features	`src/experimental/`	BUDDY, KAIROS, ULTRAPLAN, Daemon

기술 스택

계층	기술
런타임	Bun (TypeScript strict 모드)
CLI 파싱	Commander.js
터미널 UI	React + Ink
스키마 검증	Zod v4
프로토콜	MCP SDK, LSP, OAuth 2.0
인증	JWT, macOS Keychain 통합
텔레메트리	OpenTelemetry + gRPC (지연 로딩)
빌드	Bun의 `bun:bundle` (피처 플래그 기반 데드코드 제거)

주요 디렉토리 구조

claude-code/
├── src/
│   ├── core/          # 에이전틱 루프 핵심 로직
│   │   ├── QueryEngine.ts  # ~46K줄, 모델 호출·스트리밍·도구 루프
│   │   ├── context.ts      # 컨텍스트 어셈블리
│   │   └── main.tsx        # CLI 진입점 (Commander.js + React/Ink)
│   ├── tools/         # ~40개 도구 구현
│   │   ├── Tool.ts         # ~29K줄, 도구 기본 타입 정의
│   │   ├── bash.ts         # 셸 명령 실행
│   │   ├── read.ts         # 파일 읽기
│   │   ├── edit.ts         # 파일 편집
│   │   └── web-fetch.ts    # 웹 접근
│   ├── commands/      # ~50개 슬래시 명령어
│   │   └── commands.ts     # ~25K줄, 명령어 등록
│   ├── agents/        # 에이전트 시스템
│   │   ├── task.ts         # Task(AgentTool) 구현
│   │   └── coordinator.ts  # 코디네이터 모드, 스크래치 디렉토리
│   ├── bridge/        # IDE 통신
│   │   └── bridge.ts       # WebSocket + JWT 인증
│   ├── hooks/         # 훅과 권한
│   │   └── toolPermission/ # 도구 실행 전 권한 검사
│   ├── ui/            # 터미널 인터페이스
│   │   ├── repl.tsx        # 대화형 REPL
│   │   └── components/     # Ink 컴포넌트
│   └── mcp/           # MCP 연결
│       ├── client.ts       # MCP 클라이언트
│       └── server.ts       # 로컬 MCP 서버
├── package.json
└── tsconfig.json

전체 아키텍처 흐름

사용자가 명령을 입력하면 다음 순서로 처리됩니다.

사용자 입력
    ↓
[Interface Layer]  ← React/Ink REPL 또는 --print 모드
    ↓
[Core Loop]        ← 컨텍스트 어셈블리 + 모델 호출
    ↓
[Tool System]      ← 도구 권한 평가 및 실행
    ↓
[Infrastructure]   ← 설정, 로깅, 상태 저장
    ↓
외부: Anthropic API / MCP 서버 / 파일 시스템

왜 소스 구조를 이해해야 하는가

Claude Code를 단순히 사용하는 것을 넘어 효과적으로 활용 하려면 내부 동작 원리를 파악해야 합니다.

프롬프트 최적화 — 컨텍스트가 어떻게 조립되는지 알면 더 나은 지시를 작성할 수 있습니다
도구 선택 — 각 도구의 동작 방식을 알면 적절한 도구를 선택할 수 있습니다
에이전트 설계 — 에이전트 격리 모델을 이해하면 멀티에이전트 워크플로를 설계할 수 있습니다
문제 해결 — 예상치 못한 동작의 원인을 빠르게 파악할 수 있습니다

이후 챕터에서는 각 서브시스템을 순서대로 깊이 탐구합니다.