eeymoo/claude-code-source-code
1
0
Fork 0
mirror of https://github.com/sanbuphy/claude-code-source-code.git synced 2026-04-03 03:24:57 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
claude-code-source-code/README_KR.md
sanbuphy ce8ca4a8e7 init repo
2026-04-01 18:55:02 +08:00

659 lines
40 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Claude Code 아키텍처 학습 및 연구
> **소개**: 이 프로젝트는 CLI Agent 아키텍처에 대한 학습 및 연구 저장소입니다. 모든 자료는 전적으로 인터넷에 공개된 정보와 토론을 바탕으로 정리되었으며, 특히 현재 매우 인기 있는 CLI Agent인 `claude-code`와 관련된 공개 정보를 참고했습니다. 저희의 목적은 개발자들이 Agent 기술을 더 잘 이해하고 활용할 수 있도록 돕는 것입니다. 앞으로도 Agent 아키텍처와 관련된 더 많은 통찰과 실용적인 토론 콘텐츠를 지속적으로 공유할 예정입니다. 여러분의 관심과 성원에 감사드립니다!
> **면책 조항**: 본 저장소의 콘텐츠는 기술 연구, 학습, 교육 목적의 교류를 위해서만 제공됩니다. **상업적 사용은 엄격히 금지됩니다.** 어떠한 개인, 기관, 단체도 이 콘텐츠를 상업적 목적, 영리 활동, 불법 활동 또는 기타 무단 사용에 활용할 수 없습니다. 본 콘텐츠가 귀하의 법적 권리, 지적 재산권 또는 기타 이익을 침해하는 경우, 연락 주시면 즉시 확인 후 삭제 조치하겠습니다.
**언어**: [English](README.md) | [中文](README_CN.md) | **한국어** | [日本語](README_JA.md)
---
## 도구 시스템 및 권한 아키텍처
```text
도구 인터페이스
==============
buildTool(definition) ──> Tool<Input, Output, Progress>
모든 도구는 다음을 구현합니다:
┌────────────────────────────────────────────────────────┐
│ 수명주기 (LIFECYCLE) │
│ ├── validateInput() → 잘못된 인수 조기 거부 │
│ ├── checkPermissions() → 도구별 권한 검사 │
│ └── call() → 실행 및 결과 반환 │
│ │
│ 기능 (CAPABILITIES) │
│ ├── isEnabled() → 기능 플래그 확인 │
│ ├── isConcurrencySafe() → 병렬 실행 가능 여부? │
│ ├── isReadOnly() → 부작용(side effects) 없음? │
│ ├── isDestructive() → 되돌릴 수 없는 작업? │
│ └── interruptBehavior() → 취소 또는 사용자 대기? │
│ │
│ 렌더링 (RENDERING - React/Ink) │
│ ├── renderToolUseMessage() → 입력 표시 │
│ ├── renderToolResultMessage() → 출력 표시 │
│ ├── renderToolUseProgressMessage() → 스피너/상태 표시 │
│ └── renderGroupedToolUse() → 병렬 도구 그룹 표시 │
│ │
│ AI 연동 (AI FACING) │
│ ├── prompt() → LLM용 도구 설명 │
│ ├── description() → 동적 설명 │
│ └── mapToolResultToAPI() → API 응답용 포맷팅 │
└────────────────────────────────────────────────────────┘
```
### 전체 도구 인벤토리
```text
파일 작업 검색 및 탐색 실행
═════════════════ ══════════════════════ ══════════
FileReadTool GlobTool BashTool
FileEditTool GrepTool PowerShellTool
FileWriteTool ToolSearchTool
NotebookEditTool 상호작용
═══════════
웹 및 네트워크 에이전트 / 작업 AskUserQuestionTool
════════════════ ══════════════════ BriefTool
WebFetchTool AgentTool
WebSearchTool SendMessageTool 계획 및 워크플로우
TeamCreateTool ════════════════════
MCP 프로토콜 TeamDeleteTool EnterPlanModeTool
══════════════ TaskCreateTool ExitPlanModeTool
MCPTool TaskGetTool EnterWorktreeTool
ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool
ReadMcpResourceTool TaskListTool TodoWriteTool
TaskStopTool
TaskOutputTool 시스템
════════
스킬 및 확장 ConfigTool
═════════════════════ SkillTool
SkillTool ScheduleCronTool
LSPTool SleepTool
TungstenTool
```
---
## 권한 시스템
```text
도구 호출 요청
│
▼
┌─ validateInput() ──────────────────────────────────┐
│ 권한 검사 전 유효하지 않은 입력 조기 거부 │
└────────────────────┬───────────────────────────────┘
│
▼
┌─ PreToolUse Hooks (도구 사용 전 훅) ───────────────┐
│ 사용자 정의 쉘 명령 (settings.json hooks) │
│ 가능 작업: 승인, 거부 또는 입력 수정 │
└────────────────────┬───────────────────────────────┘
│
▼
┌─ Permission Rules (권한 규칙) ─────────────────────┐
│ alwaysAllowRules: 도구 이름/패턴 일치 → 자동 승인│
│ alwaysDenyRules: 도구 이름/패턴 일치 → 자동 거부│
│ alwaysAskRules: 도구 이름/패턴 일치 → 항상 확인│
│ 출처: 설정, CLI 인수, 세션 내 결정 │
└────────────────────┬───────────────────────────────┘
│
일치하는 규칙 없음?
│
▼
┌─ Interactive Prompt (대화형 프롬프트) ─────────────┐
│ 사용자가 도구 이름 + 입력값 확인 │
│ 옵션: 한 번 허용 / 항상 허용 / 거부 │
└────────────────────┬───────────────────────────────┘
│
▼
┌─ checkPermissions() ───────────────────────────────┐
│ 도구별 특수 로직 (예: 경로 샌드박스 검사) │
└────────────────────┬───────────────────────────────┘
│
승인됨 → tool.call()
```
---
## 서브 에이전트 및 다중 에이전트 아키텍처
```text
메인 에이전트
==========
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│ 포크 에이전트│ │ 원격 에이전트│ │ 프로세스 내 동료│
│ (FORK) │ │ (REMOTE) │ │ (IN-PROCESS) │
│ 프로세스 포크│ │ 브릿지 세션│ │ 동일 프로세스 │
│ 캐시 공유 │ │ 완전 격리 │ │ 비동기 컨텍스트│
│ 새 msgs[] │ │ │ │ 상태 공유 │
└──────────────┘ └──────────┘ └──────────────┘
생성 모드 (SPAWN MODES):
├─ default → 프로세스 내, 대화 공유
├─ fork → 자식 프로세스, 새로운 messages[], 파일 캐시 공유
├─ worktree → 격리된 git worktree + fork
└─ remote → Claude Code Remote / 컨테이너로의 브릿지 연결
통신 메커니즘 (COMMUNICATION):
├─ SendMessageTool → 에이전트 간 메시지 전달
├─ TaskCreate/Update → 공유 작업 보드(task board)
└─ TeamCreate/Delete → 팀 수명주기 관리
스웜 모드 (SWARM MODE, 기능 플래그로 제어됨):
┌─────────────────────────────────────────────┐
│ 리더 에이전트 (Lead Agent) │
│ ├── 동료 A ──> 작업 1 할당 │
│ ├── 동료 B ──> 작업 2 할당 │
│ └── 동료 C ──> 작업 3 할당 │
│ │
│ 공유: 작업 보드, 메시지 수신함 │
│ 격리: messages[], 파일 캐시, cwd │
└─────────────────────────────────────────────┘
```
---
## 컨텍스트 관리 (압축 시스템)
```text
컨텍스트 창 예산 (CONTEXT WINDOW BUDGET)
══════════════════════════════════════
┌─────────────────────────────────────────────────────┐
│ 시스템 프롬프트 (도구, 권한, CLAUDE.md) │
│ ══════════════════════════════════════════════ │
│ │
│ 대화 기록 (Conversation History) │
│ ┌─────────────────────────────────────────────┐ │
│ │ [이전 메시지들의 압축된 요약] │ │
│ │ ═══════════════════════════════════════════ │ │
│ │ [compact_boundary 마커] │ │
│ │ ─────────────────────────────────────────── │ │
│ │ [최근 메시지 — 원본 그대로 유지] │ │
│ │ user → assistant → tool_use → tool_result │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ 현재 턴 (사용자 + 어시스턴트 응답) │
└─────────────────────────────────────────────────────┘
3가지 압축 전략:
├─ autoCompact → 토큰 수가 임계값을 초과할 때 트리거됨
│ 압축 API 호출을 통해 이전 메시지 요약
├─ snipCompact → 불필요한 메시지와 오래된 마커 제거
│ (HISTORY_SNIP 기능 플래그)
└─ contextCollapse → 효율성을 위해 컨텍스트 재구성
(CONTEXT_COLLAPSE 기능 플래그)
압축 흐름 (COMPACTION FLOW):
messages[] ──> getMessagesAfterCompactBoundary()
│
▼
이전 메시지 ──> Claude API (요약) ──> 압축된 요약
│
▼
[요약] + [compact_boundary] + [최근 메시지]
```
---
## MCP (Model Context Protocol) 통합
```text
┌─────────────────────────────────────────────────────────┐
│ MCP 아키텍처 │
│ │
│ MCPConnectionManager.tsx │
│ ├── 서버 검색 (settings.json 구성 기반) │
│ │ ├── stdio → 자식 프로세스 생성 │
│ │ ├── sse → HTTP EventSource │
│ │ ├── http → 스트리밍 HTTP │
│ │ ├── ws → WebSocket │
│ │ └── sdk → 프로세스 내 전송 │
│ │ │
│ ├── 클라이언트 수명주기 │
│ │ ├── connect → initialize → list tools │
│ │ ├── MCPTool 래퍼를 통한 도구 호출 │
│ │ └── 백오프(backoff)가 포함된 연결 해제 / 재연결│
│ │ │
│ ├── 인증 (Authentication) │
│ │ ├── OAuth 2.0 흐름 (McpOAuthConfig) │
│ │ ├── 교차 앱 액세스 (XAA / SEP-990) │
│ │ └── 헤더를 통한 API 키 전달 │
│ │ │
│ └── 도구 등록 (Tool Registration) │
│ ├── mcp__<server>__<tool> 명명 규칙 │
│ ├── MCP 서버로부터 동적 스키마(schema) 수신 │
│ ├── Claude Code로 권한 통과(passthrough) │
│ └── 리소스 목록화 (ListMcpResourcesTool) │
│ │
└─────────────────────────────────────────────────────────┘
```
---
## 브릿지 레이어 (Claude Desktop / Remote)
```text
Claude Desktop / Web / Cowork Claude Code CLI
══════════════════════════ ═════════════════
┌───────────────────┐ ┌──────────────────┐
│ 브릿지 클라이언트│ ←─ HTTP ──→ │ bridgeMain.ts │
│ (Desktop App) │ │ │
└───────────────────┘ │ 세션 관리자 │
│ ├── CLI 스폰 │
프로토콜 (PROTOCOL): │ ├── 상태 폴링 │
├─ JWT 인증 │ ├── 메시지 릴레이│
├─ Work secret 교환 │ └── 용량 웨이크 │
├─ 세션 수명주기 │ │
│ ├── create │ 백오프(Backoff):│
│ ├── run │ ├─ 연결: 2s→2m │
│ └─ stop │ └─ 생성: 500ms→30s│
└─ 토큰 새로고침 스케줄러 └──────────────────┘
```
---
## 세션 영속성 (Session Persistence)
```text
세션 스토리지 (SESSION STORAGE)
═════════════════════════════
~/.claude/projects/<hash>/sessions/
└── <session-id>.jsonl ← 추가 전용(append-only) 로그
├── {"type":"user",...}
├── {"type":"assistant",...}
├── {"type":"progress",...}
└── {"type":"system","subtype":"compact_boundary",...}
복구 흐름 (RESUME FLOW):
getLastSessionLog() ──> JSONL 파싱 ──> messages[] 재구성
│
├── --continue → 현재 작업 디렉터리의 마지막 세션
├── --resume <id> → 특정 세션
└── --fork-session → 새 ID, 기록 복사
영속성 전략 (PERSISTENCE STRATEGY):
├─ 사용자 메시지 → 쓰기 대기 (충돌 복구를 위한 블로킹)
├─ 어시스턴트 메시지 → 비동기 전송 (순서가 유지되는 큐)
├─ 진행 상태 → 인라인 쓰기 (다음 쿼리 시 중복 제거)
└─ 플러시(Flush) → 결과 반환 시 / cowork 즉시 플러시
```
---
## 기능 플래그 시스템 (Feature Flag System)
```text
데드 코드 제거 (Bun 컴파일 시점)
══════════════════════════════
feature('FLAG_NAME') ──→ true → 번들에 포함됨
──→ false → 번들에서 제거됨
플래그 목록 (소스에서 관찰됨):
├─ COORDINATOR_MODE → 다중 에이전트 코디네이터
├─ HISTORY_SNIP → 공격적인 기록 다듬기
├─ CONTEXT_COLLAPSE → 컨텍스트 재구성
├─ DAEMON → 백그라운드 데몬 워커
├─ AGENT_TRIGGERS → 크론(cron)/원격 트리거
├─ AGENT_TRIGGERS_REMOTE → 원격 트리거 지원
├─ MONITOR_TOOL → MCP 모니터링 도구
├─ WEB_BROWSER_TOOL → 브라우저 자동화
├─ VOICE_MODE → 음성 입력/출력
├─ TEMPLATES → 작업 분류기
├─ EXPERIMENTAL_SKILL_SEARCH → 스킬 탐색
├─ KAIROS → 푸시 알림, 파일 전송
├─ PROACTIVE → 수면 도구, 선제적 행동
├─ OVERFLOW_TEST_TOOL → 테스트 도구
├─ TERMINAL_PANEL → 터미널 캡처
├─ WORKFLOW_SCRIPTS → 워크플로우 도구
├─ CHICAGO_MCP → 컴퓨터 사용 MCP
├─ DUMP_SYSTEM_PROMPT → 프롬프트 추출 (내부 전용)
├─ UDS_INBOX → 피어 탐색
├─ ABLATION_BASELINE → 실험 제거(ablation)
└─ UPGRADE_NOTICE → 업그레이드 알림
런타임 게이트 (RUNTIME GATES):
├─ process.env.USER_TYPE === 'ant' → 내부 기능
└─ GrowthBook feature flags → 런타임 A/B 실험
```
---
## 상태 관리 (State Management)
```text
┌──────────────────────────────────────────────────────────┐
│ AppState Store │
│ │
│ AppState { │
│ toolPermissionContext: { │
│ mode: PermissionMode, ← default/plan 등 │
│ additionalWorkingDirectories, │
│ alwaysAllowRules, ← 자동 승인 │
│ alwaysDenyRules, ← 자동 거부 │
│ alwaysAskRules, ← 항상 확인 │
│ isBypassPermissionsModeAvailable │
│ }, │
│ fileHistory: FileHistoryState, ← 실행 취소 스냅샷 │
│ attribution: AttributionState, ← 커밋 추적 │
│ verbose: boolean, │
│ mainLoopModel: string, ← 활성 모델 │
│ fastMode: FastModeState, │
│ speculation: SpeculationState │
│ } │
│ │
│ React 통합: │
│ ├── AppStateProvider → createContext를 통해 스토어 생성│
│ ├── useAppState(sel) → 선택자(selector) 기반 구독 │
│ └── useSetAppState() → immer 스타일 업데이트 함수 │
└──────────────────────────────────────────────────────────┘
```
---
## 12가지 점진적 안전 장치 (The 12 Progressive Harness Mechanisms)
이 아키텍처는 기본 루프 외에 프로덕션 AI 에이전트 하니스에 필요한 12계층의 점진적 메커니즘을 보여줍니다. 각 메커니즘은 이전 메커니즘을 기반으로 구축됩니다:
```text
s01 핵심 루프 (THE LOOP) "하나의 루프와 Bash면 충분하다"
query.ts: Claude API를 호출하는 while-true 루프,
stop_reason을 확인하고, 도구를 실행하며 결과를 추가합니다.
s02 도구 디스패치 (TOOL DISPATCH) "도구 추가 = 핸들러 하나 추가"
Tool.ts + tools.ts: 모든 도구가 디스패치 맵에 등록됩니다.
루프는 동일하게 유지됩니다. buildTool() 팩토리가 안전한 기본값을 제공합니다.
s03 계획 (PLANNING) "계획 없는 에이전트는 표류한다"
EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool:
단계를 먼저 나열한 다음 실행합니다. 완료율을 두 배로 높입니다.
s04 서브 에이전트 (SUB-AGENTS) "큰 작업을 나누고 하위 작업마다 컨텍스트를 정리한다"
AgentTool + forkSubagent.ts: 각 하위 에이전트는 새로운 messages[]를 가져,
메인 대화를 깨끗하게 유지합니다.
s05 온디맨드 지식 (KNOWLEDGE) "필요할 때 지식을 로드한다"
SkillTool + memdir/: 시스템 프롬프트가 아닌 tool_result를 통해 주입합니다.
디렉터리별로 CLAUDE.md 파일을 지연 로드(lazy load)합니다.
s06 컨텍스트 압축 (COMPRESSION) "컨텍스트가 꽉 차면 공간을 확보한다"
services/compact/: 3계층 전략:
autoCompact (요약) + snipCompact (자르기) + contextCollapse
s07 영구 작업 (TASKS) "큰 목표 → 작은 작업 → 디스크"
TaskCreate/Update/Get/List: 파일 기반의 작업 그래프(Task graph)로,
상태 추적, 종속성 및 영속성을 갖습니다.
s08 백그라운드 작업 (BACKGROUND) "백그라운드에서 느린 작업 실행; 에이전트는 계속 생각한다"
DreamTask + LocalShellTask: 데몬 스레드가 명령을 실행하고,
완료 시 알림을 주입합니다.
s09 에이전트 팀 (TEAMS) "혼자 하기엔 너무 크다 → 동료에게 위임한다"
TeamCreate/Delete + InProcessTeammateTask:
비동기 메일박스를 가진 영구적인 동료 에이전트들.
s10 팀 프로토콜 (PROTOCOLS) "공유된 통신 규칙"
SendMessageTool: 하나의 요청-응답 패턴이
에이전트 간의 모든 협상을 주도합니다.
s11 자율 에이전트 (AUTONOMOUS) "동료들이 스스로 작업을 스캔하고 청구한다"
coordinator/coordinatorMode.ts: 유휴 루프(Idle cycle) + 자동 할당,
리더가 모든 작업을 일일이 할당할 필요가 없습니다.
s12 작업 트리 격리 (WORKTREE) "각자 자신의 디렉터리에서 작업한다"
EnterWorktreeTool/ExitWorktreeTool: 작업은 목표를 관리하고,
작업 트리는 디렉터리를 관리하며, ID로 연결됩니다.
```
---
## 핵심 디자인 패턴 (Key Design Patterns)
| 패턴 | 위치 | 목적 |
|---------|-------|---------|
| **AsyncGenerator 스트리밍** | `QueryEngine`, `query()` | API에서 소비자로 이어지는 전체 체인 스트리밍 |
| **빌더 + 팩토리 (Builder + Factory)** | `buildTool()` | 도구 정의를 위한 안전한 기본값 제공 |
| **브랜드 타입 (Branded Types)** | `SystemPrompt`, `asSystemPrompt()` | 문자열/배열 혼동 방지 |
| **기능 플래그 + DCE** | `bun:bundle`의 `feature()` | 컴파일 시점 데드 코드 제거(DCE) |
| **구별된 유니온 (Discriminated Unions)** | `Message` 타입 | 타입 안전성이 보장되는 메시지 처리 |
| **옵저버 + 상태 머신** | `StreamingToolExecutor` | 도구 실행 수명주기 추적 |
| **스냅샷 상태 (Snapshot State)** | `FileHistoryState` | 파일 작업의 실행 취소/다시 실행 |
| **링 버퍼 (Ring Buffer)** | 에러 로그 | 긴 세션을 위한 제한된 메모리 사용 |
| **발사 후 망각 (Fire-and-Forget)** | `recordTranscript()` | 순서가 유지되는 논블로킹 영속화 |
| **지연 스키마 (Lazy Schema)** | `lazySchema()` | 성능 향상을 위한 Zod 스키마 지연 평가 |
| **컨텍스트 격리 (Context Isolation)** | `AsyncLocalStorage` | 공유 프로세스 내 각 에이전트별 컨텍스트 |
---
## 데이터 흐름: 단일 쿼리 수명주기
```text
사용자 입력 (프롬프트 / 슬래시 명령)
│
▼
processUserInput() ← /명령어 파싱, UserMessage 생성
│
▼
fetchSystemPromptParts() ← 도구 → 프롬프트 섹션, CLAUDE.md 메모리
│
▼
recordTranscript() ← 사용자 메시지를 디스크에 영속화 (JSONL)
│
▼
┌─→ normalizeMessagesForAPI() ← UI 전용 필드 제거, 필요시 압축 수행
│ │
│ ▼
│ Claude API (스트리밍) ← 도구 + 시스템 프롬프트와 함께 POST /v1/messages
│ │
│ ▼
│ 스트림 이벤트 ← message_start → content_block_delta → message_stop
│ │
│ ├─ 텍스트 블록 ──────────────→ 소비자(SDK / REPL)에게 전달
│ │
│ └─ tool_use 블록?
│ │
│ ▼
│ StreamingToolExecutor ← 분할: 동시성 안전(concurrent-safe) vs 직렬(serial)
│ │
│ ▼
│ canUseTool() ← 권한 검사 (훅 + 규칙 + UI 프롬프트)
│ │
│ ├─ 거부 ────────────────→ tool_result(error) 추가, 루프 계속
│ │
│ └─ 허용
│ │
│ ▼
│ tool.call() ← 도구 실행 (Bash, Read, Edit 등)
│ │
│ ▼
│ tool_result 추가 ← messages[]에 푸시, recordTranscript()
│ │
└─────────┘ ← API 호출로 루프 복귀
│
▼ (stop_reason != "tool_use")
결과 메시지 생성 ← 최종 텍스트, 사용량, 비용, session_id
```
---
## 목차
- [심층 분석 보고서 (`docs/`)](#심층-분석-보고서-docs) — 텔레메트리, 코드네임, 언더커버 모드, 원격 제어, 향후 로드맵
- [디렉터리 참조](#디렉터리-참조) — 코드 구조 트리
- [아키텍처 개요](#아키텍처-개요) — 진입점 → 쿼리 엔진 → 도구/서비스/상태
- [도구 시스템 및 권한 아키텍처](#도구-시스템-및-권한-아키텍처) — 40+ 도구, 권한 흐름, 서브 에이전트
- [12가지 점진적 안전 장치](#12가지-점진적-안전-장치-the-12-progressive-harness-mechanisms) — Claude Code가 에이전트 루프에 프로덕션 기능을 구현하는 방법
---
## 심층 분석 보고서 (`docs/`)
인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서. 영어/중국어/한국어/일본어 4개 국어 제공.
```
docs/
├── en/ # English
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
│
├── ko/ # 한국어
│ ├── [01-텔레메트리와-프라이버시.md] # 텔레메트리 및 프라이버시 — 수집 항목, 비활성화 불가 이유
│ ├── [02-숨겨진-기능과-코드네임.md] # 숨겨진 기능 — 모델 코드네임, feature flag, 내부/외부 사용자 차이
│ ├── [03-언더커버-모드.md] # 언더커버 모드 — 오픈소스에서 AI 저작 은폐
│ ├── [04-원격-제어와-킬스위치.md] # 원격 제어 — 관리 설정, 킬스위치, 모델 오버라이드
│ └── [05-향후-로드맵.md] # 향후 로드맵 — Numbat, KAIROS, 음성 모드, 미공개 도구
│
└── zh/ # 中文
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
```
> 파일명을 클릭하면 해당 보고서로 이동합니다.
| # | 주제 | 핵심 발견 | 링크 |
|---|------|----------|------|
| 01 | **텔레메트리 및 프라이버시** | 이중 분석 파이프라인 (1P, Datadog). 환경 핑거프린트, 프로세스 메트릭, 모든 이벤트에 세션/사용자 ID 포함. **사용자 대상 비활성화 설정 없음.** `OTEL_LOG_TOOL_DETAILS=1`로 전체 도구 입력 기록 가능. | [EN](docs/en/01-telemetry-and-privacy.md) · [한국어](docs/ko/01-텔레메트리와-프라이버시.md) · [中文](docs/zh/01-遥测与隐私分析.md) |
| 02 | **숨겨진 기능과 코드네임** | 동물 코드네임 체계 (Capybara v8, Tengu, Fennec→Opus 4.6, **Numbat** 차기). Feature flag에 무작위 단어 조합으로 목적 난독화. 내부 사용자는 더 나은 프롬프트와 검증 에이전트 제공. 숨겨진 명령어: `/btw`, `/stickers`. | [EN](docs/en/02-hidden-features-and-codenames.md) · [한국어](docs/ko/02-숨겨진-기능과-코드네임.md) · [中文](docs/zh/02-隐藏功能与模型代号.md) |
| 03 | **언더커버 모드** | 공식 직원은 공개 저장소에서 자동으로 언더커버 모드 진입. 모델 지시: **"정체를 들키지 마라"** — 모든 AI 저작 표시를 제거하고, 사람이 작성한 것처럼 커밋. **강제 비활성화 옵션 없음.** | [EN](docs/en/03-undercover-mode.md) · [한국어](docs/ko/03-언더커버-모드.md) · [中文](docs/zh/03-卧底模式分析.md) |
| 04 | **원격 제어 및 킬스위치** | 1시간마다 `/api/claude_code/settings` 폴링. 위험 변경 시 차단 다이얼로그 — **거부 = 앱 종료**. 6개 이상 킬스위치 (권한 우회, fast 모드, 음성 모드, 분석 싱크). GrowthBook으로 동의 없이 사용자 동작 변경 가능. | [EN](docs/en/04-remote-control-and-killswitches.md) · [한국어](docs/ko/04-원격-제어와-킬스위치.md) · [中文](docs/zh/04-远程控制与紧急开关.md) |
| 05 | **향후 로드맵** | **Numbat** 코드네임 확인. Opus 4.7 / Sonnet 4.8 개발 중. **KAIROS** = 완전 자율 에이전트 모드, `<tick>` 하트비트, 푸시 알림, PR 구독. 음성 모드(push-to-talk) 준비 완료. 미공개 도구 17개 발견. | [EN](docs/en/05-future-roadmap.md) · [한국어](docs/ko/05-향후-로드맵.md) · [中文](docs/zh/05-未来路线图.md) |
---
## 저작권 및 면책 조항
```text
본 저장소는 기술 연구 및 교육 목적으로만 제공됩니다. 상업적 사용은 금지됩니다.
저작권자로서 본 저장소 콘텐츠가 귀하의 권리를 침해한다고 판단되는 경우,
저장소 소유자에게 연락 주시면 즉시 삭제하겠습니다.
```
---
## 통계
| 항목 | 수량 |
|------|------|
| 파일 (.ts/.tsx) | ~1,884 |
| 라인 수 | ~512,664 |
| 최대 단일 파일 | `query.ts` (~785KB) |
| 내장 도구 | ~40개 이상 |
| 슬래시 명령 | ~80개 이상 |
| 의존성 (node_modules) | ~192개 패키지 |
| 런타임 | Bun (Node.js >= 18 번들로 컴파일) |
---
## 에이전트 모드
```
코어 루프
========
사용자 --> messages[] --> Claude API --> 응답
|
stop_reason == "tool_use"?
/ \
예 아니오
| |
도구 실행 텍스트 반환
tool_result 추가
루프 재진입 -----------------> messages[]
이것이 최소 에이전트 루프이다. Claude Code는 이 루프 위에
프로덕션급 하니스를 래핑한다: 권한, 스트리밍, 동시성,
압축, 서브에이전트, 영속화 및 MCP.
```
---
## 디렉터리 참조
```
src/
├── main.tsx # REPL 부트스트랩, 4,683줄
├── QueryEngine.ts # SDK/headless 쿼리 라이프사이클 엔진
├── query.ts # 메인 에이전트 루프 (785KB, 최대 파일)
├── Tool.ts # 도구 인터페이스 + buildTool 팩토리
├── Task.ts # 태스크 타입, ID, 상태 베이스 클래스
├── tools.ts # 도구 등록, 프리셋, 필터링
├── commands.ts # 슬래시 명령 정의
├── context.ts # 사용자 입력 컨텍스트
├── cost-tracker.ts # API 비용 누적
├── setup.ts # 최초 실행 설정 플로우
│
├── bridge/ # Claude Desktop / 원격 브릿지
│ ├── bridgeMain.ts # 세션 라이프사이클 매니저
│ ├── bridgeApi.ts # HTTP 클라이언트
│ ├── bridgeConfig.ts # 연결 설정
│ ├── bridgeMessaging.ts # 메시지 릴레이
│ ├── sessionRunner.ts # 프로세스 스폰
│ ├── jwtUtils.ts # JWT 갱신
│ ├── workSecret.ts # 인증 토큰
│ └── capacityWake.ts # 용량 기반 웨이크
│
├── cli/ # CLI 인프라
│ ├── handlers/ # 명령 핸들러
│ └── transports/ # I/O 전송 (stdio, structured)
│
├── commands/ # ~80개 슬래시 명령
├── components/ # React/Ink 터미널 UI
├── entrypoints/ # 앱 진입점
├── hooks/ # React hooks
├── services/ # 비즈니스 로직 레이어
├── state/ # 앱 상태
├── tasks/ # 태스크 구현
├── tools/ # 40개 이상 도구 구현
├── types/ # 타입 정의
├── utils/ # 유틸리티 (최대 디렉터리)
└── vendor/ # 네이티브 모듈 스텁
```
---
## 아키텍처 개요
```
┌─────────────────────────────────────────────────────────────────────┐
│ 진입 레이어 │
│ cli.tsx ──> main.tsx ──> REPL.tsx (인터랙티브) │
│ └──> QueryEngine.ts (headless/SDK) │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 쿼리 엔진 │
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
│ ├── fetchSystemPromptParts() ──> 시스템 프롬프트 조립 │
│ ├── processUserInput() ──> /명령 처리 │
│ ├── query() ──> 메인 에이전트 루프 │
│ │ ├── StreamingToolExecutor ──> 병렬 도구 실행 │
│ │ ├── autoCompact() ──> 컨텍스트 압축 │
│ │ └── runTools() ──> 도구 오케스트레이션 │
│ └── yield SDKMessage ──> 소비자에게 스트리밍 │
└──────────────────────────────┬──────────────────────────────────────┘
```
---
## 라이선스
본 저장소 콘텐츠는 기술 연구 및 교육 목적으로만 제공됩니다. 지적 재산권은 원 회사에 귀속됩니다. 권리 침해가 있는 경우 삭제를 위해 연락 주시기 바랍니다.
Reference in New Issue View Git Blame Copy Permalink