30行代码就是一个完整的AI Agent——Claude Code源码精读一核心摘要大多数人谈起 Claude Code想到的是能写代码的 AI 助手。但如果你看它的源码会发现最核心的机制出奇地简单一个while True循环 一套工具调度表不到 30 行 Python就是一个完整 Agent 的骨架。本文是 Claude Code 源码精读系列的第一篇从最底层的 Agent Loop 出发逐步拆解工具系统和任务规划机制看清这套系统的地基。 为什么 LLM 自己跑不起来做过 API 调用的人都知道ChatGPT/Claude 默认是一问一答。你问它帮我列出这个目录下所有 Python 文件它会给你一段ls命令但它自己跑不了。这就是问题所在语言模型能推理代码但碰不到真实世界——不能读文件、跑测试、看报错。解法也很直接让外部程序替它跑命令把结果喂回去再问它下一步。这个外部程序就是Agent LoopAgent 循环。 第一层最简 Agent——30行骨架整个 Agent 的本质就是下面这张图图1Agent Loop 的完整数据流。User prompt 进入累积的 messages[]LLM 决定是否调工具工具结果追加回 messages[]循环直到 stop_reason 不等于 “tool_use”。LLM 调用工具 → 工具执行 → 结果喂回 LLM → LLM 决定下一步直到不需要调用工具为止。代码实现defagent_loop(query):messages[{role:user,content:query}]whileTrue:responseclient.messages.create(modelMODEL,systemSYSTEM,messagesmessages,toolsTOOLS,max_tokens8000,)messages.append({role:assistant,content:response.content})# 模型没有调用工具 → 任务结束退出ifresponse.stop_reason!tool_use:return# 执行所有工具调用收集结果results[]forblockinresponse.content:ifblock.typetool_use:outputrun_bash(block.input[command])results.append({type:tool_result,tool_use_id:block.id,content:output,})messages.append({role:user,content:results})关键只有两点messages是累积的——每次对话的历史全在里面LLM 看得到自己之前的决策退出条件只有一个stop_reason ! tool_use——模型主动交卷这就是所有后续机制的基础。不管是多 Agent 协作、上下文压缩还是任务系统底下都是这个不变的循环。 第二层工具系统——加工具不改循环只有bash工具时所有操作都走 shell。cat截断不可预测sed遇到特殊字符就崩更重要的是——bash 是无边界的没有路径限制。Claude Code 的解法是引入专用工具但关键洞察是加工具不需要改循环。图2工具调度架构。Agent Loop 永远不变新工具只需在 TOOL_HANDLERS 字典加一行 写一个 handler 函数Handler 内部通过 safe_path() 保证路径安全。dispatch map一个字典替代所有 if/elseTOOL_HANDLERS{bash:lambda**kw:run_bash(kw[command]),read_file:lambda**kw:run_read(kw[path],kw.get(limit)),write_file:lambda**kw:run_write(kw[path],kw[content]),edit_file:lambda**kw:run_edit(kw[path],kw[old_text],kw[new_text]),}循环中的分发只有三行handlerTOOL_HANDLERS.get(block.name)outputhandler(**block.input)ifhandlerelsefUnknown tool:{block.name}加一个新工具 在字典里加一行 写一个 handler 函数。循环永远不变。路径沙箱工具层面的安全边界defsafe_path(p:str)-Path:path(WORKDIR/p).resolve()ifnotpath.is_relative_to(WORKDIR):raiseValueError(fPath escapes workspace:{p})returnpath把安全逻辑封装在工具层面而不是依赖 bash 命令的行为。这是 Claude Code 工程哲学的体现每一层只负责自己的边界。组件初始版本引入工具系统后工具数1仅 bash4bash/read/write/edit分发方式硬编码dispatch map 字典路径安全无safe_path()沙箱Agent loop—不变 第三层TodoWrite——让模型不偏航为什么模型会跑偏做一个 10 步重构任务很多时候 Agent 完成 1~3 步之后就开始即兴发挥。原因不是模型笨是上下文被工具结果淹没了。每次工具调用的输出都会追加到 messages 里。10 个文件读取 10 次命令 20 条 tool_result轻松吃掉几万 token。System prompt 的影响力就被稀释了——模型还在处理任务只是忘了任务的全貌。解法给模型一个一直盯着的便条纸图3TodoWrite 的完整机制。任务状态从 pending → in_progress → completed 依次流转若连续 3 轮不更新 todo系统自动注入reminder制造问责压力关键约束同一时刻只能有一个 in_progress。TodoWrite 的核心是TodoManager维护一个带状态的清单并通过两个机制确保模型一直盯着它机制一同一时间只能有一个in_progressdefupdate(self,items:list)-str:in_progress_count0foriteminitems:ifitem.get(status)in_progress:in_progress_count1ifin_progress_count1:raiseValueError(Only one task can be in_progress)self.itemsvalidatedreturnself.render()这个约束强制模型聚焦——同一时刻只能宣称自己在做一件事。机制二Nag Reminder——追着模型问ifrounds_since_todo3andmessages:last[content].insert(0,{type:text,text:reminderUpdate your todos./reminder,})模型连续 3 轮不更新 todo系统就把提醒注入到下一轮 tool_result 前面。不是惩罚是问责压力——你不更新计划就会被追着问。为什么插在 tool_result 前面而不是单独发一条因为模型在看到最新工具输出的同时也看到了提醒两者被当成同一时刻的信息处理不会被后面的输出冲淡。效果一个自我监督的规划机制不需要外部人类干预仅靠框架层的规则维持任务进度。 三层基础机制总览把这三层机制的演进放在一起看基础版while True bash ↓ 引入工具系统while True dispatch map 4 tools safe_path ↓ 引入任务规划while True dispatch map 5 tools TodoManager nag reminder这三层加起来已经是一个可以完成多步代码任务的基础 Agent。后面所有机制——Subagent、上下文压缩、多 Agent 团队——都是在这个基础上叠加的循环本身始终不变。 几个反直觉的设计选择1. 为什么用累积消息而不是每次清零模型需要看到自己的历史决策才能做出一致的下一步。清零意味着失忆——之前读了什么文件、改了什么全忘。2. 为什么退出条件是stop_reason ! tool_use而不是其他这把控制权完全交给了模型——模型说我不需要再调工具了循环才结束。不设轮次限制只看模型的主动表态。3. 为什么只能一个 in_progress如此有效多任务并行看似高效实际上会让模型把注意力分散到多件事上最终每件事都做不彻底。串行聚焦的完成率反而更高。 下一篇预告这一层解决了单个 Agent 怎么跑的问题。但当任务越来越大上下文窗口就成了瓶颈——读 30 个文件、跑 20 条命令轻松突破 100k token。下一篇讲 Claude Code 的三个关键进阶机制Subagent怎么用独立上下文执行子任务让父 Agent 保持干净Skill 系统按需加载领域知识不塞满 system prompt三层上下文压缩micro_compact auto_compact reactive compact实现无限会话觉得有启发的话欢迎点赞、在看、转发。跟进最新 AI 前沿关注公众号机器懂语言