我和 Claude Code 一起写了一本介绍 Claude Code 原理的书

前言 · 从"帮我修个 bug"到生产级 Agent

打开 Claude Code，输入一句：

帮我看看这个 bug。

接下来发生的事情，看起来很自然：Claude 搜索代码、读取文件、修改实现、运行测试；遇到失败会调整方案，context 快满时会压缩历史，下一次打开项目时还可能记得之前留下的规则。

但只要把这个过程拆开，问题会立刻变多：

• 模型为什么知道有哪些工具可以使用？
• 用户只输入一次，Agent 为什么能连续工作很多轮？
• 每次调用模型时，200K context 里究竟装了什么？
• 对话关闭以后，哪些信息还能留到下一次 session？
• 一套反复用到的操作知识，怎样只在需要时才进入当前任务？
• 模型出厂时没有的一个动作，怎样在不改 Claude Code 本体代码的前提下变成一个新 Tool？
• 一件事拆成几份独立的活，怎样同时派给几个 Agent 去做，又不会互相踩到对方？

这七个问题，正好对应本书的七个部分：Tools、Agent Loop、Context、Memory、Skills、多 Agent 协作、MCP。

Claude Code 不只是一组 Tools

最初研究 Claude Code，很容易从 Read、Edit、Bash 等工具开始。它们是最容易看到的部分，也是很好的入口。

仔细阅读 Tool description 后，会发现里面充满了看似啰嗦的限制：

• Edit 要求修改前先读取文件。
• Read 给每一行加上固定格式的行号。
• Bash 对 Git 操作设置了大量安全提醒。
• WebFetch 会提醒模型优先检查已有的专用能力。

这些约束不是装饰。每一个字段、每一句 Prompt、每一道 runtime 拦截，都在解决模型曾经容易犯的某类错误。

工具的形状，本身就是一份工作方法论。

但研究继续深入后会发现：Tools 只回答"Agent 能做什么"，无法解释整个系统。

• 没有 Loop，工具只能被调用一次，无法形成自主任务。
• 没有 Context 管理，历史会持续膨胀，模型也不知道当前应该看到什么。
• 没有 Memory，session 结束后，重要信息就无法跨时间存活。
• 没有 Skill，同一套操作知识只能反复重新交代，无法沉淀成一项可复用的能力。
• 没有多 Agent 协作，一次只能有一个 Agent 在推进任务，独立的子任务也只能排成一条队，一个一个来。
• 没有 MCP，Claude 只能使用出厂时已经内置的工具，遇到模型本来就不存在的动作会无能为力。

因此，这本书最终形成了七条互相连接的研究线：

Tools       ------ Agent 有哪些能力
Loop        ------ 这些能力怎样连续运转
Context     ------ 每一次运转时，模型看见什么
Memory      ------ 时间跨过 session 后，哪些信息还能留下
Skill       ------ 可复用的操作知识怎样按需展开
多 Agent 协作 ------ 一件事怎样拆开，同时交给几个 Agent
MCP         ------ 模型怎样拿到一个出厂时不存在的新动作

七部分放在一起，才构成一个生产级 Agent 的完整形状。

第一部分 · Tools · 能力怎样被交给模型

第一部分从 Tool 协议开始，逐个拆解 Claude Code 的核心工具。

这里关注的不只是"这个工具有什么参数"，而是四层契约：

1. Schema 怎样把能力描述给模型。
2. Prompt 怎样引导模型选择正确的使用方式。
3. Runtime 怎样执行那些不能只靠模型自律保证的约束。
4. Tool Result 怎样把结果重新送回模型，影响下一步判断。

这一部分回答：怎样设计一个模型真正会用、而且不容易用错的工具。

第二部分 · Agent Loop · 一次输入怎样变成连续执行

普通聊天模型回答一次就结束；Agent 会在一次用户输入后持续调用模型和工具。

第二部分从 5 行 loop 伪代码出发，一路展开到：

• 工具声明与权限批准
• Hooks 与并行调度
• stop_reason 与状态转换
• Streaming 与逐字显示
• 重试、恢复和 Interrupt
• 主代理与 Sub-agent 复用同一套 Loop

这一部分回答："AI 自主推进任务"在工程上究竟怎样发生。

第三部分 · Context · 每次调用到底发送什么

LLM 本身没有会话状态。所谓"Claude 记得刚才说过什么"，其实是客户端在下一次调用时重新发送相关信息。

于是新的问题出现了：

• Tools、system prompt 和 messages 怎样共同占用 context window？
• 为什么 messages 数组有不能破坏的结构？
• Prompt Cache 为什么会反过来塑造整个系统？
• CLAUDE.md 为什么放在 messages，而不是固定 system prompt？
• 历史太长后，Compaction 怎样压缩又不破坏任务？

这一部分回答：在有限的 context 预算内，怎样持续给模型装配正确的信息。

第四部分 · Memory · 哪些信息能够跨 session 留下来

Context 解决当前调用，Memory 解决时间跨度。

第四部分沿着信息的完整生命周期展开：

• 谁把信息写下来？
• 写进 CLAUDE.md、MEMORY.md，还是 Memory Tool？
• 信息属于个人、项目、团队，还是某个 Sub-agent？
• 下一次 session 什么时候重新加载？
• Compaction 之后，哪些记忆会自动回来？

这一部分回答：一次对话结束后，信息怎样继续存活，并在未来重新进入 Context。

第五部分 · Skills · 一套操作知识怎样变成可调用能力

前四部分描述的是一个已经装好工具的 Agent 怎样运转。但工具本身不会自己变多------一套值得反复使用的操作知识（先看什么、再做什么、什么时候该停下），默认只能靠用户每次重新讲一遍。

第五部分从这个具体麻烦出发，一路展开到：

• 渐进披露：description 常驻候选清单，instructions 只在被选中后才展开
• 发现与调用：Claude 自己判断相关，还是用户用 /skill-name 直接点名
• 执行边界：instructions 在当前对话里跑，还是被派给一个独立 subagent
• 权限治理：一项 Skill 能不能被信任去动 Bash、动生产环境
• 分发：从个人文件夹到团队共享的 Plugin

这一部分回答：怎样让一套操作知识长期存在，却只在真正需要时才进入当前任务的 context。

第六部分 · 多 Agent 协作 · 一件事怎样拆给几个 Agent 同时做

前五部分描述的都是一个 Agent 怎样运转------Loop 是它的执行循环，Context 是它每次看到的信息，Memory 是它跨 session 留下的东西，Skill 是它按需展开的能力。但真实任务经常能拆成几份互相独立的活，一个 Agent 只能排成一条队，前一份没做完，后一份就得等着。

第六部分从这道边界出发，一路展开到：

• 上下文怎样交给被派出去的 Agent：从零开始，还是接着已有的历史往下续
• 权限怎样定：被派出去的 Agent 手里能用哪些工具，是提前注册好的一份套餐
• 前台还是后台：要不要原地等它做完，默认值为什么和普通命令相反
• 怎样才算做完：一段话就够，还是必须交一份格式固定的结果
• 一批独立的活，谁定的分工：运行时抢的共享任务板，还是提前写死的脚本
• 隔离与共享的边界：文件改动可以按需隔开，token 花销却从来是一本共享账

这一部分回答：一个 Agent 干不完的活，怎样拆开交给几个 Agent，而不把协作本身变成新的麻烦。

第七部分 · MCP · 模型怎样拿到一个新动作

Skill 解决的是"已有工具怎么组合使用"；但如果模型压根没有一个能连上 Jira、连上公司内网服务的动作，再好的 instructions 也无处安放。

第七部分从这道边界出发，一路展开到：

• 连接生命周期：一个 MCP server 的配置写在哪、怎样完成握手
• Transport：本地子进程和远程服务是两种不同的连法
• 工具暴露：一个外部动作怎样改名、包装成 Tool 列表里普通的一条
• 权限：服务器级别的授权语法，和 Tool 级别的权限规则有什么不同
• 认证：OAuth 与企业级免登录怎样让"连上"这件事可重复
• 反向角色：Claude Code 本身也能反过来充当一个 MCP server

这一部分回答：在不改 Claude Code 本体代码的前提下，模型怎样获得一个出厂时不存在的新能力。

七部分之间的关系

这七部分不是七套彼此独立的知识。

一次完整的 Agent 行为通常是：

Memory 提供跨 session 留下的信息
              ↓
Context 把当前需要的信息装进一次请求
              ↓
Loop 驱动模型持续判断和行动
              ↓
Tools 对外部世界执行读取、修改和查询
              ↓
Tool Result 回到 Context，Loop 继续下一轮
              ↓
值得长期保留的信息再次沉淀进 Memory

Skill 和 MCP 不在这条运转链路之外，而是作用在最上游的 Tools 这一层：Skill 把可复用的操作知识包装成一项候选能力，MCP 把模型出厂时没有的动作变成一个新的 Tool------两者一旦生效，最终都会汇入上面这张图的 Tools 环节，走同一套 Loop、Context、Memory。

多 Agent 协作站的位置不一样------它不是往 Tools 这一层加新能力，而是让这整张图同时跑好几份。一个 Agent 是图中这一条链路的一次运转；多 Agent 协作回答的是：几条链路同时存在时，彼此的 Context 是不是从零开始、权限是不是各自独立、要不要互相等待、结果怎样汇总、哪些资源是分开的、哪些资源其实是同一本账。

也可以压缩成七句话：

Tools 讲能力。

Loop 讲执行。

Context 讲信息。

Memory 讲时间。

Skill 讲怎么做。

多 Agent 协作讲怎样分给几个人一起做。

MCP 讲能做什么。

这本书采用什么研究方法

本书不是按源码目录逐个解释类和函数，而是采用一条相对稳定的推演路径：

1. 从可观察现象开始 ------ 用户在界面上看到了什么？
2. 找到背后的约束 ------ API、模型或运行环境不允许什么？
3. 还原机制 ------ Claude Code 怎样在这些约束下组织系统？
4. 分析取舍 ------ 为什么选择这种设计，而不是更直觉的方案？

Tools 部分会进一步使用"作用、例子、触发条件、技术实现、Prompt / Schema、小结"的拆解结构；Loop、Context、Memory、Skills 与 MCP 则各自围绕自己的主线展开。

目标不是背诵实现细节，而是理解：

面对相同约束，一个成熟 Agent 系统为什么会长成现在这样。

事实与版本边界

本书同时使用三类材料：

• Anthropic 官方文档与公开的 Tool description
• Claude Code v2.1.220 源码研究
• 实际运行行为与可复现的验证

为了区分事实和推断，正文遵循几条纪律：

• 直接引用尽量保留原始英文，并附来源。
• 源码级结论在文末给出文件定位。
• 无法直接证明的解释，会明确标成推论或设计理解。
• Claude Code 会持续更新；版本相关结论应结合文中标注的研究版本阅读。

这本书不是什么

• 不是 Claude Code 使用手册 ------ 不以安装、快捷键和日常命令为主线。
• 不是通用 Prompt 教程 ------ Prompt 只在解释具体机制时出现。
• 不是逐行源码注释 ------ 重点是约束、架构和设计取舍。
• 不是唯一正确的 Agent 架构 ------ Claude Code 是一个成熟样本，不是所有系统都必须复制的模板。

怎么读

第一次系统理解 Agent

建议从头开始，依次阅读 Tools → Loop → Context → Memory → Skills → 多 Agent 协作 → MCP。前四部分的时间尺度逐渐扩大，前面的概念会成为后面的基础；Skills 与 MCP 则回到 Tools 这一层，回答"能力本身怎样继续增长"；多 Agent 协作横跨在中间，回答"一个 Agent 的这套机制，怎样扩展到好几个 Agent 同时存在"。

已经在开发 Agent

可以先从最接近当前问题的部分进入：

• 正在设计 Tool → 第一部分
• 正在实现自主执行循环 → 第二部分
• 正在处理 token、cache 或 compaction → 第三部分
• 正在设计跨 session 记忆 → 第四部分
• 正在设计可复用的操作流程 → 第五部分
• 正在编排多个 Agent 协作、拆分任务 → 第六部分
• 正在接入外部工具或 MCP server → 第七部分

每篇都尽量保留前置说明和相关链接，允许跳读；但各部分内部仍建议按顺序阅读。

地址：readingclaude.club/