Learn Claude Code 课程测评：从 Agent Loop 到完整 Harness 的 20 课

快速结论

Learn Claude Code 不是“Claude Code 快捷键大全”，也不是教你背提示词。它用 20 个逐步增加能力的 Python 示例，拆解一个编码 Agent 周围的 harness：消息循环、工具分发、权限、Hook、计划、子代理、上下文压缩、记忆、任务持久化、后台任务、团队协作、工作树隔离和 MCP。课程最有价值的地方，是每章都回到同一个 Agent Loop，让你看见复杂能力如何围绕简单循环组装，而不是把框架魔法当成智能本身。

它适合已经会 Python、知道 HTTP API 和基本 Git 操作，希望理解 Agent 工程内部机制的开发者。若目标只是学会使用官方 Claude Code，直接看产品文档更短；若要比较其他终端产品，可再看 Codex 和 Gemini CLI。这套课的正确用法是“读实现、做实验、主动找缺口”，不是复制 s20_comprehensive 后上线。

课程现在有两条轨道

截至 2026 年 7 月 21 日，仓库根目录 s01_* 到 s20_* 是当前 canonical 课程。每章有叙事文档、英中日版本、可运行的 code.py，复杂主题还配图。docs/、agents/ 和当前 Web 应用保留旧 12 课轨道，用于旧链接过渡。两条轨道章节编号并不完全对应，因此不要一边看网页旧版，一边运行根目录同编号代码。

当前 20 课可以按六段理解：

阶段	章节	真正要学的判断
让 Agent 行动	s01-s04	循环、工具、权限和 Hook 如何解耦
处理复杂工作	s05-s08	计划、子代理、按需知识和上下文压缩
记忆与恢复	s09-s11	什么值得保留，失败后如何重试或换路
长任务	s12-s14	任务依赖、后台执行和定时触发
多 Agent 协作	s15-s18	邮箱协议、自主领任务与工作树隔离
扩展与装配	s19-s20	MCP 如何进入同一工具池，机制如何组合

最值得学的三层结构

第一层是 API 对话协议。模型返回文本时循环结束，返回 tool_use 时，harness 查找 handler、执行工具、把 tool_result 追加到消息，再调用模型。理解这层后，“Agent”不再是一个模糊名词，而是一组可观测的请求、动作和状态变化。

第二层是工具执行。课程从 Bash 开始，再加入文件、技能、任务和外部 MCP 工具。关键不是工具数量，而是 schema、dispatch map、结果回传与错误处理彼此独立。模型提出动作，真正执行动作的是你的进程；因此系统权限不会因为模型“很聪明”就自动安全。

第三层是长期运行机制。上下文会满，任务会阻塞，子代理会失败，多个执行者会碰同一目录。课程依次引入 compact、持久任务、后台通知、团队协议和 worktree，把这些工程问题显式化。这比只展示一次成功 Demo 更有教学价值。

建议这样动手

先克隆仓库，创建隔离的 Python 环境，只配置一个设有预算上限的测试 API Key：

git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python s01_agent_loop/code.py

不要立刻跳到 s20。先在 s01 给 Bash handler 加一个“仅允许 pwd、ls 和测试命令”的白名单；在 s02 记录每次工具名、参数、耗时和退出码；到 s03 再比较课程权限规则能拦住什么、拦不住什么。学习 s06 子代理时，观察 fresh context 降低噪声的同时会丢失哪些隐含信息。学习 s18 时，用一次真实但可丢弃的 Git 仓库制造并行修改冲突，比只读 README 更有效。

最后才运行 s20，并把它当作架构阅读题：哪些组件共用状态，哪些异常没有补偿，进程退出后哪些数据会丢，哪个工具能越过工作目录，MCP 服务的身份从哪里来。能回答这些问题，才算学会 harness，而不只是跑通代码。

API、费用与密钥边界

仓库是免费的，推理不是。快速开始要求 ANTHROPIC_API_KEY，每一次模型请求、重试、子代理调用、压缩总结和团队协作都可能增加 token 消耗。课程没有替你承诺固定费用；模型价格、缓存规则和额度以 Anthropic 当前控制台为准。给实验 Key 设置预算告警和低权限项目，完成后轮换或删除，不要把 .env 提交到 Git。

MIT 许可证覆盖仓库中由项目授权的代码和文档，不会把 Claude API、Claude 模型、第三方依赖、示例读取的数据或外部 MCP 服务变成 MIT。把课程代码嵌入产品前，应分别检查依赖许可证、模型服务条款、数据处理约定和目标市场合规要求。

工具执行安全：课程最该补上的作业

Agent 调用工具时，提示注入可能从 README、网页、日志、issue 或工具返回值进入上下文。任何“上传密钥”“删除目录”“忽略先前规则”的外部文本都应当只是数据，不能自动取得执行权。实验至少应采用以下边界：

• 在临时目录、容器或虚拟机中运行，不挂载主目录和生产凭据。
• 工具按最小权限开放；读取、写入、网络、进程和密钥访问分开授权。
• 删除、发布、付款、发消息、改权限和访问外网等动作要求人工确认。
• 为命令设置 allowlist、工作目录、超时、输出上限和子进程清理。
• 把工具结果视为不可信输入，记录请求、决定、参数、结果和操作者。
• 为模型与外部 API 设置费用、并发、重试和总时长上限。

课程的 s03 权限和 s04 Hook 是理解这些控制点的起点，不是完整安全产品。生产系统还要处理身份绑定、租户隔离、审批不可绕过、审计防篡改、秘密扫描、网络出口、数据保留、事件响应和升级回滚。

教学实现与生产系统的明确分界

项目 README 主动说明了简化范围：完整事件总线、规则化权限治理、完整 trust workflow、会话恢复与分叉、更完整的 worktree 生命周期，以及 MCP transport、OAuth、资源订阅和轮询等细节并未完整实现。JSONL mailbox 也是教学协议，不代表任何商业产品内部实现。

因此，s20 适合回答“机制怎样拼起来”，不适合直接承担客户代码、无人值守发布或高权限运维。生产化至少还需要鉴权、授权、沙箱、密钥托管、持久状态一致性、幂等与补偿、可观测性、评测集、人工接管、数据治理和供应链审计。课程让这些缺口变得可见，反而是它比“一键造 Agent”教程更诚实的地方。

优点与不足

优点： 章节顺序清楚，代码规模适合逐步阅读；英中日文档降低语言门槛；同一循环贯穿 20 课，便于比较每个机制增加的复杂度；MIT 许可方便做课堂实验和内部原型；课程明确承认与生产实现的差距。

不足： 当前网页仍是旧 12 课，容易混淆；需要付费 API 才能完整运行；部分观点带有鲜明项目立场，不应当作行业共识；教学实现刻意省略大量安全、可靠性和治理细节；它解释的是类似 Claude Code 的 harness 设计，不是 Anthropic 官方源码复刻。

适合谁，不适合谁

适合 Python 开发者、Agent 平台工程师、需要设计工具调用和权限层的团队，以及想读懂 LangGraph 等编排框架底层问题的人。建议学习者至少熟悉异常处理、文件系统、进程、Git 和 API 计费。

不适合只想快速学提示词的新手，也不适合寻找可直接采购的生产 Agent 平台。安全团队可以用它做威胁建模练习，但不能把示例默认值当作控制基线。企业若要构建真实系统，应在课程之外补齐架构评审、数据分类、红队测试和运行手册。

总结

Learn Claude Code 的核心价值，是把“模型为什么能调用工具”还原成可以单步跟踪的工程过程。20 课从一个循环走到权限、记忆、任务、团队和 MCP，足以建立扎实的 harness 心智模型。最好的结课成果不是部署 s20，而是能指出 s20 离生产还有哪些缺口，并为每个高风险动作设计可验证的边界。

如果只选一条学习路线：以 GitHub 根目录 s01-s20 为准，逐章改代码，每章写一条失败用例和一条安全控制；网页旧版只作补充。这样学完，你得到的不是另一个“Agent Demo”，而是一套判断 Agent 系统是否可靠的工程尺度。