Claude Code 架构剖析：Anthropic终端Agent的设计哲学

引言

2025年，Anthropic 发布了 Claude Code——一个直接运行在终端中的 AI 编程助手。与传统的 IDE 插件或 Web 聊天界面不同，Claude Code 以 CLI 的形式深度嵌入开发者的日常工作流，标志着 AI Agent 从”对话式辅助”向”自主编程”的关键跨越。

Claude Code 不仅仅是一个”能写代码的聊天机器人”，而是一个完整的终端 Agent 系统，融合了模型上下文管理、工具编排、安全沙箱、跨进程通信等多层架构设计。本文将从底层架构出发，系统剖析 Claude Code 的设计哲学与实现技术。

整体架构概览

Claude Code 的架构可以概括为三层四模块的层次化设计：

┌─────────────────────────────────────────────────────┐
│                  用户交互层                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │  终端CLI     │  │  ACP客户端   │  │  MCP客户端  │ │
│  │ (REPL模式)   │  │ (Agent间通信)│  │ (工具扩展)  │ │
│  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘ │
├─────────┼─────────────────┼─────────────────┼────────┤
│         │     Agent核心层  │                 │        │
│  ┌──────┴──────────────────┴─────────────────┴──────┐│
│  │              编排引擎（Orchestrator）              ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  ││
│  │  │ 推理循环  │ │ 上下文管理 │ │  工具调度器     │  ││
│  │  │(Think→Act)│ │(Token优化)│ │(Tool Router)    │  ││
│  │  └────┬─────┘ └────┬─────┘ └────────┬─────────┘  ││
│  │       └────────────┼────────────────┘             ││
│  │              ┌─────┴──────┐                       ││
│  │              │ 安全审计层  │                       ││
│  │              │(PBC / ACL) │                       ││
│  │              └────────────┘                       ││
│  └───────────────────────────────────────────────────┘│
├───────────────────────────────────────────────────────┤
│                   工具执行层                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ 文件系统  │ │ Shell执行 │ │  Git操作 │ │  网络请求 │ │
│  │ (Read/Edit)│ │ (Sandbox) │ │(Commit/PR)│ │ (HTTP)  │ │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└───────────────────────────────────────────────────────┘

三层架构说明

用户交互层：负责与用户进行交互，包括终端 REPL、ACP 跨 Agent 通信、MCP 工具扩展三种模式
Agent核心层：编排引擎驱动推理→行动循环，管理上下文窗口，调度工具调用，执行安全检查
工具执行层：具体执行文件操作、Shell 命令、Git 操作等底层工具

Claude 模型集成方式

模型选择策略

Claude Code 支持多个 Claude 模型，核心选择策略如下：

模型	适用场景	特点
claude-sonnet-4	日常开发（推荐）	速度快、性价比高、适合绝大多数编程任务
claude-opus-4	复杂推理	更强的分析和推理能力，适合架构设计和调试
claude-haiku	快速预览	轻量级，适合简单查询

Claude Code 的默认模型是 Sonnet，这一选择背后有深刻的工程考量：编程任务中超过 80% 的操作是文件读写、代码补全、简单的重构，Sonnet 在延迟和质量之间取得了最佳平衡。

模型切换机制

用户可以通过 --model 参数或在配置文件中切换模型：

# 使用 Sonnet（默认）
claude

# 切换到 Opus 处理复杂任务
claude --model claude-opus-4

# 使用轻量模型做快速预览
claude --model claude-haiku

底层 API 集成

Claude Code 使用 Anthropic 的 Messages API，通过 streaming 模式实现实时响应。关键特性：

流式输出：模型输出 token 实时推送到终端，用户能看到思考过程
Tool Use（工具调用）：原生支持 Function Calling 风格的 tool use API，模型可以请求调用工具
Extended Thinking：Opus 模型支持 extended thinking 模式，在复杂推理任务中提供更深入的思考链

工具系统设计

Claude Code 的工具系统是其核心能力的基础。每个工具都是功能原子化的单一职责模块。

核心工具清单

Claude Code 内置了以下几类核心工具：

1. 文件操作工具

┌─────────────────────────────────────────────────┐
│              文件操作工具集                        │
├─────────────────────────────────────────────────┤
│  • Read（读取文件）                               │
│    - 按行读取，支持 offset/limit                  │
│    - 自动检测编码                                │
│  • Write（写入文件）                              │
│    - 完整覆盖写入                                │
│    - 自动格式化                                  │
│  • Edit（精确编辑）                              │
│    - 基于字符串匹配的编辑                         │
│    - 支持多行替换                                │
│  • GlobSearch（文件搜索）                        │
│    - 按文件名模式搜索                            │
│    - 支持递归遍历                                │
│  • GrepSearch（内容搜索）                        │
│    - 正则表达式全文搜索                          │
│    - 支持上下文行                               │
└─────────────────────────────────────────────────┘

这些工具的设计借鉴了 VS Code 和现代 IDE 的文件操作模式，但进行了 Agent 友好化改造——每个工具的输入输出都经过结构化设计，方便模型理解和调用。

2. Shell 执行工具

Shell 工具允许 Claude Code 在终端中执行命令：

# Claude Code 可以执行任意 shell 命令
npm run build
python test.py
docker compose up -d

关键安全机制：

命令审批：默认所有 shell 命令需要用户确认（可通过 --dangerously-skip-permissions 跳过）
超时控制：长时间运行的命令会被自动中断
输出截断：大量输出会被截断以防止上下文溢出

3. Git 操作工具

Claude Code 可以执行完整的 Git 工作流操作：

git diff / git show：查看变更
git commit：创建提交（自动生成提交信息）
git push：推送代码
git status / git log：查看状态和日志

值得注意的是，Claude Code 在 commit 时能自动分析变更内容，生成高质量的 commit message。

工具调用流程

用户请求 → 模型分析 → 选择工具 → 执行工具 → 结果返回 → 模型推理 → 下一轮
   │          │          │          │          │          │
   │          │          │          │          │          │
   └──────────┴──────────┴──────────┴──────────┴──────────┘
                    循环直到任务完成

每次工具调用的完整生命周期：

模型输出 tool_use：Claude 生成一个 tool_use 请求，包含工具名称和参数
编排引擎接收并验证：检查参数合法性、权限认证
工具调度器分发：将请求路由到具体的工具执行器
Sandbox 执行：在隔离环境中执行工具操作
结果返回：工具执行结果（stdout/stderr/返回值）作为 tool_result 送回模型
模型继续推理：基于结果决定下一步行动

ACP 协议：Agent 间通信

ACP（Agent Communication Protocol）是 Anthropic 提出的一种 Agent 间通信协议，允许不同的 AI Agent 相互协作。

ACP 的核心设计

ACP 在 Claude Code 中的实现遵循以下设计原则：

┌─────────────────┐         ACP 协议         ┌─────────────────┐
│  Claude Code A  │ ◄──────────────────────► │  Claude Code B  │
│  (主Agent)      │     Agent到Agent通信      │  (子Agent)      │
└─────────────────┘                          └─────────────────┘
        │                                            │
        │ 发送任务                                    │ 返回结果
        ▼                                            ▼
    ┌─────────────────────────────────────────────────────┐
    │                    ACP 信道                          │
    │  • 任务描述（自然语言）                               │
    │  • 上下文传递（文件、代码片段）                      │
    │  • 结果返回（结构化数据）                            │
    │  • 进度通知（事件驱动）                              │
    └─────────────────────────────────────────────────────┘

ACP 的工作模式

Claude Code 支持两种 ACP 运行模式：

1. 父子模式（Parent-Child）

主 Agent 将任务分解后分配给子 Agent，子 Agent 独立执行并返回结果。适合大型项目的模块化开发。

2. 对等模式（Peer-to-Peer）

多个 Agent 平等协作，各自负责不同领域，通过 ACP 交换中间结果。适合跨领域复杂任务。

使用 ACP 启动 Claude Code 子进程：

# 启动一个子 Agent 执行特定任务
claude --acp-mode child --parent-pipe /tmp/claude-acp-parent

# 或者在对等模式下连接
claude --acp-mode peer --channel acp://channel-name

MCP 集成：工具扩展生态

MCP（Model Context Protocol）是 Anthropic 推动的开放协议标准，Claude Code 是 MCP 的重要客户端之一。

MCP 在 Claude Code 中的角色

MCP 允许开发者扩展 Claude Code 的工具集。通过配置 MCP 服务器，可以为 Claude Code 增加数据库查询、API 调用、自定义工作流等能力。

┌───────────────────┐
│   Claude Code     │
│   (MCP Client)    │
└────────┬──────────┘
         │ MCP 协议（JSON-RPC over stdio/SSE）
         │
    ┌────┴────┬──────────┬──────────┐
    │         │          │          │
    ▼         ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ MCP    │ │ MCP    │ │ MCP    │ │ MCP    │
│ Server │ │ Server │ │ Server │ │ Server │
│ (文件)  │ │ (数据库)│ │ (API)  │ │ (自定义)│
└────────┘ └────────┘ └────────┘ └────────┘

MCP 服务器配置

在 ~/.claude/settings.json 中配置 MCP 服务器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "custom-db": {
      "command": "python",
      "args": ["path/to/mcp-server.py"]
    }
  }
}

MCP 集成使 Claude Code 从一个终端编程助手扩展为全功能的开发平台 Agent。

安全机制：PBC 与 ACL

Claude Code 设计了多层次安全机制，在 Agent 自主性和开发者控制权之间找到平衡。

PBC（Project-Based Configuration）

PBC 允许在项目级别配置 Claude Code 的行为：

// .claude/settings.json （项目级配置）
{
  "project": {
    "name": "my-app",
    "buildCommand": "npm run build",
    "testCommand": "npm test"
  },
  "permissions": {
    "allowCommands": ["npm", "node", "git", "docker"],
    "denyCommands": ["rm -rf", "curl"],
    "allowPaths": ["/home/user/projects/my-app"],
    "denyPaths": ["/home/user/projects/my-app/.env"]
  }
}

ACL（Access Control List）

ACL 提供细粒度的权限控制：

权限级别	说明	适用场景
allow-all	允许所有操作	个人开发环境
ask-first	每次操作前询问	默认设置，推荐生产环境
deny-all	禁止所有操作	沙箱/审核环境

ACL 支持按工具类型分别设置：

{
  "acl": {
    "read": "allow-all",
    "edit": "ask-first",
    "shell": "ask-first",
    "git": "ask-first",
    "network": "deny-all"
  }
}

安全审计日志

Claude Code 记录所有工具调用的审计日志：

[2026-05-09 10:23:45] TOOL: Read → src/app.ts (approved)
[2026-05-09 10:23:47] TOOL: Edit → src/app.ts:34-42 (approved)
[2026-05-09 10:23:50] TOOL: Shell → npm run build (approved)
[2026-05-09 10:24:01] TOOL: Shell → curl http://internal-api/ (⚠️ denied)

上下文管理策略

上下文管理是 Agent 系统最关键的工程挑战之一。Claude Code 采用了多级上下文管理策略。

上下文层级

┌──────────────────────────────────────────────┐
│           系统提示（System Prompt）            │
│  • 角色定义                                  │
│  • 工具使用指南                              │
│  • 行为约束                                  │
├──────────────────────────────────────────────┤
│            项目上下文（Project Context）       │
│  • 项目结构概述                              │
│  • 配置文件内容                              │
│  • 依赖声明                                  │
├──────────────────────────────────────────────┤
│            对话历史（Conversation History）    │
│  • 用户请求                                  │
│  • Agent响应                                │
│  • 工具调用记录                              │
├──────────────────────────────────────────────┤
│            当前焦点（Active Context）          │
│  • 当前文件内容                              │
│  • 最近的代码变更                            │
│  • 错误输出                                  │
└──────────────────────────────────────────────┘

Token 优化策略

滑动窗口：对话历史使用滑动窗口，丢弃最早的非关键消息
摘要压缩：长对话中，对早期内容进行摘要压缩
文件截断：读取大文件时只返回关键部分（头部的类型定义、函数签名等）
智能排序：相关内容优先保留，不相关内容优先丢弃

/compact 命令

当上下文接近上限时，用户可以使用 /compact 命令压缩上下文：

/compact
→ 正在压缩对话上下文...
→ 已从 52K tokens 压缩至 8K tokens
→ 保留了关键决策和文件变更记录

与普通 Agent 框架的区别

Claude Code 与 LangChain Agent、AutoGPT 等通用 Agent 框架有本质区别：

维度	Claude Code	通用 Agent 框架
使用方式	终端 CLI，零配置启动	需要编写代码构建
工具集	内置编程相关工具，开箱即用	需要手动注册工具
上下文管理	自动管理，支持 /compact	需开发者自行实现
安全机制	内置 PBC / ACL 层级控制	需额外集成
模型绑定	深度绑定 Claude 模型	模型无关，灵活切换
协议支持	原生支持 ACP / MCP	需额外适配
部署方式	npm 全局安装，本地运行	SDK 集成到应用中

核心差异在于：Claude Code 是面向终端编程场景的专用 Agent 产品，而通用框架是构建自定义 Agent 的开发工具。前者追求开箱即用的编程体验，后者提供灵活的自定义能力。

总结

Claude Code 的架构设计体现了 Anthropic 对”终端 AI 编程助手”这一场景的深刻理解：

三层架构：用户交互层、Agent 核心层、工具执行层，层次清晰职责分明
工具系统：功能原子化的工具集，配合安全审计机制，在自主性和可控性间取得平衡
协议生态：ACP 实现 Agent 间通信，MCP 实现工具扩展，构建开放生态
上下文管理：多级上下文策略配合滑动窗口和压缩机制，有效应对长任务
安全优先：PBC + ACL 多层安全模型，让开发者放心授权

与其他 Agent 框架不同，Claude Code 是一个面向终端编程的专用 Agent 产品——安装即用，安全可控，且通过 ACP 和 MCP 保持了良好的可扩展性。

本文最后更新于 2026-05-09