# 작동 원리

> 에이전틱 루프, 컨텍스트 로딩, 도구 실행 모델, 대화 생명주기에 대한 내부 동작 설명.

Claude Code는 터미널 기반 코딩 에이전트로, 연속적인 에이전틱 루프를 실행합니다. 요청을 읽고, 무엇을 해야 할지 추론하고, 도구를 호출하고, 결과를 관찰하고, 작업이 완료되거나 입력이 필요할 때까지 이를 반복합니다.

## 에이전틱 루프

모든 상호작용은 동일한 기본 사이클을 따릅니다:

1. **사용자가 메시지를 보냄** — 터미널에서 메시지를 입력하거나(대화형 모드), `--print` / stdin을 통해 전달합니다(비대화형/헤드리스 모드). 메시지는 대화 기록에 추가됩니다.

2. **컨텍스트 조립** — 모델을 호출하기 전에, Claude Code가 시스템 프롬프트를 조립합니다: 현재 날짜, git 상태(브랜치, 최근 커밋, 워킹트리 상태), 로드된 CLAUDE.md 메모리 파일들, 사용 가능한 도구 목록. 이 컨텍스트는 대화당 한 번 구성되고 메모이제이션됩니다.

3. **Claude가 추론하고 도구를 선택** — 조립된 대화가 Anthropic API로 전송됩니다. 모델이 작업에 대해 추론하고 하나 이상의 `tool_use` 블록을 출력합니다 — 각각 도구 이름과 구조화된 JSON 입력을 지정합니다.

4. **권한 확인** — 각 도구 호출을 실행하기 전에, Claude Code가 현재 권한 모드와 허용/차단 규칙을 평가합니다. 모드에 따라 자동 승인하거나, 확인을 요청하거나, 호출을 완전히 차단합니다.

5. **도구가 실행되고 결과를 반환** — 승인된 도구 호출이 실행됩니다. 결과(파일 내용, 명령어 출력, 검색 결과)는 `tool_result` 블록으로 대화에 추가됩니다.

6. **루프 계속** — 모델이 도구 결과를 받아 더 많은 도구를 호출하거나 최종 텍스트 응답을 생성합니다. 모델 턴에 도구 호출이 더 이상 없을 때까지 루프가 반복됩니다.

> 📝 루프는 전적으로 터미널 프로세스 안에서 실행됩니다. 원격 실행 서버가 없습니다 — 도구가 명시적으로 전송하지 않는 한(`WebFetch`, `WebSearch`, 또는 MCP 서버 등), 파일, 셸, 자격 증명이 사용자의 머신을 벗어나지 않습니다.

## 컨텍스트 로딩

각 대화 시작 시, Claude Code가 모든 API 호출에 앞에 추가되는 두 개의 컨텍스트 블록을 구성합니다:

**시스템 컨텍스트** (`context.ts`의 `getSystemContext()`로 조립):
- **Git 상태** — 현재 브랜치, 기본/메인 브랜치, git 사용자명, `git status --short` 출력(2,000자 초과 시 자름), `git log --oneline`의 마지막 5개 커밋
- **캐시 무효화 주입** — 디버깅 중 서버 측 프롬프트 캐시를 무효화하기 위해 내부적으로 사용되는 임시 문자열

**사용자 컨텍스트** (`context.ts`의 `getUserContext()`로 조립):
- **CLAUDE.md 메모리** — 4단계 계층(managed → user → project → local)에서 발견된 모든 메모리 파일
- **현재 날짜** — 모델이 항상 날짜를 알 수 있도록 `Today's date is YYYY-MM-DD`로 주입

두 컨텍스트 블록은 `lodash/memoize`를 사용해 대화 기간 동안 **메모이제이션**됩니다.

## 도구 실행 모델

Claude Code는 기본적으로 도구 호출을 자율적으로 실행하지 않습니다. 각 도구는 `checkPermissions` 메서드를 가지며, 그 결과가 다음 동작을 결정합니다:

| 권한 결과 | 동작 |
|-----------|------|
| `allow` | 도구가 즉시 실행되고 결과가 대화에 추가됩니다 |
| `ask` | Claude Code가 일시 중지하고 확인 다이얼로그를 렌더링합니다 |
| `deny` | 도구 호출이 거부되고 Claude가 오류 결과를 받습니다 |

안전하고 읽기 전용인 도구 호출(`Read`, `Glob`, `Grep` 등)은 일반적으로 모든 모드에서 자동 승인됩니다.

## 대화형 vs 비대화형(작업) 모드

**대화형(REPL) 모드** — 기본 경험. Claude Code가 React/Ink를 사용해 라이브 터미널 UI를 렌더링합니다. 에이전트가 작업하는 동안 스트리밍 출력, 도구 사용 확인, 스피너 애니메이션을 볼 수 있습니다. 메시지는 종료할 때까지 세션 전반에 걸쳐 유지됩니다.

**비대화형/프린트 모드** — `--print`로 활성화하거나 stdin을 파이핑합니다. UI가 렌더링되지 않습니다. 출력이 stdout에 기록되어 스크립트나 CI 파이프라인에서 캡처할 수 있습니다. 일회성 자동화 작업에 유용합니다.

### 서브에이전트 (Task 도구)

Claude가 `Task` 도구(`AgentTool`)를 통해 서브에이전트를 스폰할 수 있습니다. 각 서브에이전트는 격리된 대화와 선택적으로 제한된 도구 집합을 가진 자체 중첩된 에이전틱 루프를 실행합니다. 서브에이전트는 로컬(인프로세스) 또는 원격 컴퓨팅에서 실행될 수 있습니다. 서브에이전트가 완료되면 결과가 부모 에이전트로 반환됩니다.

## 대화 저장 및 재개

대화는 디스크의 JSON 트랜스크립트 파일로 저장됩니다(기본적으로 `~/.claude/`에). 각 대화에는 고유한 세션 ID가 있습니다. `--resume <session-id>`로 이전 대화를 재개하거나, `--resume`만으로 목록에서 선택할 수 있습니다.

대화가 재개될 때:
- 전체 메시지 기록이 디스크에서 로드됩니다
- 메모리 파일이 다시 발견되어 대화 최초 시작 시와 다를 수 있습니다
- 권한 모드가 세션에 유지되지 않는 한 설정된 기본값으로 재설정됩니다

> 💡 긴 대화는 주기적으로 **컴팩트**됩니다 — 가장 오래된 메시지가 요약되어 컨텍스트 윈도우를 관리 가능하게 유지합니다. 원본 트랜스크립트 전체는 항상 디스크에 보존됩니다; 컴팩트는 API에 전송되는 내용에만 영향을 줍니다.

## 쿼리 엔진

내부적으로, 에이전틱 루프의 각 "턴"은 **쿼리** — `query.ts`에 대한 호출로, 현재 메시지 목록을 Anthropic API에 전송하고 응답을 스트리밍합니다 — 에 의해 구동됩니다. 쿼리 엔진이 처리하는 것들:

- 실시간으로 터미널에 토큰 출력 스트리밍
- `tool_use` 블록을 적절한 도구 핸들러에 디스패치
- 턴당 토큰 및 도구 호출 예산 적용
- 도구 결과 수집 및 다음 모델 호출 전 추가
- 컨텍스트 윈도우가 꽉 찰 때 컴팩트 트리거

각 도구에는 `maxResultSizeChars` 속성이 있습니다. 결과가 이 한계를 초과하면 내용이 임시 파일로 저장되고 모델이 파일 경로와 함께 미리보기를 받아, 대용량 출력으로 인한 컨텍스트 윈도우 오버플로우를 방지합니다.