총평 및 핵심 요약
Claude Code는 단순한 챗봇을 넘어 사용자의 로컬 컴퓨터(터미널)에서 직접 파일을 읽고, 코드를 수정하며, 명령어를 실행하는 'AI 소프트웨어 엔지니어' 도구입니다.
이 시스템의 설계는 다음 세 가지 핵심 원칙을 따릅니다:
- 안전성: 위험한 시스템 명령(예: 파일 삭제)을 차단하고 권한을 철저히 검증
- 성능: API 스트리밍, 병렬 실행, 캐싱 및 자동 메모리 최적화
- 확장성: 45개 이상의 내장 도구(Tool) 및 MCP(Model Context Protocol)를 통한 외부 연동
전체 구조
+---------------------+
| User types in |
| the terminal |
+---------+-----------+
|
v
+---------------------+ Phase 1: STARTUP
| main.tsx | - Auth (OAuth / API key / Bedrock / Vertex)
| (initialization) | - Model selection
| | - Load settings & feature gates
+---------+-----------+ - Collect Git status + CLAUDE.md
|
v
+---------------------+ Phase 2: QUERY LOOP
| query.ts | - Send messages to Claude API (streaming)
| (core engine) |<-+ - Receive response token by token
| | | - Detect tool_use blocks in response
+---------+-----------+ |
| |
v |
+---------------------+ | Phase 3: TOOL EXECUTION
| Tool Pipeline | | - Validate input (Zod schema)
| (45+ built-in | | - Check permissions (rules + classifier)
| tools + MCP) | | - Execute tool (Bash, Read, Edit, ...)
+---------+-----------+ | - Return result to API
| |
+--------------+ (loop until no more tool_use)
|
v
+---------------------+ Phase 4: DISPLAY
| Ink TUI (React) | - Render messages, diffs, progress
| terminal display | - Show tool results
+---------------------+ - Await next user input4단계 핵심 동작 루프 (Core Engine)
프로그램의 심장부인 query.ts를 중심으로 다음 과정이 도구 사용이 끝날 때까지 무한 반복됩니다.
시작 및 초기화 (Startup): 인증 진행, 모델 선택, Git 상태 및 프로젝트 지침(CLAUDE.md) 수집
대화 루프 (Query Loop): 사용자의 요청과 컨텍스트를 API로 전송하고 스트리밍으로 응답 수신 (토큰 한계 도달 시 이전 대화 자동 요약/압축)
도구 실행 (Tool Execution): AI가 판단한 도구(파일 읽기, Bash 실행 등)를 권한 확인 후 실행. 안전한 도구는 최대 10개까지 병렬로, 위험한 도구는 순차적으로 하나씩 실행.
결과 표시 (Display): 자체 제작한 React 기반 터미널 UI(Ink)를 통해 진행 상황과 결과를 시각적으로 렌더링
주요 시스템 및 기능
다중 실행 모드: 일반적인 대화형(REPL) 모드 외에도, UI 없는 헤드리스(Headless) 모드, 리더 AI가 여러 워커 AI를 부리는 코디네이터(Coordinator) 모드, 웹 환경(claude.ai)과 로컬을 연결하는 브리지(Bridge) 모드 등 다양한 환경을 지원합니다.
도구(Tool) 및 권한(Permission) 시스템: * 도구: Bash, FileEdit, Grep, Agent(서브에이전트 고용) 등 45종의 도구를 통해 외부 세계와 상호작용합니다.
안전망: 사용자 확인(Default), AI 자동 분류(Auto), 읽기 전용(Plan) 등 세밀한 권한 모드를 통해 위험한 셸 명령어 실행을 방지하는 다중 검증 파이프라인을 거칩니다.
기억 및 상태 관리: * 메모리 시스템: 대화가 종료되어도 사용자의 성향, 프로젝트 규칙 등을 디스크에 마크다운 파일로 저장하여 다음 세션에서 기억을 유지합니다.
상태 불변성: 예측 불가능한 버그를 막기 위해 모든 글로벌 상태는 직접 수정하지 않고 복사본을 생성하는 방식(Immutable)으로 관리됩니다.
스킬(Skill)과 플러그인(Plugin): 단순한 도구를 넘어 '코드 리뷰', 'PR 생성' 같은 복합적인 작업 템플릿을 /명령어 형태로 제공하며, MCP 서버와 묶어 플러그인 형태로 확장할 수 있습니다.
아키텍처 특징
단일 파일(main.tsx)에 집중된 빌드로 초기 구동 속도를 높이고, 스트리밍 응답과 동시에 도구를 실행하는 비동기 최적화를 적용했습니다. 또한 네트워크 오류나 컨텍스트 초과 에러 발생 시, 사용자에게 에러를 노출하기 전에 내부적으로 요약이나 재시도를 통해 자체 복구를 시도하는 강력한 복원력을 갖추고 있습니다.
전체 흐름
End-to-End Data Flow
=====================
User runs "claude" in terminal
|
v
main.tsx
+-- Auth (OAuth / API key / Bedrock / Vertex)
+-- Model resolution (Opus for Max, Sonnet for others)
+-- Load settings + feature gates
+-- Collect context (Git status + CLAUDE.md) [memoized]
+-- Build tool pool (built-in + MCP)
+-- Launch REPL (or headless QueryEngine)
|
v
User types: "Fix the bug in auth.ts"
|
v
Normalize message for API
|
v
query() generator loop <-----------------------------------------+
| |
+-- [Pre-process] snip / microcompact / auto-compact if needed |
+-- [API call] stream response from Claude API |
+-- [Error?] withhold & recover (413 -> compact, max_tok -> retry) |
+-- [Tool use?] |
| YES --> permission check --> execute tool --> collect result |
| (pipeline: validate -> hooks -> rules -> classifier) -+
| NO --> display final response
|
+-- Record transcript to disk
+-- Track cost (per model: input/output/cache tokens)
+-- Await next user input