goal-loop

Agent /goal 循环

什么是 /goal

/goal 让 Agent 持续执行 plan → act → test → review → iterate。 如果一轮对话在达成目标前结束，它会自动继续，而不是等待输入。循环会在达到停止条件、用户暂停或触及 Token 预算上限时结束。它也被称为“Ralph 循环”。

在提供运行时指令前，请通过已安装 Agent 和界面的帮助信息、公开的工具或当前官方文档，检查是否支持目标功能。确认功能标志、身份验证和限制；不要把一个 Agent 的要求套用到另一个 Agent。生命周期状态、预算和暂停／恢复方式因运行时而异。

目标通过验证来强制执行约定。它不是预算命令、安全边界、“永远运行”，也不能替代 /plan。

何时使用

适用于有可验证停止条件的重复自主工作：测试通过、达到目标覆盖率、评估分数 ≥ X，或构建成功。对于代码任务，应先确保构建正常，并完成相关检查。任务时长没有最低要求。

适用场景：迁移、提升覆盖率、TDD 功能构建、带契约测试的重构、提示词／评估优化、部署重试循环、复现并修复 Bug。

不适用场景：探索性工作、模糊的“改进一下”、没有“完成”定义的任务、生产环境凭据、具有破坏性的共享基础设施操作。

4 部分约定（每个目标都需要）

1. 目标——用一句话描述一个具体结果。
2. 约束——哪些内容不得更改（公共 API、文件、库、约定）。
3. 验证命令——用于证明进展的确切 Shell 命令（pytest -q、pnpm test 等）。
4. 停止条件——可验证：“X 通过时停止”，或“需要人工／产品输入才能继续修改时停止”。

还要说明先阅读哪些内容、设置检查点，并记录简短的进度日志。

编写目标（核心交付物）

当用户要求编写目标提示词时，只以 Markdown 区块形式返回约定正文，每行一项。不要在前面加上 /goal——用户会在编辑器中添加该命令。

**Objective:** <one-sentence objective>
**Read first:** <files/PLAN.md/issue>
**Constraints:** <what not to change, libs, conventions>
**Validate:** <relevant checks during work and final acceptance command>
**Checkpoints:** work in checkpoints and log progress briefly
**Stop when:** <verifiable condition>, OR when further changes require human/product input

示例（迁移）

**Objective:** Migrate this project from Pydantic v1 to v2.
**Read first:** pyproject.toml, src/, tests/
**Constraints:** no public API changes; keep imports backwards-compatible via shims if needed; no new dependencies
**Validate:** run relevant tests during the migration; run `pytest -q` before declaring done
**Checkpoints:** work in checkpoints; log progress briefly
**Stop when:** full suite passes with zero deprecation warnings, OR when a change requires architecture decisions

示例（提升覆盖率）

**Objective:** Raise coverage in src/auth/ from ~38% to ≥75%.
**Read first:** src/auth/, tests/auth/, AGENTS.md
**Constraints:** no new deps; mirror existing test style; do not modify production code unless strictly required for testability
**Validate:** `pytest --cov=src/auth --cov-report=term-missing`
**Checkpoints:** work in checkpoints; log coverage delta each one
**Stop when:** coverage ≥75% AND all tests pass, OR when uncovered code needs design changes

编写规则

• 一个目标，一个停止条件。 不要写成待办事项列表。
• 当行为、设置或用法需要说明，或任务要求时，更新文档。
• 检查项应与改动和最终验收标准相匹配；不要要求每次编辑后都运行完整测试套件。
• 绝不要指示 Agent 创建新的 ADR——ADR 需要用户明确批准，因此目标提示词不得预先批准或鼓励创建 ADR。
• 禁止奖励作弊：“不要删除、跳过、削弱或缩小测试范围来让目标通过。”
• 遵守运行时的长度限制。较长的细节请链接至 PLAN.md／GOAL_BRIEF.md。
• 使用确切的路径、命令和问题编号。
• 明确禁止范围蔓延：“不要重构无关代码。不要添加依赖项。”
• 告诉 Agent 何时暂停：“如果 <条件>，请暂停并先询问。”

与另一个 Agent 一起起草

让第二个 AI 会话访问代码库。请它检查代码，指出假设、约束和边界情况，然后生成结构化的 4 部分约定。将该约定粘贴到目标 Agent 中。

Claude Code cmux 说明：Claude 完成后，可能会预填一条预测的下一条用户消息；该草稿来自 Claude，并非用户发言。

自行设定目标

仅当用户明确要求设定目标时，才使用受支持的目标创建工具，例如 create_goal。用户可以提供较高层次的意图：“检查此仓库，然后为自己编写一个带有可验证停止条件的 /goal 并执行。”请提供要阅读的文件、约束和验证命令。如果意图不够明确，请先提出澄清问题，再设定目标。

启动和控制目标

1. 确认 Agent、版本、接口，以及预期的工作目录或会话。
2. 检查它支持的目标命令/工具，以及任何设置或身份验证要求。
3. 使用该运行时支持的接口和约定的契约启动目标。
4. 确认目标处于活动状态，并了解如何检查、暂停/停止和恢复目标。

跨会话恢复前，请确认该运行时将目标状态存储在哪里，以及必须重新打开哪个会话。不要假设状态会在服务端持久保存、用户输入时会自动暂停、替换语义，或在预算刷新后可以恢复。

目标偏离时

• **轻微偏离：**发送纠正意见，并检查 Agent 是否已采纳。
• **目标宽泛：**使用运行时支持的暂停/停止控制，检查状态，然后收紧目标再恢复。
• **严重混乱：**停止目标，检查差异，并且只撤销已确认属于该次运行的更改。保留用户和其他 Agent 的工作；不要使用一键重置或暂存。重写目标后再重新启动。

及时纠正或停止偏离。

操作提示

• 定期使用运行时支持的命令或工具检查状态。每次监控检查都必须向用户提供一行简短更新，说明 Agent 正在做什么以及进展是否正常。
• **合并前务必检查差异。**人工监督仍然至关重要。
• 严格控制审批和沙盒设置；默认权限是正确的。
• 在开始通宵运行前，先从小任务开始，了解如何停止该运行时。通宵运行需要一台保持唤醒的机器；请参阅 合上笔记本电脑后如何让 Claude Code 继续运行。
• 将重复适用的策略写入 AGENTS.md，让每个目标都能继承这些要求，无需重复说明：完成前进行对抗性自审，即使测试通过也额外进行一轮 QA，以及使用标准验证命令。这样就不必在每段目标描述中反复写明这些要求。

故障排除

• **缺少目标命令：**在建议更新或更改配置之前，先检查已安装的 Agent 和接口是否支持该功能，以及相关设置要求。
• **无法启动或继续：**检查实际错误、目标状态、身份验证和限制。按照该运行时文档说明的恢复步骤操作。
• **没有已保存的目标：**在创建替代目标之前，先确认会话和持久化行为。