虽然看了很多 agent框架，但在实际开发中还是难免会踩很多坑，看到 GitHub 上有这么一个仓库叫 learn-claude-code，详细梳理了一下如何从 0 学习或者是理解如何开发 Claude Code，很多实践，堪称最佳。

相关 Docs 总共 12 节，我让 Codex 详细梳理了一下，整理一篇教程以做备忘。

TL;DR

把 s01 到 s12 串起来看，这套课其实不是在教 12 个零散技巧，而是在一步步搭一个真正能长期工作的 coding agent 操作系统。

先给你一张总图

s01 Agent Loop
-> 让模型可以“反复观察-行动-再观察”

s02 Tools
-> 让行动能力变成可扩展的工具系统

s03 Todo
-> 让 agent 有显式计划，不再边做边飘

s04 Subagents
-> 把局部探索丢给独立上下文，减少主上下文污染

s05 Skills
-> 把“专业做法”按需加载，而不是全塞进 prompt

s06 Compact
-> 让上下文可持续，不会越跑越胖直到爆掉

s07 Task Graph
-> 把临时 todo 升级成持久化、带依赖的任务系统

s08 Background Jobs
-> 慢命令后台跑，主 agent 不被阻塞

s09 Agent Teams
-> 从一次性 subagent 升级成持久化队友

s10 Protocols
-> 队友之间不只聊天，而是按 request-response 协议协作

s11 Autonomy
-> 队友自己看板找活、认领任务、空闲退出

s12 Worktree Isolation
-> 每个任务有独立代码工作区，避免并发改文件互相污染

你可以把它理解成 4 次大升级。

第一阶段：让 agent 从“聊天模型”变成“会做事的程序”

对应 s01-s03：

  • s01 是内核：while loop + tool call
  • s02 是能力层：把 bash 拆成结构化工具
  • s03 是执行秩序：加 todo，让它按步骤推进

这一阶段解决的是最小闭环：

  • 能不能行动
  • 能不能持续行动
  • 能不能不乱行动

如果没有这三节，后面所有高级功能都立不住。

第二阶段：让 agent 从“单线程打工人”变成“可扩展工作者”

对应 s04-s06：

  • s04 解决上下文污染：局部问题交给 subagent
  • s05 解决知识加载：需要时再加载 skill
  • s06 解决记忆膨胀：旧历史分层压缩

这一阶段本质上是在做上下文工程。
因为 agent 真正的瓶颈，很多时候不是模型不会，而是：

  • 上下文太脏
  • 历史太长
  • 无关知识太多

所以这三节其实是在给 agent 做“认知资源管理”。

第三阶段：让 agent 从“会自己干活”变成“会管理任务”

对应 s07-s08：

  • s07 把 todo 升级成持久化任务图
  • s08 把慢操作挪到后台

这一阶段开始像真正的任务系统了。
重点不再只是“做一步”，而是：

  • 哪些任务被阻塞
  • 哪些可以并行
  • 哪些结果稍后回来
  • 历史压缩之后任务状态还能不能活着

也就是从“对话内执行”走向“系统级调度”。

第四阶段：让 agent 从“一个人”变成“一个团队”

对应 s09-s12：

  • s09 有持久化队友和邮箱
  • s10 有团队协议和审批流
  • s11 队友能自己找活、自主 idle/shutdown
  • s12 每个任务配独立 worktree，真正实现并发隔离

这四节加起来，才真正像“多 agent 软件工程系统”。

因为一个真正能扩展的团队，不只需要：

  • 多个 agent

还需要：

  • 通信
  • 协议
  • 状态
  • 自治
  • 环境隔离

少一个都会乱。

如果你换一个更工程化的视角，这 12 节分别在补 6 个系统部件

1. 控制循环

  • s01 Agent Loop

2. 执行接口

  • s02 Tools

3. 规划与调度

  • s03 TodoWrite
  • s07 Tasks
  • s08 Background Tasks

4. 上下文与知识管理

  • s04 Subagents
  • s05 Skills
  • s06 Compact

5. 协作与组织

  • s09 Agent Teams
  • s10 Team Protocols
  • s11 Autonomous Agents

6. 执行环境隔离

  • s12 Worktree + Task Isolation

所以整套课不是“从简单到复杂”这么简单，它其实是在回答一个非常完整的问题：

  • 一个 coding agent 系统，除了模型本身，还缺哪些基础设施？

课程的答案是：

  • loop
  • tools
  • planning
  • memory management
  • task system
  • background execution
  • teamwork
  • protocols
  • autonomy
  • isolated workspaces

最重要的主线，你可以压缩成一句话

这 12 节是在做一件事：

  • 把“LLM 会回答问题”逐步升级成“一个能长期、稳定、并行、可恢复地完成工程任务的系统”。

或者更通俗一点：

  • s01-s03：先让它像一个会干活的人
  • s04-s06：再让它别太快糊涂
  • s07-s08：再让它会管理任务和时间
  • s09-s12：最后让它像一个真正的工程团队

我建议你优先抓这 5 个分水岭：

s01 核心不是 prompt，而是 agent loop。

s03 复杂任务必须显式计划，不能只靠模型脑补。

s06 上下文不是数据库，必须管理和压缩。

s07 长期工作必须把任务状态移出上下文，放到持久层。

s12 多 agent 并发最终一定会走到环境隔离，不然会互相踩代码。

这 5 节吃透了，整条主线基本就明白了。

s1 Agent 循环

第一节讲的是整个课程最核心的底座：Agent 其实不神秘，本质上就是“模型 + 工具 + while 循环”。

1. 这节到底在讲什么

它想回答一个最基础的问题：

  • 大模型会“想”，但默认不会“做”
  • 它不能自己读你电脑上的文件，不能运行测试，不能查看报错
  • 如果没有一个外层循环，你每次都得手动把工具结果贴回给模型
  • 所以真正缺的不是更强的提示词，而是一个自动反复执行的控制循环

这节的结论可以压缩成一句话：

  • 一个智能体 = 一个 while 循环 + 一个工具
  • 这里选的唯一工具就是 bash

也就是说，先别把 agent 想得太复杂。最小可用 agent 根本不需要“任务树”“记忆系统”“多智能体协作”这些高级机制。先有循环，再谈增强。

2. 它要解决的问题是什么

普通对话式 LLM 的工作方式是：

  1. 你发一个问题
  2. 模型回你一个答案
  3. 结束

但真实编程任务不是一次回答能解决的。比如你让它“修一个测试失败”：

  1. 它要先看项目结构
  2. 再读代码
  3. 跑测试
  4. 看报错
  5. 改代码
  6. 再跑测试验证

这是一串连续动作，不是单轮问答。

所以这节提出：
让模型决定什么时候调用工具，宿主程序负责执行工具，再把结果送回模型，反复循环，直到模型说“我不用再调工具了”。

这就是 agent loop。

3. 页面里的核心流程，拆开讲

课程给的流程可以理解成 5 步：

  1. 把用户问题放进 messages
  2. 带着 messages 和 tools 调模型
  3. 看模型返回了什么
  4. 如果它请求调用工具，就执行工具
  5. 把工具结果再塞回 messages，继续下一轮

直到模型不再请求工具，循环结束。

这里最关键的是一个字段：

  • stop_reason

课程里的判断逻辑是：

  • 如果 stop_reason == "tool_use"，说明模型这轮不是要直接结束，而是要你去执行工具
  • 如果不是 tool_use，说明模型已经准备好给最终回答了，循环可以停

所以，整个 agent 的控制权，不在 if-else 写死的业务规则里，而在模型返回的停止原因里。

4. 这几个数据结构为什么重要

messages

  • 这是智能体的“短期记忆”
  • 它不是数据库，也不是长期知识库
  • 它只是把“用户说了什么、模型做了什么、工具返回了什么”按顺序累积起来

没有这个消息列表，模型每一轮都会失忆。

response.content

  • 这不是普通字符串
  • 它可能混合包含自然语言块、工具调用块
  • 所以程序不能只把它当纯文本处理，而要遍历每个 block

tool_use

  • 表示模型提出一个工具调用请求
  • 比如它可能请求执行某条 bash 命令

tool_result

  • 表示你已经把工具跑完，并把结果还给模型
  • 它相当于告诉模型：“刚才你要的外部操作已经完成，结果如下，请继续思考”

这里有个非常重要的设计点：
工具结果会被追加回消息历史里，重新交给模型。

这意味着模型的工作模式变成了：

  • 想一步
  • 做一步
  • 看结果
  • 再想下一步

这就是 agent 和普通聊天模型最本质的区别。

5. 为什么只用 Bash 就够做第一版 agent

页面标题里有一句很强的观点：Bash is All You Need。它的意思不是说 Bash 永远最好，而是说：

  • 对“最小 agent”来说，一个通用执行工具已经足够
  • bash 能读文件、列目录、运行测试、调用脚本、看 git 状态、创建文件夹
  • 所以很多“看起来很复杂的 agent 能力”，第一版都可以收敛成 shell 命令

比如这些操作都能用 bash 完成：

  • 查看项目里有哪些 Python 文件
  • 创建一个 hello.py
  • 查询当前 git branch
  • 创建目录并写几个文件

所以课程在第一节故意不加多个工具，是为了让你先抓住本质：
工具的数量不是重点，重点是“模型能不能通过循环持续调用外部能力”。

6. 这段代码真正厉害的地方，不是复杂，而是极简

页面里说整个 agent 不到 30 行就能跑起来。它想表达的不是“代码短很酷”，而是：

  • agent 的核心内核其实非常小
  • 后面很多高级框架，本质上都是在这个循环外面继续叠功能
  • 例如：
  • 多工具注册
  • Todo 计划
  • 子 Agent
  • 上下文压缩
  • 并发任务
  • 团队协作

但这些都只是“外挂”，不是内核本身。

内核始终是：

while True:
调模型
如果要用工具:
执行工具
把结果喂回去
否则:
结束

你把这个吃透，后面很多 agent 框架就没那么玄了。

7. 一个具体例子，帮助你建立直觉

假设用户说：

  • “列出当前目录下所有 Python 文件”

agent loop 会这样跑：

  1. 用户消息进入 messages
  2. 模型判断：这个任务需要看真实文件系统
  3. 模型发起 tool_use，请求执行类似 find 或 ls 的 bash 命令
  4. 宿主程序真的去执行命令
  5. 把命令输出包装成 tool_result 发回模型
  6. 模型读到输出后，整理成自然语言答案
  7. 此时不再需要工具，stop_reason 不再是 tool_use
  8. 循环结束，返回最终答复

注意：
模型本身没直接访问文件系统，它只是“提出工具请求”；真正访问环境的是外层程序。

这是安全和架构上都很关键的分层。

8. 这节最值得你真正理解的 4 个点

第一，Agent 不是神奇新物种。
它只是给 LLM 加了“行动能力”和“反馈回路”。

第二，循环比提示词更关键。
没有循环，再好的 prompt 也只是一次性回答。

第三，工具结果必须回流给模型。
否则模型无法基于真实执行结果继续推理。

第四，停止条件是 agent 的生命线。
如果没有明确退出机制，循环就可能无限调用工具。

9. 这节的局限是什么

这一节刻意做得很“原始”，所以它也有明显不足：

  • 只有一个工具，能力边界很粗
  • 没有权限控制，bash 风险高
  • 没有任务拆解能力
  • 没有上下文裁剪，消息会越来越长
  • 没有错误恢复策略
  • 没有并发和多 agent 协作

但这不是缺点，而是教学设计。
它想先让你看清“最小闭环”是什么，再逐步加复杂度。

10. 你可以把这节理解成一句工程化定义

如果让我用更工程化的话重述这节：

  • LLM 负责决定下一步做什么
  • 宿主程序负责真的去做
  • 环境反馈再交还给 LLM
  • 直到 LLM 不再请求行动

这就是第一节全部的骨架。

这里太长难以保存，具体后续可以移步公众号：https://mp.weixin.qq.com/s/LH82Awkq23eXMD0O1luPEg