홈/Part 1: 기초/에이전트란 무엇인가
🧬
Part 1입문⏱ 약 30분 · 3개 섹션

에이전트란 무엇인가

LLM API 래퍼에서 자율 에이전트로

에이전트란 무엇인가 대표 이미지
✦이 챕터에서 배울 것
  • ▸에이전트 = LLM + 도구 + 상태 관리 + 안전성
  • ▸Claude Code는 50+개 도구, 다계층 권한, 멀티 에이전트를 포함한 완전한 에이전트 시스템
  • ▸프로덕션 에이전트에는 이론에서 다루지 않는 수많은 현실적 문제가 존재
1LLM API 호출 vs 에이전트2프로젝트 해부: 1,884개 파일의 지도3진입점에서 실행까지
전체 아키텍처에서 현재 위치
⚙️코어 엔진
→
🔧도구 시스템
→
🛡️보안
→
🧠컨텍스트
→
🤝멀티 에이전트
→
🌐생태계
→
⚡인프라
1

LLM API 호출 vs 에이전트

단순 API 호출과 에이전트 시스템의 근본적인 차이를 이해합니다

에이전트 루프도구 실행상태 관리컨텍스트 윈도우|main.tsxQueryEngine.ts

LLM API를 호출하는 것과 에이전트를 구축하는 것은 근본적으로 다릅니다. API 호출은 하나의 요청-응답 쌍이지만, 에이전트는 목표를 달성할 때까지 반복적으로 행동하는 자율 시스템입니다.

Claude Code는 이 차이를 극명하게 보여줍니다:

  • 1,884개 파일, 565,000줄의 코드
  • 50+ 도구 — 파일 읽기/쓰기, 셸 실행, 웹 검색, 에이전트 생성 등
  • 26개 보안 모듈 — 131KB Bash 파서로 명령을 AST 분석
  • 4가지 컴팩션 전략 — 무한한 대화를 유한한 컨텍스트에 맞추기 위해
  • 7가지 태스크 타입 — 로컬, 원격, 인프로세스, Dream 등

💡 비유로 이해하기

각 행을 클릭하여 대응 관계를 확인하세요

🌍레스토랑 주방
🤖AI 에이전트 시스템
◈

에이전트의 5가지 핵심 요소

클릭하여 탐색
→
→
→
→
💡 에이전트의 본질
에이전트 = LLM + 도구(Tools) + 상태 관리(State) + 안전성(Safety) + 메모리(Memory). 이 5가지 요소가 없으면 에이전트가 아니라 단순 API 래퍼입니다.
에이전트 vs API 호출 비교
1// 단순 API 호출 (에이전트가 아님)
2const response = await anthropic.messages.create({
3  model: "claude-sonnet-4-20250514",
4  messages: [{ role: "user", content: "Hello" }],
5});
6 
7// Claude Code의 에이전트 루프 (src/QueryEngine.ts, 1,295줄)
8while (true) {💡
9  const systemPrompt = await buildSystemPrompt(context);
10  const response = await apiClient.messages.create({
11    model, messages, tools, system: systemPrompt
12  });
13  for (const block of response.content) {
14    if (block.type === "tool_use") {💡
15      const result = await executeTool(block); // 검증→권한→실행→결과
16      messages.push(toolResult(result));
17    }
18  }
19  if (response.stop_reason === "end_turn") break;💡
20  if (exceedsBudget(messages)) await compact(messages);💡
21}
?

이해도 확인 퀴즈

다음 중 AI 에이전트와 단순 LLM API 호출의 가장 큰 차이점은?

2

프로젝트 해부: 1,884개 파일의 지도

Claude Code 소스 코드의 전체 구조와 각 모듈의 역할을 파악합니다

모듈 구조관심사 분리진입점의존성 그래프|Tool.tsTask.tscommands.ts+1

Claude Code의 소스 코드는 명확한 관심사 분리를 따르는 모듈 구조로 설계되어 있습니다.

프로젝트 구조 전체 지도
1src/
2├── entrypoints/               # 진입점 (cli.tsx → init.ts → main.tsx)
3├── main.tsx          [4,683L] # 메인 부트스트랩 (가장 큰 파일)
4├── QueryEngine.ts    [1,295L] # 대화 루프 엔진 (심장)
5├── Tool.ts             [792L] # 도구 인터페이스 (뼈대)
6├── tools/             [184 files] # 도구 구현체 (50+)
7│   ├── BashTool/         [18] # 가장 복잡한 도구
8│   ├── AgentTool/        [14] # 하위 에이전트 생성
9│   └── ...40+ more
10├── services/          [130 files] # 핵심 서비스 (API, MCP, LSP)
11├── utils/             [564 files] # 유틸리티 (가장 큰 모듈)
12│   ├── permissions/      [24] # 권한 시스템
13│   ├── plugins/          [44] # 플러그인 시스템
14│   └── bash/             [15] # Bash 파서 (131KB)
15├── components/        [389 files] # UI 컴포넌트
16├── commands/          [189 files] # 슬래시 커맨드 (100+)
17├── ink/                [96 files] # 터미널 UI 엔진
18├── bridge/             [31 files] # 원격 실행 브릿지
19├── tasks/              [12 files] # 태스크 시스템 (7타입)
20└── coordinator/         [1 file]  # 멀티 에이전트 조율
3

진입점에서 실행까지

CLI 시작부터 첫 응답까지의 전체 흐름을 추적합니다

부트스트랩인증설정 로드REPL 시작|entrypoints/cli.tsxmain.tsxsetup.ts

claude 명령어를 터미널에 입력하면 다음 6단계를 거쳐 첫 응답이 생성됩니다.

진입점 → 실행 흐름
1// 6단계 초기화 시퀀스
2// 1. cli.tsx     → --version 등 특수 플래그 처리
3// 2. init.ts     → 설정 검증, OAuth 로드, 텔레메트리
4// 3. main.tsx    → 인증, 모델 선택, MCP, 도구 구성
5// 4. setup.ts    → Trust 대화상자, 온보딩, 정책 승인
6// 5. REPL 시작   → Ink 루트 생성, React 마운트
7// 6. QueryEngine → 대화 루프 시작
⟩

CLI 시작부터 첫 응답까지 6단계

CLI 진입
특수 플래그 처리 (--version 등)
초기화
설정 검증, OAuth, 텔레메트리
부트스트랩
인증, 모델 선택, MCP, 도구 구성
셋업 화면
Trust 대화상자, 온보딩
REPL 시작
Ink 루트 생성, React 마운트
대화 루프
사용자 입력 대기 → 응답 생성
💡 레이지 로딩
main.tsx가 4,683줄인 이유는 모든 것을 레이지 로딩하기 때문입니다. 커맨드, 도구, MCP 서버가 필요한 시점에만 import됩니다.
?

이해도 확인 퀴즈

Claude Code가 시작될 때, '사용자 신뢰 대화상자(Trust Dialog)'는 왜 필요할까요?

✅ 학습 체크리스트

이해한 항목을 체크하고 학습 진도를 확인하세요

0/5 완료0%

📋 Chapter 1 요약: 에이전트란 무엇인가

이 챕터에서 배운 핵심 개념을 정리합니다

1
에이전트 ≠ API 래퍼
에이전트는 목표 달성까지 도구를 반복 사용하는 자율 시스템입니다. 단순한 API 호출과는 본질적으로 다릅니다.
2
5가지 핵심 요소
LLM(두뇌) + 도구(손발) + 상태(기억) + 안전성(안전장치) + 메모리(장기기억)가 프로덕션 에이전트를 구성합니다.
3
56만 줄의 이유
50+ 도구, 26개 보안 모듈, 7가지 태스크 타입, 4가지 컴팩션 전략 등 현실의 복잡성을 다루기 위한 것입니다.
4
모듈 구조
tools(도구), services(서비스), utils(유틸리티), components(UI)로 관심사가 분리되어 있습니다.
5
부트스트랩 시퀀스
CLI 진입 → 초기화 → 인증/MCP → Trust 확인 → REPL → 대화 루프의 6단계로 시작합니다.

다음 챕터 미리보기: 다음 챕터에서는 에이전트의 심장인 '대화 루프(QueryEngine)'를 해부합니다.