Claude Code 내부 동작 방식 완전 해부 — Agentic Loop부터 컨텍스트 로딩까지

Claude Code 내부 동작 방식 완전 해부 — Agentic Loop부터 컨텍스트 로딩까지
Claude Code가 터미널에서 어떻게 돌아가는지 공식 문서(VineeTagarwaL의 Mintlify 정리본) 기준으로 핵심만 정리했습니다.

Claude Code는 어떻게 동작하나?
한마디로 “읽고 → 생각하고 → 도구 쓰고 → 결과 보고 → 반복” 하는 루프입니다.
Agentic Loop 6단계
1. 사용자가 터미널에 메시지 입력 (또는 --print / stdin으로 전달)
2. 시스템 프롬프트 조립 — 현재 날짜, git 상태, CLAUDE.md 파일, 사용 가능한 도구 목록
3. Anthropic API 호출 → 모델이 tool_use 블록(도구 이름 + JSON 입력) 생성
4. 권한 체크 — 자동 승인 / 확인 요청 / 차단 중 하나 결정
5. 도구 실행 → 결과(파일 내용, 명령 출력 등)를 tool_result로 대화에 추가
6. 결과를 받은 모델이 추가 도구 호출 or 최종 응답 — 도구 호출이 없을 때까지 반복
루프는 로컬 터미널 프로세스에서만 돌아갑니다. WebFetch, WebSearch, MCP 서버처럼 명시적으로 외부를 호출하는 도구가 아닌 이상 파일·셸·인증 정보가 머신 밖으로 나가지 않습니다.

컨텍스트는 어떻게 만들어지나?
대화 시작 시 두 블록을 조립해 모든 API 호출에 앞에 붙입니다.
∙ 시스템 컨텍스트 — 현재 브랜치, 최근 5개 커밋, git status --short 결과(2,000자 초과 시 잘림)
∙ 유저 컨텍스트 — CLAUDE.md 메모리 파일(4단계 계층 탐색), 오늘 날짜(Today's date is YYYY-MM-DD)
두 블록 모두 lodash/memoize로 대화 단위 캐싱됩니다. setSystemPromptInjection() 호출 시 즉시 캐시가 초기화됩니다.

권한 모델 — 도구를 언제 실행하나?

결과	동작
allow	즉시 실행, 결과 대화에 추가
ask	일시 정지 → 확인 다이얼로그 표시
deny	거부 → 모델에게 에러 반환

∙	bypassPermissions 모드: 모든 체크 스킵  
∙	acceptEdits 모드: 파일 편집 자동 승인, bash는 여전히 확인 요청  
∙	Read, Glob, Grep 같은 읽기 전용 도구는 모든 모드에서 기본 자동 승인  

서브에이전트(Task 도구)
Claude는 Task 도구(AgentTool)로 서브에이전트를 스폰할 수 있습니다. 서브에이전트는 격리된 대화와 선택적으로 제한된 도구셋으로 자체 Agentic Loop를 돌리고, 완료 시 부모 에이전트에게 결과를 반환합니다. 로컬(인프로세스) 또는 리모트 컴퓨트에서 실행 가능합니다.

대화 저장과 복원
대화는 ~/.claude/에 JSON 트랜스크립트 파일로 저장됩니다.
∙ --resume <session-id> 또는 --resume 단독으로 이전 대화 재개
∙ 재개 시: 전체 메시지 히스토리 로드, CLAUDE.md 파일 재탐색, 권한 모드는 설정 기본값으로 리셋
∙ 긴 대화는 주기적으로 컴팩션 — 오래된 메시지를 요약해 컨텍스트 윈도우를 관리. 전체 원본 트랜스크립트는 디스크에 보존됨

쿼리 엔진이 하는 일
각 “턴”은 query.ts가 구동합니다.
∙ 토큰 스트리밍을 터미널에 실시간 출력
∙ tool_use 블록을 적절한 핸들러에 디스패치
∙ 턴당 토큰·도구 호출 예산 관리
∙ 컨텍스트 윈도우 가득 차면 컴팩션 트리거
∙ 각 도구는 maxResultSizeChars 속성을 가짐 — 결과가 이 한도를 초과하면 임시 파일로 저장하고 모델에게는 파일 경로만 전달 (컨텍스트 윈도우 overflow 방지)

원문: How Claude Code works — Mintlify
참고: VineeTagarwaL이 Claude Code 공식 문서를 Mintlify로 재정리한 비공식 미러 문서입니다.​​​​​​​​​​​​​​​​