课程大纲
课程大纲系列主页
学习进度已完成 0/7
01主循环与 8 个核心工具：Claude Code 的内部底盘

主循环与 8 个核心工具：Claude Code 的内部底盘

进阶进行中

主循环与 8 个核心工具：Claude Code 的内部底盘

本文基于 Florian BRUNIAUX 的英文原版改编，原文地址：https://cc.bruniaux.com/guide/architecture 许可：CC BY-SA 4.0

这篇你能拿走什么

很多人用 Claude Code 用了几个月，仍然把它想成一个"复杂的多 agent 系统"——其实它的核心架构出乎意料地简单：一个 while 循环，加 8 个核心工具，全部由模型自己决策。本篇带你看清这个底盘，让你之后做工具选型、调试 token 成本、设计 hook 时有一张可信的地图。

前置条件

  • 已安装 Claude Code v2.1+ 并能在终端正常启动
  • 对"工具调用（tool use）"这个概念有基本认识

主循环：一个 while 就是全部

Claude Code 不是一个新模型，而是一个包裹 Claude（Opus / Sonnet / Haiku）的编排层。它做的事可以用 4 行伪代码概括：

python
while claude_response.has_tool_call:
    result = execute_tool(tool_call)
    claude_response = send_to_claude(result)
return claude_response.text

可信度：100%（Tier 1 - Anthropic Engineering Blog 官方）

也就是说，不存在以下这些组件：

  • 意图分类器
  • 任务路由器
  • RAG / embedding 管道
  • DAG 编排器
  • planner / executor 分离

模型自己决定什么时候调用工具、调用哪些工具、什么时候完成任务。这就是 Anthropic 工程博客所说的 "agentic loop" 模式。

为什么这么设计？

  1. 简单性 — 组件越少，失效模式越少。
  2. 模型驱动 — Claude 的推理比手写启发式规则更准。
  3. 灵活性 — 没有僵硬管道限制 Claude 能做什么。
  4. 可调试性 — 出错时只有一个地方需要看。

8 个核心工具

可信度：100%（Tier 1 - code.claude.com/docs 官方）

Claude Code 正好有 8 个核心工具，这就是它的全部基本武器库：

工具用途关键行为Token 成本
Bash执行 shell 命令通用适配器，最强大低（命令）+ 可变（输出）
Read读取文件最多 2000 行，会自动截断大文件成本高
Edit修改已有文件基于 diff，需要精确匹配中等
Write创建 / 覆盖文件文件已存在必须先 Read中等
Grep搜索文件内容基于 ripgrep（regex），取代 RAG低
Glob按模式查找文件路径匹配，按 mtime 排序低
Task生成子代理隔离上下文，depth=1高（新上下文）
TodoWrite跟踪进度结构化任务管理低

Bash 是瑞士军刀

关键洞察：Bash 是 Claude 的通用适配器。它可以运行任何 CLI（git、npm、docker、curl）、执行脚本、用管道串联命令、访问系统状态。模型在海量 shell 数据上接受过训练，所以当专门工具不够用时，它非常擅长把 Bash 当作通用适配器。

工具选择没有硬编码路由

Claude 根据任务自然映射到工具，规则不是显式写死的，而是训练出来的：

text
"Read auth.ts"          → Read
"Find all test files"   → Glob
"Search for TODO"       → Grep
"Run npm test"          → Bash
"Explore the codebase"  → Task（子代理）
"Track my progress"     → TodoWrite

搜索工具选择矩阵

Grep 不是唯一选择，但 90% 的情况下是最好的选择。其他选项的合理使用场景：

搜索需求原生工具MCP / 插件替代何时升级
精确文本Grep（ripgrep）—永不需要（最快）
函数名GrepSerena find_symbol多文件重构时
按语义—grepai search不知道精确文本时
调用图—grepai trace_callers依赖分析时
结构模式—ast-grep大规模迁移（>50k 行）
文件结构—Serena get_symbols_overview需要符号上下文时

性能对比：

工具速度设置使用场景
Grep（ripgrep）~20ms无90% 的搜索
Serena~100ms需要 MCP重构、符号
grepai~500ms需要 Ollama + MCP语义、调用图
ast-grep~200ms需要插件AST 模式、迁移

决策原则：从 Grep 开始（最快），只有真正需要时才升级到专门工具。先解决 90% 的问题，剩下 10% 再花精力。

11 项原生能力清单

可信度：100%（Tier 1）

很多人只用了一半。逐项检查你是否都用过：

  1. Event Hooks — 工具执行时触发的 Bash / PowerShell 脚本（PreToolUse / PostToolUse / UserPromptSubmit / Notification）
  2. Skill-Scoped Hooks — 针对 skill 执行上下文的事件 hook
  3. Background Agents — 异步任务执行（测试套件、长操作）
  4. Explore Subagent — /explore 进行只读代码库分析
  5. Plan Subagent — /plan 进入只读规划模式
  6. Task Tool — 把任务分层委派给专门的 agent，支持 depth=1 子代理
  7. Agent Teams — 多 agent 并行协作（v2.1.32+ 实验功能）
  8. Per-Task Model Selection — 会话中途切换模型 /model opus|sonnet|haiku
  9. MCP Protocol Integration — 用 Model Context Protocol 扩展工具
  10. Permission Modes — 工具执行的细粒度控制（默认 / auto-accept / plan / 自定义规则）
  11. Session Memory — 跨会话持久化 CLAUDE.md / memory 文件 / 项目状态

实战注解

我自己常踩的坑：明明用 Grep 就能搞定的搜索，被一个"语义"念头绑架去配 grepai。结果配了半小时 Ollama 才发现，原文里就有完全可匹配的字面量。从此我的判断规则是：写得出关键词就 Grep，写不出才考虑语义。

第二个常被忽视的能力是 Plan Subagent。它是只读的，对"还不确定改什么"的需求特别有用——先 /plan 让 Claude 自己探索、给出方案、再让你确认，比直接让它改代码安全得多。

可信度回顾

  • Tier 1（官方 100%）：主循环结构、8 个核心工具列表、11 项原生能力
  • Tier 2（70-90%）：本篇没有 Tier 2 内容
  • Tier 3（推断）：本篇没有 Tier 3 内容

这一篇基本都是 Anthropic 官方文档级的内容，可以直接当作信任基线。

常见问题

Q：Claude Code 不是 multi-agent 吗？为什么说没有 DAG？ A：multi-agent 指的是可以通过 Task 工具生成子代理（depth=1），但调度仍然由主模型在 while 循环里发起，不是预先定义的 DAG。

Q：8 个核心工具里没有 WebFetch / WebSearch，是不是漏了？ A：原文记的是"基本武器库"，Web 类工具属于扩展能力。WebFetch、WebSearch 实际上确实存在于 Claude Code 中，但它们的角色更接近 MCP / 插件层而非编排底盘。

Q：什么时候应该用 Task 子代理而不是直接搜索？ A：当探索可能产生大量上下文（>10K tokens）但你只关心结论时，用子代理隔离最划算。详见本系列「子代理篇」。

来源与许可

  • 原作者：Florian BRUNIAUX；Claude（Anthropic）参与贡献
  • 英文原版地址：https://cc.bruniaux.com/guide/architecture
  • 源文件：FlorianBruniaux/claude-code-ultimate-guide / guide/core/architecture.md
  • 本文基于 CC BY-SA 4.0 改编：保留署名、来源链接，衍生作品同样以 CC BY-SA 4.0 公开
  • 内容版本：原作 v1.1.0 / Claude Code v2.1.34（2026-02）
主循环与 8 个核心工具：Claude Code 的内部底盘 | 资讯狗 | Zixungou