Claude Code 智能体循环完全指南：从 Agent Loop 到 Goal、Loop、Schedule 与 Proactive Automation
很多人第一次听到“智能体循环”时，会把它简单理解为：
让 AI 不断重复执行任务。
这个理解不能说完全错误，但过于粗糙。
真正有价值的智能体循环，不是让 AI 无限制地重复，而是设计一套完整机制：
- 什么条件触发智能体开始工作；
- 智能体每一轮具体做什么；
- 如何验证这一轮是否有效；
- 什么情况下继续下一轮；
- 什么情况下必须停止；
- 如何限制 Token、时间、权限和风险；
- 如何把一次性的人工操作，逐步升级为可持续运行的自动化系统。
Anthropic 将这种工作称为：
Loop Engineering：循环工程
循环工程不是单纯研究如何写 Prompt，而是研究如何设计一个智能体可以持续运行、持续检查、持续改进，并且能够安全退出的工作系统。
Anthropic 官方将常见的智能体循环分为四类：
- Turn-based Loop：基于对话轮次的循环；
- Goal-based Loop：基于目标完成情况的循环；
- Time-based Loop：基于时间间隔的循环；
- Proactive Loop：主动式、无人值守的循环。
这四种循环并不是四套完全不同的 Agent 架构，而是对同一个底层 Agent Loop 的不同控制方式。
它们最核心的区别在于：
- 谁负责触发下一轮；
- 谁负责判断任务结束；
- 人类需要参与多少；
- 工作是否依赖外部时间或事件；
- 循环能否脱离当前会话长期运行。
一、先理解底层：什么是 Agent Loop
在理解四类循环前，必须先理解 Claude Code 内部最基础的 Agent Loop。
Claude Code 官方将智能体的工作过程概括为三个阶段：
- 收集上下文；
- 执行动作；
- 验证结果。
这三个阶段会不断交替，而不是严格地只执行一次。
例如，当你让 Claude Code 修复一个测试失败问题时，它可能会：
- 运行测试；
- 读取错误信息；
- 搜索相关源码；
- 阅读源码；
- 修改代码；
- 再次运行测试；
- 如果仍然失败，继续分析；
- 如果测试通过，再检查是否引入其他问题；
- 最后返回结果。
这个过程可以抽象成：
接收任务
↓
分析当前状态
↓
决定下一步动作
↓
调用工具
↓
读取工具结果
↓
重新分析
↓
任务完成？
├─ 否 → 继续调用工具
└─ 是 → 返回最终结果
Claude Code Agent SDK 对底层循环的描述更加具体：
- Claude 接收用户 Prompt、系统指令、工具定义和历史上下文；
- Claude 判断下一步应该输出文本还是调用工具；
- 如果调用工具，SDK 执行工具；
- 工具结果重新进入上下文；
- Claude 根据新结果继续判断；
- 直到任务完成、发生错误或触发限制；
- SDK 返回最终结果、Token 使用量、费用和会话信息。
一个关键认识：单次对话本身就是循环
很多人以为只有 /goal、/loop 才算循环。
实际上，当你输入一句：
修复当前项目中失败的单元测试
Claude Code 已经开始了一次 Agent Loop。
它可能在一次回答中连续执行十几个动作：
读文件
→ 跑测试
→ 搜索代码
→ 修改代码
→ 再跑测试
→ 再修改
→ 最终返回
只不过，这些工具调用通常发生在同一个对话轮次中。
而 /goal、/loop 和 /schedule 的作用，是把循环从“一个模型回合内部”扩展到多个回合、多个时间点，甚至多个独立会话。
二、模型与工具：智能体循环的两个基础部件
Claude Code 官方将 Agent Loop 的核心能力概括为两个部分：
- 模型负责推理；
- 工具负责行动。
没有工具的模型，只能告诉你“应该如何做”。
拥有工具的智能体，则可以真正执行：
- 读取文件；
- 修改代码；
- 搜索项目；
- 运行 Shell 命令；
- 执行测试；
- 使用 Git；
- 搜索网页；
- 调用 MCP 服务；
- 创建子智能体；
- 操作外部系统。
Claude Code 内置工具大致包括五类：
| 工具类型 | 主要能力 |
|---|---|
| 文件操作 | 读取、修改、创建、重命名文件 |
| 搜索 | 搜索文件、正则搜索内容、浏览代码库 |
| 命令执行 | 运行测试、构建、Git、包管理器和脚本 |
| Web | 搜索文档、访问网页、查询错误信息 |
| 代码智能 | 查看类型错误、跳转定义、查找引用 |
每次工具调用都会产生新的信息，这些信息重新进入 Agent Loop，成为 Claude 下一步决策的依据。
一个简单案例
用户输入：
修复登录接口返回 500 的问题。
Claude 的循环可能是：
模型推理：
需要先找到登录接口。
工具：
搜索 login、signin、auth 等关键词。
工具结果：
找到 AuthController.ts。
模型推理：
需要阅读控制器和服务代码。
工具：
读取 AuthController.ts 和 AuthService.ts。
工具结果：
发现数据库查询结果可能为空。
模型推理：
需要查看测试和数据模型。
工具：
运行相关测试并读取错误日志。
工具结果：
Cannot read properties of null。
模型推理：
确认空对象处理缺失。
工具：
修改代码。
工具：
重新运行测试。
工具结果：
测试通过。
模型推理：
任务已经完成，返回总结。
这里真正让 Claude 成为“智能体”的，不只是模型聪明，而是模型能够：
观察 → 行动 → 获得反馈 → 调整行动
这就是智能体循环的本质。
三、四种智能体循环的完整分类
Anthropic 并不是按照“智能体有多聪明”来划分循环，而是按照四个维度划分：
- 如何触发；
- 如何停止；
- 使用什么 Claude Code 原语；
- 适合什么任务。
四种循环的总体区别如下：
| 循环类型 | 下一轮由谁触发 | 谁判断结束 | 典型工具 | 适合任务 |
|---|---|---|---|---|
| Turn-based | 用户再次输入 | Claude和用户 | 普通 Prompt、Skill | 一次性、探索性任务 |
| Goal-based | 上一轮结束后自动触发 | 独立评估模型 | /goal | 有明确验收标准的复杂任务 |
| Time-based | 时间到达 | 用户或Claude | /loop、定时任务 | 轮询、等待外部状态变化 |
| Proactive | 时间、API或事件 | 每次任务自己的目标条件 | Routine、Schedule、Goal、Workflow | 长期、重复、无人值守工作 |
可以把它们理解成四个自动化等级：
Turn-based
人决定是否继续
↓
Goal-based
目标条件决定是否继续
↓
Time-based
时间决定何时继续
↓
Proactive
外部事件或计划自动触发完整工作流
四、第一类：Turn-based Loop
1. 官方定义
Turn-based Loop 可以翻译为：
- 基于轮次的循环；
- 人工驱动循环；
- 对话式循环。
它的特点是：
- 触发方式：用户输入一个 Prompt；
- 停止条件：Claude 判断任务已经完成，或者需要用户补充信息；
- 适合任务：较短、一次性、探索性、不固定发生的工作；
- 成本控制方式：写清楚 Prompt，并提供可靠的验证方法。
在这种模式下，每一次用户输入都会启动一次 Agent Loop。Claude 收集上下文、采取行动、检查结果，然后把控制权交还给用户。
2. 运行结构
用户提出任务
↓
Claude 执行一轮 Agent Loop
↓
Claude 返回结果
↓
用户检查
↓
用户决定是否发出下一条指令
这里真正控制循环的人是用户。
3. 案例：增加一个点赞按钮
用户输入：
在文章详情页增加一个点赞按钮。
Claude 可能会：
- 查找文章详情页组件；
- 查看现有 UI 风格；
- 增加按钮和状态；
- 调用点赞接口；
- 运行前端测试；
- 返回结果。
然后用户检查页面，发现：
- 按钮功能正常；
- 但是移动端布局错位。
用户再输入：
修复移动端按钮错位，并检查 375px、768px 和桌面宽度。
这就是典型的 Turn-based Loop：
Claude 做一轮
→ 用户检查
→ 用户发下一轮
4. Turn-based 的优点
灵活
适合需求还没有完全确定的任务。
例如：
先分析这个模块为什么这么设计，暂时不要修改代码。
容易控制
每轮完成后都会回到用户手中，不容易持续消耗 Token。
适合探索
当你自己也不知道最终答案是什么时，人工介入非常重要。
例如：
- 评估三种架构；
- 理解陌生代码；
- 分析技术债；
- 调研实现方案；
- 设计产品原型。
5. Turn-based 的缺点
用户容易成为瓶颈
Claude 每做完一轮就停下来等你。
即使下一步非常明显，也需要你再次输入：
继续。
或者：
现在运行测试。
完成标准容易模糊
Claude 可能认为“代码已经写完”就是完成，但你认为还需要：
- 测试通过；
- 浏览器验证；
- 性能检查；
- 无控制台错误；
- 移动端适配。
6. 如何提升 Turn-based Loop 的质量
Anthropic 建议将人工验证步骤写成 Skill，使 Claude 能够在交付前自行完成更多检查。
例如，可以创建一个前端验证 Skill：
---
name: verify-frontend-change
description: 在宣布前端修改完成前执行端到端验证
---
# 前端修改验证流程
任何 UI 修改都不能仅凭代码编辑成功就宣布完成。
必须执行：
1. 启动开发服务器；
2. 在浏览器中打开被修改页面；
3. 直接操作新增或修改的控件；
4. 确认状态变化符合预期；
5. 检查浏览器控制台；
6. 确保没有新增错误和警告；
7. 检查移动端与桌面端布局；
8. 如果任何步骤失败，修复后重新从第一步验证。
这样，普通对话循环就会从：
修改代码 → 返回
升级为：
修改代码
→ 启动项目
→ 打开页面
→ 点击验证
→ 检查错误
→ 重新修改
→ 再验证
→ 返回
这类改进非常关键。
真正提升智能体质量的，通常不是不断增加 Prompt 长度，而是给 Agent 建立更可靠的验证闭环。
五、第二类：Goal-based Loop
1. 什么是 Goal-based Loop
Goal-based Loop 可以翻译为：
- 目标驱动循环；
- 完成条件驱动循环；
- 验收结果驱动循环。
在 Claude Code 中，主要使用：
/goal
实现。
它的特点是：
- 由用户实时启动；
- Claude 完成一轮后，不会立即把控制权交还给用户；
- 一个独立评估模型会检查目标是否达成；
- 如果没有达成，就自动开始下一轮；
- 达成目标或达到限制后才停止。
Anthropic 官方认为，它最适合：
已经知道“什么叫完成”的复杂任务。
2. Goal Loop 的运行结构
用户定义目标
↓
Claude 开始执行
↓
完成一个工作轮次
↓
独立评估器检查目标
↓
目标达成？
├─ 否 → 给出未达成原因 → Claude继续下一轮
└─ 是 → 清除目标 → 循环结束
关键点在于：
执行任务的模型和判断任务是否完成的模型，不是同一个判断过程。
官方文档说明，/goal 会在每轮结束后调用一个小型快速模型进行评估，默认通常使用配置中的快速模型，例如 Haiku。
评估器只返回：
- 是：目标已达成；
- 否：目标未达成，并给出原因。
如果返回“否”，这个原因会进入下一轮，指导 Claude 继续工作。
3. 为什么需要独立评估器
假设你让一个开发者完成任务，同时让他自己决定：
我做得够不够好？
他可能因为已经投入很多精力，而倾向于认为任务完成了。
智能体也存在类似问题：
- 它刚完成代码修改；
- 它知道自己的思路；
- 它可能过早认为问题已经解决；
- 它可能忽略没有验证的部分。
使用独立评估器，相当于让另一个没有参与执行的“验收人员”检查：
你说完成了，但证据在哪里？
测试是否真的通过？
目标中的每一项是否满足？
4. /goal 基本用法
最简单的写法：
/goal all tests in test/auth pass and the lint step is clean
设置目标后，会立即开始执行，不需要再单独发送一个任务 Prompt。
Claude 会持续工作，直到：
test/auth中所有测试通过；- lint 检查通过；
- 或者你主动取消目标。
5. 一个 Goal-based 案例
任务：
/goal 修复用户登录模块，直到 npm test exits 0，并确保没有修改 test 目录中的任何文件，最多执行 10 轮
循环可能如下：
第 1 轮
Claude：
- 运行测试；
- 发现三个失败；
- 修复身份验证逻辑；
- 再跑测试；
- 仍有一个失败；
- 尝试结束本轮。
评估器：
目标未达成：npm test 仍然返回退出码 1。
第 2 轮
Claude：
- 根据失败信息继续检查；
- 修复 Token 过期时间处理；
- 再次运行测试；
- 测试全部通过；
- 检查 Git diff；
- 发现没有修改 test 目录。
评估器：
目标已达成：npm test 返回 0，且 test 目录没有发生修改。
循环结束。
6. 如何写一个有效的 Goal
这是 /goal 最重要的部分。
官方文档建议，一个稳定的完成条件应包含三类信息：
- 可测量的最终状态；
- 明确的验证方式；
- 任务执行过程中的约束条件。
第一部分：可测量的最终状态
差的写法：
/goal 把代码优化好
问题在于“好”无法验证。
更好的写法：
/goal 将 src/order/OrderService.ts 拆分为职责明确的模块，并确保每个文件不超过 300 行
可以进一步写成：
/goal 将 OrderService.ts 拆分为多个模块，原文件和新文件均不超过 300 行，所有现有测试通过
第二部分：明确验证方式
差的写法：
/goal 修复所有问题
更好的写法：
/goal npm test exits 0 and npm run lint exits 0
验证方式最好是机器可执行的：
- 测试退出码；
- 编译结果；
- 文件数量；
- 文件大小；
- 队列是否为空；
- Lighthouse 分数；
- 类型检查结果；
- Git 状态；
- API 返回值。
第三部分：执行约束
例如：
/goal npm test exits 0，且不能修改 test 目录、数据库迁移文件和公开 API
约束条件用于防止 Agent 通过错误方式完成目标。
一个典型的错误完成方式是：
目标：让测试通过
Agent：删除失败测试
结果：测试确实通过了
从字面看目标达成，但从业务角度完全错误。
因此应写成：
/goal npm test exits 0，且不得删除、跳过或修改任何测试文件
7. 推荐的 Goal 模板
可以使用下面的结构：
/goal [最终结果]，
通过 [验证命令或验证方式] 证明，
同时不得 [禁止事项]，
如果无法完成或连续失败，则在 [轮数或时间] 后停止。
例如：
/goal 用户注册接口满足以下条件：
1. npm test -- auth/register exits 0；
2. npm run lint exits 0；
3. POST /api/register 对合法输入返回 201；
4. 重复邮箱返回 409；
5. 不得修改现有测试文件；
6. 不得改变公开 API 字段；
7. 或者执行 12 轮后停止并报告阻塞原因。
8. 必须设置停止上限
官方文档明确建议在目标中加入轮数或时间限制，例如：
or stop after 20 turns
Goal 条件最长可以达到 4,000 个字符，并且可以包含轮数或时间条款。
推荐写法：
/goal npm test exits 0 or stop after 10 turns
更完整的写法：
/goal 所有订单模块测试通过，npm test exits 0；
不得修改 test 目录；
如果 12 轮后仍未完成，停止修改并总结：
1. 已尝试的方法；
2. 当前失败原因；
3. 最可能的根因；
4. 建议由人工检查的内容。
这里有一个重要区别：
任务失败
不等于：
循环失控
一个设计良好的循环，即使没有完成目标，也应该在达到边界后有序退出，并留下足够信息供人接管。
9. 查看 Goal 状态
输入：
/goal
可以查看：
- 当前目标条件；
- 已运行时长；
- 已评估轮数；
- 当前 Token 消耗；
- 评估器最近一次未通过原因。
10. 清除 Goal
输入：
/goal clear
也可以使用以下别名：
/goal stop
/goal off
/goal reset
/goal cancel
11. Goal 与 Auto Mode 的区别
这两个概念容易混淆。
Auto Mode 解决的是工具权限问题
例如 Claude 想执行：
npm test
默认权限模式可能需要你点击同意。
Auto Mode 让 Claude 在一轮内部不必反复等待工具授权。
/goal 解决的是轮次继续问题
普通情况下，Claude 完成一轮后会停止。
/goal 会在一轮结束后检查条件，如果目标未达成，就自动启动下一轮。
因此：
Auto Mode：不用每次批准工具调用
/goal：不用每轮都由用户输入“继续”
两者可以组合：
Auto Mode + /goal
这样才能实现较完整的无人看守目标执行。官方文档也强调，/goal 本身不会改变权限设置。
12. Goal 与 Stop Hook 的区别
两者都会在每轮结束时检查是否继续。
但它们的定位不同：
| 项目 | /goal | Stop Hook |
|---|---|---|
| 作用范围 | 当前会话 | 配置范围内的多个会话 |
| 配置方式 | 会话中输入命令 | 写入配置文件 |
| 判断方式 | 模型评估 | 脚本或模型评估 |
| 适合 | 临时目标 | 固定团队规则 |
| 生命周期 | 会话级 | 持久化 |
例如：
临时目标
/goal 将当前模块迁移到新 API，直到编译和测试通过
使用 /goal。
所有任务都必须执行的固定规则
任何代码修改结束前都必须运行 npm test 和 npm run lint。
更适合写成 Stop Hook 或 Skill。
六、第三类：Time-based Loop
1. 什么是 Time-based Loop
Time-based Loop 可以翻译为：
- 时间驱动循环；
- 定时循环；
- 轮询循环。
它的特点是：
- 下一轮不是在上一轮结束后立即开始；
- 而是在指定时间到达后重新运行；
- 适合等待外部系统变化；
- 适合定期执行相同工作；
- 常用
/loop、定时任务或/schedule。
官方列出的典型场景包括：
- 等待部署完成；
- 持续关注 Pull Request；
- 检查 CI；
- 处理新的 Review 意见；
- 定时汇总 Slack 消息；
- 检查外部任务队列；
- 定期维护代码库。
2. Goal-based 与 Time-based 的根本区别
这两个循环最容易混淆。
Goal-based
上一轮结束
→ 立即检查目标
→ 未完成就马上继续
Time-based
上一轮结束
→ 等待一段时间
→ 到时间后重新运行
因此：
- 目标型循环适合内部可以持续推进的任务；
- 时间型循环适合需要等待外部变化的任务。
3. 错误使用案例
假设你刚提交了一个 PR，需要等待 CI。
不适合使用：
/goal CI 通过
因为 CI 可能要运行 15 分钟。
Claude 可能不断地：
检查 CI
→ 还没完成
→ 再检查
→ 还没完成
→ 再检查
这会产生无意义的 Token 消耗。
更合适的是：
/loop 5m 检查当前 PR 的 CI；如果失败，读取失败日志并尝试修复
这样 Claude 每五分钟检查一次。
4. /loop 基础写法
固定时间间隔：
/loop 5m check if the deployment finished
中文也可以写成：
/loop 5m 检查部署是否完成；如果失败，读取日志并分析原因
官方文档支持的时间单位包括：
s：秒；m：分钟；h：小时；d：天。
不过底层 Cron 的最小粒度是分钟，因此秒数会向上取整到分钟。某些无法整齐映射为 Cron 步长的间隔，也可能被调整到最接近的可用值。
5. /loop 的三种用法
方式一：间隔加任务
/loop 5m check the deploy
含义：
每五分钟运行一次“检查部署”。
方式二：只写任务
/loop check whether CI passed and address review comments
这种情况下，Claude 可以根据当前状态动态选择下一次检查时间。
例如：
- 构建正在进行时，一分钟后检查；
- CI 已经稳定但等待 Review 时，十分钟后检查；
- PR 长时间没有变化时，延长到一小时。
官方文档说明，动态间隔一般会在一分钟到一小时之间选择。
方式三：不写任务
/loop
Claude 会运行内置维护任务，大致包括：
- 继续当前会话未完成的工作；
- 关注当前分支对应的 PR；
- 处理 Review 意见；
- 修复失败的 CI；
- 处理合并冲突；
- 没有待办时执行 Bug 检查或简化工作。
也可以指定固定间隔：
/loop 15m
6. 使用 loop.md 定义默认循环
你可以在项目中创建：
.claude/loop.md
或者在用户目录创建：
~/.claude/loop.md
项目级文件优先级更高。
例如：
检查 release/next 分支对应的 Pull Request。
如果 CI 失败：
1. 获取失败任务日志；
2. 定位根因；
3. 提交最小修改；
4. 重新运行相关测试。
如果出现新的 Review 意见：
1. 逐条处理；
2. 回复对应线程；
3. 不要处理与当前 PR 无关的重构。
如果 CI 全部通过且没有新评论：
用一行文字报告当前状态。
之后只需输入：
/loop
Claude 就会以这份文件作为默认维护指令。
loop.md 的修改会在下一次循环时生效。官方同时建议保持文件简洁，超过 25,000 字节的内容可能会被截断。
7. 停止 /loop
在等待下一次触发时，可以按：
Esc
取消下一次唤醒。
固定间隔循环通常会持续到：
- 用户主动停止；
- 会话终止；
- 循环到期；
- 或达到系统设定的生命周期边界。
当前官方文档说明，会话级定时循环通常会在创建七天后自动到期，以避免遗忘的循环长期消耗资源。
8. /loop 的关键限制
会话级 /loop 并不是一个真正永久运行的服务器任务。
它存在以下限制：
- Claude Code 必须保持运行；
- 当前会话需要存在；
- Claude 正在回答时，定时任务会等到当前轮次结束；
- 错过的触发不会逐次补跑；
- 新建会话可能清除任务；
- 恢复会话时，只恢复尚未过期的任务；
- 固定循环存在七天到期机制。
因此，/loop 更适合：
我今天下午要盯着这个 PR
不适合：
未来一年每天检查生产系统。
9. 什么时候不应该使用轮询
轮询是最容易实现，但通常不是最高效的架构。
例如：
每 5 分钟检查一次 CI 是否失败
即使 CI 一整天没有变化，也会不断运行。
更好的方式可能是：
CI 失败时，CI 系统主动推送事件给 Claude。
两者区别是：
轮询
Claude：有变化吗？
系统：没有。
5 分钟后：
Claude：有变化吗？
系统：没有。
事件驱动
系统平时不做任何事。
CI 失败：
系统主动通知 Claude。
所以，时间型循环适合：
- 外部系统没有事件接口；
- 临时监控；
- 状态变化频率可预测；
- 实现成本优先。
如果系统支持 Webhook、API Trigger、GitHub Event 或消息推送，应优先考虑事件触发。
七、/loop、Desktop Task 与 Cloud Routine 的区别
Claude Code 官方提供了三类调度方式：
| 方式 | 运行位置 | 电脑需要开启 | 需要打开会话 | 适合场景 |
|---|---|---|---|---|
/loop | 本机当前会话 | 是 | 是 | 临时轮询 |
| Desktop Scheduled Task | 本机 | 是 | 否 | 需要本地文件和环境 |
| Cloud Routine | Anthropic 云端 | 否 | 否 | 长期无人值守工作 |
官方文档指出：
- Cloud Routine 的最小计划间隔通常为一小时；
- Desktop Task 和
/loop可以达到分钟级； /loop继承当前会话的工具和权限；- Cloud Routine 每次通常使用新的云端环境和仓库克隆；
- Cloud Routine 不依赖当前终端保持打开。
选择原则
选择 /loop
当你想：
接下来两小时，每五分钟检查一次这个部署。
选择 Desktop Task
当你想：
每天凌晨在我的电脑上扫描本地日志。
任务依赖：
- 本地文件；
- 本地工具；
- 内网环境；
- 本地数据库。
选择 Cloud Routine
当你想：
每天早上九点检查仓库中过期依赖并创建 PR。
而且希望：
- 笔记本关机后仍然运行；
- 不依赖当前会话；
- 长期持续；
- 可以通过 GitHub、API 或计划触发。
八、第四类：Proactive Loop
1. 什么是 Proactive Loop
Proactive Loop 可以翻译为：
- 主动式循环；
- 自主循环；
- 无人值守循环；
- 持续工作流。
它不是一个单独命令，而是多种 Claude Code 能力的组合。
它通常会组合：
/schedule或 Routine；/goal；- Skills；
- Auto Mode；
- Dynamic Workflows；
- 子智能体；
- GitHub 事件；
- API Trigger；
- MCP Connector；
- 独立代码审查 Agent。
Anthropic 将其定位为：
面向持续到来的、定义明确的工作流。
例如：
- 新 Bug 报告；
- Issue 分类；
- 依赖升级；
- 数据迁移；
- 文档同步；
- PR 审查；
- 告警处理；
- SDK 跨语言移植。
2. Proactive Loop 的结构
外部事件或计划触发
↓
创建新的 Agent 会话
↓
读取任务和相关上下文
↓
按照 Skill 或 Workflow 执行
↓
使用 Goal 判断单次任务是否完成
↓
审查结果
↓
提交 PR、回复消息或输出报告
↓
当前任务结束
↓
系统继续等待下一次事件
这里需要区分两个生命周期：
单次任务生命周期
例如处理一条 Bug：
Bug 被发现
→ 分析
→ 修复
→ 测试
→ 创建 PR
→ 结束
Routine 生命周期
Routine 一直处于启用状态
→ 等待下一条 Bug
→ 再创建新任务
因此官方描述为：
- 每次任务在目标完成后退出；
- 整个 Routine 会持续存在，直到用户关闭。
3. 一个完整案例：自动处理用户 Bug 反馈
目标：
每小时检查项目反馈频道中的新 Bug，自动分类、分析、修复，并回复处理结果。
可以拆成以下模块。
触发层
使用 /schedule：
/schedule every hour
或者配置一个 Cloud Routine。
输入层
通过 Slack Connector 获取：
#project-feedback
中的新消息。
筛选层
智能体判断：
- 是否真的是 Bug；
- 是否可以复现；
- 是否已有重复 Issue；
- 是否缺少必要信息；
- 严重程度；
- 影响范围。
Goal 层
针对本轮发现的问题定义：
本轮发现的所有有效 Bug 均已完成：
1. 分类；
2. 建立或关联 Issue；
3. 能自动修复的已创建 PR；
4. 无法修复的已记录阻塞原因；
5. 每条反馈均已回复。
执行层
针对每个 Bug：
- 创建隔离 Worktree；
- 一个 Agent 负责复现；
- 一个 Agent 搜索可能根因；
- 多个 Agent 并行尝试不同修复方案；
- 一个 Reviewer Agent 审查方案；
- 运行测试；
- 创建 PR。
权限层
通过 Auto Mode 或 Routine 的自动权限执行允许范围内的操作。
输出层
- 在 Slack 回复用户；
- 创建 GitHub Issue；
- 创建修复 PR；
- 输出本轮处理摘要。
官方博客给出的组合思路正是：
Schedule
+ Goal
+ Skill
+ Dynamic Workflow
+ Auto Mode
4. /schedule 与 Cloud Routine
Claude Code 当前官方文档中，Routine 处于 Research Preview，功能和限制未来仍可能变化。
Routine 本质上是保存下来的一套 Claude Code 配置，包括：
- Prompt；
- 一个或多个代码仓库；
- 环境；
- Connector；
- 触发器；
- 模型；
- 权限范围。
它可以被三类触发器启动：
Schedule Trigger
例如：
- 每小时；
- 每天；
- 工作日；
- 每周；
- 指定未来时间执行一次。
API Trigger
外部系统向专属 API Endpoint 发送 HTTP POST，触发一次新会话。
适合：
- Sentry 告警；
- 发布系统；
- 内部管理系统；
- 监控平台；
- 工单平台。
GitHub Trigger
例如：
- 新建 PR；
- PR 合并；
- Release 发布；
- Issue 创建；
- 指定仓库事件。
一个 Routine 可以同时配置多个触发器。
5. /schedule 基础示例
创建每日任务：
/schedule daily PR review at 9am
创建一次性任务：
/schedule clean up feature flag in one week
也可以：
/schedule tomorrow at 9am, summarize yesterday's merged PRs
管理 Routine：
/schedule list
/schedule update
/schedule run
通过 CLI 创建 /schedule 时，Claude 可能会继续询问：
- 具体时间；
- 使用哪个仓库；
- 每次运行的 Prompt；
- 需要哪些 Connector；
- 是否允许推送分支。
九、四种循环真正交接给 Agent 的是什么
Anthropic 的官方总结非常有价值。
不同循环，本质上是把不同决策权交给 Agent。
Turn-based：交出执行，但保留检查权
你交给 Claude：如何完成这一轮
你自己保留：是否继续
适合：
- 探索；
- 决策；
- 需求不明确；
- 高风险修改。
Goal-based：交出停止判断
你交给 Claude：持续执行
你交给评估器：判断是否完成
你负责：提前定义完成标准
适合：
- 测试可以验证；
- 编译可以验证；
- 队列可以清空；
- 指标可以量化。
Time-based：交出触发时机
你交给调度器：什么时候再运行
适合：
- 等待 CI；
- 等待部署；
- 等待 Review；
- 定期获取新输入。
Proactive：交出整个标准化流程
你只定义：
任务是什么；
成功是什么；
边界是什么；
权限是什么。
系统负责：
触发；
分析；
执行；
验证；
输出；
等待下一次任务。
十、如何选择正确的循环
可以用下面的决策流程。
第一个问题：一次 Agent Loop 能完成吗
如果能：
使用普通 Prompt
也就是 Turn-based Loop。
不要因为“智能体循环”听起来高级，就给所有任务套上复杂自动化。
第二个问题：是否有明确、可验证的完成标准
如果有：
使用 /goal
例如：
- 测试全部通过；
- 编译退出码为 0；
- 文件全部迁移；
- 队列为空；
- Lighthouse 达到 90；
- 所有 API 都符合 Schema。
第三个问题：任务是否需要等待外部状态变化
如果需要：
使用 /loop
例如：
- CI 尚未结束；
- PR 等待评论；
- 部署需要时间；
- 外部队列不断增加；
- 监控指标定期更新。
第四个问题：任务是否需要脱离当前会话长期运行
如果需要：
使用 Desktop Task、Cloud Routine 或 CI/CD
第五个问题：任务是否由事件自然触发
如果是：
优先事件触发，而不是时间轮询
例如：
PR 创建时自动审查
通常优于：
每 10 分钟扫描一次是否有新 PR
一张选择表
| 任务 | 推荐方式 |
|---|---|
| 分析一段代码 | Turn-based |
| 修改一个简单按钮 | Turn-based |
| 修复测试直到通过 | Goal-based |
| 完成重构直到满足验收条件 | Goal-based |
| 等待部署结束 | Time-based |
| 持续关注当前 PR | Time-based |
| 每天生成项目报告 | Cloud Routine |
| 新 PR 自动审查 | GitHub-triggered Routine |
| Sentry 告警自动生成修复 PR | API-triggered Routine |
| 长期自动处理 Bug 队列 | Proactive Loop |
十一、设计退出条件：循环工程最重要的能力
智能体循环最大的风险，不是 Agent 不工作，而是：
Agent 一直在工作，却没有真正接近目标。
常见表现包括：
- 在两个方案之间反复切换；
- 每次修改都会破坏其他测试；
- 不断重跑同一个命令；
- 重复阅读相同文件；
- 反复生成近似代码；
- 外部条件永远不会满足；
- 验收条件过于主观；
- Agent 用错误方式“完成”目标。
因此，一个成熟循环通常需要多层退出条件。
1. 成功退出
例如：
npm test exits 0
2. 最大轮数退出
例如：
or stop after 10 turns
3. 最大时间退出
例如：
or stop after 45 minutes
4. 连续无进展退出
例如：
如果连续三轮测试失败数量没有减少，停止并总结阻塞原因。
5. 重复行为退出
例如：
如果即将再次执行与前两轮相同的修改，停止并重新分析根因。
6. 权限边界退出
例如：
如果修复需要修改数据库 Schema、生产配置或公开 API，停止并请求人工确认。
7. 成本上限退出
例如：
如果 Token 使用超过指定预算，停止并输出当前进度。
8. 不可逆操作前退出
例如：
- 删除大量文件；
- 强制推送；
- 修改生产数据；
- 发布到生产；
- 关闭安全检查；
- 修改权限系统；
- 泄露或上传密钥。
应该明确写成：
执行任何不可逆操作前必须停止并请求人工确认。
十二、好的退出条件与坏的退出条件
坏例子一
/goal 把系统做好
问题：
- “系统”范围不明确；
- “做好”无法量化；
- 没有验证方式；
- 没有轮数限制；
- 没有禁止事项。
改进后
/goal 完成用户登录模块，使以下条件全部满足：
1. npm test -- auth exits 0；
2. npm run lint exits 0；
3. TypeScript 编译无错误；
4. 不得修改测试文件；
5. 不得改变现有 API 响应字段；
6. 不得添加新的生产依赖；
7. 如果 10 轮后仍未完成，停止并报告阻塞原因。
坏例子二
/loop 1m 优化代码
问题：
- 没有明确优化对象；
- 没有停止条件；
- 每分钟运行可能造成浪费；
- Agent 可能不断做无价值重构。
改进后
/loop 20m 检查当前 Pull Request：
1. 如果出现新的 Review 意见，逐条处理；
2. 如果 CI 失败，读取最新失败日志并修复；
3. 不处理与当前 PR 无关的重构；
4. 当 PR 已合并时停止循环；
5. 如果连续两次检查没有任何变化，只报告状态，不修改代码。
十三、验证闭环：为什么“写完代码”不等于完成
一个可靠的 Agent Loop 至少应该包括：
行动
→ 验证
→ 根据验证结果调整
而不是：
行动
→ 自我感觉良好
→ 宣布完成
不同任务的验证方式
后端代码
- 单元测试；
- 集成测试；
- 类型检查；
- lint；
- API Contract；
- 数据库兼容性；
- 性能基准。
前端代码
- 浏览器实际交互；
- 控制台无错误；
- 响应式布局；
- 截图对比；
- 可访问性检查；
- Lighthouse；
- 核心操作流程。
重构任务
- 行为不变；
- 测试通过；
- 文件体积目标；
- 依赖方向；
- 循环依赖检测；
- 公共 API 不变；
- Git diff 范围合理。
文档任务
- 每个接口是否都有说明；
- 代码示例是否能运行；
- 链接是否有效；
- 是否与当前版本一致；
- 是否覆盖全部验收项。
数据迁移
- 总记录数；
- 成功记录数；
- 失败记录数；
- 校验和；
- 抽样检查；
- 可回滚性；
- 源数据不可被破坏。
验证条件必须能够被评估器看到
/goal 的评估模型不会自行运行命令，也不会自行读取文件。
它只能根据当前对话中已经出现的信息判断。
因此，不要只写：
所有测试通过
还应要求 Claude：
运行测试，并在每轮结束前明确报告测试命令、退出码和失败数量。
因为只有测试结果进入对话上下文，评估器才能据此判断。
十四、代码质量：循环输出取决于外围系统
循环跑得久，并不意味着结果一定更好。
如果代码库本身存在：
- 命名混乱；
- 重复实现；
- 没有测试；
- 架构边界不清；
- 文档过期；
- 错误示例；
- 不一致的风格；
Agent 很可能继续模仿这些问题。
Anthropic 对维护循环质量提出了几项关键建议。
1. 保持代码库整洁
Agent 会学习和复制项目中已有模式。
如果项目中存在三种数据库访问方式，它很可能继续创造第四种。
2. 把“什么叫好”编码成 Skill
不要每次都在 Prompt 中重复：
- 如何测试；
- 如何审查；
- 如何验证 UI；
- 如何创建 PR；
- 如何处理迁移。
把这些固定流程写入 Skill。
3. 保证文档易于访问
框架和依赖版本会变化。
让 Agent 能访问当前版本文档，减少基于旧知识生成错误实现的风险。
4. 使用独立 Reviewer Agent
执行 Agent 会受自己此前推理影响。
一个拥有全新上下文的 Reviewer，更容易发现：
- 错误假设；
- 安全问题；
- 漏掉的边界条件；
- 不必要复杂度；
- 测试盲区。
5. 不要只修复一次失败，要升级系统
假设 Agent 连续三次忘记检查浏览器控制台。
低水平处理方式：
这次提醒它检查控制台。
更好的方式：
把浏览器控制台检查加入前端验证 Skill。
循环工程的核心不是让单次结果勉强正确，而是：
把失败经验沉淀为下一次循环可以自动遵守的系统规则。
Anthropic 官方也强调，当某次结果不达标时，不要只修当前问题，而应考虑如何改善未来所有循环。
十五、Token 与成本控制
循环会放大智能体的能力，也会放大成本。
1. 为什么循环容易消耗大量 Token
Claude 的上下文窗口可能包含：
- 历史对话；
- 文件内容；
- 命令输出；
CLAUDE.md；- 自动记忆；
- 已加载 Skill；
- 系统指令；
- 工具结果。
随着循环轮数增加，上下文不断扩大。Claude Code 会自动压缩上下文，但早期细节仍可能丢失。官方建议把持久规则放入 CLAUDE.md，并使用 /context 查看空间占用。
2. 选择最简单的机制
不要把所有工作都设计成 Proactive Loop。
一个简单格式化任务：
把这十个文件统一格式化
可能只需要脚本，不需要多 Agent 工作流。
3. 确定性工作优先交给脚本
例如：
- 文件重命名；
- 格式化；
- 生成固定报表；
- 批量替换；
- 数据校验；
- PDF 表单填写。
这些任务如果可以由脚本完成，通常不应该让模型每轮重新推理。
推荐架构：
Agent 判断需要做什么
→ 调用确定性脚本执行
→ Agent 验证脚本结果
而不是：
Agent 对每个文件逐个思考并修改
4. 设置明确的边界
至少应设置一个：
- 最大轮数；
- 最大时间；
- 最大任务数量；
- 最大文件范围；
- 最大 Token；
- 最大 Agent 数量。
5. 不要运行得过于频繁
如果一个外部状态平均每小时变化一次，就没有必要每分钟检查。
间隔应匹配被监控对象的变化频率。
6. 小范围试运行
动态工作流可能同时创建大量子智能体。
在处理全部仓库前，先对：
- 一个目录；
- 一个模块；
- 十个 Issue；
- 一个 PR；
进行试运行。
观察：
- 每个任务平均 Token；
- 成功率；
- 失败类型；
- 修改范围；
- 人工返工率。
再决定是否扩大。
7. 查看用量
官方博客提到，可以使用：
/usage
查看近期 Skill、子智能体和 MCP 的使用情况。
使用：
/goal
可以查看当前 Goal 的轮数和 Token 消耗。
使用：
/workflows
可以查看工作流中不同 Agent 的 Token 使用情况，并在必要时停止 Agent。
十六、权限与安全边界
智能体循环越自动化，权限设计越重要。
尤其是 Proactive Loop，因为任务运行时没有人在场。
1. 最小权限原则
Routine 只应该获得完成任务所需的权限。
例如一个文档检查 Routine，只需要：
- 读取代码；
- 读取文档；
- 创建
claude/前缀分支； - 创建 PR。
它通常不需要：
- 直接推送主分支；
- 删除仓库；
- 访问生产数据库；
- 访问全部 Slack 频道；
- 获取所有云资源权限。
2. Connector 不是只读能力
官方文档特别提醒，Routine 中启用的 Connector 可能包含写操作，并且无人值守运行时不会逐次询问权限。
因此应删除不需要的 Connector，而不是默认全部开放。
3. Routine 的操作会以你的身份出现
通过 GitHub、Slack、Linear 等 Connector 执行的操作，可能使用你的已连接身份：
- Commit 显示为你；
- PR 显示为你；
- Slack 消息显示为你；
- 工单操作显示为你。
因此不能把 Routine 当成“没有责任主体的机器人”。
4. 高风险操作保留人工闸门
推荐采用：
低风险动作自动执行
中风险动作创建草稿
高风险动作请求人工确认
例如：
| 风险 | 动作 |
|---|---|
| 低 | 读取日志、分类 Issue、运行测试 |
| 中 | 创建草稿 PR、生成迁移方案 |
| 高 | 合并 PR、发布生产、修改权限、删除数据 |
十七、三个完整实战模板
实战一：修复测试直到通过
适合 Goal-based Loop。
/goal 修复当前项目失败的测试，直到满足以下条件：
1. npm test exits 0；
2. npm run lint exits 0；
3. npm run typecheck exits 0；
4. 不得删除、跳过或修改任何测试；
5. 不得修改数据库 Schema；
6. 不得改变公开 API；
7. 每轮结束前报告：
- 当前失败测试数；
- 本轮修改内容；
- 验证命令及退出码；
8. 如果 10 轮后仍未完成，停止修改并输出：
- 已确认的根因；
- 已尝试方案；
- 当前阻塞；
- 建议人工检查项。
实战二：持续维护 Pull Request
适合 Time-based Loop。
/loop 10m 检查当前分支对应的 Pull Request：
1. 如果有新的 Review 意见，逐条分析并处理；
2. 如果 CI 失败，读取最新失败任务日志；
3. 只修复与当前 PR 相关的问题；
4. 修改后运行相关测试；
5. 不得强制推送；
6. 不得修改与当前功能无关的模块；
7. 如果 PR 已合并或关闭，停止循环；
8. 如果没有新变化，只报告当前状态，不做无意义修改。
实战三：每日自动维护依赖
适合 Proactive Loop 或 Cloud Routine。
每天工作日上午 9 点运行。
任务：
1. 检查仓库中的直接依赖；
2. 找出存在安全漏洞或稳定版本更新的依赖；
3. 忽略 major 版本升级，除非存在严重安全漏洞；
4. 每次最多升级三个依赖；
5. 为每个升级创建独立分支；
6. 运行：
- 单元测试；
- 类型检查；
- lint；
- 构建；
7. 测试全部通过时创建草稿 PR；
8. PR 中必须说明：
- 原版本；
- 新版本；
- 更新原因；
- 破坏性风险；
- 测试结果；
9. 如果升级失败，不得强行修改业务逻辑，只创建 Issue 记录阻塞原因；
10. 不得自动合并 PR。
这套设计中：
- Schedule 负责每天触发；
- Routine 负责创建无人值守会话；
- Skill 规定依赖升级流程；
- Goal 判断本轮是否完成；
- 测试提供确定性验证；
- PR 保留人工审查闸门。
十八、常见误区
误区一：循环越长，结果越好
错误。
如果目标错误、验证错误或上下文错误，循环越长只会让错误积累得越深。
误区二：/goal 就是无限自动执行
错误。
/goal 应该有可验证条件和轮数边界。
没有退出上限的 Goal 很容易成为成本黑洞。
误区三：/loop 会在后台永久工作
错误。
会话级 /loop 依赖当前运行环境，并且存在会话、恢复和七天到期等限制。
长期任务应使用 Desktop Task、Cloud Routine 或 CI/CD。
误区四：Auto Mode 会自动开始下一轮
错误。
Auto Mode 主要解决工具授权，不负责跨轮次继续。
/goal 才负责在上一轮结束后根据条件启动下一轮。
误区五：时间循环和事件驱动是一回事
错误。
时间循环主动轮询：
有变化吗？
事件驱动是在变化发生时被动接收通知。
有稳定事件源时，事件驱动通常更及时，也更节省资源。
误区六：Proactive Loop 是一个新命令
错误。
它是一种组合式工作架构，而不是单独的 /proactive 命令。
误区七：模型可以自行知道目标是否满足
不一定。
特别是 /goal 的独立评估器，只能看到对话中已经展示出来的信息，不会自行读取文件和运行命令。
误区八：给 Agent 更多权限一定更顺畅
短期可能更顺畅，长期风险会显著增加。
正确方式是：
给足完成任务所需权限，但不多给。
十九、从零开始学习 Loop Engineering 的推荐路径
第一阶段：掌握普通 Agent Loop
先使用普通 Claude Code 对话完成：
- 阅读项目；
- 修复简单 Bug；
- 增加小功能；
- 运行测试；
- 检查 Git diff。
重点观察 Claude 的：
收集上下文
→ 执行动作
→ 验证结果
第二阶段：建立验证 Skill
选择一个经常重复的人工检查流程，例如：
- 前端验证；
- API 验证；
- PR 检查；
- 数据迁移检查。
将它写成 Skill。
第三阶段：使用 /goal
从一个非常明确的目标开始：
/goal npm test exits 0，不得修改测试文件，最多 5 轮
不要一开始就让它改造整个项目。
第四阶段：使用 /loop
选择一个真正需要等待外部变化的场景：
/loop 10m 检查当前 PR 的 CI 和 Review
观察多少次检查真正产生了新信息，再调整间隔。
第五阶段：建立 Routine
选择一个：
- 重复发生；
- 输入结构稳定；
- 输出明确；
- 风险较低；
- 容易验证；
的任务。
例如：
每周检查文档与已合并代码是否不同步。
第六阶段：组合 Proactive Loop
最后再组合：
Trigger
+ Routine
+ Skill
+ Goal
+ Subagent
+ Review Agent
+ Human Approval
二十、最终结论
智能体循环的核心，不是让 AI 一直工作。
真正的核心是，把人类原本需要持续参与的某一部分决策，安全地交给系统。
四类循环分别交出了不同的控制权：
Turn-based：
把执行交给 Agent，人保留继续与否的决定。
Goal-based：
把持续执行和完成判断交给 Agent 与评估器。
Time-based：
把下一次执行时机交给调度器。
Proactive：
把标准化任务的触发、执行、验证和输出整体交给自动化系统。
一个高质量的 Agent Loop，至少应具有六个组成部分：
明确触发条件
+ 清晰任务边界
+ 可执行工具
+ 可验证成功标准
+ 安全退出条件
+ 权限与成本限制
可以把它概括为一个公式：
可靠智能体循环
=
触发器
× 明确目标
× 行动能力
× 验证闭环
× 退出机制
× 安全边界
只要其中任何一项接近于零，整个循环的可靠性都会大幅下降。
因此，Loop Engineering 的真正价值不是“让 Claude 多运行几轮”，而是：
把一次次临时 Prompt，逐步升级为有触发、有判断、有验证、有边界、能持续改进的智能体工作系统。
参考文档
Anthropic 官方博客
- Loop engineering: Getting started with loops
四种智能体循环的核心来源，介绍 Turn-based、Goal-based、Time-based 和 Proactive Loops。(Claude)
https://claude.com/blog/getting-started-with-loops
Claude Code 官方文档
- Keep Claude working toward a goal
/goal命令、目标条件、评估机制、退出条件和使用限制。(Claude)
https://code.claude.com/docs/en/goal - How the agent loop works
Claude Agent SDK 的底层 Agent Loop，包括模型推理、工具调用、工具结果回传和循环退出机制。(Claude)
https://code.claude.com/docs/en/agent-sdk/agent-loop - How Claude Code works
Claude Code 的整体运行机制，包括收集上下文、执行动作、验证结果和上下文管理。(Claude)
https://code.claude.com/docs/en/how-claude-code-works - Claude Code Commands
Claude Code 命令总览，可查询/goal等命令的最新语法。(Claude)
https://code.claude.com/docs/en/commands - Claude Code Overview
Claude Code 的产品定位、基本能力和官方文档入口。(Claude)
https://code.claude.com/docs/en/overview - Claude Code Best Practices
上下文控制、任务拆分、验证方式和长会话管理建议。(Claude)
https://code.claude.com/docs/en/best-practices - Claude Code Quickstart
Claude Code 的安装、启动和基础使用教程。(Claude)
https://code.claude.com/docs/en/quickstart - Claude Code Changelog
查询/goal、循环能力及其他 Claude Code 功能的发布时间和版本变化。(Claude)
https://code.claude.com/docs/en/changelog - Claude Code Documentation Index
Claude Code 官方完整文档索引，适合查找/loop、定时任务、Routine、Hook、Skill 等相关页面。
https://code.claude.com/docs/llms.txt
Claude Platform 官方补充文档
- How tool use works
解释模型如何发起工具调用、接收工具结果，以及服务端工具循环如何运行。(Claude Platform)
https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works - Tutorial: Build a tool-using agent
从单次工具调用逐步实现完整 Agent Loop 的官方实践教程。(Claude Platform)
https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent
前四个链接，它们分别对应：四类循环理论、Goal 循环、底层 Agent Loop、Claude Code 整体工作机制。