第01章｜登台远望：Claude Code 底层技术全景导览

第01章｜登台远望：Claude Code 底层技术全景导览

学习目标：理解 Claude Code 的整体架构、核心组件及其工作原理，建立全局视野。

1.1 Claude Code 是什么？

Claude Code 是 Anthropic 官方推出的AI 编程助手 CLI 工具，它不是一个简单的代码补全插件，而是一个完整的AI Agent 系统。

传统 AI 编程工具 vs Claude Code

一句话定义

Claude Code =大语言模型+工具系统+Agent 循环+记忆系统+多智能体协作

1.2 核心架构：五层模型

Claude Code 的架构可以分为五个层次，从上到下依次是：

┌─────────────────────────────────────────────────────┐ │ 入口层 (Entry Layer) │ │ CLI 命令行界面 / VS Code 扩展 │ ├─────────────────────────────────────────────────────┤ │ 编排层 (Orchestration Layer) │ │ 命令系统(Commands) + 技能系统(Skills) │ ├─────────────────────────────────────────────────────┤ │ 查询引擎层 (Query Engine Layer) │ │ Agent Loop 核心循环 + 流式处理 │ ├─────────────────────────────────────────────────────┤ │ 工具层 (Tool Layer) │ │ 文件读写 | Bash执行 | 网络请求 | Agent派生 │ ├─────────────────────────────────────────────────────┤ │ 服务层 (Service Layer) │ │ Anthropic API | MCP服务 | Hooks | 记忆系统 │ └─────────────────────────────────────────────────────┘

各层职责详解

🔵 入口层

用户与 Claude Code 交互的界面，支持：

• 终端 CLI：claude命令直接启动
• VS Code 扩展：编辑器内嵌集成
• JetBrains 插件：IDE 集成
• Headless 模式：claude -p "任务描述"无交互执行

🟢 编排层

负责解析用户意图，分发到对应的执行单元：

• Commands（命令系统）：内置命令如/help、/compact，以及自定义斜杠命令
• Skills（技能系统）：可复用的工作流包，通过 SKILL.md 定义

🟡 查询引擎层（核心）

这是 Claude Code 的"大脑"，实现了Agent Loop（代理循环）：

用户输入 ↓ 预处理（注入上下文、记忆、规则） ↓ 调用 Claude API（claude-opus / claude-sonnet） ↓ 解析响应（文本 or 工具调用） ↓ 执行工具（如果有工具调用） ↓ 将工具结果反馈给模型 ↓ 重复直到任务完成 ↓ 输出最终结果

🟠 工具层

Claude Code 内置了约 40+ 个工具，核心工具包括：

🔴 服务层

底层基础设施：

• Anthropic API：模型推理服务
• MCP（Model Context Protocol）：外部工具扩展协议
• Hooks：生命周期事件系统
• 记忆系统：CLAUDE.md + 会话历史

1.3 Agent Loop 深度解析

Agent Loop 是 Claude Code 最核心的机制，理解它是理解一切的基础。

工作流程图

┌──────────────────────────────────────────────────┐ │ Agent Loop │ │ │ │ ① 接收用户消息 │ │ ↓ │ │ ② 构建完整 Prompt │ │ - System Prompt（规则+记忆+技能） │ │ - 历史对话 │ │ - 当前用户消息 │ │ ↓ │ │ ③ 调用 Claude API（流式） │ │ ↓ │ │ ④ 解析响应 │ │ ├── 纯文本 → 直接输出给用户 │ │ └── 工具调用 → 执行工具 │ │ ↓ │ │ ⑤ 执行工具并获取结果 │ │ ↓ │ │ ⑥ 将工具结果追加到对话历史 │ │ ↓ │ │ ⑦ 回到步骤③，继续循环 │ │ ↓ │ │ ⑧ 模型输出最终文本（无工具调用）→ 结束 │ └──────────────────────────────────────────────────┘

实际案例：让 Claude Code 修复一个 Bug

用户输入：

帮我修复 src/auth.py 中的登录验证 bug，用户输入空密码时会崩溃

Agent Loop 执行过程：

第1轮： 模型思考 → 决定先读取文件 工具调用：Read("src/auth.py") 工具返回：文件内容（含 bug 代码） 第2轮： 模型分析代码 → 找到 bug（未判断空密码） 工具调用：Edit("src/auth.py", old_code, new_code) 工具返回：编辑成功 第3轮： 模型决定验证修复 工具调用：Bash("python -m pytest tests/test_auth.py") 工具返回：测试通过 第4轮： 模型输出最终文本："已修复 auth.py 中的空密码崩溃问题..." 循环结束

1.4 上下文窗口与 Token 管理

什么是上下文窗口？

Claude Code 使用的模型有固定的上下文窗口（Context Window），即模型一次能"看到"的最大 Token 数量。

上下文窗口 = System Prompt + 对话历史 + 工具结果 + 当前输入

Claude 3.5 Sonnet / Claude 3 Opus 的上下文窗口约为200K tokens（约15万汉字）。

Token 消耗来源

┌─────────────────────────────────────┐ │ 上下文窗口 200K │ ├──────────────┬──────────────────────┤ │ System Prompt│ ~5K（规则+记忆+技能）│ ├──────────────┼──────────────────────┤ │ 对话历史 │ 随对话增长 │ ├──────────────┼──────────────────────┤ │ 工具结果 │ 文件内容+命令输出 │ ├──────────────┼──────────────────────┤ │ 当前输入 │ 用户消息 │ └──────────────┴──────────────────────┘

自动压缩机制

当上下文接近上限时，Claude Code 会自动触发Compaction（压缩）：

• 将早期对话历史总结为摘要
• 保留关键信息，丢弃冗余细节
• 用/compact命令可手动触发

1.5 Prompt Caching（提示词缓存）

原理

Anthropic API 支持对 System Prompt 进行缓存，相同的 System Prompt 在多次请求中只计算一次，后续请求直接复用缓存。

第1次请求： System Prompt（5K tokens）→ 全量计算 → 缓存 用户消息（100 tokens）→ 计算 第2次请求： System Prompt（5K tokens）→ 命中缓存，费用降低90% 用户消息（100 tokens）→ 计算

对工程化的意义

• 降低成本：长 System Prompt 的重复计算费用大幅降低
• 提升速度：缓存命中时响应更快
• 鼓励丰富配置：可以在 CLAUDE.md 中写更详细的规则，不用担心成本

1.6 权限模型

Claude Code 有严格的权限控制，防止 AI 做出危险操作。

权限级别

危险操作分类

高风险（默认需要确认）： - 删除文件 - 执行 rm -rf 类命令 - 修改系统配置 - 网络请求到外部服务 低风险（自动执行）： - 读取文件 - 运行测试 - 格式化代码 - 查看目录结构

实际配置示例

# 以规划模式启动（只分析，不执行任何操作）claude--plan# 以自动模式启动（低风险操作自动执行）claude--auto# Headless 模式 + 自动确认（CI/CD 场景）claude-p"运行所有测试并修复失败的用例"--auto

1.7 技术栈全景

Claude Code 本身的实现技术栈：

1.8 版本演进

1.9 本章小结

🧪 动手练习

1. 安装 Claude Code：

   npminstall-g@anthropic-ai/claude-code claude--version

2. 查看内置工具列表：

   claude# 在交互界面输入：/tools

3. 体验 Agent Loop：

   # 创建一个测试文件echo"def add(a, b): return a - b # bug: 应该是 +">test_math.py# 让 Claude Code 找到并修复 bugclaude-p"读取 test_math.py，找到其中的 bug 并修复它"

4. 观察 Token 使用：

   # 开启详细模式，观察每次请求的 token 消耗claude--verbose

⬅️ 上一章：无
➡️ 下一章：第02章 - 记忆系统与 CLAUDE.md