Claude Code Architecture Analysis

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

최근 Anthropic의 터미널 기반 에이전트, Claude Code의 내부 소스코드가 npm 배포 과정에서의 실수(.map 파일 유입)로 유출되는 사건이 있었습니다. 비록 어처구니없는 실수였지만, 그 속에 담긴 4,600여 개의 소스 파일은 현재 가장 앞서나가는 '에이전틱 AI' 시스템이 어떻게 설계되었는지를 보여주는 더없이 귀중한 교재가 되었습니다.

단순한 API 래퍼를 넘어, 수많은 예외 상황과 비용, 성능을 치열하게 고민한 흔적이 역력합니다. AI 에이전트 서비스를 직접 만들고자 하는 개발자(Builder)들이 반드시 참고해야 할 핵심 설계 패턴 5가지를 정리했습니다.

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

Claude Code의 심장은 query.ts에 위치한 1,729줄의 while(true) 루프입니다. 여기서 주목할 점은 구현 방식입니다.

Async Generator의 활용

대부분의 에이전트는 EventEmitter나 콜백을 사용하지만, Claude Code는 async function* (제너레이터)을 선택했습니다.

이점: 이벤트 스트리밍(yield)과 최종 결과 반환(return)을 하나의 함수 안에서 선형적으로 처리할 수 있습니다.
에러 전파: 루프 안에서 발생한 에러가 소비자의 try-catch로 자연스럽게 전파되어 상태 관리가 매우 깔끔합니다.

Atomic State 관리

루프 내부에서 상태를 변경할 때, 각 필드를 개별적으로 수정하지 않고 전체 상태 객체를 재할당합니다.

state = { 
  ...state, 
  messages: newMessages, 
  turnCount: nextTurnCount, 
  transition: { reason: 'next_turn' } 
}

이 패턴은 상태 전알 원자적(Atomic)으로 만들어, 일부 필드만 업데이트된 채 에러가 발생하는 '불완전한 중간 상태'를 원천 차단합니다. 에이전틱 루프에서 상태가 꼬이는 것은 곧 **불필요한 API 호출(비용)**로 이어지기 때문에 매우 중요한 설계입니다.

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

AI 에이전트의 최대 적은 컨텍스트 윈도우 한계입니다. Claude Code는 무작정 요약(Summary)하지 않습니다. 비용-효과에 따라 4단계 계층을 순차적으로 적용합니다.

Snip (잘라내기): 가장 오래된 메시지를 통째로 삭제합니다. (비용 0, 정보 손실 높음)
Microcompact: 특정 도구의 결과(파일 내용 등)만 골라 "내용이 삭제됨" 문구로 교체합니다. (비용 0, 캐시 효율 유지)
Context Collapse: 원본은 두되, LLM에게 보낼 때만 특정 부분을 축소해서 보여주는 '읽기 시점 프로젝션' 방식입니다.
Auto-Compact (요약): 최종 수단으로 전체를 요약합니다. (추가 API 비용 발생, 정보 보존 높음)

Builder's Tip: 항상 가장 저렴한(API 호출이 없는) 방법부터 시도하는 '비용 인식(Cost-awareness)' 철학을 아키텍처에 녹여내야 합니다.

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

사용자는 AI가 타이핑을 멈추고 나서야 도구가 실행되는 것을 기다리고 싶어 하지 않습니다. Claude Code는 LLM이 응답을 스트리밍하는 동안 이미 도구를 실행합니다.

방법: 모든 도구에 isConcurrencySafe 플래그를 부여합니다.
실행: FileRead, Grep, Glob 같은 읽기 전용 도구는 답변 생성 중에 즉시 병렬로 실행됩니다.
예외: FileWrite나 Bash처럼 상태를 변경하는 도구는 답변이 끝난 후 배치로 실행하거나 직렬화합니다.

이러한 비동기 프리페치(Prefetch) 전략 덕분에 Claude Code는 다른 에이전트보다 훨씬 빠른 체감 속도를 제공합니다.

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

에러가 발생했을 때 즉시 포기하거나 무작정 재시도하지 않습니다. 저비용에서 고비용 순서로 복구 시나리오를 구성합니다.

Prompt Too Long (413 에러) 발생 시:
1. 즉시 적용 가능한 Context Collapse를 플러시합니다. (비용 0)
2. 그래도 부족하면 Reactive Compact로 전체 대화를 요약합니다. (비용 발생)
Token Limit 발생 시:
1. 토큰 캡(8K -> 64K)을 자동으로 올립니다. (ESCALATION)
2. "이후 내용을 이어서 작성해줘"라는 Resume 메시지를 주입해 최대 3회까지 이어서 받습니다.

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리

로컬에서 동작하는 에이전트는 파일 시스템 접근 권한이 매우 예민합니다. Claude Code는 8개 레이어의 방어 체계를 갖추고 있는데, 특히 흥미로운 점은 세션 격리 방식입니다.

웹(Claude.ai)에서 로컬의 Claude Code를 제어하는 'Bridge' 모드에서는 각 세션을 Git Worktree로 격리합니다.

이점: 컨테이너나 VM 같은 무거운 격리 없이도 각 세션이 독립적인 작업 디렉토리를 갖게 되어, 파일 충돌(Merge Conflict)을 원천 차단하면서도 가볍게 동작합니다.

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

이번 유출 사고를 통해 본 Claude Code는 단순한 프롬프트 덩어리가 아니라, 4,600개 이상의 파일이 얽혀 있는 정교한 플랫폼이었습니다.

에이전트 빌더를 위한 요약:

제너레이터를 활용해 흐름을 단순화하라.
상태 관리를 원자적으로 하여 비용 낭비를 막아라.
압축과 복구에는 반드시 비용 계층을 두어라.
가능한 모든 도구는 병렬로 미리 실행하라.
기존 인프라(Git 등)를 활용해 실용적인 격리를 달성하라.

에이전틱 AI의 핵심은 LLM의 똑똑함이 아니라, 그 똑똑함을 안전하고 효율적으로 세상을 연결해주는 치밀한 엔지니어링에 있습니다.

Claude Code Architecture Analysis

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

Claude Code의 심장은 query.ts에 위치한 1,729줄의 while(true) 루프입니다. 여기서 주목할 점은 구현 방식입니다.

Async Generator의 활용

대부분의 에이전트는 EventEmitter나 콜백을 사용하지만, Claude Code는 async function* (제너레이터)을 선택했습니다.

이점: 이벤트 스트리밍(yield)과 최종 결과 반환(return)을 하나의 함수 안에서 선형적으로 처리할 수 있습니다.
에러 전파: 루프 안에서 발생한 에러가 소비자의 try-catch로 자연스럽게 전파되어 상태 관리가 매우 깔끔합니다.

Atomic State 관리

루프 내부에서 상태를 변경할 때, 각 필드를 개별적으로 수정하지 않고 전체 상태 객체를 재할당합니다.

state = { 
  ...state, 
  messages: newMessages, 
  turnCount: nextTurnCount, 
  transition: { reason: 'next_turn' } 
}

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

Snip (잘라내기): 가장 오래된 메시지를 통째로 삭제합니다. (비용 0, 정보 손실 높음)
Microcompact: 특정 도구의 결과(파일 내용 등)만 골라 "내용이 삭제됨" 문구로 교체합니다. (비용 0, 캐시 효율 유지)
Context Collapse: 원본은 두되, LLM에게 보낼 때만 특정 부분을 축소해서 보여주는 '읽기 시점 프로젝션' 방식입니다.
Auto-Compact (요약): 최종 수단으로 전체를 요약합니다. (추가 API 비용 발생, 정보 보존 높음)

Builder's Tip: 항상 가장 저렴한(API 호출이 없는) 방법부터 시도하는 '비용 인식(Cost-awareness)' 철학을 아키텍처에 녹여내야 합니다.

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

방법: 모든 도구에 isConcurrencySafe 플래그를 부여합니다.
실행: FileRead, Grep, Glob 같은 읽기 전용 도구는 답변 생성 중에 즉시 병렬로 실행됩니다.
예외: FileWrite나 Bash처럼 상태를 변경하는 도구는 답변이 끝난 후 배치로 실행하거나 직렬화합니다.

이러한 비동기 프리페치(Prefetch) 전략 덕분에 Claude Code는 다른 에이전트보다 훨씬 빠른 체감 속도를 제공합니다.

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

에러가 발생했을 때 즉시 포기하거나 무작정 재시도하지 않습니다. 저비용에서 고비용 순서로 복구 시나리오를 구성합니다.

Prompt Too Long (413 에러) 발생 시:
1. 즉시 적용 가능한 Context Collapse를 플러시합니다. (비용 0)
2. 그래도 부족하면 Reactive Compact로 전체 대화를 요약합니다. (비용 발생)
Token Limit 발생 시:
1. 토큰 캡(8K -> 64K)을 자동으로 올립니다. (ESCALATION)
2. "이후 내용을 이어서 작성해줘"라는 Resume 메시지를 주입해 최대 3회까지 이어서 받습니다.

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리

웹(Claude.ai)에서 로컬의 Claude Code를 제어하는 'Bridge' 모드에서는 각 세션을 Git Worktree로 격리합니다.

이점: 컨테이너나 VM 같은 무거운 격리 없이도 각 세션이 독립적인 작업 디렉토리를 갖게 되어, 파일 충돌(Merge Conflict)을 원천 차단하면서도 가볍게 동작합니다.

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

이번 유출 사고를 통해 본 Claude Code는 단순한 프롬프트 덩어리가 아니라, 4,600개 이상의 파일이 얽혀 있는 정교한 플랫폼이었습니다.

에이전트 빌더를 위한 요약:

제너레이터를 활용해 흐름을 단순화하라.
상태 관리를 원자적으로 하여 비용 낭비를 막아라.
압축과 복구에는 반드시 비용 계층을 두어라.
가능한 모든 도구는 병렬로 미리 실행하라.
기존 인프라(Git 등)를 활용해 실용적인 격리를 달성하라.

에이전틱 AI의 핵심은 LLM의 똑똑함이 아니라, 그 똑똑함을 안전하고 효율적으로 세상을 연결해주는 치밀한 엔지니어링에 있습니다.

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

Async Generator의 활용

Atomic State 관리

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

Discussion (0)

Explore More Topics

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

Async Generator의 활용

Atomic State 관리

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

Discussion (0)

Explore More Topics

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

1. 에이전트 루프의 정석: Async Generator와 Atomic State

Async Generator의 활용

Atomic State 관리

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

3. 성능 극대화: isConcurrencySafe와 병렬 실행

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

5. 보안과 격리: Git Worktree를 활용한 세션 격리

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

Discussion (0)

Explore More Topics

클로드 코드가 털렸다? 에이전틱 AI 빌더를 위한 'Claude Code' 아키텍처 해설

1. 에이전트 루프의 정석: Async Generator와 Atomic State

Async Generator의 활용

Atomic State 관리

2. 4단계 컨텍스트 압축: 가장 저렴한 것부터!

3. 성능 극대화: isConcurrencySafe와 병렬 실행

4. 회복 탄력성: '비용 인식 캐스케이드' 에러 복구

5. 보안과 격리: Git Worktree를 활용한 세션 격리

결론: 에이전틱 AI 시스템은 '엔지니어링의 정점'이다

Discussion (0)

Explore More Topics

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리

1. 에이전트 루프의 정석: `Async Generator`와 `Atomic State`

3. 성능 극대화: `isConcurrencySafe`와 병렬 실행

5. 보안과 격리: `Git Worktree`를 활용한 세션 격리