Claude Code는 Anthropic이 만든 AI 코딩 에이전트로, 터미널에서 직접 실행되면서 코드 작성, 디버깅, 리팩토링을 자율적으로 수행한다. 2025년 출시 이후 연간 매출 10억 달러를 돌파하며 개발 도구 시장의 판도를 바꿨는데, 그 핵심에는 놀라울 정도로 단순한 아키텍처가 있다. 이 글에서는 Claude Code의 내부 동작 방식을 에이전틱 루프부터 컨텍스트 로딩, 권한 모델, 서브에이전트까지 완전히 해부한다.
에이전틱 루프: 단일 스레드의 힘
Claude Code의 심장부는 "nO"라는 코드네임의 마스터 에이전트 루프다. 경쟁사들이 멀티 에이전트 스웜이나 복잡한 오케스트레이션을 추구하는 동안, Anthropic은 단일 스레드 while 루프 하나로 모든 것을 처리하는 접근법을 택했다.
이 루프는 6단계로 동작한다:
- 사용자 입력: 터미널(대화형) 또는 stdin/
--print(헤드리스) 모드로 메시지가 들어온다 - 컨텍스트 조립: 시스템이 현재 날짜, git 상태(브랜치, 최근 커밋, 워킹 트리), CLAUDE.md 메모리 파일, 사용 가능한 도구 목록을 포함한 프롬프트를 구성한다
- 모델 추론: Anthropic API가 대화를 처리하고 하나 이상의
tool_use블록을 생성한다. 각 블록은 도구 이름과 구조화된 JSON 입력을 포함한다 - 권한 평가: 각 도구 호출이 실행 전에 권한 검사를 거친다
- 도구 실행: 승인된 호출이 실행되고, 결과가
tool_result블록으로 추가된다 - 루프 지속: 모델이 추가 도구를 호출하거나 최종 텍스트 응답을 생성한다
이 구조는 2023년 Yao et al.이 제안한 ReAct(Reasoning + Acting) 패턴과 정확히 일치한다. 생각(Thought) → 행동(Action) → 관찰(Observation)의 반복이 Claude Code에서는 추론 → 도구 호출 → 결과 피드백으로 구현된 것이다.
핵심 제약 조건이 하나 있다: 루프는 전적으로 사용자의 터미널 프로세스에서 실행된다. 원격 실행 서버가 없으므로 파일, 셸, 인증 정보가 도구가 명시적으로 전송하지 않는 한 로컬 머신을 벗어나지 않는다.
컨텍스트 로딩 시스템: 두 개의 캐시 블록
모든 API 호출 전에 두 종류의 컨텍스트 블록이 조립된다.
시스템 컨텍스트시스템 컨텍스트는 개발 환경의 현재 상태를 캡처한다:
- Git 브랜치명, 기본 브랜치, 사용자명: 현재 작업 중인 브랜치와 프로젝트 구조를 파악
git status --short출력: 워킹 트리의 변경 사항을 최대 2,000자까지 포함. 이 제한은 대규모 모노레포에서 컨텍스트 윈도우를 보호하기 위한 설계git log --oneline으로 최근 5개 커밋: 최근 작업 이력을 통해 모델이 프로젝트 방향을 이해- 선택적 캐시 무효화 인젝션: 상황에 따라 캐시된 컨텍스트를 강제로 갱신
CLAUDE_CODE_REMOTE=1 환경변수가 설정되거나 git 지시가 비활성화되면 git 상태 수집이 생략된다. 이는 원격 실행 환경에서 불필요한 git 호출을 방지하기 위함이다.
사용자 컨텍스트사용자 컨텍스트는 프로젝트별 지식과 설정을 담는다:
- CLAUDE.md 메모리 파일: 4단계 계층(managed → user → project → local)으로 관리된다. 프로젝트 루트의 CLAUDE.md에 코딩 컨벤션, 아키텍처 규칙, 자주 쓰는 명령어를 기록하면 매 대화에서 자동으로 로딩된다
- 현재 날짜 인젝션: "Today's date is YYYY-MM-DD" 형식으로 주입되어 시간 감각을 제공
두 블록 모두 lodash/memoize로 성능 최적화되어 있어, 동일 대화 내에서 반복 계산을 피한다. CLAUDE_CODE_DISABLE_CLAUDE_MDS=1로 메모리 파일 로딩을 완전히 비활성화할 수도 있다.
권한 모델: 3단계 게이트
보안은 Claude Code 설계의 핵심 축이다. 모든 도구 호출은 실행 전에 권한 검사를 거치며, 결과는 세 가지 중 하나다:
| 결과 | 동작 | 예시 |
|---|---|---|
| allow | 즉시 실행, 결과 추가 | Read, Glob, Grep (읽기 전용) |
| ask | 사용자 확인 프롬프트 표시 | Bash 명령, 파일 삭제 |
| deny | 거부, 에러 피드백 반환 | 금지된 명령 패턴 |
Read, Glob, Grep 같은 읽기 전용 도구는 모든 모드에서 자동 승인된다. acceptEdits 모드에서는 파일 편집도 자동 승인되지만, bash 명령은 여전히 확인을 요구한다. 이 설계는 안전성과 생산성 사이의 균형을 정밀하게 조율한다.
사용자는 .claude/settings.json에서 도구별 권한을 세밀하게 설정할 수 있고, 허용 패턴(allowedTools)과 거부 패턴을 정규식으로 정의할 수 있다.
서브에이전트: 격리된 컨텍스트의 활용
Claude Code의 Task 도구는 자체 에이전틱 루프를 가진 서브에이전트를 생성할 수 있다. 각 서브에이전트는 격리된 대화 컨텍스트와 선택적으로 제한된 도구 세트를 가진다.
이 설계의 핵심 통찰은 "비상관 컨텍스트 윈도우를 테스트 타임 컴퓨트의 한 형태로 활용"하는 것이다. 긴 단일 세션에서는 이전 대화의 잡음이 쌓이지만, 오염되지 않은 신선한 컨텍스트 윈도우를 가진 병렬 서브에이전트는 특정 하위 작업에서 더 높은 추론 능력을 발휘할 수 있다.
서브에이전트의 두 가지 활용 패턴:
- Subagent: 단일 작업 내 빠른 병렬 조사. 예를 들어 여러 파일에서 특정 패턴을 동시에 검색하거나, 독립적인 리서치를 병렬로 수행
- Team: 진정한 병렬 워크스트림. 한 에이전트가 백엔드를 리팩토링하는 동안 다른 에이전트가 프론트엔드 테스트를 업데이트하는 식의 대규모 병렬 작업
서브에이전트는 로컬에서 실행되거나 원격으로 실행될 수 있으며, git worktree를 활용해 격리된 파일 시스템에서 작업할 수도 있다.
쿼리 엔진과 스트리밍
쿼리 엔진(query.ts)은 에이전틱 루프의 실행 인프라를 담당한다:
- 실시간 스트리밍: API 응답이 Server-Sent Events로 도착하며 점진적으로 렌더링된다. 도구 호출은 전체 응답이 완료되기 전에 mid-stream에서 감지되어 실행 파이프라인을 트리거한다
- 도구 디스패칭:
tool_use블록을 파싱하고 적절한 도구로 라우팅한다 - 턴별 예산 관리: 토큰과 도구 호출 횟수에 대한 per-turn 제한을 적용한다. 이를 통해 무한 루프나 비용 폭주를 방지한다
- 결과 크기 관리: 각 도구는
maxResultSizeChars를 지정하며, 초과 결과는 임시 파일에 저장되고 미리보기만 모델에 전달된다
실시간 조향: h2A 큐
h2A라는 비동기 이중 버퍼 큐가 마스터 루프와 협력하여 진정한 대화형 스트리밍을 구현한다. 에이전트가 복잡한 작업을 수행하는 도중에도 사용자가 새로운 지시, 제약 조건, 방향 전환을 삽입할 수 있다. 전체 작업을 중단하고 재시작할 필요 없이 실시간으로 코스를 수정할 수 있는 것이다.
이 기능은 실제 프로덕션에서 핵심적이다. 에이전트가 잘못된 방향으로 진행 중일 때 즉시 교정할 수 있고, 추가 컨텍스트를 작업 중간에 주입할 수 있다.
컨텍스트 압축과 대화 지속성
세션은 ~/.claude/에 JSON 트랜스크립트로 저장된다. --resume <session-id>로 전체 히스토리를 복원하고, 메모리 파일을 재탐색하며, 권한을 기본값으로 초기화한다.
긴 대화에서는 컨텍스트 윈도우 사용량이 약 92%에 도달하면 wU2 압축기가 자동으로 트리거된다. 오래된 메시지를 요약하여 컨텍스트 윈도우를 확보하되, 원본 트랜스크립트는 디스크에 항상 보존되므로 정보 손실은 없다.
TODO 리스트 기능(TodoWrite)도 장기 대화 관리에 핵심적인 역할을 한다. 모델이 다단계 작업을 수행할 때 구조화된 JSON 작업 목록을 생성하고, 진행 상황을 추적하며, 도구 실행 후 시스템 메시지로 현재 TODO 상태가 주입되어 목표를 잃지 않게 한다.
터미널 UI: React in the Terminal
터미널 인터페이스는 Ink(CLI용 React 렌더러)를 사용한 React 앱이다. 대화 뷰, 입력 영역, 도구 호출 표시, 권한 다이얼로그, 진행 표시기 모두 Yoga(CSS flexbox)로 레이아웃하고 ANSI 이스케이프 코드로 스타일링하는 React 컴포넌트다.
이 접근법 덕분에 터미널이라는 제약된 환경에서도 풍부한 상호작용 경험을 제공하며, VS Code 확장, JetBrains 플러그인, 웹 UI 등 다양한 프론트엔드로의 확장도 동일한 에이전트 코어 위에서 이루어진다.
왜 이 아키텍처가 작동하는가
Claude Code의 설계 철학은 "단순하고 규율 있는 단일 스레드 마스터 루프가 제어 가능한 자율성을 제공한다"는 것이다. 복잡한 멀티 에이전트 시스템 대신 하나의 루프가 하나의 일관된 대화 히스토리를 유지하면서, 필요할 때만 서브에이전트로 병렬성을 확보한다.
이 단순함이 세 가지를 만든다. 첫째, 디버깅 용이성 — 단일 스레드이므로 상태 추적이 쉽다. 둘째, 예측 가능성 — 도구 호출 순서가 명확하고 권한 게이트가 일관된다. 셋째, 사용자 신뢰 — 모든 것이 로컬에서 실행되고 모든 도구 호출이 권한 게이트를 통과하며 대화 전체가 JSON으로 보존된다.
Boris Cherny가 Sonnet 3.5 API 테스트용으로 만든 가벼운 터미널 인터페이스에서 시작해, 연간 20억 달러 규모의 프로덕트로 성장한 Claude Code. 그 기술적 토대는 ReAct 패턴이라는 검증된 방법론 위에 실용적인 엔지니어링 결정들이 쌓인 결과다.
