大家好，我是悟鸣。（微信公众号：悟鸣AI）
很多朋友都在问两个问题：
想系统学习 Agent 原理，但不知道从哪里开始。
已经在用 Claude Code，但想搞清楚它背后的机制。
今天这篇就推荐一个很适合入门到进阶的开源项目：learn-claude-code。
这个项目解决了什么问题？
它把“会用工具”和“理解原理”之间的鸿沟补上了：
-
不只讲概念，而是从最小可运行循环开始。
-
每一课只增加一个机制，学习路径清晰。
-
代码能跑、过程可观察、原理可追踪。
GitHub 仓库地址：https://github.com/shareAI-lab/learn-claude-code
先看最小循环：Agent 是怎么“动起来”的
这是 AI Coding Agent 的最小循环。生产级 Agent 会在此基础上叠加策略、权限和生命周期管理。
LLM 本身只能生成文本，但编程任务需要与真实世界交互（读写文件、运行命令、搜索代码）。 这个循环的作用是让 LLM 能够：
-
判断何时需要调用工具
-
调用工具并获取结果
-
基于结果继续推理和执行
12 节课怎么设计？
项目提供了 12 节循序渐进的课程：从简单循环到隔离化自动运行。每节课只增加一个机制，并配一句“格言”。
|
s01 |
One loop & Bash is all you need |
一个工具 + 一个循环 = 一个智能体 |
|
s02 |
加一个工具，只加一个 handler |
循环不用动，新工具注册进 dispatch map 就行 |
|
s03 |
没有计划的 agent 走哪算哪 |
先列步骤再动手，完成率翻倍 |
|
s04 |
大任务拆小，每个小任务干净的上下文 |
子智能体用独立 messages[]，不污染主对话 |
|
s05 |
用到什么知识，临时加载什么知识 |
通过 tool_result 注入，不塞 system prompt |
|
s06 |
上下文总会满，要有办法腾地方 |
三层压缩策略，换来无限会话 |
|
s07 |
大目标要拆成小任务，排好序，记在磁盘上 |
文件持久化的任务图，为多 agent 协作打基础 |
|
s08 |
慢操作丢后台，agent 继续想下一步 |
后台线程跑命令，完成后注入通知 |
|
s09 |
任务太大一个人干不完，要能分给队友 |
持久化队友 + 异步邮箱 |
|
s10 |
队友之间要有统一的沟通规矩 |
一个 request-response 模式驱动所有协商 |
|
s11 |
队友自己看看板，有活就认领 |
不需要领导逐个分配，自组织 |
|
s12 |
各干各的目录，互不干扰 |
任务管目标，worktree 管目录，按 ID 绑定 |
这 12 课的关键价值在于：循环框架基本不变，你看到的是“能力层层叠加”的过程。
怎么跑起来？（CLI 实操）
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # 编辑 .env 填入你的 ANTHROPIC_API_KEY
python agents/s01_agent_loop.py # 从这里开始
python agents/s12_worktree_task_isolation.py # 完整递进终点
python agents/s_full.py # 总纲：全部机制合一
这个项目是可运行的 Coding Agent 简化实现，需要配置你自己的 API Key，才能观察完整交互过程。
为什么要 cp .env.example .env？
-
.env.example 是模板文件，可以提交到仓库。
-
.env 通常在 .gitignore 中，会在 Git 推送时被忽略。
-
这样能避免 API Key 泄露。
所以，把你的密钥和配置写进 .env 即可。
如果运行时报错，优先检查环境变量是否配置正确。多数初始问题都来自这里。
跑通脚本后，你可以直接在终端里和智能体对话；一边跑、一边看源码，理解速度会快很多。
再用 Web 可视化加深理解
CLI 适合实操，Web 页面更适合建立整体认知。项目提供了交互式可视化、分步动画、源码查看器，以及每节课的配套文档。
cd web && npm install && npm run dev # http://localhost:3000
命令执行后，在浏览器打开对应地址即可进入学习页面。
每节课都能看到动画演示、学习材料、模拟过程和源码，还能进一步做深入探索。
你可以在这个交互页面按章节学习，也可以回到终端直接和对应章节的 Agent 对话。
每个章节都明确标注了相对前一章的变化点，这对建立“演进视角”非常有帮助。
从智能体循环、TODO 子智能体，到 Skills、任务系统、上下文压缩、Agent 团队、自主协作与用户隔离，这套内容覆盖得很完整。
总结
如果你想真正理解 AI Agent 的工作原理，而不只是停留在“会用工具”，这个项目是很好的切入点：
-
循序渐进：12 节课，每节只加一个机制，学习负担可控。
-
可运行代码：不是纸上谈兵，代码能跑、能调试、能改。
-
可视化学习：交互式页面把抽象循环变得可感知。
-
生产级思维：任务拆分、上下文管理、多 Agent 协作都贴近真实系统设计。
无论你是想从零搭建一个 Agent，还是想深入理解 Claude Code 这类工具背后的设计逻辑，这个项目都值得系统过一遍。
仓库地址：https://github.com/shareAI-lab/learn-claude-code
觉得有帮助的话，记得给作者点个 Star ⭐
欢迎关注我的公众号：悟鸣AI，持续分享比较有用的 AI 工具和比较好的 AI 经验，比较客观理性的 AI 观点等。
