Claude Code 学习笔记（综合版）
2026年4月10日大约 15 分钟
Claude Code 学习笔记（综合版）
用途：面向分享与复习。本文主线按「Learn Claude Code」课程的四阶段、十九步来讲清 Claude Code 作为一类 Code Agent 的本质；泄露事件与工程深挖仅作补充。
说明：正文不夹带网址；需要延伸阅读与引用时，见文末「附录：链接索引」。材料性质（官方文档 / 社区解读 / 个人笔记）分享时需口头区分，产品行为以 Anthropic 官方为准。
最想先讲清楚的：Claude Code 是什么
它不是一个「更大的提示词」，而是一套在终端里长期干活的 Agent 产品，核心可以概括成五句话：
- 本质是循环：发消息 → 模型决定是否调用工具 → 执行工具 → 结果写回对话 → 重复，直到结束。
- 能力在工具上扩展：加能力 = 加工具与处理函数，不必每次重写循环骨架。
- 计划要可见：复杂任务先拆步（Todo），避免模型一路漂移。
- 上下文是稀缺资源：长会话要靠压缩、记忆分层、缓存策略，否则会爆 token、费钱、质量差。
- 安全与持久化不是补丁：权限是管线；任务可以比单次会话活得更久；多 Agent 要隔离与协议，而不是多开几个聊天窗口。
下面整篇笔记的讲法，建议严格跟着 Learn Claude Code 的十九步顺序走（从最小循环一路讲到多 Agent 与 MCP）；听众会最容易跟上。
主线：四阶段 · 十九步（建议按此顺序讲）
课程把路径分成 4 个阶段、19 章：从「最小 Agent 循环」到「多 Agent 平台 + 外部能力总线」。下面每一步用一句话本质 + 几句展开，对应你现场可以怎么讲。
阶段一：Core Loop（核心循环）
| 步 | 主题（英） | 本质（中文） |
|---|---|---|
| s01 | Agent Loop | Agent 就是循环：发消息、执行工具、把结果喂回去，再转下一轮。没有循环，就没有「持续做事」。 |
| s02 | Tool Use | 加一个工具 = 加一个 handler；循环代码尽量不动。扩展性来自工具表，而不是把逻辑写进 prompt。 |
| s03 | TodoWrite | 可见的计划：任务列表先摆出来（常先全是 pending），复杂任务才不容易跑偏。 |
| s04 | Subagent | 子代理首先是上下文边界：独立消息流，主对话保持干净；子侧用完可丢。 |
| s05 | Skills | 先轻量发现、再按需深读：知识不必一次性塞进 system，需要时再注入（与「工具搜索」同一套省 token 思路）。 |
| s06 | Context Compact | 压缩不是「删历史」了事，而是把细节挪到别处（摘要、外置存储、结构化记忆），让模型还能继续工作。 |
阶段一小结：先把「能转起来的最小 Agent」讲透，再谈别的；前六步是听众心智模型的地基。
阶段一 · 呼应与补充（可选展开）
- s01：实现上常见
while (true)+ 调模型 API；每轮前可能先做压缩再送上下文，避免上一轮工具输出把窗口撑爆。 - s02：工具注册表集中管理；参数多用 schema 校验模型吐出的 JSON；一个工具名对应一个 handler，循环代码保持薄。
- s03：Todo 的价值是对模型可见的状态机——「还有哪些没做」和「当前做哪一步」比一句「请帮我做项目」更可执行。
- s04：子会话与主会话隔离，工程上常用 query source / 线程 一类标记，避免压缩时误删子对话里不存在的工具块。
- s05：与 Tool Search 同类思路：先给名称+摘要，需要再拉全量定义，省 token；Skills 则是知识侧的「按需注入」。
- s06：微压缩往往不调模型（规则占位旧工具结果）；重压缩才调模型归纳；二者成本与风险不同，别混成一句「自动摘要」。
阶段二：System Hardening（系统加固）
| 步 | 主题（英） | 本质（中文） |
|---|---|---|
| s07 | Permission System | 安全是流水线（拒绝、检查、允许、再询问），不是单一「全允许/全禁止」。 |
| s08 | Hook System | 循环拥有控制流；Hook 只在命名节点上观察、阻断或标注，不替代主循环。 |
| s09 | Memory System | 记忆给方向，当前观察给事实；二者混成一团就会又冗长又过时。 |
| s10 | System Prompt | 模型看到的是拼装出来的输入管线，不是一块写死的超长字符串。 |
| s11 | Error Recovery | 多数异常是换路径的信号（重试、降级、换工具），不必等于整任务失败。 |
阶段二小结：产品能不能上生产，往往取决于这几步是否想清楚。
阶段二 · 呼应与补充（可选展开）
- s07：高危工具（如 Bash）背后往往是大量规则（路径、网络、命令模式）；权限不是 bool，而是「能否执行、是否先审、是否改参数再问」。
- s08：Hook 适合记日志、审计、拦截；不要让 Hook 变成第二套 Agent 大脑，否则调试会地狱。
- s09：记忆宜分层：指针/索引（memory 类文件）+ 专题笔记 + 按需 Grep；慎把整段易变源码长期当「真理」写进记忆。
- s10：静态片段（通用指令、稳定工具列表）与动态片段（时间、Git、当前文件）混写会拖累 Prompt Cache；设计输入管线时就要想好「哪一段该稳定」。
- s11：工具失败、网络抖动、权限拒绝，在好产品里多是可恢复分支；循环里应区分「可重试」「需换人」「需用户输入」。
阶段三：Task Runtime（任务运行时）
| 步 | 主题（英） | 本质（中文） |
|---|---|---|
| s12 | Task System | 可持久化的任务图（顺序、并行、依赖）；比「仅本次会话内的 Todo」更能协调跨时间的活。 |
| s13 | Background Tasks | 背景执行是同一条 Agent 运行时里的一条车道，不是再写一个独立大脑。 |
| s14 | Cron Scheduler | 定时触发只是换种方式往同一条循环里喂任务，不必另起一套调度哲学。 |
阶段三小结：会话会结束，任务不应跟着一起消失——这是从 demo 走向「干长活」的分水岭。
阶段三 · 呼应与补充（可选展开）
- s12：会话内 Todo 解决「这一轮怎么走」；任务图解决「跨轮次、跨进程谁依赖谁」。压缩清空对话时，磁盘上的任务状态仍是单一事实来源。
- s13：背景任务不是另起一个无限
while，而是同一条运行时里的队列或工作线程，结果仍要落回可观察的状态（文件、任务状态、消息）。 - s14：Cron = 定时往循环里塞任务；关键仍是：触发器与 Agent 执行模型一致，运维心智简单。
阶段四：Multi-Agent Platform（多 Agent 平台）
| 步 | 主题（英） | 本质（中文） |
|---|---|---|
| s15 | Agent Teams | 队友要有身份与可跨会话存在的协作通道，而不是一次性 prompt。 |
| s16 | Team Protocols | 协议消息要有结构（例如请求带 id、响应对上同一 id），否则多 Agent 只会互相踩脚。 |
| s17 | Autonomous Agents | 自主性是有边界的机制（空闲、扫描、认领、恢复），不是「放手就魔法发生」。 |
| s18 | Worktree Isolation | 任务回答做什么，worktree 回答在哪里做；目录隔离减少互相污染。 |
| s19 | MCP & Plugin | 外部能力走与内置工具相同的路由、权限与结果回写，才能统一治理。 |
阶段四小结：多 Agent 的难点在协调与隔离，不在「多喊几个模型」。
阶段四 · 呼应与补充（可选展开）
- s15–s16：没有协议的多 Agent = 群聊里所有人同时改同一文件；请求 id、响应 id、状态机比「再写一段自然语言协调一下」可靠。
- s17：自主 = 有限状态（闲时扫板、认领、执行、阻塞则挂起），每一步都要可观测、可打断，而不是无限自主循环。
- s18：同一仓库里并行的最佳实践往往是目录 / worktree 隔离；与 s12 任务依赖合起来，才同时回答「谁做什么」和「在哪做」。
- s19：MCP 的价值是统一治理：外部浏览器、数据库、内部 API 若各写一套调用方式，权限与审计永远对不齐。
讲述时长怎么切（可选）
主线不变，只控制展开深度：
- 约 25 分钟：讲清开篇「五句本质」+ 阶段一、二两张表 + 各阶段「小结」首句；每阶段「呼应与补充」不讲或各只举 1 条；后文补充节只点 A 的前三条。
- 约 45 分钟：四张表全讲 + 每阶段「呼应与补充」各挑 2～3 条；补充节展开 A、B、D；阶段四用「协议、自治边界、目录隔离、外接总线」四词帮助记忆 s15–s19。
- 有人追问某一步：先回到对应 s0x，再翻到补充节 A–H 里同一字母下的段落，避免从泄露八卦或实现细节起讲，冲淡主线。
与主线呼应的补充（需要时再展开）
下面这些不是另一条平行大纲，而是给上面某几步加细节时用的；分享时间紧可以整节跳过。主线仍是十九步，这里全是「挂钩」。
A. 上下文压缩：两套说法怎么对齐（扣 s06、s09）
- 教学上常讲三层：微压缩（旧工具输出占位）→ 自动压缩（超 token 阈值则摘要）→ 手动 compact。
- 工程上还会拆更细：
- 微压缩：多靠规则（白名单工具类型、只保留最近 n 条结果），不调用模型；常与 Prompt Cache 策略联动（避免删法导致整块缓存失效）。
- 会话记忆：把事实抽成结构化条目写进本地记忆文件，用
memory类载体承接，而不是只做「整段对话摘要」。 - 完整压缩：token 仍爆时才调模型做多维度归纳；常见 先 analysis 再 summary，展示时剥掉内部 analysis，减少噪声与泄露冗思。
- 自动触发：每轮后看 token，接近窗口上限减缓冲即触发；顺序往往是「先试会话记忆 → 再完整压缩」；并带 熔断（如连续失败超过阈值则停），避免无效 API 风暴。
- 边界条件：
tool_use与tool_result成对出现的不宜拆开；含 thinking 的块不能只留半截。 - 统一原则：上下文是稀缺资源——这个 token 是否还值得留在窗口里？
B. System Prompt 与缓存（扣 s10、s05、s02）
- 输入宜分块：系统说明、工具定义、动态上下文、当轮消息分层拼装；课程里强调「模型看到的是构造后的管线」，不是一块静态天书。
- 若使用云端 Prompt Cache：稳定内容尽量形成可缓存前缀；时间、Git、文件内容等动态信息频繁变动时，会拖累缓存命中。工具定义、system、messages 在不同 API 模型下往往有前缀层级，改动了前段，后段缓存一并失效——设计时要心里有数。
- Tool Search / 延迟加载：按需挂载工具，新工具以引用形式追加时，可减轻「工具表巨长」对前缀的压力（具体机制以所用 API 为准）。
- 与 s05 呼应：Skills 也是「别一次塞满，用到了再注入」，和缓存友好性同向。
C. 工具层工程细节（扣 s02、s07）
- 并发：常见做法是读操作可并行，写操作串行或等前置完成；未声明「并发安全」的工具默认偏保守。
- 大输出：工具结果过大时写入外部存储，模型侧只保留引用或按需拉取，避免单轮把上下文撑爆。
- 元工具：用「子 Agent」当工具时，本质是 s04 的产品化——主会话只看到子任务的摘要。
- 内置工具数量：不同统计口径从几十到八十以上都有（是否含实验能力、是否含 MCP 动态工具）；分享时说「数十量级 + 可扩展」即可。
D. 记忆与检索（扣 s09）
- 三层常见分法：指针层（短
memory、像目录）→ 专题文件（约定、踩坑）→ 历史检索。 - 为何常提 Grep 而不是向量 RAG：固定记忆文件上文本搜索实现简单、无索引过期问题；由模型决定搜什么，有时比「预先 embedding 一切」更贴任务。你的产品里也可二选一或混用。
- Memory gives direction; current observation gives truth：可当作 s09 的英文一句版。
E. 客户端源码泄露（背景，简略带过即可）
- 近端 npm 包曾误带 Source Map，公开包内可还原大量 TypeScript 客户端实现；讨论多集中在实现细节（循环、工具、压缩、权限等），不等于官方公开设计文档，也不替代十九步主线。
- 听分享时只需知道：泄露的是客户端工程视角的可读信息；模型权重、用户数据是否涉及，以厂商正式说明为准。
- 与主线关系：泄露讨论帮你「印证」s01–s06、s07 等确有扎实实现；听众若不问，不必展开版本号与体积。
F. 「五级压缩」等个人笔记说法（与 s06 对照）
另文若写「剪裁 → 微压缩 → 折叠 → 自动 → 应急（如 413）」，可与 节 A 叠加理解：前者是从轻到重的阶梯命名，后者是同一问题的教学版与工程版。分享时只讲 s06 + 节 A 第一段通常够用。
G. 与通用范式的关系（扣 s01–s02）
- ReAct：推理与行动交替；Code Agent 把行动落到仓库与 shell。
- 流式 UI：终端里常见 SSE 流式输出，边生成边渲染；与「循环里何时插入压缩」是两件独立但相关的事。
- 不必在分享里强调具体代码行数；强调行为：循环 + 工具 + 权限 + 压缩。
H. Harness 与主线（扣 s06、s11、全文）
- 改压缩、改权限、改子 Agent 策略后，用固定任务集回放对比 成功率、轮次、token、时延、人工接管，才能把 s11 错误恢复 和 s06 压缩 的改动变成可证明的改进，而不是「体感」。
一页纸「分享用」结论
- Agent = while 循环 + 工具调度；加工具不必改循环核心（s01–s02）。
- 先计划、再执行（s03）；子代理卖的是上下文隔离（s04）；技能卖的是按需加载（s05）。
- 压缩与记忆是产品线，不是一句「太长就摘要」（s06、s09）。
- 权限、Hook、错误恢复决定能不能上生产（s07–s11）。
- 任务可持久、背景与定时仍是同一条循环（s12–s14）。
- 多 Agent 要协议、自治边界、目录隔离、外部能力同一总线（s15–s19）。
写在最后（实践参考）
我自己在做的 AI 驱动 H5 生成与迭代平台里，也落地了与上述主线相通的东西：例如 上下文压缩、推理与对外输出分层（思维链拆分），以及用 Harness 把典型任务做成可回放用例，避免「感觉变好了」却无法对比。
若你在做类似的 Agent 项目，建议以本文件「十九步」为讲述顺序，需要细节时再翻个人笔记或文末索引里的材料；不必照抄任何单一产品，但「循环—工具—计划—压缩—权限—持久任务—多 Agent—外接能力」这条轴，大体通用。
延伸阅读、Harness 与自检（无链接版）
为何提 Harness
与上文 节 H 同旨：主线讲清「是什么」之后，落地时要用可回放任务证明「改好了没」。指标仍建议盯 成功率、平均轮次或工具调用数、token 成本、P95 时延、人工接管率。
自建 Agent 时可自问
- 长会话里工具输出会不会无限堆进上下文？触发压缩的条件是否明确？
- 若用 Prompt Cache，动态信息是否尽量后置，避免整块前缀频繁失效？
- 压缩或摘要连续失败时，有没有熔断避免重试风暴？
- 工具执行前是否可审计、可分级？
- 跨会话的任务状态存在哪里？压缩后能否恢复？
现场 Q&A 备答（每题 15–30 秒）
- 来源是否靠谱？ 分三类：官方 API 文档、可复现事实（如包内文件）、社区解读；后一类口头标注即可。
- 泄露算不算用户数据外泄？ 公开讨论焦点多在客户端源码可读；是否涉及权重、用户数据，以厂商正式说明为准。
- 为何不全靠 RAG？ RAG 偏「取外部知识」；压缩与记忆解决的是对话内 token 与连贯性。
- 最小落地顺序？ 先微压缩与熔断，再结构化记忆，最后再上重摘要。
- 思维链拆分解决什么？ 内部分析与对外可交付内容分层，减少噪声、便于压缩与协作。
- 多 Agent 何时值得上？ 单 Agent 先跑通；并行强或上下文严重污染时再引入协议与隔离。
- 你怎么证明 H5 平台变好了？ 用 Harness 指标前后对比，而不是主观感觉。
附录：链接索引（正文不放网址时使用）
课程站点（本文主线所依）
- Learn Claude Code：
https://learn.shareai.run/
仓库内相关笔记
CC-ContextManagement.md（上下文管理深挖）ClaudeCode.md（泄露与架构条目）src/posts/ai/LearnCC.md（英文要点摘录）
可选：公开报道与二次解读（泄露背景）
- NodeSource、TeqStars、typescript.news、dev.to 等相关文章标题可自行搜索「Claude Code source map npm」。
可选：Anthropic 官方文档（缓存与工具）
- Prompt caching、Tool use with prompt caching（文档站路径以当前官网为准）。