Claude Code 深度解析

一、什么是 Claude Code

Claude Code 是 Anthropic 推出的 Agentic 编程工具，它不是一个简单的代码补全插件，而是一个能够理解整个代码库、自主执行多步骤任务的 AI Agent。它可以在终端、IDE、桌面应用、浏览器等多个平面上运行，通过自然语言指令帮助开发者完成从代码编写到 Git 工作流的全流程任务。

与传统的 Copilot 类工具相比，Claude Code 的核心区别在于其 Agentic 架构：它不仅能生成代码片段，还能主动读取文件、执行命令、搜索代码库、创建 Pull Request —— 一切通过一个统一的工具调用循环实现。

Claude Code 的核心能力可以概括为以下几个维度：

二、整体架构

2.1 架构总览

Claude Code 的整体架构可以分为五个核心层次：

整个系统的核心运行循环非常清晰：

1. 用户输入：通过任一 Surface（终端、IDE、桌面、Web）接收自然语言指令
2. Prompt 构建：将用户指令、系统提示词、CLAUDE.md 配置、工具描述、对话历史组装为完整 Prompt
3. 模型推理：调用 Claude API，流式接收模型输出
4. 工具调用：如果模型输出包含工具调用，经过权限检查后执行对应工具
5. 结果回注：将工具执行结果注入对话历史，返回步骤 2 继续推理
6. 输出展示：将最终文本结果展示给用户

2.2 多平台统一引擎

Claude Code 的一个关键设计决策是统一引擎 —— 所有平台共享同一个 Agentic 运行时核心。这意味着无论你在终端还是 VS Code 中使用 Claude Code，底层的工具系统、权限模型、记忆机制完全一致。

// SDK 的核心抽象 —— 统一的会话接口
interface ClaudeCodeSession {
  // 会话生命周期
  start(options: SessionOptions): AsyncIterator<Message>;
  resume(sessionId: string): AsyncIterator<Message>;

  // 工具能力 —— 所有平台共享
  tools: ToolRuntime;

  // 权限控制 —— 统一的权限模型
  permissions: PermissionManager;

  // 记忆系统 —— 跨平台持久化
  memory: MemorySystem;
}

各平台的差异仅体现在 UI 层：

• Terminal CLI：全功能命令行界面，支持管道操作和脚本集成
• VS Code：内联 Diff 预览、@-mention 文件选择、对话历史面板
• JetBrains：与 IntelliJ/PyCharm/WebStorm 深度集成，支持 Diff 审查
• Desktop App：原生 macOS/Windows 应用，支持多标签会话和定时任务
• Web (claude.ai/code)：浏览器端零配置，支持长时运行任务

三、CLI 核心引擎

3.1 会话循环

Claude Code 的 CLI 是最完整的交互入口。它的核心是一个 REPL（Read-Eval-Print Loop），但与传统 REPL 不同，这里的 "Eval" 是一个完整的 Agentic 推理循环。

// 简化的会话循环伪代码
async function sessionLoop() {
  while (true) {
    const userInput = await readUserInput();

    // 触发 UserPromptSubmit hooks
    const hookResult = await runHooks('UserPromptSubmit', userInput);
    if (hookResult.blocked) continue;

    // Agentic 工具循环
    let messages = buildMessages(userInput);
    while (true) {
      const response = await callClaudeAPI(messages);

      // 检查是否有工具调用
      const toolCalls = extractToolCalls(response);
      if (toolCalls.length === 0) break;  // 纯文本回复，循环结束

      // 并行执行独立的工具调用
      const results = await executeTools(toolCalls);
      messages.push(...results);
      // 继续循环，将结果交给模型继续推理
    }

    // 触发 Stop hooks
    await runHooks('Stop', response);
  }
}

关键的设计点在于工具调用的并行化。Claude Code 会分析模型返回的多个工具调用之间是否存在依赖关系，独立的调用会并行执行，依赖的调用按序执行。这在处理大型重构任务时显著提升效率。

3.2 流式输出

Claude Code 采用流式输出架构，模型生成的每个 token 都会实时推送到用户界面。这不仅提供了更好的用户体验（用户可以在模型思考过程中就看到输出），还允许用户在任意时刻中断生成。

// SDK 中的流式消息处理
for await (const message of session.start({
  prompt: userInput,
  permissionMode: 'default',
})) {
  switch (message.type) {
    case 'assistant':
      // 模型的文本输出
      renderText(message.content);
      break;
    case 'tool_use':
      // 工具调用请求
      showToolCallSpinner(message.tool, message.input);
      break;
    case 'tool_result':
      // 工具执行结果
      renderToolResult(message.content);
      break;
    case 'system':
      // 系统事件（权限请求、错误等）
      handleSystemEvent(message);
      break;
  }
}

流式架构还支持 Thinking 模式 —— 模型的内部推理过程可以实时展示，帮助用户理解 AI 的决策路径。

四、工具系统

工具系统是 Claude Code 的核心能力基座。模型通过工具调用与外部世界交互 —— 读写文件、执行命令、搜索代码、访问网络。

4.1 内置工具

Claude Code 内置了超过 20 种工具，覆盖软件开发的完整流程：

Edit 工具的设计特别值得关注。它采用精确字符串匹配 + 替换的方式进行文件修改，而不是生成整个文件内容。这有两个关键优势：

1. 最小化 token 消耗：只需要发送变更的部分，而不是整个文件
2. 精确可控：每次修改都是原子性的，失败时可以精确定位问题

// Edit 工具的调用接口
{
  "tool": "Edit",
  "input": {
    "file_path": "/src/server.ts",
    "old_string": "const port = 3000;",
    "new_string": "const port = process.env.PORT || 3000;",
    "replace_all": false
  }
}

4.2 MCP 工具扩展

Model Context Protocol (MCP) 是 Claude Code 的工具扩展标准。通过 MCP，你可以将任何外部服务接入 Claude Code 的工具系统。

// .claude/settings.json 中的 MCP 配置
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "database": {
      "type": "http",
      "url": "https://mcp.example.com/db",
      "headers": { "Authorization": "Bearer ${DB_TOKEN}" }
    }
  }
}

MCP 工具在 Claude Code 内部被命名为 mcp__<server>__<tool>。例如，GitHub MCP 服务器提供的 PR 创建工具会被识别为 mcp__github__create_pull_request。

MCP 支持两种传输协议：

• Stdio：启动子进程，通过 stdin/stdout 进行 JSON-RPC 通信，适合本地工具
• HTTP：通过 HTTP POST 请求通信，支持 OAuth 认证，适合远程服务

为了避免大量 MCP 工具占用上下文窗口，Claude Code 引入了 Tool Search（延迟加载）机制。启用后，MCP 工具不会在会话启动时全部加载，而是通过 ToolSearch 工具按需发现和加载。

五、AI 集成层

5.1 Prompt 构建

Claude Code 的 System Prompt 是一个复杂的动态组装过程。最终的 Prompt 由多个来源叠加而成：

这种分层组装的设计允许在不同粒度上定制 Claude Code 的行为：团队通过 .claude/CLAUDE.md 共享编码规范，个人通过 ~/.claude/CLAUDE.md 设置偏好，而组织通过 Managed Settings 强制执行安全策略。

5.2 上下文管理

上下文窗口是 LLM 应用的核心瓶颈。Claude Code 通过几个关键机制管理上下文：

自动压缩（Auto-Compaction）：当对话历史接近上下文窗口限制时，系统自动触发压缩。压缩过程会保留关键信息（任务目标、重要发现、Skills 状态），同时丢弃冗余的中间步骤。

// 压缩时的优先级保留策略
const compactionPriority = [
  'system_prompt',       // 始终保留
  'active_skills',       // Skills 内容（每个 5K tokens 上限）
  'recent_tool_results', // 最近的工具结果
  'task_state',          // 任务列表状态
  'user_messages',       // 用户消息（摘要化）
  'assistant_messages',  // AI 回复（摘要化）
  'old_tool_results',    // 早期工具结果（最先被丢弃）
];

Prompt 缓存：Claude API 支持 Prompt 缓存，具有 5 分钟 TTL。Claude Code 利用这一特性，通过保持 System Prompt 前缀的稳定性来最大化缓存命中率。这就是为什么 SDK 提供了 exclude_dynamic_sections 选项 —— 将动态内容（CWD、Git 状态）从 System Prompt 移到第一条用户消息，使 System Prompt 可跨用户共享缓存。

六、Hooks 系统

Hooks 是 Claude Code 最强大的扩展机制之一。它允许在 AI 执行流程的关键节点注入自定义逻辑 —— 从简单的命令验证到复杂的审批工作流。

6.1 生命周期层级

Hooks 事件分为三个生命周期层级：

6.2 处理器类型

Hooks 支持五种处理器类型，覆盖从简单脚本到复杂 AI 审查的场景：

1. Command Hook（Shell 脚本）

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "type": "command",
      "command": "python3 /scripts/validate_bash.py"
    }]
  }
}

Shell 脚本通过 stdin 接收 JSON 格式的工具调用参数，通过 stdout 返回决策结果（allow/deny/ask），通过退出码表示成功（0）或阻塞错误（2）。

2. MCP Tool Hook —— 直接调用已连接的 MCP 工具：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "type": "mcp_tool",
      "server": "audit-logger",
      "tool": "log_action",
      "input": {
        "action": "bash_executed",
        "command": "${tool_input.command}"
      }
    }]
  }
}

3. Agent Hook —— 将 Hook 决策委托给一个 AI 子 Agent：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "type": "agent",
      "prompt": "Review the proposed file change. Check for: security vulnerabilities, breaking API changes, and test coverage. Return ALLOW if safe, DENY with reason if not."
    }]
  }
}

Hooks 的配置优先级遵循与 Settings 相同的层级：Managed Policy > Plugin Hooks > Project Settings > Local Settings > Skill Hooks > User Settings。

七、记忆系统

Claude Code 的记忆系统采用双轨架构：人类编写的 CLAUDE.md 和 AI 自动学习的 Auto Memory。这种设计平衡了精确控制和自动化学习的需求。

7.1 CLAUDE.md 机制

CLAUDE.md 是 Claude Code 的配置即指令系统。它们是 Markdown 文件，在会话启动时被加载到 System Prompt 中，直接影响模型的行为。

CLAUDE.md 的加载遵循严格的层级和顺序：

路径特定规则是一个精巧的设计。通过 .claude/rules/ 目录下的文件，你可以为特定路径的文件设置专门的规则：

---
paths:
  - "src/api/**/*.ts"
  - "src/middleware/**/*.ts"
---

# API 代码规范

- 所有 API handler 必须使用 try-catch 包裹
- 错误响应必须包含 request_id
- 禁止在 handler 中直接操作数据库，必须通过 service 层

这些规则只在 Claude Code 操作匹配路径的文件时才会加载到上下文中，有效节省了上下文窗口空间。

7.2 自动记忆

Auto Memory 是 Claude Code 的自主学习系统。它存储在 ~/.claude/projects/<project>/memory/ 目录中，入口文件为 MEMORY.md（前 200 行或 25KB 在会话启动时加载）。

自动记忆的内容由 Claude Code 自主决定，但遵循明确的分类体系：

• user：用户角色、偏好、技术背景
• feedback：用户对 Claude Code 行为的纠正和确认
• project：项目的目标、截止日期、技术决策
• reference：外部资源的指针（Jira 项目、Grafana 面板等）

每条记忆存储为独立的 Markdown 文件，带有 YAML frontmatter：

---
name: testing-preference
description: 用户偏好集成测试而非 mock 测试
type: feedback
---

集成测试必须连接真实数据库，不使用 mock。
**Why:** 上季度 mock 测试通过但生产迁移失败的事故。
**How to apply:** 编写测试时默认使用测试数据库连接。

八、Skills 引擎

Skills 是 Claude Code 的可复用工作流封装。与 Hooks 不同，Skills 不拦截执行流程，而是注入额外的能力和知识。

8.1 定义与配置

每个 Skill 是一个目录，包含一个 SKILL.md 文件：

---
name: deploy
description: 执行生产环境部署流程
when_to_use: 当用户要求部署代码到生产环境时
argument-hint: <环境名称>
allowed-tools:
  - Bash(npm run deploy:*)
  - Bash(git push *)
model: opus
effort: high
---

# 部署流程

1. 运行 `npm run test` 确保所有测试通过
2. 运行 `npm run build` 构建生产包
3. 检查 Git 状态，确保没有未提交的更改
4. 执行 `npm run deploy:$ARGUMENTS`
5. 验证部署状态

Skills 的生命周期管理是精心设计的：

• 描述始终在上下文中：模型随时知道有哪些 Skills 可用
• 内容按需加载：只在被调用时才注入完整内容
• 会话期间持续生效：一旦激活，Skill 内容在整个会话中保持
• 压缩保护：每个 Skill 在上下文压缩时保留 5K tokens，所有 Skills 共享 25K tokens 上限

8.2 高级模式

动态上下文注入：Skills 支持在内容中内嵌 shell 命令，在加载时自动执行并将输出注入上下文：

---
name: pr-review
description: 审查当前 PR 的变更
---

# PR 审查

当前分支的变更摘要：
!`git diff main...HEAD --stat`

最近的提交历史：
!`git log main..HEAD --oneline`

请基于以上变更进行代码审查。

!`command` 语法在 Skill 加载时执行命令，将输出替换到 Skill 内容中。这使得 Skill 可以包含实时的项目状态信息。

子 Agent 模式：通过 context: fork，Skill 可以在独立的子 Agent 中运行，避免污染主会话的上下文：

---
name: codebase-audit
description: 对代码库进行全面安全审计
context: fork
agent: Explore
---

对整个代码库进行安全审计，检查：
1. 硬编码的密钥和凭证
2. SQL 注入风险
3. XSS 漏洞
4. 不安全的依赖

九、Agent 编排

9.1 子 Agent 系统

Claude Code 的子 Agent（Subagent）是其处理复杂任务的核心机制。每个子 Agent 拥有独立的上下文窗口、工具权限和系统提示词，完成任务后只将摘要结果返回给主 Agent。

// Agent 工具的调用结构
{
  "tool": "Agent",
  "input": {
    "description": "搜索认证相关代码",
    "prompt": "在代码库中搜索所有与用户认证相关的代码...",
    "subagent_type": "Explore",
    "run_in_background": true
  }
}

内置的 Agent 类型针对不同场景优化：

• Explore：只读探索型，拥有 Glob/Grep/Read 但没有 Edit/Write/Bash
• Plan：规划型，可以搜索和阅读代码，但不能修改
• general-purpose：通用型，拥有完整工具集

子 Agent 的关键设计原则：

1. 上下文隔离：子 Agent 的探索过程不会膨胀主 Agent 的上下文
2. 并行执行：多个独立的子 Agent 可以同时运行（run_in_background: true）
3. 结果浓缩：子 Agent 返回的只是任务摘要，而非完整的探索轨迹
4. 权限继承：子 Agent 的权限不能超过父 Agent

9.2 Agent Teams

Agent Teams 是更高级的多 Agent 编排模式（实验性功能）。与子 Agent 的 "派遣-返回" 模式不同，Team 中的 Agent 可以相互通信。

// Team 创建示例
{
  "tool": "TeamCreate",
  "input": {
    "teammates": [
      {
        "name": "frontend-dev",
        "description": "负责前端 React 组件开发",
        "tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
      },
      {
        "name": "backend-dev",
        "description": "负责后端 API 开发",
        "tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
      },
      {
        "name": "reviewer",
        "description": "负责代码审查和测试",
        "tools": ["Read", "Glob", "Grep", "Bash"]
      }
    ]
  }
}

Coordinator Agent（主 Agent）可以通过 SendMessage 向 Team 成员分配任务，成员之间也可以互相通信。这种模式特别适合大型重构、跨模块开发等需要多角色协作的场景。

十、安全模型

10.1 权限模式

Claude Code 提供六种权限模式，从最严格到最宽松：

即使在最宽松的 bypassPermissions 模式下，以下目录仍然受到保护：

• .git、.claude、.vscode、.idea、.husky —— 配置目录
• 例外：.claude/commands、.claude/agents、.claude/skills 可以自由写入

10.2 规则系统

权限规则支持灵活的匹配语法：

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Edit(/src/**)",
      "Write(/src/**)",
      "mcp__github__*",
      "WebFetch(domain:docs.anthropic.com)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(* --force *)",
      "Edit(/node_modules/**)",
      "Write(.env*)"
    ]
  }
}

规则匹配的关键特性：

• 复合命令分解：Bash(npm test && npm run build) 会被分解为两个独立命令，每个都需要独立匹配
• 进程包装器剥离：timeout、nice、nohup、stdbuf 等前缀会被自动剥离
• 符号链接保护：Allow 规则要求符号链接和目标都匹配，Deny 规则只要任一匹配就拒绝
• 只读命令识别：内置识别 ls、cat、grep、find 等只读命令，减少不必要的权限提示

十一、Git 工作流

Claude Code 深度集成了 Git 工作流，覆盖从分支创建到 Pull Request 提交的完整流程。

Git 操作的核心设计原则是 "安全优先"：

• 默认创建新提交而非 amend 已有提交
• 永远不跳过 Git hooks（--no-verify）
• 永远不执行 force push 到 main/master
• 使用具体的文件名进行 git add，避免意外提交敏感文件
• 破坏性操作（git reset --hard、git checkout .）需要用户明确确认

自动化 Git 工作流的典型流程：

# Claude Code 执行的标准 commit 流程
# 1. 检查状态
git status
git diff --staged --diff-stat

# 2. 查看提交风格
git log --oneline -10

# 3. 暂存文件（使用具体路径）
git add src/auth.ts src/middleware/validate.ts tests/auth.test.ts

# 4. 创建提交（通过 HEREDOC 保证格式）
git commit -m "$(cat <<'EOF'
fix: resolve token refresh race in concurrent sessions

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF
)"

Claude Code 还支持通过 gh CLI 自动创建 Pull Request，包括自动生成标题、描述、测试计划和变更摘要。

Worktree 隔离是处理并行任务的高级功能。通过 EnterWorktree 工具，Claude Code 可以创建 Git worktree，在不影响当前工作目录的情况下在独立分支上工作：

// Worktree 的典型使用场景
// 1. 主 Agent 在 feature-branch 上工作
// 2. 生成子 Agent，在独立 worktree 中修复一个 bug
{
  "tool": "Agent",
  "input": {
    "description": "修复 auth bug",
    "prompt": "修复 #123 报告的认证 bug...",
    "isolation": "worktree"
  }
}
// 子 Agent 在 .claude/worktrees// 中工作
// 完成后 worktree 自动清理或保留

十二、性能优化

12.1 Prompt 缓存

Prompt 缓存是 Claude Code 性能优化的关键。Claude API 的 Prompt 缓存有 5 分钟 TTL，缓存命中可以显著降低延迟和成本。

Claude Code 的缓存优化策略：

1. System Prompt 前缀稳定性：保持 System Prompt 的前缀部分（核心指令 + CLAUDE.md）尽可能不变，动态内容放在后面
2. 工具描述排序稳定性：工具 schema 的顺序保持固定，避免不必要的缓存失效
3. 跨用户共享：SDK 的 exclude_dynamic_sections 将用户特定内容移出 System Prompt，实现跨用户缓存共享

在定时任务和 /loop 模式中，缓存的影响更加显著。Claude Code 的 ScheduleWakeup 机制会考虑缓存 TTL 来选择唤醒时间：

• 60-270 秒：缓存保持温热，适合活跃工作（等待构建、轮询状态）
• 300 秒以上：缓存失效，承受一次 cache miss，适合长等待
• 避免 300 秒：刚好错过缓存，是最差的选择

12.2 上下文压缩

随着对话深入，上下文窗口会逐渐被填满。Claude Code 通过自动压缩机制解决这个问题：

• 当上下文接近窗口限制（Opus 4.7 为 1M tokens）时自动触发
• 压缩过程将历史消息摘要化，保留任务目标和关键发现
• 活跃 Skills 的内容被特殊保护（每个 5K tokens，总共 25K tokens）
• 任务列表、记忆索引等结构化数据被完整保留

Claude Code 还在基础设施层面进行了优化：

• 内存管理：修复了处理大量图片时的无限内存增长问题（v2.1.121）
• 文件描述符：优化了 Bash 工具在大目录树上的 FD 使用，避免系统级崩溃
• 会话恢复：大会话的 --resume 速度提升 67%（v2.1.116）
• 并发 MCP：多个 MCP 服务器并行连接而非串行（v2.1.117）

十三、总结与思考

Claude Code 代表了 AI 编程工具从 "代码补全" 到 "Agentic 编程助手" 的范式转变。它的设计回答了几个关键问题：

• 如何赋予 AI 足够的能力？ —— 工具系统 + MCP 扩展，让 AI 可以读写文件、执行命令、搜索代码、访问外部服务
• 如何保持人类控制权？ —— 六种权限模式 + 细粒度规则 + Hooks 拦截器 + Managed Settings
• 如何管理有限的上下文窗口？ —— 子 Agent 隔离 + 自动压缩 + Prompt 缓存 + Skills 按需加载
• 如何让 AI 记住经验？ —— CLAUDE.md 的分层配置 + Auto Memory 的自动学习
• 如何扩展而不破坏稳定性？ —— Skills 的沙箱化 + MCP 的标准协议 + Hooks 的生命周期管理

从架构角度来看，Claude Code 最值得学习的设计决策包括：

1. 统一引擎 + 多平台 Surface：避免了能力分裂，确保所有平台的一致体验
2. Edit 工具的最小 Diff 设计：用字符串匹配替换而非整文件重写，精确且 token 高效
3. 子 Agent 的上下文隔离：通过独立上下文窗口解决探索任务的上下文膨胀问题
4. Hooks 的分层拦截：在不修改核心逻辑的情况下注入企业级安全策略和自定义工作流
5. 缓存感知的调度策略：ScheduleWakeup 根据 Prompt 缓存 TTL 选择唤醒时间