Claude Code 아키텍처 심층 분석 — AI 코딩 에이전트의 설계 원리를 추론하다

들어가며

Claude Code는 Anthropic이 개발한 CLI 기반 AI 코딩 에이전트다. 터미널에서 직접 코드를 읽고, 수정하고, 빌드하고, 테스트까지 수행하는 에이전트형 도구로, 2025년 이후 빠르게 발전해왔다.

이 글에서는 Claude Code를 오랜 기간 사용하면서 관찰한 동작 패턴, 공식 문서, 그리고 공개된 기술 스택(TypeScript, Bun, Ink 등)의 특성을 바탕으로 내부 아키텍처의 설계 원리를 추론·분석한다.

분석의 근거:

• 공식 문서 및 블로그 포스트
• CLI 사용 중 관찰되는 동작 패턴
• 공개된 npm 패키지 메타데이터 및 의존성 트리
• 시스템 프롬프트에서 관찰 가능한 구조
• AI 에이전트 설계의 일반적 패턴과 모범 사례

참고: 이 글은 공개된 정보와 사용 경험에 기반한 추론이며, 실제 내부 구현과 다를 수 있습니다.

---

1. 프로젝트 개요 — 기술 스택과 규모감

1-1. 공개된 기술 스택

항목	기술
언어	TypeScript
런타임	Bun
UI 프레임워크	React + Ink (터미널 TUI)
패키지 매니저	npm (@anthropic-ai/claude-code)
내장 도구	42개 이상 (Read, Write, Edit, Bash, Glob, Grep, Agent 등)
확장	MCP (Model Context Protocol) 서버 연동

사용 중 관찰되는 동작으로 미루어, 상당한 규모의 코드베이스임을 짐작할 수 있다. 시작 시간 최적화, 지연 로딩, 도구별 조건부 활성화 등 대규모 프로젝트에서 볼 수 있는 패턴이 관찰된다.

1-2. 시작 시간 최적화

CLI 도구로서 체감 시작 시간이 매우 빠르다. --version 같은 단순 플래그는 거의 0ms에 가깝게 응답한다.

이는 동적 import를 활용한 지연 로딩 패턴을 사용하고 있음을 시사한다:

• 단순 플래그 처리 시 무거운 모듈을 로드하지 않음
• 인증, 설정 읽기 등 초기화 작업을 병렬로 수행
• Bun 런타임의 빠른 시작 시간을 활용

---

2. 아키텍처 — 요청이 도구 실행까지 흐르는 경로

Claude Code의 동작을 관찰하면 다음과 같은 파이프라인 구조를 추론할 수 있다:

사용자 입력
    ↓
[1] CLI 부트스트랩 — 인증, 모델 선택, 권한 모드 설정
    ↓
[2] TUI (터미널 UI) — React/Ink 기반 대화형 인터페이스
    ↓
[3] 쿼리 엔진 — 시스템 프롬프트 조립, 메시지 정규화
    ↓
[4] API 호출 + 도구 실행 루프
    │   ├→ Anthropic API (SSE 스트리밍)
    │   ├→ 도구 실행 (42+ 내장 도구 + MCP 도구)
    │   ├→ 자동 컨텍스트 관리 (컴팩션)
    │   └→ 메모리 시스템
    ↓
[5] 결과를 사용자에게 렌더링

2-1. 빌드 타임 피처 게이팅

Bun의 번들링 기능을 활용한 빌드 타임 Dead Code Elimination이 적용되어 있는 것으로 보인다. 특정 기능은 빌드 시점에 활성화/비활성화되어, 해당 기능의 코드가 최종 번들에서 완전히 제거된다.

이 방식의 장점:

• 런타임 조건 분기 없이 코드 크기 최적화
• 내부 전용 기능과 외부 공개 기능의 깔끔한 분리
• 번들 크기 최소화

---

3. Tool 시스템 — 도구의 타입 설계

3-1. 도구 인터페이스 패턴

Claude Code의 각 도구(Read, Write, Edit, Bash 등)는 공통 인터페이스를 따르는 것으로 관찰된다. 일반적인 AI 에이전트 도구 설계를 참고하면, 다음과 같은 계약(contract)이 필요하다:

도구 인터페이스 (추론):
├── name: 도구 이름
├── call(): 도구 실행 + 결과 반환
├── checkPermissions(): 권한 확인
├── description(): 도구 설명 생성
│
├── isReadOnly(): 읽기 전용 여부
├── isConcurrencySafe(): 동시 실행 가능 여부
├── isDestructive(): 파괴적 작업 여부
│
├── renderToolUseMessage(): 도구 사용 시 UI 표시
├── renderToolResultMessage(): 결과 UI 표시
│
└── maxResultSizeChars: 결과 크기 제한

3-2. Fail-Closed 기본값

Claude Code의 동작을 관찰하면 Fail-Closed 원칙이 일관되게 적용된다:

• 새로운 도구는 기본적으로 안전하지 않다고 가정 — 동시 실행 불가, 쓰기 가능으로 간주
• 명시적으로 안전하다고 선언한 도구만 병렬 실행 허용
• 명시적으로 읽기 전용이라고 선언한 도구만 자동 허용 대상

이 원칙은 보안 설계에서 매우 중요한데, 새 도구를 추가할 때 안전성 선언을 잊더라도 항상 안전한 쪽으로 동작하기 때문이다.

3-3. 도구 풀 조립

내장 도구와 MCP 외부 도구를 합쳐서 하나의 도구 풀을 구성한다. 이때 이름순 정렬이 중요한데, Anthropic API의 프롬프트 캐시 키가 도구 목록의 순서에 영향을 받기 때문이다. 순서가 바뀌면 캐시가 깨져서 비용이 증가한다.

3-4. 도구 지연 로딩

시스템 프롬프트에서 확인할 수 있듯이, 일부 도구는 지연 로딩(deferred) 방식으로 동작한다. 모든 도구를 처음부터 로드하면 시스템 프롬프트가 너무 길어지므로, 필요할 때 스키마를 가져오는 방식이다.

---

4. 핵심 설계 패턴 상세 분석

4-1. Bash 보안 — 다층 방어 모델

Claude Code의 Bash 도구는 가장 강력하면서도 가장 위험한 도구다. 사용 중 관찰되는 동작으로 미루어, 다층 보안 파이프라인이 적용되어 있다:

[1] 정규식 기반 위험 패턴 탐지
    - 프로세스 치환, 명령 치환 등 위험 구문 감지
    - Unicode 공격, 제어 문자 필터링

[2] AST 기반 구조 분석
    - Bash 명령을 파싱하여 추상 구문 트리(AST) 생성
    - 허용목록에 없는 구조 → 자동 거부 (Fail-Closed)
    - 단순 명령(simple command)만 자동 처리 대상

[3] 권한 규칙 매칭
    - argv[0]과 사전 정의된 패턴 매칭
    - settings.json의 alwaysAllow / alwaysDeny 규칙 적용

[4] 사용자 확인 다이얼로그
    - 위 단계를 모두 통과하지 못하면 사용자에게 직접 확인

핵심 원칙: “이 명령에서 신뢰할 수 있는 argv[]를 추출할 수 있는가?” → 가능하면 규칙 매칭, 불가능하면 사용자에게 직접 확인. 이해하지 못하는 것은 차단한다.

4-2. 프롬프트 캐시 최적화

Claude Code는 API 호출 비용을 최적화하기 위해 프롬프트 캐시를 적극 활용한다.

캐시 키 구성 요소 (Anthropic API 문서 기반):

• 시스템 프롬프트
• 도구 목록 (순서 포함)
• 모델
• 메시지 프리픽스

이를 위한 관찰 가능한 최적화:

• 도구 목록의 결정론적 정렬 (이름순, 빌트인 우선)
• 시스템 프롬프트의 정적/동적 영역 분리 (캐시 가능 영역 최대화)
• 서브에이전트의 시스템 프롬프트를 부모와 동일하게 유지하여 캐시 공유

4-3. 구조화 컨텍스트 컴팩션

대화가 길어지면 Claude Code가 자동으로 컨텍스트를 압축하는 것을 관찰할 수 있다. /compact 명령으로 수동 트리거도 가능하다.

관찰된 컴팩션 동작:

1. 자동 트리거: 컨텍스트 윈도우의 일정 비율을 넘으면 자동 실행
2. 구조화된 요약: 단순 요약이 아닌, 여러 섹션으로 나뉜 구조적 압축
   • 사용자 요청과 의도
   • 기술적 개념
   • 파일과 코드 섹션
   • 오류와 해결법
   • 남은 작업과 현재 작업 상태
3. 사용자 메시지 보존: 사용자가 제공한 피드백과 지시사항은 압축 시에도 보존
4. 이미지 처리: 압축 전에 이미지를 텍스트 마커로 대체하여 API 호출 최적화

4-4. 토큰 초과 복구 전략

API 호출 시 토큰 제한에 도달하면 단계적 복구 전략이 적용된다:

상황	복구 전략
토큰 초과 (1차)	반응적 컴팩션 — 대화 히스토리 압축
토큰 초과 (2차)	최대 출력 토큰 단계적 증가
토큰 초과 (3차)	강제 종료
컨텍스트 윈도우 임박	사전적 자동 컴팩션
API 오류	지수 백오프 재시도

4-5. 메모리 시스템의 관련성 검색

Claude Code의 메모리 시스템(~/.claude/projects/*/memory/)은 전통적인 벡터 검색이 아닌, LLM 기반 관련성 판단을 사용하는 것으로 보인다.

관찰된 동작:

• 메모리 파일의 헤더(name, description)를 기반으로 관련성 판단
• 한 턴에 최대 소수의 메모리만 선택적으로 로딩
• 이미 사용된 도구의 레퍼런스 문서는 중복 로딩 방지
• 이전 턴에서 이미 제공된 메모리는 필터링

4-6. 대형 도구 결과 처리

도구 실행 결과가 매우 클 때(파일 읽기, 검색 결과 등), 결과 전체를 컨텍스트에 넣지 않고 디스크에 영속화한 후 미리보기만 전달하는 패턴이 관찰된다.

이는 컨텍스트 윈도우를 절약하면서도 필요 시 전체 결과에 접근할 수 있게 하는 합리적인 설계다.

4-7. 선택적 재시도 전략

API 과부하(529) 상황에서의 재시도 동작을 관찰하면:

• 사용자가 기다리는 메인 요청: 재시도 수행
• 백그라운드 작업 (제목 생성, 요약 등): 즉시 실패 (재시도 안 함)

이는 과부하 시 불필요한 재시도가 상황을 악화시키는 것을 방지하는 설계로, “capacity cascade에서 각 재시도는 3-10배의 gateway 증폭을 일으킨다”는 원칙에 기반한 것으로 보인다.

---

5. 시스템 프롬프트 구조

5-1. 정적/동적 경계

시스템 프롬프트를 관찰하면 정적 영역과 동적 영역이 분리되어 있다:

[정적 영역 — 프롬프트 캐시 가능]
  ├── 도구 설명
  ├── 기본 지침 (# System, # Doing tasks, # Using your tools)
  ├── 보안 지침
  └── 코드 스타일 지침
──── (경계선) ────
[동적 영역 — 매 턴 변경]
  ├── CLAUDE.md 내용
  ├── git status 스냅샷
  ├── 세션별 가이던스
  ├── 메모리 (MEMORY.md)
  └── 언어 설정, 출력 스타일

정적 영역을 앞쪽에 배치하면 프롬프트 캐시 히트율이 높아진다. 동적 영역의 내용이 바뀌어도 정적 영역의 캐시는 유지되기 때문이다.

5-2. CLAUDE.md 로딩 우선순위

공식 문서에서 확인 가능한 로딩 순서:

1. /etc/claude-code/CLAUDE.md  — 관리자 설정 (최저 우선순위)
2. ~/.claude/CLAUDE.md          — 사용자 글로벌 설정
3. {프로젝트}/CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md
4. {프로젝트}/CLAUDE.local.md  — 최고 우선순위

나중에 로드된 것이 모델에게 더 가까운 위치에 배치되어 주의를 더 받는다.

---

6. 실전 파워 유저 팁

6-1. 환경변수 튜닝

공식 문서 및 설정에서 확인 가능한 환경변수:

환경변수	기능
DISABLE_AUTO_COMPACT=1	자동 컴팩트 비활성화
CLAUDE_CODE_MAX_OUTPUT_TOKENS	최대 출력 토큰 설정

환경변수 목록은 버전에 따라 변경될 수 있으므로, 공식 문서를 참고하는 것이 좋다.

6-2. Hook 이벤트 활용

공식 문서에서 확인된 Hook 이벤트:

PreToolUse / PostToolUse
Notification
Stop
SubagentStop

Hook이 반환할 수 있는 액션:

• approve / deny / block — 도구 실행 허용/거부/차단
• reason — 결정 이유
• updatedInput — 수정된 입력

Hook을 활용하면 도구 실행을 자동화하거나, 특정 패턴의 명령을 자동 승인/거부할 수 있다.

6-3. 에이전트 활용 최적화

시스템 프롬프트에서 확인 가능한 에이전트 유형:

에이전트	용도	특징
Explore	코드베이스 탐색	quick / medium / very thorough 깊이 지정
Plan	설계/계획	구현 전략 설계에 특화
general-purpose	멀티스텝 작업	CLAUDE.md 포함, 가장 범용적

Explore에 탐색 깊이를 명시하면 탐색 범위가 달라지므로, 단순 검색에는 quick, 깊은 분석에는 very thorough를 지정하는 것이 효율적이다.

---

7. 보안 설계 원칙

Claude Code의 보안 설계에서 일관되게 관찰되는 원칙들:

7-1. Fail-Closed 전략

• 이해하지 못하는 Bash 명령 → 차단 후 사용자 확인 요청
• 새 도구의 기본 권한 → 비허용 (명시적 허용 필요)
• 동시성 안전성 미선언 → 직렬 실행

7-2. 다층 방어 (Defense in Depth)

Bash 명령 하나를 실행하기 위해 정규식 필터 → AST 분석 → 권한 매칭 → 사용자 확인의 다단계 검증을 거친다.

7-3. 파일시스템 보호

.gitconfig, .bashrc, .zshrc 등 시스템 설정 파일과 .git, .vscode, .claude 등 중요 디렉토리에 대한 보호가 관찰된다.

7-4. 5단계 퍼미션 결정 흐름

도구 사용 요청
  ↓
① 정적 규칙 (settings.json의 alwaysAllow/alwaysDeny)
  ↓
② Hook 실행 (외부 프로세스 훅이 등록된 경우)
  ↓
③ 자동 분류 (안전한 명령 자동 판별)
  ↓
④ 멀티에이전트 위임 (서브에이전트의 경우)
  ↓
⑤ 사용자 다이얼로그 (최종 확인)

---

8. 마치며

Claude Code를 깊이 사용하면서 관찰한 설계 철학은 세 가지로 요약된다:

1. Fail-Closed 보안: 이해하지 못하는 것은 차단한다. Bash 보안, 권한 시스템 전체가 이 원칙 위에 있다.

2. 비용 최적화: 프롬프트 캐시, 선택적 재시도, 도구 결과 디스크 영속화, 이미지 처리 최적화 등 토큰 하나까지 아끼려는 설계가 곳곳에 있다.

3. 점진적 기능 출시: 피처 플래그로 기능을 격리하고, 단계적으로 롤아웃한다. 관찰되지 않는 기능이 빌드에 포함되어 있을 가능성도 있다.

이러한 설계 원리는 Claude Code에만 해당하는 것이 아니라, 대규모 AI 에이전트를 구축할 때 보편적으로 적용할 수 있는 아키텍처 패턴이다. 특히 Fail-Closed 보안 모델과 구조화된 컴팩션은 어떤 AI 에이전트 프로젝트에서든 참고할 가치가 있다.

---

참고 자료

• Claude Code 인사이트 — Claude Code의 기본 활용법
• Anthropic Tool Use Documentation — 공식 도구 사용 가이드
• Claude Code 공식 문서 — 공식 사용 가이드
• Model Context Protocol — MCP 공식 문서