cx-viewer 1.0.0

package/concepts/ko/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## 정의
+
+태스크 리스트 내 특정 태스크의 상태, 내용 또는 의존 관계를 업데이트합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `taskId` | string | 예 | 업데이트할 태스크 ID |
+| `status` | enum | 아니오 | 새 상태: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | 아니오 | 새 제목 |
+| `description` | string | 아니오 | 새 설명 |
+| `activeForm` | string | 아니오 | 진행 중 표시할 현재 진행형 텍스트 |
+| `owner` | string | 아니오 | 새 태스크 담당자 (agent 이름) |
+| `metadata` | object | 아니오 | 병합할 메타데이터 (null로 설정하면 키 삭제) |
+| `addBlocks` | string[] | 아니오 | 이 태스크에 의해 차단되는 태스크 ID 목록 |
+| `addBlockedBy` | string[] | 아니오 | 이 태스크를 차단하는 선행 태스크 ID 목록 |
+
+## 상태 전이
+
+```
+pending → in_progress → completed
+```
+
+`deleted`는 모든 상태에서 전이 가능하며, 태스크를 영구 삭제합니다.
+
+## 사용 시나리오
+
+**적합한 경우:**
+- 작업 시작 시 태스크를 `in_progress`로 마킹
+- 작업 완료 후 태스크를 `completed`로 마킹
+- 태스크 간 의존 관계 설정
+- 요구사항 변경 시 태스크 내용 업데이트
+
+**중요 규칙:**
+- 태스크를 완전히 완료한 경우에만 `completed`로 마킹
+- 오류나 차단에 직면하면 `in_progress` 유지
+- 테스트 실패, 구현 불완전, 미해결 오류가 있으면 `completed`로 마킹 불가
+
+## 주의사항
+
+- 업데이트 전 TaskGet으로 태스크의 최신 상태를 가져와 오래된 데이터를 피할 것
+- 태스크 완료 후 TaskList를 호출하여 다음 사용 가능한 태스크 검색
+
+## 원문
+
+<textarea readonly>Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```
+</textarea>

package/concepts/ko/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## 정의
+
+프로젝트를 진행하는 여러 agent를 조율하는 새로운 팀을 생성합니다. 팀은 공유 태스크 목록과 agent 간 메시지 교환을 통해 병렬 태스크 실행을 가능하게 합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `team_name` | string | 예 | 새 팀의 이름 |
+| `description` | string | 아니오 | 팀 설명 / 목적 |
+| `agent_type` | string | 아니오 | 팀 리더의 타입 / 역할 |
+
+## 생성되는 항목
+
+- **팀 설정 파일**: `~/.claude/teams/{team-name}/config.json` — 멤버 목록과 메타데이터 저장
+- **태스크 목록 디렉토리**: `~/.claude/tasks/{team-name}/` — 모든 팀원이 공유하는 태스크 목록
+
+팀과 태스크 목록은 1:1 대응 관계입니다.
+
+## 팀 워크플로우
+
+1. **TeamCreate** — 팀과 태스크 목록 생성
+2. **TaskCreate** — 팀의 태스크 정의
+3. **Agent** (`team_name` + `name` 지정) — 팀에 합류하는 팀원 생성
+4. **TaskUpdate** — `owner`를 통해 팀원에게 태스크 할당
+5. 팀원들이 태스크를 수행하며 **SendMessage**로 소통
+6. 완료 후 팀원 종료, 이후 **TeamDelete**로 정리
+
+## 관련 도구
+
+| 도구 | 용도 |
+|------|------|
+| `TeamDelete` | 팀과 태스크 디렉토리 제거 |
+| `SendMessage` | 팀 내 agent 간 통신 |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 공유 태스크 목록 관리 |
+| `Agent` | 팀에 합류하는 팀원 생성 |

package/concepts/ko/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## 정의
+
+다중 agent 협업 작업이 완료되었을 때 팀과 관련 태스크 디렉토리를 제거합니다. TeamCreate의 정리 대응 작업입니다.
+
+## 동작
+
+- 팀 디렉토리 제거: `~/.claude/teams/{team-name}/`
+- 태스크 디렉토리 제거: `~/.claude/tasks/{team-name}/`
+- 현재 세션에서 팀 컨텍스트 초기화
+
+**중요**: 팀에 아직 활성 멤버가 있으면 TeamDelete는 실패합니다. SendMessage 종료 요청을 통해 먼저 모든 팀원을 정상적으로 종료해야 합니다.
+
+## 일반적인 사용 방법
+
+TeamDelete는 팀 워크플로우 종료 시 호출됩니다:
+
+1. 모든 태스크 완료
+2. `SendMessage`로 `shutdown_request`를 보내 팀원 종료
+3. **TeamDelete**가 팀과 태스크 디렉토리 제거
+
+## 관련 도구
+
+| 도구 | 용도 |
+|------|------|
+| `TeamCreate` | 새 팀과 태스크 목록 생성 |
+| `SendMessage` | 팀원과의 통신 / 종료 요청 전송 |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 공유 태스크 목록 관리 |
+| `Agent` | 팀에 합류하는 팀원 생성 |

package/concepts/ko/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## 정의
+
+지정된 URL의 웹페이지 내용을 가져와 HTML을 markdown으로 변환하고, AI 모델로 prompt에 따라 내용을 처리합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `url` | string (URI) | 예 | 가져올 완전한 URL |
+| `prompt` | string | 예 | 페이지에서 어떤 정보를 추출할지 설명 |
+
+## 사용 시나리오
+
+**적합한 경우:**
+- 공개 웹페이지의 내용 가져오기
+- 온라인 문서 참조
+- 웹페이지에서 특정 정보 추출
+
+**적합하지 않은 경우:**
+- 인증이 필요한 URL (Google Docs, Confluence, Jira, GitHub 등) — 먼저 전용 MCP 도구를 찾아야 함
+- GitHub URL — `gh` CLI를 우선 사용
+
+## 주의사항
+
+- URL은 완전한 유효 URL이어야 함
+- HTTP는 자동으로 HTTPS로 업그레이드
+- 내용이 너무 크면 결과가 요약될 수 있음
+- 15분 자동 정리 캐시 포함
+- URL이 다른 호스트로 리다이렉트되면 도구가 리다이렉트 URL을 반환하며, 새 URL로 재요청 필요
+- MCP 제공 web fetch 도구가 사용 가능하면 그것을 우선 사용
+
+## 원문
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

package/concepts/ko/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## 정의
+
+검색 엔진 쿼리를 실행하여 최신 정보를 얻기 위한 검색 결과를 반환합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `query` | string | 예 | 검색 쿼리 (최소 2자) |
+| `allowed_domains` | string[] | 아니오 | 이 도메인의 결과만 포함 |
+| `blocked_domains` | string[] | 아니오 | 이 도메인의 결과를 제외 |
+
+## 사용 시나리오
+
+**적합한 경우:**
+- 모델의 지식 컷오프 날짜를 넘는 최신 정보 획득
+- 현재 이벤트 및 최신 데이터 검색
+- 최신 기술 문서 검색
+
+## 주의사항
+
+- 검색 결과는 markdown 하이퍼링크 형식으로 반환
+- 사용 후 응답 끝에 "Sources:" 섹션을 추가하고 관련 URL을 나열해야 함
+- 도메인 필터링 (포함/제외) 지원
+- 검색 쿼리에 현재 연도를 사용해야 함
+- 미국에서만 사용 가능
+
+## 원문
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

package/concepts/ko/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## 정의
+
+로컬 파일 시스템에 내용을 씁니다. 파일이 이미 존재하면 덮어씁니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `file_path` | string | 예 | 파일의 절대 경로 (절대 경로여야 함) |
+| `content` | string | 예 | 쓸 내용 |
+
+## 사용 시나리오
+
+**적합한 경우:**
+- 새 파일 생성
+- 파일 내용을 완전히 재작성해야 하는 경우
+
+**적합하지 않은 경우:**
+- 파일 내 부분적인 내용 수정 — Edit를 사용해야 함
+- 문서 파일 (*.md)이나 README를 자발적으로 생성하지 말 것. 사용자가 명시적으로 요청한 경우를 제외
+
+## 주의사항
+
+- 대상 파일이 이미 존재하면 먼저 Read로 읽어야 함. 그렇지 않으면 실패
+- 기존 파일의 전체 내용을 덮어씀
+- 기존 파일 편집에는 Edit를 우선 사용하고, Write는 새 파일 생성 또는 완전한 재작성에만 사용
+
+## 원문
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/ko/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## 정의
+
+현재 notebook 파일의 Jupyter kernel에서 Python 코드를 실행합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `code` | string | 예 | 실행할 Python 코드 |
+
+## 사용 시나리오
+
+**적합한 경우:**
+- Jupyter notebook 환경에서 코드 실행
+- 코드 스니펫 테스트
+- 데이터 분석 및 계산
+
+**적합하지 않은 경우:**
+- 비 Jupyter 환경에서의 코드 실행 — Bash를 사용해야 함
+- 파일 수정 — Edit 또는 Write를 사용해야 함
+
+## 주의사항
+
+- 이것은 MCP (Model Context Protocol) 도구이며, IDE 통합에 의해 제공
+- 코드는 현재 Jupyter kernel에서 실행되며, 상태는 호출 간에 유지
+- 사용자가 명시적으로 요청하지 않는 한 변수 선언이나 kernel 상태 변경을 피해야 함
+- kernel 재시작 후 상태가 소실됨
+
+## 원문
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

package/concepts/ko/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## 정의
+
+VS Code에서 언어 진단 정보를 가져옵니다. 구문 오류, 타입 오류, lint 경고 등을 포함합니다.
+
+## 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|----------|------|------|------|
+| `uri` | string | 아니오 | 파일 URI. 제공하지 않으면 모든 파일의 진단 정보를 가져옴 |
+
+## 사용 시나리오
+
+**적합한 경우:**
+- 코드의 구문, 타입, lint 등 시맨틱 문제 확인
+- 코드 편집 후 새로운 오류가 도입되지 않았는지 검증
+- Bash 명령 대신 코드 품질 확인
+
+**적합하지 않은 경우:**
+- 테스트 실행 — Bash를 사용해야 함
+- 런타임 오류 확인 — Bash로 코드를 실행해야 함
+
+## 주의사항
+
+- 이것은 MCP (Model Context Protocol) 도구이며, IDE 통합에 의해 제공
+- VS Code / IDE 환경에서만 사용 가능
+- 코드 문제 확인에는 Bash 명령보다 이 도구를 우선 사용
+
+## 원문
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/ko/Tools.md

@@ -0,0 +1,67 @@
+# Claude Code 도구 목록
+
+Claude Code는 Anthropic API의 tool_use 메커니즘을 통해 모델에 일련의 내장 도구를 제공합니다. 각 MainAgent 요청의 `tools` 배열에 이러한 도구의 완전한 JSON Schema 정의가 포함되며, 모델은 응답 내의 `tool_use` content block으로 이를 호출합니다.
+
+다음은 모든 도구의 카테고리별 인덱스입니다.
+
+## Agent 시스템
+
+| 도구 | 용도 |
+|------|------|
+| [Task](Tool-Task.md) | 서브 agent (SubAgent)를 시작하여 복잡한 다단계 태스크 처리 |
+| [TaskOutput](Tool-TaskOutput.md) | 백그라운드 태스크의 출력 가져오기 |
+| [TaskStop](Tool-TaskStop.md) | 실행 중인 백그라운드 태스크 중지 |
+| [TaskCreate](Tool-TaskCreate.md) | 구조화된 태스크 리스트 항목 생성 |
+| [TaskGet](Tool-TaskGet.md) | 태스크 상세 정보 가져오기 |
+| [TaskUpdate](Tool-TaskUpdate.md) | 태스크 상태, 의존 관계 등 업데이트 |
+| [TaskList](Tool-TaskList.md) | 모든 태스크 목록 표시 |
+
+## 파일 작업
+
+| 도구 | 용도 |
+|------|------|
+| [Read](Tool-Read.md) | 파일 내용 읽기 (텍스트, 이미지, PDF, Jupyter notebook 지원) |
+| [Edit](Tool-Edit.md) | 정확한 문자열 치환으로 파일 편집 |
+| [Write](Tool-Write.md) | 파일 쓰기 또는 덮어쓰기 |
+| [NotebookEdit](Tool-NotebookEdit.md) | Jupyter notebook 셀 편집 |
+
+## 검색
+
+| 도구 | 용도 |
+|------|------|
+| [Glob](Tool-Glob.md) | 파일명 패턴 매칭으로 파일 검색 |
+| [Grep](Tool-Grep.md) | ripgrep 기반 파일 내용 검색 |
+
+## 터미널
+
+| 도구 | 용도 |
+|------|------|
+| [Bash](Tool-Bash.md) | 셸 명령 실행 |
+
+## Web
+
+| 도구 | 용도 |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | 웹페이지 내용을 가져와 AI로 처리 |
+| [WebSearch](Tool-WebSearch.md) | 검색 엔진 쿼리 |
+
+## 계획 및 상호작용
+
+| 도구 | 용도 |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | 계획 모드 진입, 구현 방안 설계 |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | 계획 모드 종료 및 방안을 사용자 승인에 제출 |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | 사용자에게 질문하여 확인 또는 결정 획득 |
+
+## 확장
+
+| 도구 | 용도 |
+|------|------|
+| [Skill](Tool-Skill.md) | 스킬 (slash command) 실행 |
+
+## IDE 통합
+
+| 도구 | 용도 |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | VS Code 언어 진단 정보 가져오기 |
+| [executeCode](Tool-executeCode.md) | Jupyter kernel에서 코드 실행 |

package/concepts/ko/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Tools가 왜 먼저 나열되는가?
+
+cc-viewer의 Context 패널에서 **Tools는 System Prompt와 Messages보다 앞에 표시됩니다**. 이 순서는 **Anthropic API의 KV-Cache 프리픽스 시퀀스**를 정확히 반영한 것입니다.
+
+## KV-Cache 프리픽스 시퀀스
+
+Anthropic의 API가 KV-Cache를 구성할 때, 컨텍스트를 다음 **고정된 순서**로 프리픽스에 연결합니다:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+즉, **Tools는 System Prompt보다 앞에, 캐시 프리픽스의 맨 처음에 위치합니다**.
+
+## Tools가 System보다 캐시 가중치가 높은 이유는?
+
+KV-Cache 프리픽스 매칭에서는 **앞쪽의 콘텐츠일수록 더 중요**합니다 — 변경이 발생하면 그 이후의 모든 내용이 무효화됩니다:
+
+1. **프리픽스 매칭은 처음부터 시작됩니다**: KV-Cache는 현재 요청을 캐시된 프리픽스와 처음부터 token 단위로 비교합니다. 불일치가 발견되는 순간, 이후의 모든 콘텐츠가 무효화됩니다.
+
+2. **Tools 변경 = 전체 캐시 무효화**: Tools가 맨 앞에 있기 때문에, tool 정의의 변경(MCP tool 하나를 추가하거나 제거하는 것만으로도)은 **프리픽스를 맨 처음부터 깨뜨려**, 캐시된 System Prompt와 Messages 전체를 무효화합니다.
+
+3. **System 변경 = Messages 캐시 무효화**: System Prompt는 중간에 위치하므로, 변경 시 그 뒤에 오는 Messages 부분만 무효화됩니다.
+
+4. **Messages 변경 = 끝부분만 영향받음**: Messages는 마지막에 있으므로, 새로운 message 추가는 작은 끝부분 세그먼트만 무효화합니다 — Tools와 System 캐시는 그대로 유지됩니다.
+
+## 실제 영향
+
+| 변경 유형 | 캐시 영향 | 일반적인 시나리오 |
+|-------------|-------------|-----------------|
+| Tool 추가/제거 | **전체 무효화** | MCP 서버 연결/연결 해제, IDE 플러그인 전환 |
+| System Prompt 변경 | Messages 캐시 손실 | CLAUDE.md 편집, system reminder 삽입 |
+| 새 message 추가 | 끝부분 증분만 | 일반적인 대화 흐름 (가장 일반적, 가장 저렴) |
+
+이것이 [CacheRebuild](CacheRebuild.md)에서 `tools_change`가 가장 비용이 많이 드는 리빌드 이유가 되기 쉬운 이유입니다 — 프리픽스 체인을 맨 앞에서부터 깨뜨리기 때문입니다.
+
+## 왜 도구 정의가 "두뇌"보다 먼저 배치되는가?
+
+캐싱 관점에서 Tools가 맨 앞에 오는 것은 기술적 사실입니다. 하지만 인지 설계 관점에서도 이 순서는 합리적입니다 —— **Tools는 손과 발이고, System Prompt는 두뇌입니다**.
+
+사람은 행동하기 전에 자신이 어떤 팔다리와 도구를 사용할 수 있는지 먼저 인지해야 합니다. 갓난아기는 먼저 세상의 규칙(System)을 이해하고 나서 손을 뻗는 것이 아닙니다 — 먼저 자신에게 손과 발이 있다는 것을 감지하고, 환경과의 상호작용을 통해 점차 규칙을 이해합니다. 마찬가지로 LLM은 작업 지시(System Prompt)를 받기 전에 어떤 도구를 호출할 수 있는지(파일 읽기, 코드 작성, 검색, 명령 실행) 알아야, 지시를 처리할 때 "내가 무엇을 할 수 있는지"와 "어떻게 해야 하는지"를 정확하게 평가할 수 있습니다.
+
+만약 반대라면 — 모델에게 먼저 "이 모듈을 리팩토링하라"고 말하고, 그 다음에 "Read, Edit, Bash 도구가 있다"고 알려주면 — 모델은 작업을 이해할 때 핵심적인 능력 경계 정보가 부족해져, 비현실적인 계획을 세우거나 사용 가능한 방법을 놓칠 수 있습니다.
+
+**가진 패를 먼저 확인하고, 어떻게 낼지 결정한다.** 이것이 Tools가 System보다 먼저 오는 인지적 논리입니다.
+
+## 왜 MCP 도구도 이 위치에 있는가?
+
+MCP(Model Context Protocol) 도구는 내장 도구와 마찬가지로 Tools 영역의 맨 앞에 배치됩니다. 컨텍스트에서 MCP의 위치를 이해하면 실제 이점과 비용을 평가하는 데 도움이 됩니다.
+
+### MCP의 장점
+
+- **능력 확장**: MCP를 통해 모델은 외부 서비스(데이터베이스 쿼리, API 호출, IDE 조작, 브라우저 제어 등)에 접근할 수 있어 내장 도구의 한계를 넘어섭니다
+- **개방형 생태계**: 누구나 MCP 서버를 구현할 수 있으며, 모델은 재훈련 없이 새로운 능력을 얻습니다
+- **온디맨드 로딩**: 작업 시나리오에 따라 MCP 서버를 선택적으로 연결/해제하여 도구 세트를 유연하게 구성할 수 있습니다
+
+### MCP의 비용
+
+- **캐시 킬러**: 각 MCP 도구의 JSON Schema 정의는 KV-Cache 접두사의 맨 앞에 연결됩니다. MCP 도구 1개 추가/제거 = **전체 캐시가 처음부터 무효화**됩니다. MCP 서버를 자주 연결/해제하면 캐시 적중률이 크게 떨어집니다
+- **접두사 비대화**: MCP 도구 Schema는 일반적으로 내장 도구보다 큽니다(상세한 매개변수 설명, 열거 값 등 포함). 많은 MCP 도구는 Tools 영역의 토큰 수를 크게 늘려 Messages에 사용할 수 있는 컨텍스트 공간을 압박합니다
+- **지연 오버헤드**: MCP 도구 호출은 프로세스 간 통신(JSON-RPC over stdio/SSE)이 필요하여 내장 함수 호출보다 한 자릿수 느립니다
+- **안정성 위험**: MCP 서버는 외부 프로세스로, 충돌, 타임아웃, 예상치 못한 형식 반환이 발생할 수 있어 추가적인 오류 처리가 필요합니다
+
+### 실용적 권장 사항
+
+| 시나리오 | 권장 |
+|----------|------|
+| 긴 대화, 고빈도 상호작용 | MCP 도구 수를 최소화하여 캐시 접두사 안정성 보호 |
+| 짧은 작업, 일회성 작업 | MCP 도구 자유롭게 사용 가능; 캐시 영향 제한적 |
+| MCP 서버 빈번한 추가/제거 | 변경할 때마다 캐시 전체 재구축 발생; 도구 세트 고정 고려 |
+| 과대한 Tool Schema | description과 enum을 축소하여 접두사 토큰 소비 절감 |
+
+cc-viewer의 Context 패널에서 MCP 도구는 내장 도구와 함께 Tools 영역에 표시되어, 각 도구의 Schema 크기와 캐시 접두사에 대한 기여를 직관적으로 확인할 수 있습니다.

package/concepts/ko/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# 번역 API 컨텍스트 오염
+
+## 배경
+
+CC-Viewer에는 Anthropic Messages API를 활용한 내장 번역 기능(`POST /api/translate`)이 포함되어 있습니다. 초기 구현에서는 번역 요청이 Claude Code 세션에서 캐시된 인증 자격 증명(`x-api-key`와 `authorization` 헤더 모두)을 재사용했습니다. 이로 인해 미묘하지만 심각한 문제가 발생했습니다: 번역 결과에 관련 없는 콘텐츠가 빈번하게 반환되었습니다.
+
+## 근본 원인
+
+### 두 가지 인증 방식의 본질적 차이
+
+Anthropic API는 두 가지 인증 방식을 지원합니다:
+
+| 방식 | 헤더 | 일반적인 출처 | 특징 |
+|------|------|---------------|------|
+| API 키 | `x-api-key: sk-ant-...` | 환경 변수 / Console | 무상태, 각 요청이 독립적 |
+| OAuth 토큰 | `authorization: Bearer sessionToken` | Claude Code 구독 로그인 | 세션에 바인딩, 서버가 컨텍스트 연관을 유지 |
+
+핵심 차이점: **API 키는 무상태(stateless)**로 각 요청이 완전히 독립적입니다. 반면 **OAuth 세션 토큰은 상태 유지(stateful)**로, Anthropic 서버가 동일한 토큰을 사용하는 요청을 같은 세션 컨텍스트에 연관시킵니다.
+
+### 오염 체인
+
+Claude Code가 구독형 OAuth 로그인을 사용할 때 인증 흐름은 다음과 같습니다:
+
+```
+Claude Code 메인 대화 ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                    ↑
+CC-Viewer 번역 요청 ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+번역 요청이 동일한 세션 토큰을 재사용했기 때문에, Anthropic 서버가 번역 요청을 Claude Code의 메인 대화 컨텍스트에 연관시킬 수 있었습니다. 이로 인해 다음과 같은 문제가 발생합니다:
+
+1. **번역 결과가 메인 대화 컨텍스트의 영향을 받음**: 번역 요청의 시스템 프롬프트는 "당신은 번역가입니다"이지만, 서버 컨텍스트에는 여전히 Claude Code의 대화 기록이 포함되어 있어 모델에 간섭할 수 있습니다
+2. **메인 대화가 번역 요청에 의해 교란됨**: 번역 요청 내용(UI 텍스트 조각)이 메인 대화 컨텍스트에 주입되어 Claude Code의 응답이 벗어날 수 있습니다
+3. **예측 불가능한 동작**: 컨텍스트 오염은 서버 측 동작이므로 클라이언트에서 감지하거나 제어할 수 없습니다
+
+## 교훈
+
+- **OAuth 세션 토큰은 "단순한 또 다른 API 키"가 아닙니다** — 서버 측 상태를 가지고 있으며, 재사용은 컨텍스트 공유를 의미합니다
+- **내부 서비스 호출은 독립적이고 무상태인 인증을 사용해야** 하며, 사용자 세션과의 연관을 피해야 합니다
+
+## 참고 자료
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)