how-claude-code-works 딥다이브
— 51만 줄 Claude Code를 15편 문서로 역설계한 저장소

세션 관리와 루프 실행의 분리

이 저장소가 가장 강조하는 구조적 결정 중 하나다. QueryEngine(외곽)은 "대화 전체가 얼마나 진행됐는지, 비용이 얼마인지, 사용자가 방금 뭘 입력했는지"를 관리한다. 내부의 query()는 "이번 한 사이클에서 압축이 필요한지, API가 뭘 반환했는지, 도구가 성공했는지"만 신경 쓴다. 왜 나누는가 — 관심사가 완전히 다르기 때문이다. 세션 레이어는 사용자 중단, 토큰 예산 소진, 대화 영속화 같은 생명주기 문제를 다루고, 쿼리 레이어는 "API 호출 → 응답 파싱 → 도구 실행 → 결과 조립"이라는 촘촘한 루프에만 집중한다.

비용이 낮은 순서대로 시도하는 압축 파이프라인

이 저장소가 "가장 정교한 설계"로 꼽는 부분이다. 컨텍스트 윈도우가 가득 차갈 때 한 번에 통째로 요약하는 대신, 4단계로 나눠 순차 시도한다. 각 단계는 이전 단계보다 "더 무겁고, 더 많은 세부 정보를 잃는다".

왜 4단계로 나누는가? Autocompact만 있다면 컨텍스트가 찰 때마다 반드시 API를 호출해 요약을 생성해야 한다 — 지연시간과 정보 손실 둘 다 발생한다. 무비용 Snip과 거의 무비용인 Microcompact를 먼저 시도하면, 대부분의 대화는 비싼 Autocompact까지 가지 않고 끝난다. 이 저장소는 실제 소스 주석을 인용해 그 근거를 뒷받침한다 — 서킷 브레이커(연속 3회 압축 실패 시 중단) 도입 배경으로 "1,279개 세션에서 연속 50회 이상(최대 3,272회) 압축 실패가 발생해 하루 약 25만 회의 API 호출을 낭비했다"는 실제 프로덕션 데이터를 인용한다.

모델이 아직 말하는 중에 도구는 이미 실행된다

이 저장소가 "Claude Code가 왜 빠르게 느껴지는가"의 핵심 답으로 제시하는 메커니즘이다. 소박한 구현이라면: 모델 응답 전체 대기 → 도구 호출 파싱 → 순차 실행 → 결과 전송. Claude Code는 다르다 — 모델이 여전히 다음 텍스트를 생성하는 동안, 이미 완전히 파싱된 tool_use 블록은 즉시 실행을 시작한다.

이 저장소가 짚어낸 숫자로 말하면: 도구 하나 실행에 보통 약 1초가 걸리는데, 모델의 스트리밍 응답은 5~30초 지속된다. 3~4개의 도구 호출이 포함된 응답이라면, 이 겹침 효과로 사용자가 체감하는 종단 지연시간을 크게 줄일 수 있다. 도구는 queued → executing → completed → yielded 4가지 상태를 거치며, 오직 읽기 전용이고 isConcurrencySafe가 참인 도구끼리만 병렬 실행되고, 쓰기 작업은 독점 실행된다.

단 하나의 확인창이 아니라, 서로 다른 기술을 쓰는 7개 층

Claude Code는 사용자 컴퓨터에서 실제 명령을 실행하므로 보안이 타협 불가능한 전제조건이다. 이 저장소가 상세 분석한 방어선은(문서 간 표기가 5층/7층으로 다르게 등장하는데, 핵심 검사 체계 기준으로 보면 아래 흐름이다):

핵심 통찰은 각 층이 완전히 다른 기술을 쓴다는 점이다 — 규칙 매칭(문자열), 문법 분석(tree-sitter AST), 정적 패턴(정규식 23종), 머신러닝(경량 분류기), 인간 판단(확인창). 이 저장소는 "왜 하나의 통합 검사가 아니라 7층인가"에 이렇게 답한다 — 심층 방어의 핵심 가정은 "어떤 층이든 우회될 수 있다"는 것이다. tree-sitter 의미 분석이 우회되더라도, 경로 제약과 사용자 확인은 여전히 막을 수 있다.

이 저장소는 여러 에이전트가 협업하는 3가지 모드를 상세 분석한다.

충돌 방지를 위해 시스템은 Git Worktree로 각 에이전트에 독립된 코드 사본을 제공한다. 작업이 끝났을 때 실질적 변경이 없으면 자동 정리되고, 변경이 있으면 경로와 브랜치명을 반환해 사용자가 병합 여부를 결정하게 한다.

챗봇과 에이전트의 근본 차이를 코드 레벨에서 배울 수 있다. 챗봇은 요청-응답 1회로 끝나지만, 에이전트는 while(true) 루프를 돌며 모델이 도구 호출을 포함하지 않는 순수 텍스트 응답을 낼 때까지 계속된다. 종료 신호나 카운터가 따로 없다 — "도구를 안 부른다"는 선택 자체가 곧 "끝났다"는 신호다. 이 저장소는 여기서 그치지 않고, 실전에서 이 단순한 루프가 왜 1,729줄로 자라야 했는지를 7개 Continue Site(장애 복구 재진입점)로 설명한다: 프롬프트 초과(PTL), 출력 토큰 한도, API 과부하, 압축 트리거 재시도 등 각각의 실패 시나리오.

배울 것: async generator로 스트리밍 루프 구현, 상태 머신으로 재시도 로직 정리, "에러 보류(withholding)" — 복구 가능한 에러는 사용자에게 노출하지 않고 내부에서 처리 후 계속 진행하는 패턴.

LLM 애플리케이션에서 가장 저평가된 주제를 정면으로 다룬다. 프롬프트 캐시는 바이트 단위로 완전히 동일해야만 히트한다 — 이 제약이 시스템 프롬프트 구성 순서, 도구 배열 정렬 방식, 심지어 어떤 정보를 메시지 앞에 붙이고 뒤에 붙일지까지 결정한다는 것을 배울 수 있다. "정적 콘텐츠는 앞, 동적 콘텐츠는 뒤"라는 한 문장 원칙이 시스템 전체 설계를 관통한다.

배울 것: KV 캐시(전위 캐시)의 작동 원리, 캐시 경계(cache_control) 설정 전략, <system-reminder> XML 태그로 시스템 메타정보를 사용자 발화와 섞이지 않게 주입하는 기법, memoize로 반복 계산을 회피하는 패턴.

"보안은 여러 층으로 만들어야 한다"는 원칙을 교과서가 아니라 실제 프로덕션 코드 수준에서 배울 수 있다. tree-sitter AST + 정규식 23종 + ML 분류기 + 인간 확인이 각각 독립적으로 동작하도록 설계된 이유, "FAIL-CLOSED"(이해 못 하는 구조는 무조건 차단)라는 원칙이 코드에 어떻게 반영되는지, 화이트리스트가 블랙리스트보다 안전한 이유(신규 속성 추가 시 기본값이 "거부"가 되도록)까지 배운다.

배울 것: 정규식 기반 보안 검사의 한계와 AST 기반 분석의 우위, fail-closed 기본값 설계, 사용자 확인 UI와 자동화 검사를 "경주"시켜 지연 없이 빠른 결정을 내리는 패턴.

대규모 플러그인/도구 생태계를 어떻게 설계해야 신규 도구 추가가 기존 코드를 건드리지 않게 되는지를 배운다. 모든 도구가 동일한 Tool 인터페이스를 구현하고, 안전 속성(isReadOnly, isConcurrencySafe)을 "입력값을 받는 메서드"로 선언해 같은 도구라도 입력에 따라 안전도가 달라질 수 있게 한 설계가 인상적이다.

배울 것: 개방-폐쇄 원칙(OCP)의 실전 적용, fail-closed 기본값 팩토리 패턴(TOOL_DEFAULTS), 대용량 도구 결과를 디스크로 스필오버하는 패턴, ToolSearch로 지연 로딩해 초기 프롬프트 크기를 줄이는 기법.

서브 에이전트를 만들 때 "부모 컨텍스트를 공유할 것인가, 격리할 것인가"라는 트레이드오프를 정면으로 다룬다. 기본은 격리("deny by default")지만, Fork 서브 에이전트는 예외적으로 부모의 전체 요청 전위(prefix)를 그대로 상속해 프롬프트 캐시를 공유하는 경제학적 이유를 설명한다.

배울 것: Git Worktree로 파일 시스템 격리하기, AbortController 체이닝으로 장애를 격리하는 패턴, "협업자는 실행하지 않는다"는 제약으로 역할을 강제 분리하는 설계.

15편 중 가장 긴 문서(14-system-prompt-design.md)가 다루는 주제. 시스템 프롬프트를 "그냥 긴 지시문 텍스트"가 아니라 7층으로 계층화된 아키텍처로 설계하는 법, 반패턴을 미리 "접종"(inoculation)해 모델이 흔한 실수를 피하게 만드는 프롬프트 기법, 위험 반경(explosion radius) 프레임워크로 조작의 위험도를 분류하는 사고방식을 배울 수 있다.

배울 것: 프롬프트를 코드처럼 버전 관리하고 계층화하는 법, 부정 예시(negative example)로 모델을 유도하는 기법, "실습 아이디어" — 자신의 에이전트 시스템 프롬프트에 "절대 하지 말 것" 섹션을 추가해 반패턴 접종을 실험해보기.

실습 1 — 로컬에서 문서 사이트 띄우고 quick-start.md부터 정독하기

저장소를 클론하고 Docsify로 로컬 미리보기를 띄운다. 15편 전체를 다 읽기 전에 먼저 docs/quick-start.md(10분 요약본)로 전체 지도를 파악하는 것이 이 저장소가 직접 권장하는 순서다.

git clone https://github.com/Windy3f3f3f3f/how-claude-code-works.git
cd how-claude-code-works
npx docsify-cli serve .          # 또는: python3 -m http.server 3000
# 브라우저에서 http://localhost:3000 접속

확인 포인트: quick-start.md를 읽은 뒤, "Agent Loop가 언제 멈추는가"를 자기 말로 한 문장 요약해본다. (정답 힌트: 모델 응답에 tool_use 블록이 없을 때.)

실습 2 — 4단계 압축 파이프라인을 다이어그램으로 직접 그려보기

docs/03-context-engineering.md를 읽고, Snip → Microcompact → Context Collapse → Autocompact 4단계 각각의 "무엇을 지우는가", "비용은 얼마인가", "되돌릴 수 있는가"를 표로 정리한다. 이 문서의 설명을 보지 않고 자기 힘으로 채워본 뒤 원문과 비교한다.

확인 포인트: "왜 Context Collapse가 Autocompact보다 먼저 시도되는가"를 설명할 수 있는지 스스로 점검한다. (힌트: 투영식이라 되돌릴 수 있고, 90% 활용률에서 커밋되어 Autocompact 트리거를 종종 막아준다.)

실습 3 — claude-code-from-scratch로 최소 Agent Loop 직접 실행 + 수정

자매 저장소를 클론해 실제로 실행해본다. 15장 분석 문서에서 설명한 "7개 Continue Site" 중 하나(예: 프롬프트 초과 시 대화 요약)를 최소 버전에는 어떻게 단순화했는지 비교한다.

git clone https://github.com/Windy3f3f3f3f/claude-code-from-scratch.git
cd claude-code-from-scratch
npm install
# ANTHROPIC_API_KEY 환경변수 설정 후
npm run build && npm start
# src/agent.ts의 while(true) 루프를 열어서 직접 수정해본다

확인 포인트: checkAndCompact() 함수를 찾아 압축 트리거 임계값(85%)을 90%로 바꿔보고, 실제로 더 늦게 압축되는지 관찰한다.

실습 4 — 이 저장소의 "숫자 주장"을 검증하는 체크리스트 만들기

이 저장소는 "9단계 병렬 시작으로 약 235ms", "66+ 도구", "23항목 보안 검사" 같은 구체적 숫자를 많이 인용한다. 15편 문서를 훑으며 이런 구체적 수치·상수명을 모두 뽑아 표로 정리하고, 각각이 어느 챕터·어느 소스 파일 경로에서 인용됐는지 출처를 붙인다. (이 저장소는 3자 분석이므로 실제 Claude Code 버전에 따라 숫자가 달라질 수 있다는 점도 함께 메모한다.)

확인 포인트: 정리한 표가 docs/reference.md(속성 참조 페이지)와 얼마나 겹치는지 비교해, 자신이 놓친 핵심 상수가 있는지 확인한다.

실습 5 — 5층 방어 권한 시스템을 미니어처로 직접 구현하기

docs/11-permission-security.md를 참고해, 아주 작은 규모(정규식 위험 명령어 목록 + 사용자 확인 프롬프트)로 자신만의 "위험 명령 차단기"를 Node.js나 Python으로 만들어본다. 그 다음 "정규식만으로는 왜 부족한가"를 직접 겪어본다 — $(echo rm) -rf . 같은 명령이 자신이 만든 정규식을 우회하는지 테스트해본다.

# 예시 위험 패턴 (최소 버전, 이 저장소의 23항목보다 훨씬 단순)
const DANGEROUS_PATTERNS = [
  /\brm\s/, /\bsudo\b/, /\bmkfs\b/, />\s*\/dev\//, /\bkill\b/,
];
// 시도: "echo hi && $(echo rm) -rf ./test" 가 위 패턴을 통과하는지 확인

확인 포인트: 우회 사례를 하나 찾았다면, 이 저장소가 설명한 tree-sitter AST 접근이 왜 이 문제를 근본적으로 해결하는지(문자열이 아니라 "실행될 명령의 실제 구조"를 본다는 점) 스스로 설명해본다.

목표: 15편 문서를 순서대로(README가 권장하는 순서: 개요→메인루프→컨텍스트→도구시스템) 읽고 전체 아키텍처를 손으로 다이어그램화한다.

자료: 온라인 문서 사이트, 특히 docs/quick-start.md와 docs/reference.md.

실습: 이 딥다이브 4장의 시스템 구조도를 자기 손으로 다시 그려보고, 빠진 서브시스템(Hook, 기억, 기술)을 추가해 완전한 버전을 만든다.

목표: JavaScript/TypeScript의 async generator 문법을 익히고, "모델이 스스로 멈춘다"는 루프 종료 조건을 직접 구현해본다.

자료: MDN "Iterators and generators", docs/02-agent-loop.md, claude-code-from-scratch의 src/agent.ts.

실습: Anthropic SDK로 최소 도구 호출 루프(read_file, write_file, run_shell 3개 도구만)를 처음부터 작성해본다.

목표: LLM API의 프롬프트 캐싱 메커니즘(전위 캐시)을 이해하고, 캐시 히트율을 높이는 요청 설계 원칙을 체화한다.

자료: Anthropic 공식 Prompt Caching 문서, docs/03-context-engineering.md.

실습: 같은 대화를 두 가지 방식(매번 시스템 프롬프트 순서를 바꾸는 버전 vs 고정하는 버전)으로 반복 호출해 캐시 히트율(cache_read_input_tokens) 차이를 직접 측정한다.

목표: tree-sitter의 기본 사용법을 익히고, 셸 명령을 문법 트리로 파싱하는 경험을 쌓는다.

자료: tree-sitter 공식 문서, tree-sitter-bash 문법 정의, docs/11-permission-security.md.

실습: tree-sitter-bash로 간단한 명령을 파싱해 AST를 출력해보고, 명령 치환($())이 포함된 명령과 아닌 명령의 트리 구조 차이를 관찰한다.

목표: 통합 인터페이스 기반 플러그인 아키텍처를 설계하고, 읽기/쓰기 동시성 규칙을 구현한다.

자료: docs/04-tool-system.md, Model Context Protocol(MCP) 공식 스펙.

실습: 자신만의 도구 3~5개(파일 읽기/검색/셸 실행)를 Tool 인터페이스 스타일로 정의하고, 읽기 전용 도구끼리는 Promise.all로 병렬 실행, 쓰기 도구는 직렬 실행하도록 오케스트레이션 로직을 작성한다.

목표: 서브 에이전트 위임 패턴을 이해하고, 컨텍스트 격리 vs 캐시 공유의 트레이드오프를 실험한다.

자료: docs/07-multi-agent.md, Git Worktree 공식 문서(git worktree add).

실습: 부모 에이전트가 "리서치용 서브 에이전트"를 fork해 결과를 받아오는 최소 구현을 만들고, Git Worktree로 파일 시스템을 격리해 두 에이전트가 같은 파일을 동시에 안전하게 편집하지 못하게 막아본다.

목표: 지금까지 배운 요소(에이전트 루프, 압축, 보안 검사, 도구 병렬 실행)를 하나의 CLI 프로그램으로 통합한다.

자료: claude-code-from-scratch 전체 11장 튜토리얼, 이 딥다이브 15장 표(6장 학습 포인트) 재확인.

실습: 8주간 만든 컴포넌트를 조합해 "파일 읽기·검색·편집·셸 실행 4개 도구 + 85% 임계값 압축 + 위험 명령 확인창"을 갖춘 완결된 미니 코딩 에이전트를 완성하고, 실제 작은 버그 수정 작업을 시켜본다.