Agent 开发入门｜手写一个 Claude Code，机制很多循环就一个

大家好 ，我是想风！

如果想学习智能体开发，我一定推荐开源项目「Learn Claude Code」，一套 20 集的系列，从一个 while 循环讲到一整套 Claude Code。

智能体、多智能体是这一年最热的词。拆开看，都是同一个循环往上加东西。

这篇是系列的介绍入口文章：

先摊开 20 集的地图，再讲整个循环，最后分五段说每段在解决什么。

目录：

1. 这个系列是什么

2. 20 集地图

3. 核心就一个循环

4. 五段各在解决什么

5. 怎么看这个系列

6. 动手：先把 第一集 S01 跑起来

一、这个系列是什么

简单说，把 Claude Code 拆成 20 个机制，一集只讲一个。

底子是开源项目 learn-claude-code，每一集配一份能跑的 Python 教学代码。

第 1 集有102 行代码，就讲了一个循环，后续每集增加代码循序渐进！

真正的 Claude Code，光主循环文件 query.ts 就有 1729 行 近连钱行，会复杂得多。

一上来就读一堆代码读不下去。从 第一集的102 行开始，一集加一点，就读得下去。 指在让你读懂智能体开发各个环节要素，具备上手真正生产项目的基础

这就是整个系列的思路。

二、20 集地图

最后一集那句，就是整个系列的结论：机制很多，循环就一个。

三、核心就一个循环

没有循环之前，用 AI 写代码是这样的：

AI 说「帮我跑一下 npm test」，你复制命令，贴进终端，跑完，再把输出贴回去。

中间那个搬运工，是你。

S01 干的事，就是把你换成 20 行代码：

1. 把对话发给模型

2. 模型要用工具（stop_reason == "tool_use"），就执行，把结果塞回对话，回到第 1 步

3. 不要工具了，退出。

4. 就这三步伪代码演示如下：

while True:
    resp = 问模型(messages)            # 把整段对话发过去
    messages.append(resp)              # 模型的回复记进对话
    if resp.stop_reason != "tool_use": # 不要工具了，说明干完了
        break
    结果 = 执行工具(resp)              # 跑命令、读文件……
    messages.append(结果)              # 结果塞回去，再问一轮

代码里几个词，第一次见先认一下：

最小能跑的版本，见《最小版的智能体 Supervisor》——那篇用的就是这个循环，主管和手下共用一份。

后面每一集都长在这个循环上, 加工具、加权限、加压缩、加团队——循环本身一行不改。

四、五段各在解决什么

骨架：S01 到 S05

一个智能体最少要什么。

循环让它能自己跑，工具让它能动手，权限决定哪些手不能动。

钩子是在循环外面挂东西，比如每次执行工具前记一笔日志，不用改循环本身。

计划是先让它列清单，再一条条做，免得做到一半忘了要干嘛。

干得久：S06 到 S11

活一长，对话就会塞满。

S06 子智能体，等于开一个新终端去追一件事，追完关掉，只把结论写进笔记。它有全新的对话记录，最多跑 30 轮，回传的只有最后一句结论——回传整个对话列表，等于没隔离。

技能是按需加载的说明书，用到才读进来。

压缩是装不下了，把旧对话缩成摘要。记忆另开一层，压缩时不动它。

系统提示不是一段写死的话，是每轮按情况拼出来的。

错误恢复是 API 报错、限流时不崩，等一下再试。

干得多：S12 到 S14

一个目标拆成很多小任务，排好先后，存到文件里，不会聊着聊着就丢了。

慢的活丢到后台，跑完自己回来报。

到点自己醒，不用人一直盯着。

组队：S15 到 S18

一个智能体搞不定，就招人组队。

S15 里有一个 Lead 和几个队友。队友是一直在的同事，不是 S06 那种干完就散的临时工。队友之间靠文件收件箱传话，发一条消息，就是往文件末尾追加一行。

只有 Lead 能招人，队友不能再往下招。

S16 定队友之间的说话规矩，S17 让队友自己去任务板领活，S18 给每人一个单独的目录，改代码不打架。

外接与收尾：S19 到 S20

MCP 是外接工具的标准插口，别人写好的工具，按协议插上就能用。

最后一集把前面所有机制串成完整的一轮，回到开头那句：机制很多，循环就一个。

五、怎么看这个系列

建议的顺序：

1. S01 一定先看，把那份代码跑起来。后面每一集都是在它上面加东西，这一集没跑通，后面全是空中楼阁。

2. 每看一集，拿它的代码和上一集对比，看多了哪几行。

3. 看到 S06 和 S15，可以停下来自己写一个最小的多智能体，比如《最小版的智能体 Supervisor》那种。

新手最容易犯的错，是跳过前五集直接看组队。

组队那几集的代码，七八百行里大半是前面的机制。前面没看，就分不清哪些是在组队、哪些是在压缩、哪些只是在挡权限。

第 1 步怎么跑，本文第六段下一节一步步看。

六、动手：先把 第一集 S01 跑起来

如果你真要学点智能体开发知识，建议还是手动去学习的，甚至手写代码，学习是可以的。 工作为了效率、产出是不建议手写了，根据你实际来就好了！

光看不跑代码容易晕，循环里具体的逻辑处理是记不住的。

下面的命令按 Mac 写，Windows 不一样的地方单独标了。

要准备什么

• Python 3.10 以上。 终端里输 python3 --version 看一眼，低了就去 python.org 下载安装包。最新版的 anthropic SDK 要求 3.10。

• git。 输 git --version，能出版本号就行。Mac 第一次输会弹窗让装命令行工具，点安装。

• 一个 API Key。 官方的在 console.anthropic.com 申请。

如果用不了官方的也有办法。仓库里的 .env.example 列了几家兼容 Anthropic 格式的服务，国内能用的有 GLM、Kimi、DeepSeek、MiniMax，地址都写在里面。

那个文件自己也提醒了：兼容不等于行为完全一样。想要最稳，用官方的。

五步装好

git clone https://github.com/shareAI-lab/learn-claude-code   # 1. 把代码拉到本地
cd learn-claude-code                                         # 2. 进目录
python3 -m venv .venv && source .venv/bin/activate           # 3. 建一个独立环境并进去
pip install -r requirements.txt                              # 4. 装依赖：anthropic、python-dotenv、pyyaml
cp .env.example .env                                         # 5. 复制一份配置文件

第 3 步做完，提示符前面会多出 (.venv)。

这个独立环境的意思是：这次装的包只在这个目录里用，不弄乱电脑上别的 Python。

Windows 上，第 3 步后半句换成 .venv\Scripts\activate，第 5 步的 cp 换成 copy。

改配置：只动两行

Mac 上输 open -e .env，会用「文本编辑」打开它。

找到最上面这两行：

ANTHROPIC_API_KEY=sk-ant-xxx
MODEL_ID=claude-sonnet-4-6

• sk-ant-xxx 换成你的 Key

• MODEL_ID 换成你的 Key 能用的模型

用国内的兼容服务，再往下找到对应那一段，把 # ANTHROPIC_BASE_URL=… 那行开头的 # 删掉。

Key 填对方的，最上面的 MODEL_ID 改成对方的模型名。再保存，关掉编辑器。

如下所示例 deepseek API 配置运行效果

用Python 把代码跑起来

python s01_agent_loop/code.py   # 在 learn-claude-code 目录里跑

先出现 s01: Agent Loop 和一行英文提示，然后是输入提示符 s01 >>。

输一句话回车。网站上给的例子是这个：

s01 >> Create a file called hello.py that prints 'Hello, World!'

中文也行。

屏幕上会出现三种东西：

• 黄色、以 $ 开头的行——模型要跑的命令

• 紧跟着的几行——命令的输出，只显示前 200 个字符

• 最后一段普通文字——模型干完给你的话

这就是第三节那个循环在转。

模型说要跑命令 → 代码去跑 → 结果塞回对话 → 模型再看, 转到它不再要命令，就停了。

输 q 回车退出。在终端里输入执行 ls，hello.py 会真的在目录里，python hello.py 能跑。

再试一句 What is the current git branch?，能看到它自己去敲 git 命令。

它是真的在你电脑上执行命令。

代码里只拦了 sudo、rm -rf / 这几条，别让它去动重要目录。

错误集锦：跑不起来，先查这四处

• zsh: command not found: python

Mac 上默认只有 python3。激活了独立环境才有 python，或者直接用 python3。

• ModuleNotFoundError: No module named 'anthropic'

依赖没装上，或者装进了别的 Python。看提示符前有没有 (.venv)，没有就重新 source .venv/bin/activate，再装一次。

• KeyError: 'MODEL_ID'

没读到 .env，或者里面没有 MODEL_ID。看第 5 步那个 cp 跑没跑。

• Error code: 401，后面带 authentication_error

Key 不对。要么复制少了字符，要么 Key 和 ANTHROPIC_BASE_URL 不是同一家的。

和网站对不上的两处

网站上说 S01 是 102 行。截至 2026 年 10 月，仓库里的 s01_agent_loop/code.py 是 151 行。

多出来的是开头一大段说明注释、终端输入的兼容处理、Windows 的判断。循环本身还是那几行。

仓库 README 现在写的是「新版 17 章主线」，后面几章的编号和网站的 20 集对不上。

第一集S01 是同一个起点，先跑起这块代码就好不受影响的。

最后

Learn Claude Code 一共20 集，核心就是一个循环。学完你基本具备开发一个真实业务场景的智能体的上手条件。真实的开发能力还需要你的更多的生产实践经验！

先把那 102 行跑起来，剩下的每一集，就都是在回答一个问题：这个循环还缺什么。

这个项目 除了讲得比较细之外，最好的是他提供了源代码，直接可以上手运行！

下一篇：最小版的智能体Supervisor，用 S01、S06、S15 三集的原理，写一个只派活、不干活的主管。 #claudecode #agent

参考来源：

learn-claude-code 中文版（各集行数、工具数和机制描述出自这里） https://www.shoptofly.com/lcc/zh/

GitHub 仓库（第六节的安装命令、.env 配置和屏幕输出出自仓库 README 与 s01 代码） https://github.com/shareAI-lab/learn-claude-code

我是想风@xaiwind，一个关注出海与 AI、AIGC 的创作者。

本文基于AI辅助与个人实践融合创作，如果文章对你有帮助，欢迎点赞、收藏、关注，

本人文章持续修正、欢迎联系或者评论区见，每天进步一点，我们终会到达目的地！