GitHub ↗
CHAPTER 02 OF 10
⚙️

Claude Code's Internal Architecture

Claude Code 내부 아키텍처 해부

queryLoop()부터 7개 안전 레이어까지 — Claude Code가 실제로 어떻게 작동하는지 이해해야 하네스를 제대로 설계할 수 있다.

Claude Code's Internal Architecture cheatsheet
🍌 NANO BANANA CHEATSHEET · CH 02

Overview

개관

하네스를 제대로 설계하려면 그 하네스가 감싸는 시스템의 내부 구조를 알아야 한다. 유출된 Claude Code 소스코드 분석은 우리에게 이 귀한 기회를 제공했다.

Claude Code의 핵심은 queryLoop()라는 비동기 제너레이터 함수다. 이것이 ReAct(Reasoning + Acting) 패러다임을 구현한다: 모델 호출 → 도구 사용 요청 수신 → 안전 레이어 통과 → 결과 피드백 → 반복. 텍스트만 반환할 때까지 이 루프가 계속된다.

주목할 것은 이 루프가 exhaustive search planning보다 simplicity와 latency를 우선시한다는 점이다. 에이전트가 느리게 느껴진다면 모델의 문제가 아니라 컨텍스트 조립이나 도구 호출 오버헤드일 가능성이 높다.

5-Layer 스택은 Surface(UI) → Core(루프 + 압축) → Safety/Action(권한 + 훅 + 도구) → State(컨텍스트 + 메모리) → Backend(셸 + MCP) 순으로 구성된다.

🎯 Learning Goals
  • Claude Code의 5개 레이어 스택 구조를 설명할 수 있다
  • queryLoop()가 ReAct 패턴을 어떻게 구현하는지 설명할 수 있다
  • 7개 안전 레이어의 순서와 역할을 나열할 수 있다
  • 5단계 컨텍스트 압축 파이프라인이 왜 중요한지 설명할 수 있다

Sections

본문

queryLoop — ReAct 패턴의 구현

ReAct 패턴 = Reasoning(추론) + Acting(행동)을 반복하는 에이전트 실행 방식. LLM이 생각하고, 도구를 호출하고, 결과를 관찰하고, 다시 생각하는 루프.

Claude Code의 queryLoop()는 이를 비동기 제너레이터로 구현한다:

1. 모델 호출 (현재 컨텍스트 전달)
2. 응답 파싱:
   a. text-only → 루프 종료, 결과 반환
   b. tool_use → 안전 레이어 통과 시도
3. 도구 실행 (허가된 경우)
4. 도구 결과를 컨텍스트에 추가
5. 1로 돌아가기

설계 철학: 단순성과 지연 시간 우선, 포괄적 탐색 계획은 나중. 이것이 때로 에이전트가 '성급하게' 행동하는 이유다. 이 동작을 원하는 방향으로 유도하는 것이 CLAUDE.md와 훅의 역할이다.

5-Layer 스택 구조

Claude Code는 5개 레이어로 구성된다. 하네스 설정이 어느 레이어에 영향을 미치는지 이해하면 더 정확한 진단이 가능하다.

레이어 이름 주요 컴포넌트 당신이 제어하는 부분
1 Surface CLI, IDE Extension, Desktop App -
2 Core queryLoop(), 5단계 압축 파이프라인 모델 선택
3 Safety/Action 권한 시스템, 훅, 도구 풀, 서브에이전트 훅, 권한 (핵심)
4 State 컨텍스트 조립, 세션 영속, CLAUDE.md, MEMORY.md CLAUDE.md, 메모리
5 Backend 셸 실행, MCP, 42개 도구 구현 MCP 서버

Layer 3, 4, 5가 하네스 엔지니어링의 주요 제어 지점이다.

7개 안전 레이어 — 심층 방어

Claude Code는 7개의 독립적인 안전 레이어를 중첩한다. 이를 이해하면 왜 특정 설정이 다른 설정보다 더 확실한 보호를 제공하는지 알 수 있다.

도구 사전 필터링 — 거부된 도구는 모델이 보기 전에 제거됨 2.

Deny-first 규칙 평가 — deny → ask → allow 순서, 첫 매칭이 우선 3.

Permission mode 제약 — plan, default, auto, bypassPermissions 등 4.

ML 기반 auto-mode 분류기 — Claude Sonnet 4.6이 별도로 실행 5.

셸 샌드박싱 — 23개 bash 보안 체크 (zero-width 문자 삽입, 경로 순회 등) 6.

세션 재개 시 권한 미복구 — resume해도 이전 권한 승인이 리셋됨 7.

훅 기반 인터셉션 — PreToolUse, PermissionRequest 훅

핵심 통찰: Layer 1-3는 입력 시점, Layer 4-5는 실행 시점, Layer 6-7은 런타임 인터셉션이다. 당신의 훅은 Layer 7에 해당한다 — 가장 유연하고 커스터마이즈 가능한 레이어.

5단계 컨텍스트 압축 파이프라인

Claude Code가 자동으로 실행하는 컨텍스트 압축 파이프라인은 하네스 엔지니어에게 매우 중요하다. 무엇이 살아남고 무엇이 사라지는지 알아야 중요한 규칙을 어디에 두어야 할지 결정할 수 있다.

단계 이름 설명
1 Budget Reduction 메시지당 도구 결과 크기 제한
2 Snip 오래된 히스토리의 경량 시간적 트리밍
3 Microcompact 캐시 인식 세밀 압축
4 Context Collapse 히스토리에 대한 읽기 시점 프로젝션
5 Auto-compact 모델 생성 시맨틱 요약 (최후 수단)

압축 후 살아남는 것: 현재 태스크, 최근 오류, 변경된 파일명, 도구 호출 결과

압축으로 사라지는 것: 초기 지시사항, 중간 결정 사항, 이전 대화 뉘앙스

핵심 결론: 중요한 규칙은 CLAUDE.md에 넣어야 한다. 세션 초기 프롬프트에만 있으면 압축으로 사라진다.

💡 Analogy · 비유
자동차 공장 자동화 라인

Claude Code의 5-Layer 스택을 자동차 공장 자동화 라인으로 생각해보자.

Surface Layer는 고객이 주문을 넣는 인터페이스 — CLI, IDE Extension, Desktop App. Core Layer는 중앙 제어 시스템(queryLoop) — 모든 공정의 오케스트레이터. Safety/Action Layer는 각 공정마다 설치된 안전 게이트 — 잘못된 부품이 다음 단계로 넘어가지 못하게 막는다. State Layer는 공장 메모리 시스템 — 각 차량의 사양서(CLAUDE.md)와 진행 상황 로그(MEMORY.md). Backend Layer는 실제 로봇팔과 용접기 — 셸 실행, MCP 서버.

중요한 것: 당신이 공장 설계자라면 로봇팔(모델)보다 안전 게이트(훅)와 사양서(CLAUDE.md)를 더 꼼꼼히 설계해야 한다. 로봇팔은 Anthropic이 만든다. 안전 게이트와 사양서는 당신이 만든다.

Claude Code의 컨텍스트 압축 후 무엇이 살아남는지 시뮬레이션하는 도구. 자신의 CLAUDE.md와 세션 내용이 압축 후 어떻게 보이는지 미리 파악할 수 있다.

python
#!/usr/bin/env python3
"""압축 시뮬레이터 — 세션에서 무엇이 살아남는지 미리 보기"""
import json
from pathlib import Path

def analyze_compaction_survival(session_jsonl: str):
    """JSONL 세션 파일 분석하여 압축 생존율 예측"""
    lines = Path(session_jsonl).read_text().splitlines()
    events = [json.loads(l) for l in lines if l.strip()]
    
    always_survives = []
    likely_survives = []
    likely_lost = []
    
    for i, event in enumerate(events):
        role = event.get('role', '')
        content = str(event.get('content', ''))
        recency = len(events) - i  # 최근일수록 낮은 값
        
        if 'CLAUDE.md' in content or 'MEMORY.md' in content:
            always_survives.append(f"[{i}] CLAUDE.md/MEMORY.md 참조")
        elif recency <= 5:  # 최근 5개 이벤트
            likely_survives.append(f"[{i}] 최근 이벤트: {content[:60]}...")
        elif 'error' in content.lower() or 'fail' in content.lower():
            likely_survives.append(f"[{i}] 에러/실패 기록: {content[:60]}...")
        elif role == 'tool' and recency > 20:
            likely_lost.append(f"[{i}] 오래된 도구 결과: {content[:60]}...")
        elif i == 0:  # 첫 번째 지시사항
            likely_lost.append(f"[{i}] 초기 지시사항 (압축 위험!): {content[:60]}...")
    
    print("=== 압축 생존 분석 ===")
    print(f"\n✅ 항상 살아남음 ({len(always_survives)}):")
    for item in always_survives[:5]:
        print(f"  {item}")
    
    print(f"\n🟡 생존 가능 ({len(likely_survives)}):")
    for item in likely_survives[:5]:
        print(f"  {item}")
    
    print(f"\n❌ 압축으로 사라질 위험 ({len(likely_lost)}):")
    for item in likely_lost[:5]:
        print(f"  {item}")
    
    print(f"\n📌 권장사항: 중요 규칙은 반드시 CLAUDE.md에 두세요")

# 사용법: python3 analyze_compaction.py ~/.claude/projects/xxx/session.jsonl
if __name__ == '__main__':
    import sys
    if len(sys.argv) > 1:
        analyze_compaction_survival(sys.argv[1])
    else:
        print("Usage: python3 analyze_compaction.py <session.jsonl>")

세션 JSONL 파일을 읽어서 각 이벤트가 압축 후에도 살아남을 가능성을 분류한다. CLAUDE.md/MEMORY.md 참조 이벤트는 항상 살아남고, 오래된 초기 지시사항은 위험하다. 이 분석으로 어떤 규칙을 CLAUDE.md에 올려야 할지 결정할 수 있다.

🏭 현업에서의 평가
Claude Code의 내부 아키텍처를 이해한다는 것은 단순히 지식의 문제가 아니다. 에이전트가 예상과 다르게 행동할 때 '왜?'를 빠르게 진단할 수 있는 능력의 차이다.

✅ 시니어가 보는 것

  • queryLoop와 ReAct 패턴을 연결해서 설명할 수 있는가
  • 7개 안전 레이어 중 자신이 제어할 수 있는 것은 무엇인지 아는가
  • 컨텍스트 압축 후 초기 지시사항이 사라질 수 있다는 것을 아는가
  • 에이전트 이상 행동 시 Layer별로 원인을 좁혀가는 디버깅 방법론을 가지고 있는가

⚠️ 레드 플래그

  • 에이전트가 규칙을 무시할 때 '모델 문제'라고만 말함
  • CLAUDE.md와 훅의 차이(확률적 vs 결정론적)를 모름
  • 컨텍스트 압축이 무엇인지 모름

🎤 예상 인터뷰 질문

  1. Claude Code에서 PreToolUse 훅과 permissions.deny 규칙이 모두 있을 때 평가 순서는?
  2. 세션 초기에 '절대 main 브랜치에 push하지 말 것'이라고 했는데 에이전트가 나중에 push했다. 원인은?
  3. queryLoop()가 'simplicity and latency over exhaustive search planning'을 우선시한다는 것이 에이전트 행동에 미치는 실제 영향은?
숙달 vs 익숙함: 단순히 아는 사람은 '7개 안전 레이어가 있다'고 말한다. 마스터한 사람은 각 레이어가 어떤 순서로 실행되고, 자신의 훅이 Layer 7에 해당하며, ML 분류기(Layer 4)가 별도 Sonnet 인스턴스로 돌아간다는 것까지 알고 이를 활용해서 auto-mode를 의도적으로 배치한다.

Key Takeaways

핵심 정리

queryLoop = ReAct

Claude Code의 핵심은 모델 호출 → 도구 실행 → 관찰 반복하는 비동기 제너레이터 함수다.

단순성 우선

queryLoop는 exhaustive planning보다 단순성과 낮은 지연을 우선한다. 에이전트의 '성급한' 행동은 설계 선택이다.

Layer 3,4,5가 제어 지점

Safety/Action, State, Backend — 이 3개 레이어가 하네스 엔지니어의 주요 작업 공간이다.

7개 안전 레이어

훅은 Layer 7 — 가장 유연하고 커스터마이즈 가능한 레이어다. 다른 레이어는 Anthropic이 제어한다.

압축 = 초기 지시 消滅

세션 초기의 지시사항은 Auto-compact(5단계)에서 사라진다. 중요 규칙은 CLAUDE.md에 넣어야 한다.

54개 도구

19개 무조건 + 35개 feature flag 조건부. MCP는 이 도구 풀을 동적으로 확장한다.

Deny-first

권한 평가 순서: deny → ask → allow. 첫 매칭이 우선. Specificity는 순서를 이기지 않는다.

98.4% 다시 한번

아키텍처를 이해하면 98.4%가 단순한 숫자가 아님을 알게 된다. 5단계 압축, 7개 안전 레이어, 23개 bash 체크 — 이게 다 그 98.4%다.