12节课拆解AI编程Agent核心原理

从黑盒到白盒：Learn Claude Code如何用12节课拆解AI编程Agent的核心原理

如果你还在把AI编程助手当作神秘黑盒，那么是时候揭开它的面纱了。

在2026年的今天，几乎每个开发者的电脑上都运行着某种AI编程助手------Claude Code、Cursor或是其他类似工具。它们能自动修改文件、执行命令、甚至帮你调试代码，但当你问一句"它到底是怎么工作的"，大多数人却答不上来。

最近在GitHub上爆火的开源项目 Learn Claude Code 正在改变这一现状。这个由shareAI-lab开发的教学项目，在短短几周内就获得了超过41.6K星标，连知名开发者宝玉老师都赞不绝口："Learn Claude Code是真做得好，强烈推荐"。

为什么我们需要理解AI Agent的原理？

就像天天开车的人不一定懂发动机原理，但如果你不懂原理，你就只能是个"用户"。当AI Agent的能力边界在哪里、为什么有时候会"抽风"、怎么优化它的表现------这些你都无从判断。

Learn Claude Code的目标很简单：让你从根本上理解AI编程Agent是怎么工作的。它用12节课，每节课只加一个机制，每个机制都有可运行的Python代码。整个过程就像剥洋葱一样，一层一层地把AI Agent的核心原理展现在你面前。

核心洞察：所有AI编程Agent的底层都是同一个循环

这个项目的核心洞察非常犀利：所有AI编程Agent的底层都是同一个循环。

用户发消息给模型，模型决定要不要调用工具，调用了就执行，把结果喂回去，继续循环，直到模型觉得任务完成了。整个Agent的最小实现不到30行代码。剩下的一切------规划、子任务拆分、上下文压缩、多Agent协作、工作目录隔离------都是在这个循环上面一层一层叠加的。

12节课的渐进式学习路径

Learn Claude Code最吸引人的地方，就是它的学习路径设计。12节课，每节课只解决一个问题，每节课都有一句核心motto，整个过程逻辑清晰，循序渐进。

第一阶段：核心循环（前2节）

s01：The Agent Loop --- "One loop & Bash is all you need"

这是一切的起点。在这节课里，你会看到一个最最基础的Agent循环，只有一个while循环加上工具调用的逻辑。就这么简单的一个循环，就是所有AI Agent的核心。

s02：Tool Use --- "Adding a tool means adding one handler"

有了循环之后，我们需要让Agent能调用工具。这节课讲的就是怎么设计一个工具调度系统，新加工具只需要加一个handler，循环本身完全不用改。

第二阶段：规划与知识（第3-6节）

s03：TodoWrite --- "An agent without a plan drifts"

没有计划的Agent会跑偏。这节课加入了TodoWrite机制，让Agent在执行任务之前先列好计划，完成率直接翻倍。

s04：Subagents --- "Break big tasks down; each subtask gets a clean context"

大任务要拆成小任务，每个子任务用独立的messages[]，这样主对话就不会被污染。

s05：Skills --- "Load knowledge when you need it, not upfront"

知识不用一开始就全塞进system prompt，需要的时候通过tool_result注入进去就行。

s06：Context Compact --- "Context will fill up; you need a way to make room"

上下文窗口是有限的，不压缩大项目根本跑不动。这节课讲的是三层压缩策略，让会话可以无限延续。

第三阶段：持久化（第7-8节）

s07：Tasks --- "Break big goals into small tasks, order them, persist to disk"

把大目标拆成小任务，排好顺序，持久化到磁盘上。这是多Agent协作的基础。

s08：Background Tasks --- "Run slow operations in the background; the agent keeps thinking"

慢操作放到后台跑，用守护线程执行，完成了发通知，Agent继续思考别的事情。

第四阶段：多Agent协作（最后4节）

s09：Agent Teams --- "When the task is too big for one, delegate to teammates"

任务太大一个人干不完？那就组队！持久化的队友加上异步邮箱，开始协作。

s10：Team Protocols --- "Teammates need shared communication rules"

队友之间需要共同的通信规则。一个请求-响应模式驱动所有的协商。

s11：Autonomous Agents --- "Teammates scan the board and claim tasks themselves"

不需要领导一个个分配任务，队友自己扫描看板，认领任务就行。

s12：Worktree + Task Isolation --- "Each works in its own directory, no interference"

每个人在自己的目录里干活，互不干扰。任务管理目标，工作树管理目录，用ID绑定。

心智模型优先的教学方法

Learn Claude Code的文档风格也很值得一提。它不是上来就给你一堆代码，而是"心智模型优先"：先讲问题是什么，再讲解决方案，配ASCII图，最后是最小可运行代码。

这种教学方式真的很贴心。它不是让你死记硬背代码，而是让你真正理解每个机制解决了什么问题，为什么要这么设计。

比如，在讲Agent Loop的时候，它先给你画了一张ASCII图，然后再给你看核心代码：

python 复制代码

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return
        
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS**block.input
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

快速上手：从零到一的实践体验

说了这么多，不如亲自跑起来试试。Learn Claude Code的安装和使用非常简单。

首先，克隆项目：

bash 复制代码

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code

然后安装依赖：

bash 复制代码

pip install -r requirements.txt

配置API Key：

bash 复制代码

cp .env.example .env
# 编辑.env文件，填入你的ANTHROPIC_API_KEY

现在你就可以开始学习了！建议从s01开始：

bash 复制代码

python agents/s01_agent_loop.py

然后逐步推进到s12：

bash 复制代码

python agents/s12_worktree_task_isolation.py

如果你想看完整版，可以直接运行：

bash 复制代码

python agents/s_full.py

如果你想体验交互式Web平台，也可以：

bash 复制代码

cd web
npm install
npm run dev

然后打开浏览器访问http://localhost:3000就可以了。

从理解到落地：Kode生态

学完这12节课之后，你对AI Agent的工作原理已经了如指掌了。接下来怎么把这些知识用起来呢？

项目作者还提供了两个后续项目：

Kode Agent CLI --- 开源编程助手CLI

bash 复制代码

npm i -g @shareai-lab/kode

这是一个开箱即用的开源编程助手CLI，支持技能和LSP，Windows可用，可以接入GLM、MiniMax、DeepSeek等开源模型。Kode已从AGPLv3协议升级为更宽松的Apache 2.0开源协议，这意味着开发者可以在任何个人、商业或企业项目中使用Kode，而无需开源自己的代码。

Kode Agent SDK --- 在你的应用中嵌入Agent能力

官方的Claude Code Agent SDK是在底层跟一个完整的CLI进程通信的，每个并发用户都需要一个独立的终端进程。而Kode SDK是一个独立的库，没有每个用户一个进程的开销，可以嵌入到后端、浏览器扩展、嵌入式设备或者任何运行时中。

Kode Agent SDK提供了完整的工具调用、状态管理、事件流等能力，支持Anthropic Claude和OpenAI GPT模型，以及兼容API的模型提供者。它内置了20+工具，覆盖文件系统、Shell、任务管理等常见场景，并通过Source Generator实现零反射开销的工具定义。

写在最后

对想搞懂AI Agent内部原理的开发者来说，Learn Claude Code可能是目前最好的从零到一的学习路径。不需要什么前置知识，有Python基础就能跟。

学完之后再去看Claude Code或者任何Agent框架的源码，你会发现都和这个教程介绍的差不多。那种"黑盒子"的感觉会消失，取而代之的是一种"原来如此"的通透感。

AI编程助手确实很好用，但作为开发者，我们不应该只满足于用它们。了解它们是怎么工作的，不仅能让我们更好地使用它们，还能让我们有能力去创造它们。

而Learn Claude Code，就是帮你打开这扇门的钥匙。

GitHub项目地址：https://github.com/shareAI-lab/learn-claude-code

在线学习平台：https://learn.shareai.run

Kode CLI项目：https://github.com/shareAI-lab/Kode

Kode SDK项目：https://github.com/shareAI-lab/kode-sdk