01：Agent Loop：Claude Code 的运行时主循环
上一篇先把 Claude Code 放回工程系统里看。它更像一个能进入仓库、观察环境、调用工具、处理风险、验证结果的 coding agent。
沿着这个角度往下拆，第一条主线就是 Agent Loop。
工具、上下文、提示词、计划、权限、恢复、多 agent，后面都会单独讲。但这些模块最后都要挂到同一条运行链路上：
用户给出一个目标以后，Claude Code 如何一轮一轮地观察、判断、行动、接收反馈，直到任务完成、阻塞或需要用户决策？
这篇先把范围收窄到主循环本身：工具系统、提示词、上下文管理和权限细节，只看它们在主循环里的位置。后面第 02 篇会专门讲工具，第 03 篇讲提示词，第 05 篇讲上下文，第 07 篇讲权限，第 09 篇讲失败恢复。
这篇文章要拆的主线
这一篇回答的问题是：
Claude Code 如何把模型、工具、上下文、权限和验证组织进一个可持续推进的运行时主循环？
普通的大模型问答通常是一次请求响应。用户提出问题，模型根据已有输入给出答案。这个过程可以很强，但它主要发生在文本里。
Coding agent 面对的是另一种任务。用户通常希望它在真实仓库里完成一件事：
- “帮我修一下这个构建错误。”
- “根据现有风格加一个页面。”
- “看看这个接口为什么返回 500。”
- “把这段逻辑重构一下，别破坏测试。”
这些任务一开始只有目标，现场信息还很少。入口文件、错误根因、项目约定、验证方式，都要在运行过程中逐步找出来。模型需要先看现场，再决定下一步。
所以 Agent Loop 的意义，是让模型进入一个持续更新的工程现场。每一轮都拿到新的信息，每一轮都更新任务状态，每一轮都判断下一步是继续、停止，还是询问用户。
用一句话概括：
Agent Loop 是 coding agent 把模糊用户目标推进成可验证工程结果的运行时主循环。
为什么主循环要管理状态和反馈
“模型调用工具，然后继续问模型”，可以解释一个演示版本。
真实 coding agent 需要处理的问题要多得多：
- 工具可能成功，也可能失败。
- 命令输出可能很长，需要裁剪和摘要后再回到上下文。
- 用户可能拒绝某个权限请求。
- 修改文件以后，验证可能失败。
- 一轮搜索可能返回空结果，这个空结果本身也会改变下一步策略。
- 任务变长以后，agent 需要记住已经做过什么，还差什么。
所以主循环的重点在于维护状态、保留证据、控制风险、判断出口。
有资料把 Claude Code 的主循环描述成一个围绕queryLoop展开的运行时结构：每一轮都像一次状态转移，可以在不同阶段产出事件、等待工具结果、处理权限和继续推进[1][2]。
这类源码细节在这一篇点到即可。这里真正值得吸收的是工程思路：
主循环要能暂停、恢复、记录、分支和收束。
这也是 Claude Code 和简单工具调用 demo 的差别。demo 证明模型能调用工具就够了；生产级 coding agent 还要在工具失败、上下文变长、权限受限、用户插入新要求时继续保持任务方向。
主循环的工程形态：任务状态机
更合适的理解方式，是把 Agent Loop 看成一个任务状态机。
状态机这个词听起来有点硬，但放到 coding agent 里很直观：系统每一刻都处在某种任务状态里，然后根据新的观察结果进入下一个状态。
比如：
- 用户刚提出目标，系统处在“需要理解任务”的状态。
- 搜索找到了相关文件，系统进入“需要阅读证据”的状态。
- 已经定位修改点，系统进入“准备行动”的状态。
- 写文件前发现风险，系统进入“需要权限判断”的状态。
- 测试失败，系统进入“根据失败输出继续排查”的状态。
- 验证通过，系统进入“可以总结”的状态。
主循环真正做的事，就是不断完成这种状态转移。
这也解释了为什么很多看起来分散的机制都要接进 Agent Loop：
- 工具系统提供外部观察和行动能力，第 02 篇展开。
- 上下文管理决定哪些信息进入下一轮，第 05 篇展开。
- 计划和任务状态帮助长任务保持方向，第 06 篇展开。
- 权限系统决定哪些动作可以执行，第 07 篇展开。
- 可观测系统记录每轮发生了什么，第 08 篇展开。
- 失败恢复决定卡住以后怎么换路，第 09 篇展开。
也有资料把 Claude Code 的价值概括为多个模块挂到同一条运行链路上：工具、上下文、hook、subagent 围绕主循环协同工作[4]。
在 01 这里先只保留一个总判断：
Agent Loop 是所有运行时能力的总线。
一轮循环如何推进任务
把一轮主循环拆开看，大致会经历这些步骤。
接收目标。
系统先把用户的话变成当前任务目标。这里可以先得到一个可推进版本：这次是解释、调试、修改、重构，还是高风险操作。组装上下文。
系统把当前目标、已有对话、项目规则、相关文件片段、工具说明和任务状态放进本轮输入。提示词、记忆、上下文和任务状态的细节，会在第 03、04、05、06 篇分别展开。模型决策。
模型基于当前状态判断下一步：需要搜索、读文件、编辑、运行命令、验证，还是问用户。工具请求。
如果下一步需要接触仓库，就会转成工具调用。工具是 agent 接触真实环境的手。工具系统后面第 02 篇单独讲。权限判断。
读文件、写文件、运行命令、访问外部系统的风险不同。主循环需要在工具执行前接入权限判断。这里先标注位置，第 07 篇再展开。工具执行。
工具真正去读文件、搜索代码、修改文件或运行命令。执行结果会改变系统能看到的事实。观察结果更新。
工具结果会回到任务状态里。成功输出、错误信息、diff、测试结果、权限拒绝，都会影响下一轮。进入下一轮判断。
系统判断现在该继续、停止，还是询问用户。
这个过程可以画成一条闭环：
用户目标 -> 当前任务状态 -> 本轮上下文 -> 模型决策 -> 工具请求 -> 权限判断 -> 工具执行 -> 观察结果 -> 更新任务状态 -> 停止 / 继续 / 询问用户这个闭环里最重要的是最后两步：工具结果会从工具层回到任务状态，成为下一轮输入。
如果读文件成功，下一轮就基于文件内容继续判断。
如果测试失败，下一轮就基于失败输出继续定位。
如果权限被拒绝，下一轮就要换一个低风险策略，或者向用户解释为什么需要这一步。
如果搜索返回空结果，下一轮也要调整关键词、换入口或说明当前线索不足。
所以 Agent Loop 更像：
模型决策和环境反馈之间的循环协议。
任务状态：主循环真正维护的东西
普通聊天里，流动的是文本。上一轮说了什么，下一轮接着说。
Coding agent 里，流动的是任务状态。文本仍然存在，但它要被组织成更稳定的结构，否则任务一长就容易丢线索。
一个主循环至少要维护这些状态：
| 状态 | 它回答的问题 |
|---|---|
| 目标 | 用户这次到底要完成什么 |
| 上下文 | 当前已经掌握哪些项目事实 |
| 计划 | 接下来准备怎么推进 |
| 工具结果 | 刚才的搜索、读取、编辑、命令返回了什么 |
| 改动 | 仓库里已经发生了哪些变化 |
| 证据 | 有哪些信息证明任务接近完成，或证明还没完成 |
| 风险 | 下一步是否可能越界，是否需要确认 |
| 阻塞点 | 当前为什么卡住 |
| 下一轮理由 | 为什么要继续、停止或询问用户 |
这里的“下一轮理由”很关键。
一个可靠的 agent 每次继续都应该有原因：
- 因为搜索发现了相关文件。
- 因为错误输出暴露了新的调用点。
- 因为验证失败给了可追踪的线索。
- 因为权限拒绝后需要换成只读观察。
- 因为目标已经满足，可以停止。
- 因为缺少业务判断，需要问用户。
缺少这个理由时，主循环就容易变成“多试几次”。多试几次有时能碰巧成功，稳定性很弱。
Claude Code 这类工具最值得学的地方，也在这里：它把模型的临场判断放进一个受控的任务状态里，让长任务沿着状态推进。
失败反馈：下一轮判断的重要输入
很多系统把失败当成终点：命令报错，任务失败；测试报错，任务失败；权限被拒绝，任务失败。
对 coding agent 来说，失败经常是最有价值的观察结果。
测试失败告诉它哪里没满足预期。
构建报错告诉它语法、依赖或路径哪里有问题。
搜索无结果告诉它当前关键词可能错了。
权限拒绝告诉它当前动作风险太高，或者用户更希望换一种路径。
命令缺失告诉它项目的验证方式需要重新判断。
资料里也反复提到，Claude Code 的主循环周围有很多工程守卫：权限拒绝要进入后续判断，失败和压缩问题要有降级路径，工具输出过大还要进入上下文处理链路[2][3]。
这一篇先看这些守卫对主循环的意义：
失败是下一轮状态的一部分。
这句话非常重要。
如果构建失败，agent 先提取失败里的有效信号：哪个文件、哪一行、哪个模块、哪个命令、哪个依赖。然后决定下一轮是读文件、搜索调用方、修改代码，还是说明当前环境缺失。
当然，失败也需要预算。连续几轮都缺少新信息时，主循环要停下来。好的恢复会判断“继续这样试的收益已经很低”。这部分会在第 09 篇展开。
循环控制器：什么时候继续、停止或询问用户
Agent Loop 最容易被忽略的能力，是停止。
很多人谈 agent 时会强调“它能自动执行多少步”。对真实工程任务来说，一个可靠的 agent 还必须知道什么时候停、什么时候问、什么时候说明当前卡点。
主循环每一轮结束时，至少有三类出口。
继续。
还有明确的新线索，继续执行有收益。比如测试失败给出了新的文件路径，或者搜索结果指向了关键模块。停止。
目标已经满足，验证证据足够，或者继续执行收益很低。停止时要总结做了什么、改了什么、验证了什么。询问用户。
当前问题需要用户做业务判断。比如有两个业务方案，或者下一步动作风险较高，或者权限不足。
这三个出口可以整理成一张表：
| 控制选择 | 触发条件 | 输出 |
|---|---|---|
| 继续 | 有新证据，下一步清楚，风险可控 | 进入下一轮观察或行动 |
| 停止 | 完成条件满足，验证足够 | 总结结果和验证情况 |
| 询问用户 | 需要业务判断、权限确认或风险确认 | 给出清楚的问题和选项 |
| 阻塞停止 | 多轮缺少新进展，或环境缺失 | 说明卡点和已尝试路径 |
这里的关键是“控制选择要有理由”。
一个成熟的 agent 最终给用户的，应该是一份当前状态：
- 改了什么。
- 为什么这么改。
- 用什么验证过。
- 哪些验证还缺失。
- 还剩什么风险。
这让用户能接管，也让后续恢复有依据。
案例解析：博客构建失败如何被逐步收敛
用一个常见任务看得更清楚：用户说“博客页面构建失败了，帮我修一下”。
普通问答可能会回答：
请检查依赖是否安装、语法是否正确、路径是否存在。
这个回答方向合理，但任务还停在建议层。coding agent 的主循环更像一串事件。
事件 1：接收目标 用户目标被识别为：修复博客页面构建失败。 当前完成条件暂定为：构建命令通过，且改动范围集中。 事件 2：观察项目 读取 package.json，确认构建命令。 运行构建命令，拿到具体错误输出。 事件 3：更新状态 错误指向某个 Markdown 文件的 frontmatter。 任务状态里新增相关文件、错误信息和可能修改点。 事件 4：行动前判断 修改 Markdown 属于低到中风险写入。 如果文件已经有用户改动，需要先确认；如果当前没有冲突，可以继续最小修改。 事件 5：执行修改 只修改出错字段，改动范围保持集中。 事件 6：验证 重新运行构建。 如果仍然失败，把新的错误输出放回状态，进入下一轮。 如果构建通过，检查本轮改动范围。 事件 7：停止 总结错误原因、修改内容、验证命令和结果。这条轨迹里，最重要的是状态如何变化。
第一次构建失败把模糊目标变成了具体线索。第二次构建通过是停止条件的一部分。中间每一步都在回答同一个问题：当前状态是否足够支持下一步？
对我写 Agent 的启发：先设计运行时契约
如果要自己写一个 coding agent，第一版可以先放慢：工具少一点，提示词短一点，主循环清楚一点。
更应该先设计运行时契约。
所谓运行时契约，就是主循环里哪些东西必须被结构化保存，哪些动作必须有记录，什么时候可以继续，什么时候必须停。
我会先设计五个对象。
| 对象 | 作用 |
|---|---|
| 任务状态 | 保存目标、上下文、计划、改动、证据和阻塞点 |
| 工具结果 | 统一描述工具是否成功、返回了什么、是否改变环境 |
| 下一轮理由 | 记录为什么继续、停止或询问用户 |
| 停止条件 | 定义什么叫完成、阻塞、越界或预算耗尽 |
| 失败预算 | 限制同类失败重复出现的次数 |
这个版本很朴素，但它已经比“用户目标进来，模型直接回答”稳定很多。
它至少能保证四件事：
- 任务有状态，减少模型在长上下文里硬记。
- 工具有反馈，模型能基于真实环境继续判断。
- 失败有去处，报错以后还能转成下一轮输入。
- 循环有出口，执行过程能自然收束。
如果继续往后做，再逐步接上工具系统、上下文压缩、权限裁决、任务计划和可观测日志。
这些模块都是主循环变长以后需要的支撑结构。
下一篇：工具系统如何让主循环真正行动
这一篇先把 Agent Loop 当作 Claude Code 的运行时主线来理解。
这条主线的结论是：
Claude Code 会把用户目标、项目环境、工具结果、权限判断和验证反馈组织进一个持续循环，让任务逐渐收敛。
主循环本身负责组织过程。
真正让 agent 能读仓库、改代码、跑测试、拿到反馈的，是工具系统。
所以下一篇继续追的问题是：
一个 coding agent 的最小工具集是什么？工具结果又是怎么回到下一轮判断里的？
参考资料
Claude Code 源码分析
[1] 《驾驭工程：从 Claude Code 源码到 AI 编码最佳实践》
本文主要参考它关于主循环、状态重建、错误恢复和工程化拆解方式的分析。
[2] What Claude Code’s Leaked Source Actually Teaches Us About Building AI Agents - Kubesimplify
本文主要参考它关于主循环是状态机、工具结果回流、权限降级和成本工程的分析。
[3] What the Claude Code Source Leak Reveals - Blake Crosley
本文主要参考它关于权限守卫、失败检测、缓存风险和工程边界的分析。
[4] Diving into Claude Code’s Source Code Leak - Engineer’s Codex
本文主要参考它关于主循环与工具、上下文、hook、subagent 等模块挂接关系的分析。
