agent-Specialization/goal_research.md

AI 编码 Agent 自主工作循环调研报告

一句话总结：/goal 命令真实存在。 Claude Code（v2.1.139, 2026年5月12日发布）和 OpenAI Codex CLI（v0.128.0+）都内置了 /goal 这一斜杠命令，用于设置"完成条件"让 Agent 跨多轮持续工作直到目标达成。两者实现机制不同但目标一致：打破"模型停 = 任务完"的默认假设，通过额外的验证步骤判断任务是否真正完成。

---

第一部分：命令真实性核查

1. Claude Code 的 /goal 命令

✅ 真实存在。

Claude Code 于 2026 年 5 月 12 日发布的版本 2.1.139 中引入了 /goal 命令。Anthropic 官方文档将其描述为：

"Set a completion condition with /goal and Claude keeps working across turns until the condition is met."（用 /goal 设置完成条件，Claude 会跨多轮持续工作直到条件满足。）

官方文档核心描述：

• 用法：/goal all tests in test/auth pass and the lint step is clean
• 每个 turn 结束后，一个独立的轻量级 evaluator model（默认使用 Claude Haiku）会读取对话 transcript，检查条件是否满足
• Evaluator 不运行命令、不读取文件，仅基于对话中已有的输出来判断
• 条件必须是可观测的（如测试通过、lint clean）而非模糊描述（如"让应用变得更专业"）
• 可用 /goal（无参数）查看当前状态：已用 turn 数、token 消耗、最后 evaluator 的判断理由

来源：

• 官方文档：https://code.claude.com/docs/en/goal
• 官方对比 /goal vs /loop vs Stop hooks 三种自主机制：同上页面的 "Compare to other autonomous workflows" 表格
• 社区分析文章（非官方，但引用了官方文档）：https://blog.dailydoseofds.com/p/claude-codes-goal-command

---

2. Codex CLI 的 /goal 命令

✅ 真实存在。 在 Codex 社区中常被称为 "Ralph Loop"。

OpenAI 官方 Cookbook 中有一篇专门的指南 "Using Goals in Codex"，详细介绍了其用法和设计哲学。从 Codex 0.128.0 版本开始可用。

官方 Cookbook 核心定义：

"A Goal gives Codex a completion condition: what should be true, how success should be checked, and what constraints must stay intact. ... Goals are for tasks where the next step depends on what Codex learns along the way."

用法示例：

/goal Reduce p95 latency below 120 ms without regressing correctness tests

生命周期管理：

• /goal — 查看当前 Goal
• /goal pause — 暂停
• /goal resume — 恢复
• /goal clear — 清除

官方推荐 Goal 写作六要素：

1. 期望结束状态
2. 验证方式（具体证据）
3. 约束条件（什么不能改变）
4. 允许的输入/工具/边界
5. 各轮次之间如何选择下一步
6. 被阻塞时如何报告

来源：

• 官方 Cookbook：https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
• 官方 CLI 参考：https://developers.openai.com/codex/cli/reference
• OpenAI 官方博客（Agent Loop 技术细节）：https://openai.com/index/unrolling-the-codex-agent-loop
• 社区评测（非官方）：https://kingy.ai/ai/openai-codex-goal-the-new-long-horizon-mode-for-agentic-coding
• GitHub 讨论（非官方）：https://github.com/openai/codex/discussions/22749

---

3. 结论来源汇总

结论	来源类型	链接
Claude Code /goal 真实存在	官方文档	https://code.claude.com/docs/en/goal
Codex CLI /goal 真实存在	官方 Cookbook	https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
Claude Code /goal 使用 Haiku 做 evaluator	社区分析（引用官方文档）	https://blog.dailydoseofds.com/p/claude-codes-goal-command
Codex 从 v0.128.0 起支持 Goals	官方 Cookbook	同上 Cookbook
Codex Agent Loop 技术细节	OpenAI 官方博客（Michael Bolin 撰写）	https://openai.com/index/unrolling-the-codex-agent-loop
Codex 开源代码仓库	GitHub（官方）	https://github.com/openai/codex

---

第二部分：自主循环的实现机制（核心）

4. Agent 如何判断"任务还没做完、需要继续"？

这是核心技术问题。两个工具采用了不同的方案：

Claude Code /goal 的循环控制逻辑

1. 每个 turn 结束后触发 evaluator：Claude 完成一个 turn（读取文件、运行命令、编辑代码等工具调用完成并输出 assistant message），evaluator model 被调用
2. Evaluator 接收：完整的对话 transcript + 用户设置的完成条件
3. Evaluator 判断：条件是否已满足（基于 transcript 中的证据）
4. 不满足 → 自动开启新 turn：条件未满足时，Claude 继续工作
5. 满足 → 停止：evaluator 判断条件达成，循环结束

关键设计：Evaluator model 是独立的、轻量级的模型调用（默认 Claude Haiku），不共享主工作模型的上下文。它仅做"裁判"，不参与实际工作。这是打破"模型停止输出 = 任务完成"假设的核心机制。

Codex /goal 的循环控制逻辑

Codex 的实现更加工程化，它是一个 thread-scoped（线程级）的持久化状态机：

1. Goal 作为持久化线程状态：Goal 不是全局内存或项目指令，而是绑定到当前线程的持久状态记录（包含目标、生命周期、预算、进度）
2. 事件驱动的 continuation：Codex 仅在安全的边界检查是否应继续：
   • 上一个 turn 已完成
   • 没有其他工作正在 pending
   • 没有用户输入排队
   • 线程处于空闲状态
3. Plan-only 不触发继续：如果上一个 turn 只是"计划模式"（只读），不会自动触发下一轮
4. 空转抑制：如果 continuation turn 没有做任何 tool call，下一次自动继续被抑制，防止空转烧钱
5. 基于证据的完成判定：Codex 必须将"目标 vs 具体证据"进行对比——修改的文件、运行的命令输出、测试结果、benchmark 输出等

两种方案的本质差异

维度	Claude Code /goal	Codex /goal
完成判定者	独立 evaluator model（Haiku）	主工作模型 + 硬编码规则
判定依据	对话 transcript	对话 transcript + 硬编码状态检查
继续触发	evaluator 判断"未完成"	事件驱动（idle + active + no input）
空转防护	依赖 evaluator 判断	硬编码抑制（无 tool call 则停止下次自动继续）

来源：

• Claude Code 官方文档（evaluator 说明）：https://code.claude.com/docs/en/goal
• Claude Code /goal 社区深度分析：https://blog.dailydoseofds.com/p/claude-codes-goal-command
• Codex 官方 Cookbook（架构设计详解，含架构图）：https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
• Codex Agent Loop 官方博客（turn 概念）：https://openai.com/index/unrolling-the-codex-agent-loop

---

5. "模型停止输出文本 = 任务完成"的默认假设，它们是怎么打破的？

Claude Code：独立的 Evaluator 审查步骤

• 不是模型自己说"我做完了"：主工作模型完成 turn 后输出 assistant message（如"我已经修好了 bug"），但这不等同于 Goal 完成
• Evaluator model 是独立的审查者：它是一个独立的模型调用（默认 Haiku），只读取对话 transcript，对照完成条件做判断
• 模型"相信"不算，证据才算：官方文档要求条件必须基于可观测输出（如测试通过、lint clean），排斥模糊条件（如"看起来很棒"）

Codex：硬编码的"证据审计"步骤

• must be evidence-based（必须基于证据）：官方 Cookbook 反复强调，"A Goal should not be marked complete because the model believes it is probably done"
• 多层次的验证：
  • 硬编码检查：文件变更、命令执行结果、测试输出
  • 模型辅助判断：对比目标与证据，给出是否完成的判断
• 每轮结束后都有一个"检查点"：Codex 在 turn 完成后检查 Goal 状态，而不是模型随时可以声明"完成"
• 预算耗尽时明确区分：budget 耗尽 ≠ 目标完成，Codex 必须区分两者并总结 blocker

关键差异

审查方式	Claude Code	Codex
审查者	独立 evaluator model	主模型 + 硬编码规则
审查时机	每个 turn 后	每个 turn 后的 idle 检查点
证据要求	对话中可见的输出	对话中的证据 + 系统状态

来源：

• Claude Code 官方文档 How evaluation works：https://code.claude.com/docs/en/goal
• 社区文章详解 evaluator loop：https://blog.dailydoseofds.com/p/claude-codes-goal-command
• Codex Cookbook "How Goals are designed" 章节：https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
• OpenAI 安全博客 Auto-review（相关机制）：https://alignment.openai.com/auto-review

---

6. 是否用到 plan / todo / task list 结构来追踪进度？

Claude Code

• Claude Code 的 Agent SDK 有内置的 TaskCreate / TaskUpdate 工具（在 SDK 工具列表中明确列出）
• /goal 的官方文档未明确提到必须使用 task list 来驱动循环；evaluator 直接判断条件是否满足
• 但从 SDK 文档看，task 工具是可用的编排能力（https://code.claude.com/docs/en/agent-sdk/agent-loop）

Codex

• Codex 有内置的 update_plan 工具（在 OpenAI 官方博客的 Agent Loop 文章中有代码示例）
• 对于 Goal 模式，Cookbook 的架构描述中提到 "Goal records the objective, lifecycle, budget, and progress accounting"
• Goal 本身作为 thread 的状态，承担了"进度追踪"的角色
• 使用模式是**"目标 + 当前证据 + 下一步"**，而非严格的 checklist 式 todo

结论

两个工具都没有将"todo list 全部勾选"作为循环继续/停止的唯一依据。而是采用**"条件 vs 证据"**的判定模式。Plan/task 工具是辅助模型组织工作的手段，不是硬编码的循环控制逻辑。

来源：

• Claude Code SDK 工具列表（含 TaskCreate/TaskUpdate）：https://code.claude.com/docs/en/agent-sdk/agent-loop
• Codex blog Agent Loop 中 update_plan 工具代码：https://openai.com/index/unrolling-the-codex-agent-loop
• Codex Cookbook How Goals are designed：https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex

---

7. 防止死循环和失控的机制

Claude Code /goal

机制	详情	来源
无内置 token budget	/goal 本身没有 token 或金钱上限；官方建议在条件中显式加 stop after 20 turns	https://code.claude.com/docs/en/goal
Agent SDK 层 max_turns	通过 SDK 编程使用时，可设置 max_turns 和 max_budget_usd	https://code.claude.com/docs/en/agent-sdk/agent-loop
手动中断	Ctrl+C 或 /goal clear 随时中断	同上
Trust dialog 限制	/goal 仅在用户接受信任对话框的工作区可用	同上
Hooks 限制	disableAllHooks 或 allowManagedHooksOnly 设置时 /goal 不可用	同上
Context window 管理	SDK 支持自动 compaction（PreCompact hook），防止上下文溢出	https://code.claude.com/docs/en/agent-sdk/agent-loop

Codex /goal

机制	详情	来源
Budget accounting（预算核算）	Goal 状态中包含预算；达到预算时停止实质性工作，总结进度和 blockers	https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
空转抑制	如果 continuation turn 未做任何 tool call，下一次自动继续被抑制	同上
Safe boundary 检查	仅在 turn 完成 + 线程空闲 + 无用户输入排队时检查是否需要继续	同上
手动生命周期控制	/goal pause（暂停）、/goal resume（恢复）、/goal clear（清除）	同上
Auto-compaction	超过 auto_compact_limit 时自动压缩上下文	https://openai.com/index/unrolling-the-codex-agent-loop
Prompt caching	通过精确 prompt 前缀匹配实现缓存，降低长期运行成本	同上

共同模式

两者都没有"检测到重复输出自动停止"的硬编码机制——这仍然依赖模型自身判断和 evaluator/证据检查。但两者都有多层"软硬"防护：预算限制、turn 数限制、空转抑制、手动中断点。

---

8. AGENTS.md / CLAUDE.md / Plan Mode / Hooks 在自主循环中的角色

Codex 的 AGENTS.md

• 注入到初始 prompt 中：AGENTS.md 的内容作为 role=user 的消息注入到 Responses API 的 input 中（官方博客 Agent Loop 文章第3步）
• 层级结构：
  1. $CODEX_HOME/AGENTS.override.md 或 AGENTS.md（全局）
  2. 从 Git/project root 向上到 cwd：读取 AGENTS.override.md、AGENTS.md 或 project_doc_fallback_filenames 中配置的文件
• 在 Goal 模式中的作用：AGENTS.md 在每次模型调用中都会被包含（作为 prompt 前缀），提供项目规范、代码风格、验收标准等"持久上下文"，确保模型在长达 N 个 turn 的自主运行中保持一致的行为
• Skills 系统：如果配置了 skills，skill metadata 和如何使用 skills 的说明也会被注入

来源：

• 官方博客 Agent Loop "Building the initial prompt" 第3步：https://openai.com/index/unrolling-the-codex-agent-loop
• 官方 AGENTS.md 指南：https://developers.openai.com/codex/guides/agents-md

Claude Code 的 CLAUDE.md

• 通过 settingSources 加载：CLAUDE.md 在 session 开始时被加载，其完整内容在每次 API 请求中都被包含（但受益于 prompt caching，只有第一次请求支付完整成本）
• 在 Goal 模式中的作用：
  • CLAUDE.md 定义架构决策、编码规范、验收标准
  • 确保模型在 30+ 个 turn 的长运行中保持一致的上下文理解
  • 可包含 summarization 指令，指导自动 compaction 时保留关键信息

来源：

• Claude Code Agent Loop SDK 文档"What consumes context"：https://code.claude.com/docs/en/agent-sdk/agent-loop
• 社区最佳实践：https://blog.dailydoseofds.com/p/claude-codes-goal-command

Claude Code 的 Plan Mode（plan mode）

• SDK 中有 permission_mode: "plan"，在此模式下只允许只读工具运行，Claude 只探索和产出计划而不编辑文件
• 官方 /goal 文档未明确说明 plan mode 与 goal 的交互，但 SDK 中 plan mode 是独立概念
• 来自非官方来源的分析提到 plan-only 工作不触发 Goal 的 continuation

Claude Code 的 Hooks 机制

官方 SDK 文档列出了完整的 hooks 体系：

Hook	触发时机	在 Goal 循环中的作用
PreToolUse	工具执行前	验证输入、阻止危险命令
PostToolUse	工具返回后	自动运行 lint / type-check，在运行中发现错误
Stop	Agent 完成时	验证结果、保存 session 状态
PreCompact	上下文压缩前	归档完整 transcript 后再摘要

Hooks 与 /goal 配合使用时，可以在每次文件编辑后自动做验证（PostToolUse hook），减少返工。

来源：

• Claude Code Agent Loop SDK Hooks 文档：https://code.claude.com/docs/en/agent-sdk/agent-loop
• Claude Code Hooks 参考：https://code.claude.com/docs/en/hooks

Claude Code 的 Auto Mode

• Auto mode 是独立的权限模式（permission_mode: "auto"），用模型分类器自动审批/拒绝每个工具调用
• 两层分类：快速初筛 + 深度分析（处理不确定的危险操作）
• Auto mode + /goal 是最佳组合：Auto mode 让每个 turn 不被权限确认打断，/goal 让多个 turn 自动衔接

来源：

• Anthropic 官方博客 Auto Mode：https://www.anthropic.com/engineering/claude-code-auto-mode
• InfoQ 分析文章：https://www.infoq.com/news/2026/05/anthropic-claude-code-auto-mode

---

第三部分：同类开源方案（补充参考）

9. 其他做"自主循环直到完成"的方案

Aider

• 完成判定：Aider 的默认模式是"一次请求一次回复"，但可通过配置实现循环。它主要依靠模型自身的判断（模型输出"任务完成"）来结束。没有独立的 evaluator。
• 自我验证：依赖用户提供测试命令（/test），Aider 在每次修改后自动运行测试，测试失败则自动尝试修复。这形成了一种"修改→测试→修复"的内循环。
• 链接：https://github.com/paul-gauthier/aider

OpenHands（原 OpenDevin）

• 完成判定：OpenHands 使用 agent 自己判断任务是否完成（模型声明完成）。但社区最佳实践建议在 prompt 中要求 agent "运行测试套件后再声明完成"。
• 自我验证：强调 "verification loop"——agent 被提示在完成任务前必须运行测试/验证命令并展示通过证据。这不是硬编码的，而是 prompt engineering 的结果。
• 链接：https://github.com/All-Hands-AI/OpenHands | 深度分析：https://dev.to/truongpx396/openhands-deep-dive-build-your-own-guide-1al0

SWE-agent

• 完成判定：SWE-agent 使用固定步数限制（如 30 步）或模型自行判断。没有独立的完成条件 evaluator。
• 自我验证：SWE-agent 的核心创新是其 Agent-Computer Interface (ACI)——精心设计的工具和反馈格式。它通过让模型查看命令执行结果来做判断，但没有额外的验证层。
• 已转向更简化的 mini-SWE-agent：当前主要开发精力已转移到 mini-swe-agent。
• 链接：https://github.com/SWE-agent/SWE-agent | 论文：https://arxiv.org/abs/2405.15793

AutoGPT

• 完成判定：AutoGPT 是早期"自主循环"的典型代表。它使用任务列表（task list）机制：主 agent 将目标分解为子任务，逐一执行并勾选，直到列表清空。
• 自我验证：每个子任务执行后，agent 会生成新的子任务并重新排序优先级。这是一种"任务队列为空 = 完成"的模式，没有独立的验证步骤。容易出现死循环（agent 不断生成新任务）。
• 链接：https://github.com/Significant-Gravitas/AutoGPT

总结对比

方案	完成判定	验证机制	独立 evaluator
Claude Code /goal	独立 Haiku evaluator	模型审查 transcript	✅ 有
Codex /goal	主模型 + 硬编码规则	证据 vs 目标审计	⚠️ 半独立（模型+规则）
Aider	模型自判断	用户提供的测试命令	❌ 无
OpenHands	模型自判断	Prompt 引导的验证	❌ 无
SWE-agent	模型自判断 + 步数限制	工具输出反馈	❌ 无
AutoGPT	任务列表清空	任务队列管理	❌ 无

---

附录：对你设计自己 Agent 项目的建议

基于以上调研，Claude Code 和 Codex 的 /goal 设计可以提炼出以下可复用的设计原则：

1. 分离"工作者"和"裁判"：Claude Code 的独立 evaluator model 是最优雅的方案。即使不用独立模型，至少应该有一个"审查步骤"，不让工作模型自己声明"我做完了"。

2. 证据驱动，而非信心驱动：两个工具都强调"条件必须是可观测的"。设计你的 Goal 系统时，要求用户定义可被自动化验证的完成标准（如测试通过、构建成功、文件存在等）。

3. 硬编码安全边界：Codex 的空转抑制和 event-driven continuation 值得借鉴。不要让 Agent 无限制地自循环——设置 turn 上限、空转检测、预算上限。

4. 分层权限：Claude Code 的 Auto mode（模型分类器审批）+ Goal 的组合模式很实用。设计时考虑"什么操作可以自动审批"和"什么操作需要人类确认"。

5. 持久化上下文很重要：AGENTS.md / CLAUDE.md 在长运行中提供一致性。你的系统也需要类似的"项目规范注入"机制。

6. 可中断 + 可恢复：两者都支持 pause/resume/clear 生命周期。长时间运行的 Agent 必须支持这些操作。

7. 即使没有单独 evaluator model，也可以在 prompt 中实现"审查步骤"：在每轮结束后，向模型发送一个特殊的审查 prompt（"请基于以上对话中可见的证据，判断以下条件是否已满足..."），这本质上就是 Codex 当前的做法。

---

报告完成时间：2026年5月29日 调研工具：web_search + extract_webpage 声明：所有标注为"官方"的结论均来源于官方文档、GitHub 仓库或官方博客；标注为"社区/非官方"的来源于第三方博客或分析文章。未找到的信息已明确标注"未找到"。