claude-analysis
skill
Warn
Health Warn
- No license — Repository has no license file
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Warn
- process.env — Environment variable access in src/QueryEngine.ts
- network request — Outbound network request in src/assistant/sessionHistory.ts
- process.env — Environment variable access in src/bootstrap/state.ts
- network request — Outbound network request in src/bridge/bridgeApi.ts
- process.env — Environment variable access in src/bridge/bridgeConfig.ts
- network request — Outbound network request in src/bridge/bridgeDebug.ts
- process.env — Environment variable access in src/bridge/bridgeEnabled.ts
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Anthropic의 공식 AI 코딩 어시스턴트 Claude Code 소스코드 심층 분석
README.md
Claude Code CLI — Source Code Analysis
Anthropic의 공식 AI 코딩 어시스턴트 Claude Code 소스코드 심층 분석
이 프로젝트가 도움이 되셨다면 Star를 눌러주세요!
Index (MOC) · Directory Structure · Stats Report · Source Code · Tutorial
Quick Navigation — README가 매우 길어요! 관심 분야로 바로 이동하세요:
유출 배경 아키텍처 프롬프트 분석 소스코드 탐색 12장 튜토리얼
Table of Contents
- Overview
- Background — 소스코드 유출 경위
- Project Scale
- Architecture
- Design Principles
- Design Patterns
- Tech Stack
- Module Deep Dive
- Module Distribution
- Prompt & Agent Architecture
- Document Map
- Source Code Browse
- Usage with Obsidian
- Tutorial
- License & Disclaimer
- Contributing
Overview
이 저장소는 Anthropic의 공식 CLI 도구인 Claude Code 의 소스코드(src/ 디렉터리)를 정적 분석한 결과물입니다. 총 1,902개 파일, ~160개 디렉터리를 분석하여 39개의 상호 연결된 Obsidian 마크다운 문서로 구성했습니다.
실제 소스코드 포함: 이 저장소의
./src/디렉터리에는 Claude Code의 실제 TypeScript/TSX 소스코드 1,902개 파일이 포함되어 있습니다. 분석 문서를 읽으면서 원본 코드를 직접 열어볼 수 있으며, GitHub에서도 모든 파일을 바로 탐색할 수 있습니다. 전체 파일 목록은 Source Code Browse 섹션을 참고하세요.
모든 문서는 [[위키링크]]로 상호 연결되어 있어, Obsidian의 Graph View에서 모듈 간 관계를 시각적으로 탐색할 수 있습니다.
Background — 소스코드 유출 경위
출처: CyberSecurityNews — Anthropic's Claude Code Source Code Reportedly Leaked Via Their npm Registry
Anthropic의 공식 CLI 도구인 Claude Code의 전체 TypeScript 소스코드가 npm 패키지 설정 미스컨피규레이션을 통해 의도치 않게 외부에 노출되었습니다.
사건의 전말
- Anthropic이 npm에 배포한
@anthropic-ai/claude-code패키지에 **소스맵 파일(.map)**이 포함되어 있었습니다. - 해당
.map파일에는 난독화되지 않은(unobfuscated) 원본 TypeScript 소스코드의 참조 경로가 기록되어 있었습니다. - 이 경로는 Anthropic의 자체 R2 클라우드 스토리지 버킷을 가리키고 있었으며, 완전한 소스코드가 ZIP 아카이브 형태로 직접 다운로드 가능한 상태였습니다.
- 보안 연구자가 이를 발견한 후, 원본 소스코드가 공개 GitHub 저장소(nirholas/claude-code의 backup 브랜치)에 미러링되었습니다.
flowchart LR
NPM["npm Registry<br/>@anthropic-ai/claude-code"] -->|"패키지에 .map 파일 포함"| Map[".map 소스맵 파일"]
Map -->|"원본 경로 참조"| R2["Anthropic R2<br/>Cloud Storage"]
R2 -->|"ZIP 다운로드 가능"| Source["전체 TypeScript<br/>소스코드"]
Source -->|"보안 연구자 발견"| Mirror["GitHub 미러<br/>nirholas/claude-code"]
Mirror -->|"분석 및 문서화"| This["이 저장소<br/>leaf-kit/claude-analysis"]
style NPM fill:#cb3837,stroke:#cb3837,color:#fff
style R2 fill:#f38020,stroke:#f38020,color:#fff
style Source fill:#3178c6,stroke:#3178c6,color:#fff
style This fill:#e8f5e9,stroke:#2e7d32
핵심 포인트
- 유출 원인: npm 패키지 빌드 시 소스맵 파일(
.map)이 제거되지 않았고, 해당 파일이 Anthropic의 클라우드 스토리지에 있는 원본 소스를 직접 참조 - 유출 범위:
src/디렉터리 전체 — 1,902개 TypeScript/TSX 파일, 약 51만 줄의 코드 - 영향: Claude Code의 내부 아키텍처, 도구 시스템, 권한 모델, API 통신 구조 등이 모두 공개
이 저장소는 유출된 소스코드를 교육 및 아키텍처 분석 목적으로 정리한 것입니다.
기술적 인사이트 — 소스맵에서 전체 소스코드가 추출된 과정
이것은 해킹이 아닙니다. Anthropic 자체가 소스 맵(
cli.js.map)을 npm 릴리스에 포함시킨 것이 원인입니다.
57MB cli.js.map 파일의 구조:
| 항목 | 값 |
|---|---|
| 전체 소스 파일 수 | 4,756개 |
| Claude Code 자체 | 1,906개 (TypeScript/TSX) |
| node_modules 종속성 | 2,850개 |
추출 방법: cli.js.map은 단순한 JSON 객체로, 두 개의 키 배열만 읽으면 됩니다:
sources[]— 파일 경로 배열sourcesContent[]— 해당 파일의 정확한 원본 코드 배열
두 배열의 인덱스가 1:1 대응하므로, 역컴파일이나 난독화 해제 없이 원본 소스를 그대로 복원할 수 있습니다.
flowchart LR
NPM["npm install<br/>@anthropic-ai/claude-code"] --> Map["cli.js.map (57MB)<br/>JSON 파일"]
Map --> Sources["sources[]: 4,756개 파일 경로"]
Map --> Content["sourcesContent[]: 원본 코드"]
Sources --> Extract["인덱스 1:1 대응<br/>→ 파일 복원"]
Content --> Extract
Extract --> Full["전체 소스코드<br/>(아키텍처, 시스템 프롬프트,<br/>도구 호출 로직 포함)"]
style Map fill:#ffebee,stroke:#c62828
style Full fill:#e8f5e9,stroke:#2e7d32
복원된 소스에서 확인된 것들:
- React + Ink 기반 CLI 인터페이스 구축
- 자연어 입력과 슬래시 명령어를 지원하는 REPL 루프
- 도구 시스템을 통한 LLM API 상호작용
- 아키텍처 설계, 시스템 프롬프트, 도구 호출 로직 전체
사건의 교훈:
소스 맵(Source Map)은 프로덕션에 배포해서는 안 됩니다.
소스 맵은 개발/디버깅 용도로 변수 이름부터 주석까지 모든 정보를 포함합니다.sourcesContent에 한 줄만 포함되어도 전체 코드가 공개됩니다.
- Anthropic은 이후 소스 맵을 삭제하고, 추출된 GitHub 저장소를 DMCA로 차단했습니다
- 그러나 npm 패키지의 이전 버전들은 이미 아카이빙되어 소스 코드가 커뮤니티에 유포된 상태였습니다
npm 패키지를 게시하는 모든 개발자에게: 게시 전에
.map파일을 반드시 확인하세요.
커뮤니티 인사이트 — 같은 실수의 반복, 그리고 AI 경쟁
1년 전에도 똑같은 실수가 있었습니다.
Anthropic은 약 1년 전에도 동일한 방식(source map 미제거)으로 소스코드가 유출된 전례가 있었습니다.
JS/TS 빌드 시.map파일을 제거하는 것은 기본적인 프로덕션 배포 체크리스트임에도 불구하고, 같은 실수가 1년 만에 그대로 반복된 것입니다.이번에 유출된 코드에는 Claude Code에만 있는 고유 기술들이 포함되어 있습니다:
- 프롬프트 캐싱 전략 (정적/동적 경계 분리)
- 멀티에이전트 오케스트레이션 (Coordinator, Swarm, Fork 패턴)
- 메모리 시스템 (세션/자동/팀 메모리, AI 기반 관련성 선택)
- 컨텍스트 압축 알고리즘 (9항목 보존 전략)
- tree-sitter 기반 Bash 보안 파이프라인
- React + Ink 커스텀 터미널 렌더링 엔진
이러한 구현 디테일이 공개됨으로써, 경쟁사들이 유사한 기능을 더 빠르게 구현할 수 있는 참고 자료가 된 셈이며, AI 코딩 도구 간의 경쟁이 더욱 가속화될 것으로 예상됩니다.
Project Scale
| 지표 | 값 | 상세 |
|---|---|---|
| 총 파일 수 | 1,902 | TypeScript (.ts, .tsx) |
| 총 디렉터리 수 | ~160 | 34개 상위 모듈 |
| UI 프레임워크 | React + Ink | 터미널 선언적 UI |
| 레이아웃 엔진 | Yoga | Flexbox 기반 터미널 레이아웃 |
| 빌드/런타임 | Bun / Node.js | 고속 TypeScript 실행 |
| 스키마 검증 | Zod v4 | 모든 도구 입출력 검증 |
| 도구 (Tools) | 40+ | 상세 보기 |
| 명령어 (Commands) | 100+ | 상세 보기 |
| 서비스 (Services) | 19 | 상세 보기 |
| React 훅 (Hooks) | 104 files | 상세 보기 |
Architecture
Layered Architecture
Claude Code는 5-Layer Architecture를 채택하여 각 계층이 단방향 의존성을 유지합니다.
graph TB
subgraph USER["USER INPUT LAYER"]
Terminal["Terminal"]
IDE["IDE Extension"]
Web["Web App"]
Voice["Voice Input"]
end
subgraph ENTRY["ENTRYPOINT LAYER"]
cli["cli.tsx"]
init["init.ts"]
main["main.tsx"]
setup["setup.ts"]
cli --> init --> main --> setup
end
subgraph ENGINE["ENGINE LAYER"]
QE["QueryEngine.ts"]
query["query.ts"]
context["context.ts"]
QE <--> query
QE --> context
end
subgraph EXECUTION["EXECUTION LAYER"]
subgraph TOOLS["TOOL LAYER (40 Tools)"]
File["File R/W/Edit"]
Bash["Bash/Shell"]
Agent["Agent/Swarm"]
WebT["Web Fetch/Search"]
MCP_T["MCP Tools"]
Task["Task CRUD"]
end
subgraph COMMANDS["COMMAND LAYER (100+)"]
help["/help"]
model["/model"]
config["/config"]
compact["/compact"]
mcp_cmd["/mcp"]
more["..."]
end
end
subgraph SERVICE["SERVICE LAYER"]
API["API Client<br/>(4 SDK)"]
MCP_S["MCP Server<br/>Manager"]
Compact["Compact<br/>Service"]
ToolExec["Tool<br/>Executor"]
LSP["LSP Server"]
OAuth["OAuth 2.0"]
Analytics["Analytics"]
Plugins["Plugins"]
SessionMem["Session<br/>Memory"]
ExtractMem["Extract<br/>Memories"]
end
subgraph INFRA["INFRASTRUCTURE LAYER"]
Perm["Permissions (26)"]
Settings["Settings (19)"]
Model["Model (18)"]
BashUtil["Bash Utils (15)"]
Telemetry["Telemetry (14)"]
Shell["Shell (12)"]
Git["Git (5)"]
Sandbox["Sandbox"]
end
USER --> ENTRY
ENTRY --> ENGINE
ENGINE --> TOOLS
ENGINE --> COMMANDS
TOOLS --> SERVICE
SERVICE --> INFRA
style USER fill:#e1f5fe,stroke:#0288d1
style ENTRY fill:#f3e5f5,stroke:#7b1fa2
style ENGINE fill:#fff3e0,stroke:#ef6c00
style TOOLS fill:#e8f5e9,stroke:#2e7d32
style COMMANDS fill:#e8f5e9,stroke:#2e7d32
style SERVICE fill:#fce4ec,stroke:#c62828
style INFRA fill:#f5f5f5,stroke:#616161
상세 아키텍처: Index.md (MOC) | 디렉터리 구조: Directory_Structure.md
Initialization Flow
앱 시작부터 REPL 진입까지의 4-Phase Bootstrap 시퀀스:
flowchart TD
Start([앱 시작]) --> P1
subgraph P1["Phase 1: CLI Bootstrap — cli.tsx"]
direction LR
fast{"Fast-path?"}
fast -->|--version| ver["버전 출력 → 종료"]
fast -->|MCP 서버| mcp_s["MCP 서버 시작"]
fast -->|데몬 워커| daemon["데몬 스포닝"]
fast -->|일반 시작| dynimport["동적 임포트로 지연 로딩"]
end
P1 --> P2
subgraph P2["Phase 2: Environment Init — init.ts"]
direction LR
cfg["Config 검증"] --> ca["CA 인증서"]
ca --> oauth_init["OAuth 초기화"]
oauth_init --> policy["정책 제한"]
policy --> mtls["mTLS 설정"]
mtls --> preconnect["API 프리커넥션"]
end
P2 --> P3
subgraph P3["Phase 3: Service Bootstrap — main.tsx"]
direction LR
otel["OpenTelemetry 지연 로딩"]
otel --> metrics["메트릭 수집 설정"]
metrics --> svc_init["서비스 초기화"]
end
P3 --> P4
subgraph P4["Phase 4: Session Setup — setup.ts"]
direction LR
node_ver["Node 버전 검증"]
node_ver --> worktree["Git 워크트리"]
worktree --> session_mem["세션 메모리"]
session_mem --> perm_check["권한 검증"]
end
P4 --> REPL([REPL 대화형 루프 시작])
style P1 fill:#f3e5f5,stroke:#7b1fa2
style P2 fill:#e8eaf6,stroke:#283593
style P3 fill:#fff3e0,stroke:#ef6c00
style P4 fill:#e8f5e9,stroke:#2e7d32
style REPL fill:#c8e6c9,stroke:#1b5e20,stroke-width:3px
Query Execution Flow
사용자 입력이 처리되어 응답으로 돌아오기까지의 핵심 실행 루프:
sequenceDiagram
participant U as User
participant QE as QueryEngine.ts
participant CTX as context.ts
participant Q as query.ts
participant API as API Service
participant STE as StreamingToolExecutor
participant PERM as Permissions System
participant T as Tool.call()
participant C as Compact Service
U->>QE: 사용자 입력
activate QE
QE->>CTX: 컨텍스트 조립 요청
CTX-->>QE: 시스템 + 사용자 컨텍스트
QE->>Q: 쿼리 실행
activate Q
loop 도구 실행 루프 (tool_use 블록이 있을 때까지)
Q->>API: Claude API 스트리밍 호출
API-->>Q: 응답 스트림 (텍스트 + tool_use)
opt tool_use 블록 존재
Q->>STE: 도구 실행 요청
activate STE
STE->>PERM: 권한 체크
alt 허용 (ALLOW)
PERM-->>STE: ✅ 허용
STE->>T: 도구 실행
T-->>STE: 실행 결과
else 거부 (DENY)
PERM-->>STE: ❌ 거부 메시지
else 문의 (ASK)
PERM->>U: 권한 요청 다이얼로그
U-->>PERM: 사용자 응답
end
STE-->>Q: 도구 결과
deactivate STE
end
Q->>C: 컨텍스트 압축 필요?
alt 압축 필요
C-->>Q: 대화 요약/압축
else 불필요
C-->>Q: 패스
end
end
Q-->>QE: 최종 응답
deactivate Q
QE-->>U: 응답 렌더링
deactivate QE
상세: Query_Engine.md
Tool Execution Flow
모든 도구 실행은 권한 시스템을 거칩니다:
flowchart TD
A["모델 응답에서<br/>tool_use 블록 추출"] --> B["tools.ts<br/>findToolByName()"]
B --> C{"Tool.<br/>checkPermissions()"}
C -->|ALLOW| D["Tool.call() 실행"]
C -->|DENY| E["거부 메시지 반환"]
C -->|ASK| F["사용자 권한<br/>요청 다이얼로그"]
F -->|승인| D
F -->|거부| E
D --> G{"isConcurrencySafe?"}
G -->|Yes| H["병렬 실행<br/>(Promise.all)"]
G -->|No| I["직렬 실행<br/>(순차 await)"]
H --> J["결과를 메시지에 추가"]
I --> J
E --> J
J --> K["다음 턴"]
style C fill:#fff3e0,stroke:#ef6c00
style D fill:#e8f5e9,stroke:#2e7d32
style E fill:#ffebee,stroke:#c62828
style F fill:#e3f2fd,stroke:#1565c0
MCP Connection Flow
Model Context Protocol 서버 연결부터 도구 사용까지:
flowchart LR
Config["settings.json<br/>MCP 서버 정의"] --> MCPService["MCP Service"]
MCPService --> Transport{"전송 프로토콜<br/>선택"}
Transport -->|stdio| STDIO["stdio 프로세스"]
Transport -->|SSE| SSE["Server-Sent Events"]
Transport -->|WebSocket| WS["WebSocket"]
Transport -->|HTTP| HTTP["HTTP Streamable"]
STDIO --> Conn["MCPConnectionManager<br/>서버 연결"]
SSE --> Conn
WS --> Conn
HTTP --> Conn
Conn --> Auth{"인증 필요?"}
Auth -->|Yes| OAuth["OAuth 인증"]
Auth -->|No| Discover["도구/리소스 발견"]
OAuth --> Discover
Discover --> Pool["tools.ts<br/>assembleToolPool()"]
BuiltIn["내장 40 도구"] --> Pool
Pool --> Merged["통합 도구 풀<br/>(중복 제거)"]
style MCPService fill:#e8eaf6,stroke:#283593
style Merged fill:#e8f5e9,stroke:#2e7d32
Design Principles
Claude Code 소스코드에서 관찰되는 6가지 핵심 설계 원칙:
| 원칙 | 설명 | 구현 위치 |
|---|---|---|
| Layered Architecture | 진입점 → 엔진 → 도구 → 서비스 → 유틸리티의 단방향 의존성 | Index.md |
| Permission-First | 모든 도구 실행 전 checkPermissions() 통과 필수 |
Tools_Overview.md |
| Extensibility | MCP, 플러그인, 스킬을 통한 기능 확장 | Services_Overview.md |
| Declarative Terminal UI | React + Ink를 통한 선언적 터미널 렌더링 | Ink_Framework.md |
| Multi-Agent | AgentTool, Coordinator, Swarm 패턴 지원 | tools/AgentTool.md |
| Multi-Provider API | Anthropic Direct, Bedrock, Vertex AI, Azure Foundry | services/API_Service.md |
Design Patterns
소스코드 전반에서 사용되는 설계 패턴 분석:
| 패턴 | 빈도 | 주요 위치 | 설명 |
|---|---|---|---|
| Factory | 높음 | Tool.ts (buildTool()), LSP |
도구/서버 인스턴스 생성 |
| Async Generator | 높음 | StreamingToolExecutor |
스트리밍 결과 반환 (async function*) |
| React Hooks | 높음 | Hooks_Overview.md | 104개 커스텀 훅 |
| Singleton Store | 중간 | bootstrap/state.ts |
209개 getter/setter 글로벌 상태 |
| Observer/Event | 중간 | Ink_Framework.md | 터미널 이벤트, 파일 감시 |
| Strategy | 중간 | 권한 핸들러, 셸 프로바이더 | 런타임 전략 교체 |
| Memoization | 높음 | context.ts, commands.ts |
중복 계산 방지 |
| Forked Agent | 낮음 | SessionMemory, ExtractMemories | 백그라운드 서브에이전트 |
상세: Stats_Report.md
Tech Stack
Core Dependencies
| 패키지 | 용도 | 분석 문서 |
|---|---|---|
@anthropic-ai/sdk |
Claude API Direct | API_Service.md |
@anthropic-ai/bedrock-sdk |
AWS Bedrock | API_Service.md |
@anthropic-ai/vertex-sdk |
Google Vertex AI | API_Service.md |
@anthropic-ai/foundry-sdk |
Azure Foundry | API_Service.md |
@modelcontextprotocol/sdk |
MCP 프로토콜 | MCP_Service.md |
react |
UI 프레임워크 | Components_Overview.md |
ink |
터미널 React 렌더러 | Ink_Framework.md |
zod (v4) |
스키마 검증 | Tools_Overview.md |
yoga-layout |
Flexbox 레이아웃 | Ink_Framework.md |
tree-sitter |
AST 파싱 | Utils_Overview.md |
vscode-languageserver-protocol |
LSP | Services_Overview.md |
Module Deep Dive
1. Entrypoints
앱 시작부터 REPL 진입까지의 부트스트랩 흐름
| 파일 | 역할 | 핵심 기능 |
|---|---|---|
cli.tsx |
CLI 진입점 | Fast-path 분기, 동적 임포트 |
init.ts |
환경 초기화 | OAuth, TLS, 정책, API 프리커넥션 |
main.tsx |
서비스 부트스트랩 | OpenTelemetry, 메트릭 |
setup.ts |
세션 셋업 | 워크트리, 세션 메모리, 권한 검증 |
2. Query Engine
핵심 실행 루프 — 사용자 입력부터 응답 렌더링까지
- QueryEngine.ts: 쿼리 라이프사이클 관리 (시작 → 실행 → 압축 → 종료)
- query.ts: Claude API 호출 + 도구 실행 루프
- context.ts: 시스템/사용자 컨텍스트 조립 (메모이제이션)
상세: Query_Engine.md
3. Tool System (40 Tools)
파일 시스템, 셸, 에이전트, 웹, MCP 등 40개 도구
| 카테고리 | 도구 수 | 주요 도구 | 문서 |
|---|---|---|---|
| 파일 시스템 | 5 | Read, Edit, Write, Glob, Grep | FileReadTool.md, FileEditTool.md |
| 셸 실행 | 2 | Bash, PowerShell | BashTool.md |
| 에이전트 | 3 | Agent, SendMessage, Skill | AgentTool.md |
| 웹 | 2 | WebFetch, WebSearch | Tools_Overview.md |
| 태스크 관리 | 6 | Create, Update, List, Get, Stop, Output | TaskTools.md |
| MCP | 4 | MCPTool, ListResources, ReadResource, Auth | MCPTool.md |
| 코드 인텔리전스 | 1 | LSP | Tools_Overview.md |
| 워크트리/플랜 | 4 | EnterWorktree, ExitWorktree, EnterPlan, ExitPlan | Tools_Overview.md |
| 스케줄링 | 3 | ScheduleCron, CronDelete, CronList | Tools_Overview.md |
| 기타 | 10 | Config, Notebook, RemoteTrigger, ... | Tools_Overview.md |
핵심 인터페이스:
interface Tool<Input, Output, Progress> {
name: string;
call(input: Input, context: ToolUseContext): Promise<Output>;
checkPermissions(input: Input, context: ToolPermissionContext): PermissionResult;
isReadOnly(): boolean;
isConcurrencySafe(): boolean;
}
도구 카테고리 분포:
pie title Tool Categories (40 Tools)
"File System" : 5
"Shell Execution" : 2
"Agent / Multi-Agent" : 3
"Web" : 2
"Task Management" : 6
"MCP" : 4
"Code Intelligence" : 1
"Worktree / Plan" : 4
"Scheduling" : 3
"Others" : 10
도구 클래스 구조:
classDiagram
class Tool {
<<interface>>
+name: string
+description(): string
+call(input, context): Promise~Output~
+checkPermissions(input, context): PermissionResult
+isReadOnly(): boolean
+isConcurrencySafe(): boolean
+isDestructive(): boolean
}
class buildTool {
<<factory>>
+buildTool(def: ToolDef): Tool
}
class ToolRegistry {
+getAllBaseTools(): Tool[]
+getTools(context): Tool[]
+assembleToolPool(): Tool[]
+filterToolsByDenyRules(): Tool[]
}
Tool <|.. BashTool
Tool <|.. FileReadTool
Tool <|.. FileEditTool
Tool <|.. FileWriteTool
Tool <|.. GlobTool
Tool <|.. GrepTool
Tool <|.. AgentTool
Tool <|.. MCPTool
Tool <|.. WebFetchTool
Tool <|.. TaskCreateTool
buildTool --> Tool : creates
ToolRegistry --> Tool : manages
class BashTool {
+isReadOnly(): false
+isConcurrencySafe(): false
}
class FileReadTool {
+isReadOnly(): true
+isConcurrencySafe(): true
}
class AgentTool {
+isReadOnly(): false
+isConcurrencySafe(): true
}
4. Service Layer (19 Services)
API 통신, MCP, 컨텍스트 관리, 인증, 분석 등 핵심 비즈니스 로직
| 서비스 | 파일 수 | 복잡도 | 문서 |
|---|---|---|---|
| API Client | 16 | 높음 | API_Service.md |
| MCP Server Manager | 23 | 높음 | MCP_Service.md |
| Compact (Context Compression) | 11 | 중간 | Compact_Service.md |
| Tool Executor | 4 | 중간 | Services_Overview.md |
| LSP Server | 7 | 중간 | Services_Overview.md |
| OAuth 2.0 | 5 | 중간 | Services_Overview.md |
| Analytics (DD + 1P) | 9 | 중간 | Services_Overview.md |
| Session Memory | 3 | 낮음 | Services_Overview.md |
| Extract Memories | 2 | 낮음 | Services_Overview.md |
| Plugins | 3 | 중간 | Services_Overview.md |
서비스 레이어 의존성 관계:
graph TD
subgraph Services["Service Layer"]
API["API Client<br/>(client.ts)"]
MCP["MCP Service<br/>(23 files)"]
Compact["Compact Service<br/>(11 files)"]
ToolSvc["Tool Executor<br/>(4 files)"]
LSP_S["LSP Server<br/>(7 files)"]
OAuth_S["OAuth 2.0<br/>(5 files)"]
Analytics_S["Analytics<br/>(9 files)"]
Plugins_S["Plugins<br/>(3 files)"]
SessionMem_S["Session Memory"]
ExtractMem_S["Extract Memories"]
end
subgraph Providers["API Multi-Provider"]
Direct["Anthropic Direct<br/>api.anthropic.com"]
Bedrock["AWS Bedrock<br/>@anthropic-ai/bedrock-sdk"]
Vertex["Google Vertex AI<br/>@anthropic-ai/vertex-sdk"]
Foundry["Azure Foundry<br/>@anthropic-ai/foundry-sdk"]
end
API --> Direct
API --> Bedrock
API --> Vertex
API --> Foundry
ToolSvc --> API
ToolSvc --> MCP
Compact --> API
MCP --> OAuth_S
SessionMem_S --> API
ExtractMem_S --> API
LSP_S --> ToolSvc
style API fill:#e3f2fd,stroke:#1565c0
style Providers fill:#f3e5f5,stroke:#7b1fa2
5. UI Components
React 기반 터미널 UI — 389개 파일
| 카테고리 | 파일 수 | 설명 |
|---|---|---|
| 메시지 렌더링 | 36 | 스트리밍 응답, 마크다운, 코드 하이라이트 |
| 권한 다이얼로그 | 32 | 도구 실행 권한 요청/승인/거부 |
| 디자인 시스템 | 18 | 테마, 컬러, 타이포그래피 |
| 에이전트 UI | 16 | 서브에이전트 상태 표시 |
| MCP UI | 15 | MCP 서버 연결 상태 |
| 프롬프트 입력 | 8 | 멀티라인 입력, 자동완성 |
6. Ink Framework
커스텀 터미널 렌더링 프레임워크 — 96개 파일
React의 선언적 UI 모델을 터미널에 적용한 커스텀 Ink 프레임워크:
flowchart LR
subgraph React["React Layer"]
JSX["JSX Components<br/>(Box, Text, ScrollBox)"]
Reconciler["React Reconciler<br/>(커스텀 렌더러)"]
end
subgraph Layout["Layout Engine"]
Yoga["Yoga Layout<br/>(Flexbox 계산)"]
Measure["노드 측정<br/>(width, height, padding)"]
end
subgraph Output["Terminal Output"]
ANSI["ANSI 이스케이프<br/>시퀀스 생성"]
Stdout["stdout.write()<br/>터미널 렌더링"]
end
subgraph Events["Event System"]
Keyboard["키보드 입력"]
Mouse["마우스 이벤트"]
Resize["터미널 리사이즈"]
end
JSX --> Reconciler
Reconciler --> Yoga
Yoga --> Measure
Measure --> ANSI
ANSI --> Stdout
Events --> Reconciler
style React fill:#e3f2fd,stroke:#1565c0
style Layout fill:#fff3e0,stroke:#ef6c00
style Output fill:#e8f5e9,stroke:#2e7d32
style Events fill:#fce4ec,stroke:#c62828
컴포넌트 렌더링 트리:
graph TD
REPL["REPL.tsx<br/>(메인 화면)"]
REPL --> FL["FullscreenLayout"]
FL --> SB["ScrollBox<br/>(스크롤 가능 영역)"]
FL --> PI["PromptInput<br/>(하단 고정)"]
FL --> SL["StatusLine<br/>(상태바)"]
FL --> Modal["모달 다이얼로그"]
SB --> UPM["UserPromptMessage"]
SB --> ATM["AssistantTextMessage"]
SB --> ATUM["AssistantToolUseMessage"]
SB --> UTRM["UserToolResultMessage"]
SB --> APL["AgentProgressLine"]
PI --> BTI["BaseTextInput"]
PI --> PIF["PromptInputFooter"]
PI --> Notif["Notifications"]
Modal --> PermReq["PermissionRequest"]
Modal --> QOD["QuickOpenDialog"]
Modal --> DD["DiffDialog"]
style REPL fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
style FL fill:#f3e5f5,stroke:#7b1fa2
style SB fill:#fff3e0,stroke:#ef6c00
style PI fill:#e8f5e9,stroke:#2e7d32
style Modal fill:#fce4ec,stroke:#c62828
7. Hooks System
104개 React 훅 — 상태 관리, 도구 권한, 태스크 관리
- 도구 권한 훅 (ToolPermission)
- 태스크 관리 훅 (TaskManagement)
- UI 상태 훅 (useInput, useKeyboard, useFocus)
flowchart TD
subgraph Permission["권한 훅 (toolPermission/)"]
PC["PermissionContext.ts<br/>오케스트레이션"]
PC --> IH["interactiveHandler<br/>(메인 에이전트)"]
PC --> CH["coordinatorHandler<br/>(코디네이터)"]
PC --> SWH["swarmWorkerHandler<br/>(분산 워커)"]
IH --> Race{"훅/분류기 vs<br/>사용자 경합"}
Race -->|훅 승리| AutoDecide["자동 결정"]
Race -->|사용자 승리| UserResp["다이얼로그 응답"]
end
subgraph Queue["큐 & 태스크 훅"]
QP["useQueueProcessor<br/>우선순위: now > next > later"]
TV["useTasksV2<br/>싱글톤 + fs.watch"]
end
subgraph UI["UI 훅"]
TI["useTextInput"]
VI["useVimInput"]
HS["useHistorySearch"]
TS["useTerminalSize"]
end
style Permission fill:#fff3e0,stroke:#ef6c00
style Queue fill:#e8eaf6,stroke:#283593
style UI fill:#e8f5e9,stroke:#2e7d32
8. Commands System
100+ CLI 슬래시 명령어
/help, /model, /config, /compact, /mcp, /vim, /cost, /doctor 등 100개 이상의 슬래시 명령어와 스킬 시스템.
9. Utilities
564개 파일 — 프로젝트의 29.7%를 차지하는 인프라 라이브러리
| 모듈 | 파일 수 | 설명 | 문서 |
|---|---|---|---|
| Permissions | 26 | 규칙 기반 + AI 분류 권한 시스템 | Utils_Overview.md |
| Settings | 19 | 계층적 설정 관리 | Utils_Overview.md |
| Model | 18 | 모델 선택/관리/가격 | Utils_Overview.md |
| Bash | 15+ | AST 파싱, 인젝션 방지 | Utils_Overview.md |
| Telemetry | 14 | OpenTelemetry 기반 | Utils_Overview.md |
| Shell | 12 | 셸 추상화 계층 | Utils_Overview.md |
| Swarm | 16+ | 분산 에이전트 | Utils_Overview.md |
| Git | 5 | Git 상태 읽기 | Utils_Overview.md |
10. Security Architecture
Claude Code의 다층 보안 구조:
| 보안 계층 | 파일 수 | 기법 |
|---|---|---|
| 권한 시스템 | 26 | 규칙 기반 + AI 분류 (허용/거부/문의) |
| Bash 보안 | 15+ | tree-sitter AST 파싱, 명령 인젝션 방지 |
| 셸 검증 | 12 | 읽기전용 명령 레지스트리 |
| 경로 검증 | 5+ | 안전 경로 체크 (디렉터리 탈출 방지) |
| 샌드박싱 | 2 | @anthropic-ai/sandbox-runtime |
flowchart TD
ToolReq["도구 실행 요청"] --> L1
subgraph L1["Layer 1: Permission System (26 files)"]
Rules["규칙 기반 검사<br/>(allowlist / denylist)"]
AI["AI 분류기<br/>(자동 판단)"]
Rules --> Decision{"판단"}
AI --> Decision
end
Decision -->|ALLOW| L2
Decision -->|ASK| UserDialog["사용자 확인 다이얼로그"]
Decision -->|DENY| Blocked["❌ 실행 차단"]
UserDialog -->|승인| L2
UserDialog -->|거부| Blocked
subgraph L2["Layer 2: Input Validation"]
BashAST["Bash AST 파싱<br/>(tree-sitter)"]
PathCheck["경로 검증<br/>(디렉터리 탈출 방지)"]
CmdRegistry["읽기전용 명령<br/>레지스트리"]
end
L2 --> L3
subgraph L3["Layer 3: Sandbox Runtime"]
Sandbox["@anthropic-ai/<br/>sandbox-runtime"]
Isolation["프로세스 격리"]
end
L3 --> Exec["✅ 안전한 도구 실행"]
style L1 fill:#fff3e0,stroke:#ef6c00
style L2 fill:#e8eaf6,stroke:#283593
style L3 fill:#e8f5e9,stroke:#2e7d32
style Blocked fill:#ffebee,stroke:#c62828
style Exec fill:#c8e6c9,stroke:#1b5e20
11. Multi-Agent System
Claude Code의 멀티에이전트 오케스트레이션:
- AgentTool: 서브에이전트 생성 (워크트리 격리 지원)
- Coordinator Mode: 멀티 워커 에이전트 오케스트레이션
- Swarm: 분산 에이전트 패턴 (
utils/swarm/) - SendMessage: 에이전트 간 메시지 전달
graph TD
Main["Main Agent<br/>(메인 대화)"]
Main -->|"AgentTool<br/>(spawn)"| Sub1["Sub-Agent 1<br/>general-purpose"]
Main -->|"AgentTool<br/>(spawn)"| Sub2["Sub-Agent 2<br/>Explore"]
Main -->|"AgentTool<br/>(spawn)"| Sub3["Sub-Agent 3<br/>worktree isolation"]
Main -->|"Coordinator<br/>Mode"| Coord["Coordinator"]
Coord -->|"워커 할당"| W1["Worker 1"]
Coord -->|"워커 할당"| W2["Worker 2"]
Coord -->|"워커 할당"| W3["Worker 3"]
Sub1 ---|"SendMessage"| Main
Sub2 ---|"SendMessage"| Main
W1 ---|"메일박스"| Coord
W2 ---|"메일박스"| Coord
Main -->|"Swarm<br/>Mode"| Swarm["Swarm Leader"]
Swarm --> SW1["Swarm Worker 1"]
Swarm --> SW2["Swarm Worker 2"]
style Main fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
style Coord fill:#f3e5f5,stroke:#7b1fa2
style Swarm fill:#fff3e0,stroke:#ef6c00
style Sub3 fill:#e8f5e9,stroke:#2e7d32
12. Memory System
파일 기반 영속 메모리 시스템:
- Memdir: AI 선택 기반 파일 메모리, 팀 메모리
- Session Memory: 대화 중 자동 메모 유지 (포크된 서브에이전트)
- Extract Memories: 쿼리 루프 종료 시 지속 메모리 추출
stateDiagram-v2
[*] --> SessionStart: 세션 시작
SessionStart --> ActiveConversation: REPL 루프 진입
state ActiveConversation {
[*] --> QueryLoop
QueryLoop --> SessionMemoryUpdate: 백그라운드
SessionMemoryUpdate --> QueryLoop: 메모리 파일 업데이트
QueryLoop --> CompactTrigger: 컨텍스트 한계 도달
CompactTrigger --> MemoryExtract: 압축 시 메모리 추출
MemoryExtract --> QueryLoop
}
ActiveConversation --> SessionEnd: 세션 종료
state SessionEnd {
[*] --> ExtractMemories: 포크된 에이전트
ExtractMemories --> PersistToFile: 메모리 파일 저장
PersistToFile --> TeamSync: 팀 메모리 동기화
TeamSync --> [*]
}
SessionEnd --> [*]
note right of ActiveConversation
Session Memory:
포크된 서브에이전트가
백그라운드에서 자동 업데이트
end note
note right of SessionEnd
Extract Memories:
프롬프트 캐시 공유로
효율적 추출
end note
13. Additional Modules
| 모듈 | 설명 | 문서 |
|---|---|---|
| Bootstrap / State | 글로벌 세션 상태 싱글톤 (209 getter/setter) | bootstrap/state.md |
| Screens | REPL, 세션 재개, 진단 화면 | screens/Screens_Overview.md |
| Server | WebSocket 직접 연결 세션 관리 | server/Server_Overview.md |
| Upstream Proxy | CCR용 CONNECT-over-WebSocket 릴레이 | upstreamproxy/UpstreamProxy_Overview.md |
| Keybindings | 커스텀 키보드 단축키 + 코드 시퀀스 | keybindings/Keybindings_Overview.md |
| Migrations | 설정/모델 마이그레이션 11개 | migrations/Migrations_Overview.md |
| Native TS | color-diff, file-index, yoga-layout TS 포트 | native-ts/NativeTS_Overview.md |
| Buddy | 컴패니언 캐릭터 절차적 생성 시스템 | buddy/Buddy_Overview.md |
| Plugins | 내장 플러그인 레지스트리 + 마켓플레이스 | plugins/Plugins_Module.md |
| Voice | 음성 모드 피처 게이트 | voice/voiceModeEnabled.md |
| Root Files | src/ 루트 18개 핵심 파일 | Root_Files_Overview.md |
Module Distribution
pie title Module File Distribution (1,902 files)
"utils (564)" : 564
"components (389)" : 389
"commands (207)" : 207
"tools (184)" : 184
"services (130)" : 130
"hooks (104)" : 104
"ink (96)" : 96
"bridge (31)" : 31
"constants (21)" : 21
"skills (20)" : 20
"others (156)" : 156
utils ████████████████████████████████████████ 564 (29.7%)
components ██████████████████████████████ 389 (20.5%)
commands ████████████████ 207 (10.9%)
tools █████████████ 184 (9.7%)
services █████████ 130 (6.8%)
hooks ███████ 104 (5.5%)
ink ██████ 96 (5.0%)
bridge ██ 31 (1.6%)
constants █ 21 (1.1%)
skills █ 20 (1.1%)
others ████ 156 (8.2%)
상세: Stats_Report.md
Prompt & Agent Architecture
소스코드 기반으로 분석한 Claude Code의 프롬프트 조립 순서, 에이전트 구성, API 호출 구조.
사용자 입력이 어떤 프롬프트와 결합되어 Claude API에 전달되는지, 그 전체 흐름을 추적합니다.
1. System Prompt Assembly Order
Claude Code의 시스템 프롬프트는 src/constants/prompts.ts의 getSystemPrompt() 함수에서 조립됩니다.
캐시 가능한 정적 구간과 세션별 동적 구간이 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 마커로 분리됩니다.
flowchart TD
subgraph STATIC["정적 구간 (Cacheable — 글로벌 캐시 가능)"]
direction TB
S1["1. getSimpleIntroSection()<br/><i>'You are Claude Code,<br/>Anthropic's official CLI...'</i>"]
S2["2. getSimpleSystemSection()<br/><i>도구 권한, 태그, 훅, 압축 규칙</i>"]
S3["3. getSimpleDoingTasksSection()<br/><i>코드 작성 가이드라인, 보안 규칙</i>"]
S4["4. getActionsSection()<br/><i>가역성, 영향 범위, 확인 요청 규칙</i>"]
S5["5. getUsingYourToolsSection()<br/><i>도구 사용 가이드 (Bash보다 전용 도구)</i>"]
S6["6. getSimpleToneAndStyleSection()<br/><i>톤 & 스타일 (이모지 금지 등)</i>"]
S7["7. getOutputEfficiencySection()<br/><i>출력 간결성 지침</i>"]
S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
end
BOUNDARY["═══ SYSTEM_PROMPT_DYNAMIC_BOUNDARY ═══"]
subgraph DYNAMIC["동적 구간 (세션별 — systemPromptSection() 레지스트리)"]
direction TB
D1["8. session_guidance<br/><i>에이전트 도구, 스킬, 검증 에이전트</i>"]
D2["9. memory<br/><i>loadMemoryPrompt() — 메모리 지침</i>"]
D3["10. env_info_simple<br/><i>cwd, git 상태, 모델, OS, 셸</i>"]
D4["11. language<br/><i>언어 선호 설정</i>"]
D5["12. mcp_instructions<br/><i>MCP 서버 지침 (volatile)</i>"]
D6["13. scratchpad<br/><i>스크래치패드 디렉터리</i>"]
D7["14. frc / summarize_tool_results<br/><i>함수 결과 정리 / 도구 결과 요약</i>"]
D8["15. token_budget / brief<br/><i>토큰 예산, KAIROS 브리프</i>"]
D1 --> D2 --> D3 --> D4 --> D5 --> D6 --> D7 --> D8
end
STATIC --> BOUNDARY --> DYNAMIC
style STATIC fill:#e8f5e9,stroke:#2e7d32
style BOUNDARY fill:#fff9c4,stroke:#f9a825,stroke-width:3px
style DYNAMIC fill:#e3f2fd,stroke:#1565c0
시스템 프롬프트 우선순위 체인 — src/utils/systemPrompt.ts의 buildEffectiveSystemPrompt():
flowchart LR
Override["1. Override<br/>(loop 모드)"]
Coord["2. Coordinator<br/>시스템 프롬프트"]
Agent["3. Agent 정의<br/>시스템 프롬프트"]
Custom["4. --system-prompt<br/>플래그"]
Default["5. Default<br/>시스템 프롬프트"]
Override -->|"없으면"| Coord
Coord -->|"없으면"| Agent
Agent -->|"없으면"| Custom
Custom -->|"없으면"| Default
Append["+ appendSystemPrompt<br/>(항상 추가)"]
Override -.-> Append
Coord -.-> Append
Agent -.-> Append
Custom -.-> Append
Default -.-> Append
style Override fill:#ffebee,stroke:#c62828
style Default fill:#e8f5e9,stroke:#2e7d32
style Append fill:#fff3e0,stroke:#ef6c00
2. Context Injection Flow
시스템 프롬프트 외에 User Context와 System Context가 별도로 조립되어 API 호출에 주입됩니다.
sequenceDiagram
participant QE as QueryEngine.ts<br/>submitMessage()
participant CTX as context.ts
participant CMD as claudemd.ts
participant GIT as git utils
participant API as API 호출
QE->>CTX: getUserContext()
activate CTX
CTX->>CMD: getClaudeMds()
CMD-->>CTX: CLAUDE.md 계층 콘텐츠
CTX-->>QE: { claudeMd, currentDate }
deactivate CTX
QE->>CTX: getSystemContext()
activate CTX
CTX->>GIT: getGitStatus()
GIT-->>CTX: branch, commits, status
CTX-->>QE: { gitStatus, cacheBreaker }
deactivate CTX
QE->>API: prependUserContext()<br/>→ messages[0]에 system-reminder 삽입
QE->>API: appendSystemContext()<br/>→ system 배열 끝에 추가
주입 위치:
| 컨텍스트 | API 파라미터 | 형식 | 소스 |
|---|---|---|---|
| claudeMd | messages[0] (user role) |
<system-reminder># claudeMd\n{내용}</system-reminder> |
src/utils/claudemd.ts |
| currentDate | messages[0] (user role) |
# currentDate\nToday's date is 2026-04-01 |
src/context.ts |
| gitStatus | system 배열 끝 |
gitStatus: branch main, 3 commits... |
src/context.ts |
3. API Request Assembly
src/services/api/claude.ts의 paramsFromContext()에서 최종 API 파라미터가 조립됩니다.
flowchart TD
subgraph Params["최종 API 파라미터 (paramsFromContext)"]
direction TB
system["<b>system:</b><br/>TextBlockParam[]<br/>시스템 프롬프트 블록 + 캐시 마커"]
messages["<b>messages:</b><br/>정규화된 메시지 배열<br/>+ UserContext system-reminder<br/>+ 캐시 브레이크포인트"]
tools["<b>tools:</b><br/>도구 스키마 배열 (40+)<br/>name, description, input_schema<br/>+ cache_control"]
model["<b>model:</b><br/>claude-sonnet-4-20250514"]
thinking["<b>thinking:</b><br/>{ type: 'adaptive' }<br/>or budget_tokens"]
betas["<b>betas:</b><br/>interleaved-thinking<br/>advanced-tool-use<br/>prompt-caching-scope"]
metadata["<b>metadata:</b><br/>device_id, session_id, user_id"]
max_tokens["<b>max_tokens:</b> 16384"]
end
System_Prompt["getSystemPrompt()"] --> system
Context["getUserContext()<br/>getSystemContext()"] --> messages
ToolReg["도구 레지스트리<br/>toolToAPISchema()"] --> tools
Config["모델/설정"] --> model
Config --> thinking
Config --> betas
style Params fill:#f5f5f5,stroke:#616161
style system fill:#e3f2fd,stroke:#1565c0
style messages fill:#fff3e0,stroke:#ef6c00
style tools fill:#e8f5e9,stroke:#2e7d32
도구 스키마 구조 (각 도구별):
{
type: "function",
name: "Bash", // 도구 이름
description: "Executes a...", // prompt.ts에서 로드
input_schema: { ... }, // Zod → JSON Schema
strict: true, // 엄격 모드
cache_control: { type: "ephemeral" } // 캐시 제어
}
4. Built-In Agent Types
Claude Code에는 6개의 내장 에이전트가 src/tools/AgentTool/built-in/에 정의되어 있습니다.
| Agent Type | 모델 | 도구 접근 | 시스템 프롬프트 핵심 | 소스 |
|---|---|---|---|---|
general-purpose |
inherit | 모든 도구 (['*']) |
"Complete the task fully — don't gold-plate, but don't leave it half-done." | generalPurposeAgent.ts |
Explore |
haiku (외부) / inherit | Glob, Grep, Read, Bash(읽기전용) | "You are a file search specialist... READ-ONLY MODE" | exploreAgent.ts |
Plan |
sonnet | Glob, Grep, Read, Bash(읽기전용) | "You are a software architect... READ-ONLY PLANNING TASK" | planAgent.ts |
verification |
inherit | 모든 도구 (편집 제외) | "Adversarial testing — try to break implementation. PASS/FAIL/PARTIAL" | verificationAgent.ts |
claude-code-guide |
haiku | WebFetch, WebSearch, Glob, Grep, Read | "Answer questions about Claude Code CLI, Agent SDK, Claude API" | claudeCodeGuideAgent.ts |
statusline-setup |
inherit | Read, Edit | "Configure the user's Claude Code status line setting" | statuslineSetup.ts |
graph TD
subgraph BuiltIn["Built-In Agents (6 types)"]
GP["general-purpose<br/>모든 도구, 범용 연구/실행"]
EX["Explore<br/>READ-ONLY, Haiku, 빠른 탐색"]
PL["Plan<br/>READ-ONLY, 아키텍처 설계"]
VF["verification<br/>적대적 테스트, PASS/FAIL"]
GD["claude-code-guide<br/>공식 문서 기반 가이드"]
SL["statusline-setup<br/>상태바 설정"]
end
subgraph Custom["Custom Agents"]
UA[".claude/agents/*.md<br/>사용자 정의 에이전트"]
JA[".claude/agents.json<br/>JSON 에이전트"]
end
subgraph Spawn["AgentTool 호출"]
Call["Agent(description, subagent_type, prompt)"]
end
Call -->|"subagent_type"| GP
Call -->|"subagent_type"| EX
Call -->|"subagent_type"| PL
Call -->|"subagent_type"| VF
Call -->|"subagent_type"| GD
Call -->|"subagent_type"| SL
Call -->|"subagent_type"| UA
style GP fill:#e3f2fd,stroke:#1565c0
style EX fill:#e8f5e9,stroke:#2e7d32
style PL fill:#f3e5f5,stroke:#7b1fa2
style VF fill:#ffebee,stroke:#c62828
style Custom fill:#fff3e0,stroke:#ef6c00
Agent 정의 구조 (src/tools/AgentTool/loadAgentsDir.ts):
type BaseAgentDefinition = {
agentType: string; // 고유 식별자
whenToUse: string; // 사용 시점 설명
tools?: string[]; // 허용 도구 목록
disallowedTools?: string[]; // 금지 도구 목록
model?: string; // 모델 오버라이드
permissionMode?: PermissionMode; // 'ask' | 'allow' | 'dontAsk'
maxTurns?: number; // 최대 턴 수
omitClaudeMd?: boolean; // CLAUDE.md 생략 (토큰 절약)
isolation?: 'worktree' | 'remote'; // 격리 모드
memory?: 'user' | 'project' | 'local';
getSystemPrompt: () => string; // 시스템 프롬프트 생성
}
5. Agent Spawning & Prompt Flow
에이전트가 생성될 때 어떤 프롬프트가 어떤 순서로 조립되는지:
sequenceDiagram
participant Main as Main Agent
participant AT as AgentTool
participant Load as loadAgentsDir
participant Sub as Sub-Agent
Main->>AT: Agent({ subagent_type, prompt, description })
AT->>Load: 에이전트 정의 조회
Load-->>AT: AgentDefinition (시스템 프롬프트, 도구, 모델)
AT->>Sub: 서브에이전트 생성
Note over Sub: 시스템 프롬프트 조립 순서:
Note over Sub: 1. Agent.getSystemPrompt()
Note over Sub: 2. enhanceWithEnvDetails()
Note over Sub: 3. CLAUDE.md (omitClaudeMd가 아닌 경우)
Note over Sub: 4. 사용자 prompt (첫 메시지)
Sub->>Sub: 도구 실행 루프
Sub-->>AT: 최종 응답 (text)
AT-->>Main: 결과 반환 (caller에게 전달)
Fork vs Fresh Agent:
flowchart LR
subgraph Fork["Fork (subagent_type 생략)"]
F1["부모 컨텍스트 상속"]
F2["프롬프트 캐시 공유"]
F3["저비용"]
F4["중간 출력 불필요 시"]
end
subgraph Fresh["Fresh Agent (subagent_type 지정)"]
R1["독립 컨텍스트"]
R2["전체 브리핑 필요"]
R3["에이전트별 시스템 프롬프트"]
R4["특화된 도구 세트"]
end
Decision{"작업 유형?"}
Decision -->|"컨텍스트 재활용"| Fork
Decision -->|"특화 에이전트 필요"| Fresh
style Fork fill:#e8f5e9,stroke:#2e7d32
style Fresh fill:#e3f2fd,stroke:#1565c0
6. Coordinator Mode
Coordinator 모드가 활성화되면 (src/coordinator/coordinatorMode.ts), 메인 에이전트가 다수의 Worker를 병렬로 오케스트레이션합니다.
sequenceDiagram
participant User as 사용자
participant Coord as Coordinator
participant W1 as Worker 1<br/>(조사)
participant W2 as Worker 2<br/>(조사)
participant W3 as Worker 3<br/>(구현)
participant W4 as Worker 4<br/>(검증)
User->>Coord: 작업 요청
rect rgb(232, 245, 233)
Note over Coord,W2: Phase 1: Research (병렬)
Coord->>W1: Agent(prompt: "파일 A 조사")
Coord->>W2: Agent(prompt: "파일 B 조사")
W1-->>Coord: task-notification (결과)
W2-->>Coord: task-notification (결과)
end
Note over Coord: Synthesis: 결과 종합 → 구체적 구현 명세 작성
rect rgb(227, 242, 253)
Note over Coord,W3: Phase 2: Implementation
Coord->>W3: Agent(prompt: "파일 X:42 수정,<br/>구체적 코드 스니펫 포함")
W3-->>Coord: task-notification (완료)
end
rect rgb(255, 235, 238)
Note over Coord,W4: Phase 3: Verification
Coord->>W4: Agent(subagent_type: verification,<br/>prompt: "변경사항 테스트")
W4-->>Coord: PASS / FAIL / PARTIAL
end
Coord-->>User: 최종 결과 보고
Coordinator 프롬프트 핵심 규칙:
- "절대 이해를 위임하지 마라" — "네 조사 결과를 바탕으로 버그를 고쳐" ❌
- "항상 종합하라" — 구체적 파일 경로, 라인 번호, 코드 스니펫 포함 ✅
- Worker에게 보내는 프롬프트에 사용자 원문을 포함하지 마라 — 종합한 명세만 전달
Worker → Coordinator 알림 형식:
<task-notification>
<task-id>{agentId}</task-id>
<status>completed|failed|killed</status>
<summary>Human-readable status</summary>
<result>Agent's final text response</result>
<usage>
<total_tokens>N</total_tokens>
<tool_uses>N</tool_uses>
<duration_ms>N</duration_ms>
</usage>
</task-notification>
7. Context Compaction Prompt
컨텍스트 윈도우가 한계에 도달하면 src/services/compact/prompt.ts에서 압축 프롬프트가 실행됩니다.
stateDiagram-v2
[*] --> Normal: 대화 진행
Normal --> ThresholdCheck: 매 턴마다 확인
ThresholdCheck --> Normal: 여유 있음
ThresholdCheck --> Compaction: 컨텍스트 한계 근접
state Compaction {
[*] --> AnalyzeConversation
AnalyzeConversation --> GenerateSummary
Note right of GenerateSummary: 도구 사용 금지 (NO_TOOLS_PREAMBLE)
Note right of GenerateSummary: 텍스트 전용 응답
state GenerateSummary {
[*] --> PrimaryRequest: 1. 주요 요청과 의도
PrimaryRequest --> TechnicalConcepts: 2. 핵심 기술 개념
TechnicalConcepts --> FilesAndCode: 3. 파일과 코드 스니펫
FilesAndCode --> ErrorsAndFixes: 4. 에러와 수정 내역
ErrorsAndFixes --> ProblemSolving: 5. 문제 해결 과정
ProblemSolving --> UserMessages: 6. 모든 사용자 메시지
UserMessages --> PendingTasks: 7. 대기 중 작업
PendingTasks --> CurrentWork: 8. 현재 작업 상태
CurrentWork --> NextStep: 9. 다음 단계 (인용 포함)
end
GenerateSummary --> ExtractMemory: 메모리 추출 통합
ExtractMemory --> ReplaceMessages: 기존 메시지를 요약으로 교체
end
Compaction --> Normal: 압축 완료, 대화 계속
Note right of Compaction: analysis 블록은 요약 전에 제거됨
압축 프롬프트 출력 형식:
<analysis>
[사고 과정 — 모든 포인트가 커버되었는지 확인]
</analysis>
<summary>
1. Primary Request and Intent: ...
2. Key Technical Concepts: ...
3. Files and Code Sections: [스니펫 + 중요도]
4. Errors and fixes: ...
5. Problem Solving: ...
6. All user messages: [비도구 사용자 메시지 전체]
7. Pending Tasks: ...
8. Current Work: [정확한 작업 상태]
9. Optional Next Step: [대화에서 인용]
</summary>
8. Memory Extraction Prompt
세션 종료 시 src/services/extractMemories/prompts.ts에서 메모리 추출 에이전트가 실행됩니다.
flowchart TD
SessionEnd["세션 종료 / 압축 트리거"] --> Fork["포크된 서브에이전트 생성<br/>(프롬프트 캐시 공유)"]
Fork --> Analyze["최근 ~N개 메시지 분석"]
Analyze --> Classify{"4-Type 분류"}
Classify --> T1["User Feedback<br/><i>사용자 선호, 수정 지침</i>"]
Classify --> T2["Project Patterns<br/><i>프로젝트 패턴/관습</i>"]
Classify --> T3["Workflow Learnings<br/><i>워크플로우/프로세스</i>"]
Classify --> T4["Technical Discoveries<br/><i>기술적 발견</i>"]
T1 --> Save
T2 --> Save
T3 --> Save
T4 --> Save
subgraph Save["저장 프로세스 (2단계)"]
Step1["Step 1: 개별 메모리 파일 작성<br/>(frontmatter + 내용)"]
Step2["Step 2: MEMORY.md 인덱스 업데이트<br/>(1줄 포인터 추가)"]
Step1 --> Step2
end
Save --> Team{"팀 메모리?"}
Team -->|Yes| TeamSync["team/MEMORY.md에도 동기화"]
Team -->|No| Done["완료"]
TeamSync --> Done
style Fork fill:#f3e5f5,stroke:#7b1fa2
style Classify fill:#fff3e0,stroke:#ef6c00
style Save fill:#e8f5e9,stroke:#2e7d32
Session Memory 템플릿 (src/services/SessionMemory/prompts.ts):
# Session Title
# Current State ← 압축 후 연속성에 가장 중요
# Task specification
# Files and Functions
# Workflow ← bash 명령어, 순서, 해석
# Errors & Corrections
# Codebase and System Documentation
# Learnings
# Key results
# Worklog
규칙: 섹션당 ~2,000 토큰, 전체 최대 12,000 토큰. 포크된 서브에이전트가 백그라운드에서 자동 업데이트.
9. CLAUDE.md Loading Chain
src/utils/claudemd.ts에서 CLAUDE.md 파일이 계층적으로 로드됩니다.
flowchart TD
subgraph Loading["CLAUDE.md 로딩 순서 (우선순위: 아래 > 위)"]
L1["1. /etc/claude-code/CLAUDE.md<br/><i>Managed — 전체 사용자 공통</i>"]
L2["2. ~/.claude/CLAUDE.md<br/><i>User — 개인 전역 설정</i>"]
L3["3. 프로젝트 루트/CLAUDE.md<br/> .claude/CLAUDE.md<br/> .claude/rules/*.md<br/><i>Project — 코드베이스 체크인</i>"]
L4["4. cwd까지 탐색하며<br/> CLAUDE.local.md<br/><i>Local — 개인 프로젝트 설정</i>"]
L1 --> L2 --> L3 --> L4
end
L4 --> Include{"@include 지시어?"}
Include -->|"@path"| Resolve["참조 파일 재귀 로드<br/>(순환 참조 방지)"]
Include -->|"없음"| Concat["콘텐츠 연결"]
Resolve --> Concat
Concat --> Inject["getUserContext()에<br/>claudeMd로 주입"]
Inject --> Msg["messages[0]에<br/>system-reminder로 삽입"]
style Loading fill:#f5f5f5,stroke:#616161
style L1 fill:#ffebee,stroke:#c62828
style L2 fill:#fff3e0,stroke:#ef6c00
style L3 fill:#e3f2fd,stroke:#1565c0
style L4 fill:#e8f5e9,stroke:#2e7d32
MEMORY.md 제한: 최대 200줄 / 25,000 바이트. 초과 시 라인 경계에서 잘림.
10. End-to-End Prompt Flow Summary
사용자 입력부터 Claude API 호출까지의 전체 프롬프트 조립 흐름:
flowchart TD
User["사용자 입력"] --> QE["QueryEngine.submitMessage()"]
QE --> FetchParts["fetchSystemPromptParts()"]
subgraph Build["프롬프트 조립"]
direction TB
SP["getSystemPrompt()<br/><i>정적 7개 + 동적 8개 섹션</i>"]
UC["getUserContext()<br/><i>claudeMd + currentDate</i>"]
SC["getSystemContext()<br/><i>gitStatus + cacheBreaker</i>"]
ESP["buildEffectiveSystemPrompt()<br/><i>우선순위 체인 적용</i>"]
SP --> ESP
end
FetchParts --> Build
Build --> QueryFn["query() 제너레이터<br/><i>src/query.ts</i>"]
QueryFn --> QM["queryModel()<br/><i>src/services/api/claude.ts</i>"]
subgraph Assembly["최종 조립 (paramsFromContext)"]
TS["toolToAPISchema()<br/>40개 도구 스키마"]
NM["normalizeMessagesForAPI()<br/>메시지 정규화"]
SB["buildSystemPromptBlocks()<br/>캐시 마커 부착"]
PU["prependUserContext()<br/>system-reminder 삽입"]
AS["appendSystemContext()<br/>git 상태 추가"]
end
QM --> Assembly
Assembly --> APICall["anthropic.beta.messages.create()<br/>스트리밍 호출"]
APICall --> Stream["응답 스트림 처리"]
Stream --> ToolExec{"tool_use 블록?"}
ToolExec -->|Yes| RunTool["도구 실행 → 결과 추가"]
RunTool --> QueryFn
ToolExec -->|No| Response["최종 응답 렌더링"]
style User fill:#e3f2fd,stroke:#1565c0
style Build fill:#f5f5f5,stroke:#616161
style Assembly fill:#fff3e0,stroke:#ef6c00
style APICall fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px
style Response fill:#c8e6c9,stroke:#1b5e20,stroke-width:3px
API 호출 시 전달되는 최종 구조:
anthropic.beta.messages.create({
model: "claude-sonnet-4-20250514",
system: [ ← 시스템 프롬프트
{ text: "You are Claude Code...", cache_control: { scope: "global" } },
{ text: "[동적 섹션들]" },
{ text: "gitStatus: branch main..." }
],
messages: [ ← 대화 메시지
{ role: "user", content: [
{ text: "<system-reminder># claudeMd\n..." }, ← CLAUDE.md
{ text: "사용자 실제 입력" }
]},
{ role: "assistant", content: [...] },
...
],
tools: [ ← 도구 정의
{ name: "Bash", description: "...", input_schema: {...} },
{ name: "Read", description: "...", input_schema: {...} },
...40+ tools
],
thinking: { type: "adaptive" }, ← 사고 모드
betas: ["interleaved-thinking-...", "prompt-caching-scope-..."],
max_tokens: 16384
})
관련 소스 파일:
| 파일 | 역할 |
|---|---|
src/constants/prompts.ts |
시스템 프롬프트 섹션 생성 |
src/utils/systemPrompt.ts |
프롬프트 우선순위 체인 |
src/context.ts |
User/System 컨텍스트 조립 |
src/utils/claudemd.ts |
CLAUDE.md 계층 로딩 |
src/QueryEngine.ts |
쿼리 제출 진입점 |
src/query.ts |
쿼리 실행 루프 |
src/services/api/claude.ts |
API 파라미터 최종 조립 |
src/utils/api.ts |
도구 스키마 변환, 컨텍스트 주입 |
src/tools/AgentTool/prompt.ts |
에이전트 도구 프롬프트 |
src/tools/AgentTool/built-in/ |
6개 내장 에이전트 정의 |
src/coordinator/coordinatorMode.ts |
Coordinator 시스템 프롬프트 |
src/services/compact/prompt.ts |
컨텍스트 압축 프롬프트 |
src/services/SessionMemory/prompts.ts |
세션 메모리 템플릿 |
src/services/extractMemories/prompts.ts |
메모리 추출 프롬프트 |
src/buddy/prompt.ts |
Buddy 컴패니언 프롬프트 |
Document Map
Core Documents
| 문서 | 유형 | 설명 |
|---|---|---|
| Index.md | MOC | 전체 프로젝트 지도 (Map of Content) |
| Directory_Structure.md | Structure | 폴더 트리 + 모듈별 파일 수 |
| Stats_Report.md | Report | 의존성 통계, 모듈 분포, 품질 지표 |
Layer Documents
| 문서 | 유형 | 설명 |
|---|---|---|
| Entrypoints_Overview.md | Module | 앱 시작 흐름 (cli → init → main → setup) |
| Query_Engine.md | Module | 핵심 실행 루프 |
| Tools_Overview.md | Module | 40개 도구 전체 카탈로그 |
| Services_Overview.md | Module | 19개 서비스 레이어 |
| Components_Overview.md | Module | 389개 UI 컴포넌트 |
| Ink_Framework.md | Module | 커스텀 터미널 렌더링 |
| Hooks_Overview.md | Module | 104개 React 훅 |
| Commands_Overview.md | Module | 100+ 슬래시 명령어 |
| Utils_Overview.md | Module | 564개 유틸리티 파일 |
| Root_Files_Overview.md | Module | src/ 루트 18개 파일 |
Deep Dive Documents
| 문서 | 분석 대상 |
|---|---|
| tools/AgentTool.md | 서브에이전트 생성 + 워크트리 격리 |
| tools/BashTool.md | 셸 실행 + AST 보안 검증 |
| tools/FileReadTool.md | 파일 읽기 (PDF, 이미지, 노트북) |
| tools/FileEditTool.md | 문자열 치환 기반 파일 편집 |
| tools/MCPTool.md | MCP 서버 도구 실행 |
| tools/TaskTools.md | 태스크 CRUD 도구 |
| services/API_Service.md | 4-SDK 멀티프로바이더 API |
| services/MCP_Service.md | MCP 서버 연결/인증/발견 |
| services/Compact_Service.md | 컨텍스트 윈도우 압축 전략 |
| bootstrap/state.md | 글로벌 상태 싱글톤 |
| coordinator/coordinatorMode.md | 멀티에이전트 오케스트레이션 |
| memdir/Memdir_Overview.md | 파일 기반 영속 메모리 |
| screens/Screens_Overview.md | REPL, 세션 재개, 진단 |
| server/Server_Overview.md | WebSocket 직접 연결 |
| keybindings/Keybindings_Overview.md | 키바인딩 + 코드 시퀀스 |
| migrations/Migrations_Overview.md | 설정 마이그레이션 11개 |
| native-ts/NativeTS_Overview.md | 네이티브 모듈 TS 포트 |
| buddy/Buddy_Overview.md | 컴패니언 캐릭터 시스템 |
| upstreamproxy/UpstreamProxy_Overview.md | CONNECT-over-WS 릴레이 |
Source Code Browse
이 저장소에는 Claude Code의 실제 소스코드가 포함되어 있습니다.
./src/디렉터리에서 모든 TypeScript/TSX 파일을 직접 열어볼 수 있습니다.
분석 문서와 원본 코드를 나란히 비교하며 아키텍처를 이해해 보세요.
Module Summary (36 modules, 1,902 files)
| Module | Files | Description | Browse |
|---|---|---|---|
| src/ Root | 18 | 핵심 엔트리 파일 | src/ Root |
| assistant/ | 1 | 세션 히스토리 | assistant/ |
| bootstrap/ | 1 | 글로벌 상태 싱글톤 | bootstrap/ |
| bridge/ | 31 | IDE 브릿지 통신 | bridge/ |
| buddy/ | 6 | 컴패니언 캐릭터 | buddy/ |
| cli/ | 19 | CLI 전송/핸들러 | cli/ |
| commands/ | 207 | 100+ 슬래시 명령어 | commands/ |
| components/ | 389 | React 터미널 UI | components/ |
| constants/ | 21 | 상수 정의 | constants/ |
| context/ | 9 | 시스템/사용자 컨텍스트 | context/ |
| coordinator/ | 1 | 멀티에이전트 오케스트레이션 | coordinator/ |
| entrypoints/ | 8 | 앱 진입점 (CLI, SDK, MCP) | entrypoints/ |
| hooks/ | 104 | React 커스텀 훅 | hooks/ |
| ink/ | 96 | 터미널 렌더링 프레임워크 | ink/ |
| keybindings/ | 14 | 키바인딩 시스템 | keybindings/ |
| memdir/ | 8 | 파일 기반 메모리 | memdir/ |
| migrations/ | 11 | 설정 마이그레이션 | migrations/ |
| moreright/ | 1 | REPL 패널 스텁 | moreright/ |
| native-ts/ | 4 | 네이티브 모듈 TS 포트 | native-ts/ |
| outputStyles/ | 1 | 출력 스타일 로더 | outputStyles/ |
| plugins/ | 2 | 플러그인 레지스트리 | plugins/ |
| query/ | 4 | 쿼리 설정 | query/ |
| remote/ | 4 | 원격 세션 | remote/ |
| schemas/ | 1 | Zod 스키마 정의 | schemas/ |
| screens/ | 3 | REPL/진단 화면 | screens/ |
| server/ | 3 | WebSocket 서버 | server/ |
| services/ | 130 | 핵심 서비스 레이어 | services/ |
| skills/ | 20 | 스킬 시스템 | skills/ |
| state/ | 6 | 앱 상태 관리 | state/ |
| tasks/ | 12 | 백그라운드 태스크 | tasks/ |
| tools/ | 184 | 40개 도구 구현 | tools/ |
| types/ | 11 | TypeScript 타입 정의 | types/ |
| upstreamproxy/ | 2 | CONNECT-over-WS 릴레이 | upstreamproxy/ |
| utils/ | 564 | 인프라 유틸리티 | utils/ |
| vim/ | 5 | Vim 모드 | vim/ |
| voice/ | 1 | 음성 모드 | voice/ |
| Total | 1,902 | ./src/ |
Complete File Listing
전체 1,902개 파일 목록 펼치기 (click to expand)아래 테이블의 모든 파일명은 클릭하면 해당 소스코드로 직접 이동합니다.
src/ Root Files
| # | File | Type |
|---|---|---|
| 1 | QueryEngine.ts | .ts |
| 2 | Task.ts | .ts |
| 3 | Tool.ts | .ts |
| 4 | commands.ts | .ts |
| 5 | context.ts | .ts |
| 6 | cost-tracker.ts | .ts |
| 7 | costHook.ts | .ts |
| 8 | dialogLaunchers.tsx | .tsx |
| 9 | history.ts | .ts |
| 10 | ink.ts | .ts |
| 11 | interactiveHelpers.tsx | .tsx |
| 12 | main.tsx | .tsx |
| 13 | projectOnboardingState.ts | .ts |
| 14 | query.ts | .ts |
| 15 | replLauncher.tsx | .tsx |
| 16 | setup.ts | .ts |
| 17 | tasks.ts | .ts |
| 18 | tools.ts | .ts |
assistant/
| # | File | Type |
|---|---|---|
| 1 | sessionHistory.ts | .ts |
bootstrap/
| # | File | Type |
|---|---|---|
| 1 | state.ts | .ts |
bridge/
| # | File | Type |
|---|---|---|
| 1 | bridgeApi.ts | .ts |
| 2 | bridgeConfig.ts | .ts |
| 3 | bridgeDebug.ts | .ts |
| 4 | bridgeEnabled.ts | .ts |
| 5 | bridgeMain.ts | .ts |
| 6 | bridgeMessaging.ts | .ts |
| 7 | bridgePermissionCallbacks.ts | .ts |
| 8 | bridgePointer.ts | .ts |
| 9 | bridgeStatusUtil.ts | .ts |
| 10 | bridgeUI.ts | .ts |
| 11 | capacityWake.ts | .ts |
| 12 | codeSessionApi.ts | .ts |
| 13 | createSession.ts | .ts |
| 14 | debugUtils.ts | .ts |
| 15 | envLessBridgeConfig.ts | .ts |
| 16 | flushGate.ts | .ts |
| 17 | inboundAttachments.ts | .ts |
| 18 | inboundMessages.ts | .ts |
| 19 | initReplBridge.ts | .ts |
| 20 | jwtUtils.ts | .ts |
| 21 | pollConfig.ts | .ts |
| 22 | pollConfigDefaults.ts | .ts |
| 23 | remoteBridgeCore.ts | .ts |
| 24 | replBridge.ts | .ts |
| 25 | replBridgeHandle.ts | .ts |
| 26 | replBridgeTransport.ts | .ts |
| 27 | sessionIdCompat.ts | .ts |
| 28 | sessionRunner.ts | .ts |
| 29 | trustedDevice.ts | .ts |
| 30 | types.ts | .ts |
| 31 | workSecret.ts | .ts |
buddy/
| # | File | Type |
|---|---|---|
| 1 | CompanionSprite.tsx | .tsx |
| 2 | companion.ts | .ts |
| 3 | prompt.ts | .ts |
| 4 | sprites.ts | .ts |
| 5 | types.ts | .ts |
| 6 | useBuddyNotification.tsx | .tsx |
cli/
| # | File | Type |
|---|---|---|
| 1 | exit.ts | .ts |
| 2 | handlers/agents.ts | .ts |
| 3 | handlers/auth.ts | .ts |
| 4 | handlers/autoMode.ts | .ts |
| 5 | handlers/mcp.tsx | .tsx |
| 6 | handlers/plugins.ts | .ts |
| 7 | handlers/util.tsx | .tsx |
| 8 | ndjsonSafeStringify.ts | .ts |
| 9 | print.ts | .ts |
| 10 | remoteIO.ts | .ts |
| 11 | structuredIO.ts | .ts |
| 12 | transports/HybridTransport.ts | .ts |
| 13 | transports/SSETransport.ts | .ts |
| 14 | transports/SerialBatchEventUploader.ts | .ts |
| 15 | transports/WebSocketTransport.ts | .ts |
| 16 | transports/WorkerStateUploader.ts | .ts |
| 17 | transports/ccrClient.ts | .ts |
| 18 | transports/transportUtils.ts | .ts |
| 19 | update.ts | .ts |
commands/
components/
constants/
| # | File | Type |
|---|---|---|
| 1 | apiLimits.ts | .ts |
| 2 | betas.ts | .ts |
| 3 | common.ts | .ts |
| 4 | cyberRiskInstruction.ts | .ts |
| 5 | errorIds.ts | .ts |
| 6 | figures.ts | .ts |
| 7 | files.ts | .ts |
| 8 | github-app.ts | .ts |
| 9 | keys.ts | .ts |
| 10 | messages.ts | .ts |
| 11 | oauth.ts | .ts |
| 12 | outputStyles.ts | .ts |
| 13 | product.ts | .ts |
| 14 | prompts.ts | .ts |
| 15 | spinnerVerbs.ts | .ts |
| 16 | system.ts | .ts |
| 17 | systemPromptSections.ts | .ts |
| 18 | toolLimits.ts | .ts |
| 19 | tools.ts | .ts |
| 20 | turnCompletionVerbs.ts | .ts |
| 21 | xml.ts | .ts |
context/
| # | File | Type |
|---|---|---|
| 1 | QueuedMessageContext.tsx | .tsx |
| 2 | fpsMetrics.tsx | .tsx |
| 3 | mailbox.tsx | .tsx |
| 4 | modalContext.tsx | .tsx |
| 5 | notifications.tsx | .tsx |
| 6 | overlayContext.tsx | .tsx |
| 7 | promptOverlayContext.tsx | .tsx |
| 8 | stats.tsx | .tsx |
| 9 | voice.tsx | .tsx |
coordinator/
| # | File | Type |
|---|---|---|
| 1 | coordinatorMode.ts | .ts |
entrypoints/
| # | File | Type |
|---|---|---|
| 1 | agentSdkTypes.ts | .ts |
| 2 | cli.tsx | .tsx |
| 3 | init.ts | .ts |
| 4 | mcp.ts | .ts |
| 5 | sandboxTypes.ts | .ts |
| 6 | sdk/controlSchemas.ts | .ts |
| 7 | sdk/coreSchemas.ts | .ts |
| 8 | sdk/coreTypes.ts | .ts |
hooks/
ink/
keybindings/
| # | File | Type |
|---|---|---|
| 1 | KeybindingContext.tsx | .tsx |
| 2 | KeybindingProviderSetup.tsx | .tsx |
| 3 | defaultBindings.ts | .ts |
| 4 | loadUserBindings.ts | .ts |
| 5 | match.ts | .ts |
| 6 | parser.ts | .ts |
| 7 | reservedShortcuts.ts | .ts |
| 8 | resolver.ts | .ts |
| 9 | schema.ts | .ts |
| 10 | shortcutFormat.ts | .ts |
| 11 | template.ts | .ts |
| 12 | useKeybinding.ts | .ts |
| 13 | useShortcutDisplay.ts | .ts |
| 14 | validate.ts | .ts |
memdir/
| # | File | Type |
|---|---|---|
| 1 | findRelevantMemories.ts | .ts |
| 2 | memdir.ts | .ts |
| 3 | memoryAge.ts | .ts |
| 4 | memoryScan.ts | .ts |
| 5 | memoryTypes.ts | .ts |
| 6 | paths.ts | .ts |
| 7 | teamMemPaths.ts | .ts |
| 8 | teamMemPrompts.ts | .ts |
migrations/
moreright/
| # | File | Type |
|---|---|---|
| 1 | useMoreRight.tsx | .tsx |
native-ts/
| # | File | Type |
|---|---|---|
| 1 | color-diff/index.ts | .ts |
| 2 | file-index/index.ts | .ts |
| 3 | yoga-layout/enums.ts | .ts |
| 4 | yoga-layout/index.ts | .ts |
outputStyles/
| # | File | Type |
|---|---|---|
| 1 | loadOutputStylesDir.ts | .ts |
plugins/
| # | File | Type |
|---|---|---|
| 1 | builtinPlugins.ts | .ts |
| 2 | bundled/index.ts | .ts |
query/
| # | File | Type |
|---|---|---|
| 1 | config.ts | .ts |
| 2 | deps.ts | .ts |
| 3 | stopHooks.ts | .ts |
| 4 | tokenBudget.ts | .ts |
remote/
| # | File | Type |
|---|---|---|
| 1 | RemoteSessionManager.ts | .ts |
| 2 | SessionsWebSocket.ts | .ts |
| 3 | remotePermissionBridge.ts | .ts |
| 4 | sdkMessageAdapter.ts | .ts |
schemas/
| # | File | Type |
|---|---|---|
| 1 | hooks.ts | .ts |
screens/
| # | File | Type |
|---|---|---|
| 1 | Doctor.tsx | .tsx |
| 2 | REPL.tsx | .tsx |
| 3 | ResumeConversation.tsx | .tsx |
server/
| # | File | Type |
|---|---|---|
| 1 | createDirectConnectSession.ts | .ts |
| 2 | directConnectManager.ts | .ts |
| 3 | types.ts | .ts |
services/
skills/
| # | File | Type |
|---|---|---|
| 1 | bundled/batch.ts | .ts |
| 2 | bundled/claudeApi.ts | .ts |
| 3 | bundled/claudeApiContent.ts | .ts |
| 4 | bundled/claudeInChrome.ts | .ts |
| 5 | bundled/debug.ts | .ts |
| 6 | bundled/index.ts | .ts |
| 7 | bundled/keybindings.ts | .ts |
| 8 | bundled/loop.ts | .ts |
| 9 | bundled/loremIpsum.ts | .ts |
| 10 | bundled/remember.ts | .ts |
| 11 | bundled/scheduleRemoteAgents.ts | .ts |
| 12 | bundled/simplify.ts | .ts |
| 13 | bundled/skillify.ts | .ts |
| 14 | bundled/stuck.ts | .ts |
| 15 | bundled/updateConfig.ts | .ts |
| 16 | bundled/verify.ts | .ts |
| 17 | bundled/verifyContent.ts | .ts |
| 18 | bundledSkills.ts | .ts |
| 19 | loadSkillsDir.ts | .ts |
| 20 | mcpSkillBuilders.ts | .ts |
state/
| # | File | Type |
|---|---|---|
| 1 | AppState.tsx | .tsx |
| 2 | AppStateStore.ts | .ts |
| 3 | onChangeAppState.ts | .ts |
| 4 | selectors.ts | .ts |
| 5 | store.ts | .ts |
| 6 | teammateViewHelpers.ts | .ts |
tasks/
| # | File | Type |
|---|---|---|
| 1 | DreamTask/DreamTask.ts | .ts |
| 2 | InProcessTeammateTask/InProcessTeammateTask.tsx | .tsx |
| 3 | InProcessTeammateTask/types.ts | .ts |
| 4 | LocalAgentTask/LocalAgentTask.tsx | .tsx |
| 5 | LocalMainSessionTask.ts | .ts |
| 6 | LocalShellTask/LocalShellTask.tsx | .tsx |
| 7 | LocalShellTask/guards.ts | .ts |
| 8 | LocalShellTask/killShellTasks.ts | .ts |
| 9 | RemoteAgentTask/RemoteAgentTask.tsx | .tsx |
| 10 | pillLabel.ts | .ts |
| 11 | stopTask.ts | .ts |
| 12 | types.ts | .ts |
tools/
types/
| # | File | Type |
|---|---|---|
| 1 | command.ts | .ts |
| 2 | generated/events_mono/claude_code/v1/claude_code_internal_event.ts | .ts |
| 3 | generated/events_mono/common/v1/auth.ts | .ts |
| 4 | generated/events_mono/growthbook/v1/growthbook_experiment_event.ts | .ts |
| 5 | generated/google/protobuf/timestamp.ts | .ts |
| 6 | hooks.ts | .ts |
| 7 | ids.ts | .ts |
| 8 | logs.ts | .ts |
| 9 | permissions.ts | .ts |
| 10 | plugin.ts | .ts |
| 11 | textInputTypes.ts | .ts |
upstreamproxy/
| # | File | Type |
|---|---|---|
| 1 | relay.ts | .ts |
| 2 | upstreamproxy.ts | .ts |
utils/
vim/
| # | File | Type |
|---|---|---|
| 1 | motions.ts | .ts |
| 2 | operators.ts | .ts |
| 3 | textObjects.ts | .ts |
| 4 | transitions.ts | .ts |
| 5 | types.ts | .ts |
voice/
| # | File | Type |
|---|---|---|
| 1 | voiceModeEnabled.ts | .ts |
Usage with Obsidian
Quick Start
# 1. 저장소 클론
git clone https://github.com/leaf-kit/claude-analysis.git
# 2. Obsidian에서 클론된 폴더를 Vault로 열기
# Obsidian → Open folder as vault → claude-analysis/
Features
- Graph View: 모든 문서가
[[위키링크]]로 연결되어 모듈 간 관계를 시각적으로 탐색 - YAML Frontmatter:
tags,type,status기반 필터링 및 Dataview 쿼리 지원 - Tag Navigation:
#tools,#services,#architecture등 태그로 빠른 탐색 - Search: 전체 문서에 걸친 코드 패턴, 함수명, 모듈명 검색
Recommended Plugins
| 플러그인 | 용도 |
|---|---|
| Dataview | YAML frontmatter 기반 동적 테이블/리스트 |
| Graph Analysis | 그래프 중심성, 클러스터 분석 |
| Admonition | 정보/경고/팁 박스 렌더링 |
Tutorial
🟢 초급부터 🔴 고급까지, 12장 완전 가이드로 Claude Code의 내부를 쉽고 깊게 이해할 수 있습니다.
이모지, Mermaid 다이어그램, 실제 소스코드 링크, 엔지니어 팁이 모두 포함되어 있습니다.
| 🟢 초급 | ||
|---|---|---|
| 1️⃣ | 우리의 똑똑한 친구, Claude | 🤖 Claude 소개, 4가지 API |
| 2️⃣ | 스스로 생각하는 에이전트 | 🕵️ ReAct 패턴, 6개 에이전트, 코디네이터 |
| 3️⃣ | AI를 움직이는 프롬프트 마법 | 🪄 15개 프롬프트 블록, CLAUDE.md |
| 4️⃣ | 실제 코드로 보는 구조 | 🛠️ 5-Stop 소스코드 투어 |
| 🟡 중급 | ||
| 5️⃣ | AI의 기억 시스템 | 🧠 세션/자동/팀 메모리, 추출 에이전트 |
| 6️⃣ | 보안과 권한 시스템 | 🛡️ 3층 방어, 12단계 권한, AST Bash 보안 |
| 7️⃣ | MCP와 확장성 | 🔌 MCP 프로토콜, 스킬, 플러그인 |
| 8️⃣ | 터미널 렌더링 엔진 | 🖥️ React→Yoga→ANSI, 더블 버퍼링 |
| 🔴 고급 | ||
| 9️⃣ | 상태 관리와 글로벌 스토어 | ⚙️ 209개 상태, 비용 추적 |
| 🔟 | 컨텍스트 압축과 토큰 관리 | 🧹 9항목 보존, 캐싱 전략 |
| 1️⃣1️⃣ | 화면 시스템과 세션 관리 | 📺 REPL, Vim, 음성, Buddy |
| 1️⃣2️⃣ | 고급 패턴과 내부 최적화 | 🏗️ 8대 패턴, 동시성, TS 포트 |
| 🔮 특별편 | ||
| 1️⃣3️⃣ | 소스코드에 숨겨진 비밀들 | 🔮 autoDream, Speculation, YOLO, Buddy, Tengu 등 |
| 1️⃣4️⃣ | 실행 흐름 완전 해부 | 🔄 Enter→응답 15단계, 실전 예시, 루프, 프롬프트 |
| 1️⃣5️⃣ | 리버스 엔지니어링 | 🔬 코드 스니펫 10개로 5대 설계 원칙 역공학 |
| 1️⃣6️⃣ | 다른 에이전트와 비교 | ⚔️ Codex, Cursor, Copilot, Aider, Devin 비교 |
License & Disclaimer
이 분석 문서는 교육 및 참고 목적으로 작성되었습니다.
- 분석 대상인 Claude Code는 Anthropic의 제품입니다.
- 이 저장소의 마크다운 분석 문서 및 튜토리얼은 자유롭게 참고할 수 있습니다.
src/디렉터리의 원본 소스코드 저작권은 Anthropic에 있습니다.- 이 저장소는 npm 소스맵 유출로 공개된 코드를 학습 목적으로 분석한 것이며, 상업적 이용이나 재배포를 권장하지 않습니다.
- Anthropic은 유출된 소스코드가 포함된 일부 GitHub 저장소에 대해 DMCA 차단 조치를 취한 바 있습니다.
Contributing
이 프로젝트에 기여하고 싶으시다면:
- 분석 문서의 오류 수정, 누락된 모듈 분석 추가
- 튜토리얼 개선 (설명 보강, 다이어그램 추가)
- 새로운 인사이트나 아키텍처 발견 공유
Issue나 Pull Request를 환영합니다!
이 프로젝트가 유용했다면 Star를 눌러주세요!
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found