안녕하세요! 오늘은 최근 개발자 커뮤니티를 뜨겁게 달궜던 Claude Code 의 내부 소스 코드 분석 내용을 공유해 드리려고 합니다.
Claude Code는 단순한 챗봇을 넘어, 터미널에서 직접 코드를 수정하고 테스트를 실행하는 'AI 소프트웨어 엔지니어' 를 지향합니다. 약 1,884개의 TypeScript 및 React 파일로 구성된 이 거대한 프로젝트가 어떤 철학으로 설계되었는지, 핵심 엔진부터 UI 최적화 기법까지 하나씩 살펴보겠습니다.
1. Claude Code의 핵심 아키텍처
Claude Code의 동작은 크게 4단계의 파이프라인 으로 구성됩니다. 모든 설계 결정은 안전성, 성능, 확장성 이라는 세 가지 원칙을 따르고 있습니다.
주요 동작 흐름
- 시작과 초기화 (Startup): 인증(OAuth/API Key), 모델 선택, Git 상태 및
CLAUDE.md컨텍스트 수집. - 대화 루프 (Query Loop): 사용자의 입력을 Claude API에 스트리밍으로 보내고 응답을 처리.
- 도구 실행 (Tool Execution): AI가 요청한
tool_use블록을 해석하여 파일 읽기/쓰기, 셸 명령 등을 실행. - 결과 표시 (Display): React 기반의 Ink 프레임워크를 사용하여 터미널 UI(TUI) 렌더링.
2. 심장부: query.ts와 비동기 제너레이터
Claude Code의 핵심 엔진인 query.ts는 비동기 제너레이터(Async Generator) 패턴을 사용합니다. 이는 API 응답이 도착하는 즉시 한 글자씩 사용자에게 보여주기 위함입니다.
턴(Turn) 처리 로직
대화가 길어지면 토큰 제한에 걸리기 마련인데, Claude Code는 이를 해결하기 위해 정교한 메시지 전처리 전략을 사용합니다.
- Snip Compact: 너무 오래된 메시지는 통째로 제거.
- Microcompact: 도구 사용 기록(
tool_use)을 인라인으로 축소하여 부피를 줄임. - Auto-Compact: 토큰 한계치에 근접하면 AI가 지금까지의 대화를 스스로 요약하게 함.
Note: 413(Prompt Too Long) 에러가 발생하면 사용자에게 에러를 띄우기 전, 내부적으로 컨텍스트 축소를 먼저 시도하는 'Withhold & Recover' 패턴이 인상적입니다.
3. 도구(Tool) 시스템: AI의 팔과 다리
Claude AI 자체는 파일을 읽거나 명령어를 칠 수 없습니다. Claude Code는 45개 이상의 내장 도구 를 통해 AI에게 권한을 부여합니다.
안전한 실행을 위한 설계
가장 강력하면서 위험한 도구는 BashTool입니다. rm -rf / 같은 파괴적인 명령을 방지하기 위해 Claude Code는 다음과 같은 방어선을 구축했습니다.
- Tree-sitter 분석: 셸 명령어의 구문 트리(AST)를 분석합니다.
- Fail-closed 설계: 안전하다고 증명된 화이트리스트 구문만 통과시키고, 모호하면 차단합니다.
- 병렬성 제어: 읽기 전용 도구는 최대 10개까지 병렬 실행하지만, 수정 도구는 순차적으로 하나씩 실행합니다.
4. 터미널 UI의 혁신: React와 Ink
Claude Code의 UI는 웹 개발자들에게 친숙한 React 로 작성되었습니다. 터미널이라는 제한된 환경에서 고성능 UI를 구현하기 위해 몇 가지 독특한 최적화 기법이 적용되었습니다.
TUI 렌더링 최적화
- 이중 버퍼링 (Double Buffering): '현재 화면'과 '다음 화면' 버퍼를 비교하여 변경된 셀만 업데이트함으로써 깜빡임을 방지합니다.
- 객체 풀링 (Object Pooling): 동일한 문자열이나 ANSI 스타일 코드를 재사용하여 메모리 오버헤드를 줄입니다.
- Yoga Layout Engine: 터미널에서도 Flexbox 레이아웃을 사용할 수 있게 해줍니다.
5. 권한 및 훅(Hook) 시스템
사용자의 자산을 보호하기 위해 Claude Code는 매우 세밀한 권한 모드 를 제공합니다.
| 모드 | 특징 |
|---|---|
| Default | 읽기는 자동, 쓰기/실행은 사용자 승인 필요 |
| Auto | AI 분류기가 위험도를 평가하여 안전하면 자동 승인 |
| Plan | 읽기 전용 도구만 허용하여 계획 수립에만 집중 |
| Bypass | 모든 작업을 자동 승인 (주의 필요) |
또한, PreToolUse나 PostToolUse 같은 훅 시스템 을 통해 도구 실행 전후에 사용자 정의 로직(예: 린터 자동 실행, 보안 검사)을 끼워 넣을 수 있습니다.
결론: 단순한 도구 그 이상의 설계
Claude Code의 소스 코드를 분석하며 느낀 점은, 단순히 AI API를 호출하는 래퍼가 아니라는 것입니다. CLI 환경에서의 사용자 경험(UX) 을 극대화하기 위해 시작 속도 최적화(main.tsx 단일화), 토큰 관리, 복구 메커니즘 등 엔지니어링 측면에서 배울 점이 매우 많았습니다.
특히 복합적인 에이전트 오케스트레이션(Coordinator Mode) 과 영속적 메모리 시스템 은 앞으로 AI CLI 도구가 나아가야 할 방향을 명확히 제시하고 있습니다.