Back to Details

goal-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent 
/goal
Loop

Agent 
/goal
循环

What 
/goal
is

什么是 
/goal

/goal
is a slash command that turns an agent prompt into a persistent agent looping 
plan → act → test → review → iterate
until a stop condition is met, the user pauses, or the token budget runs out. Internally called the "Ralph loop."
Agents with the 
/goal
feature right now: Codex, Claude Code, and Hermes Agent.
Key difference from a normal prompt: when a turn ends but the goal isn't met, the agent auto-continues instead of waiting for input.
Lifecycle states: 
pursuing
, 
paused
, 
achieved
, 
unmet
, 
budget-limited
.
When monitoring a running 
/goal
, every check should include a one-line update to the user: what the agent is doing and whether it is on track. Keep it extremely concise.
Not: a budget command, a safety boundary, "run forever", or a replacement for 
/plan
. It's a contract enforcer with a verification loop.
/goal
是一个斜杠命令，可将代理提示词转换为持久化代理，按照 
计划→执行→测试→评审→迭代
的流程循环，直到满足停止条件、用户暂停或token预算耗尽。该循环在内部被称为“Ralph loop”。
目前支持 
/goal
功能的代理：Codex、Claude Code和Hermes Agent。
与普通提示词的核心区别：当一轮任务结束但目标未达成时，代理会自动继续执行，而非等待用户输入。
生命周期状态： 
pursuing
（执行中）、
paused
（已暂停）、
achieved
（已完成）、
unmet
（未达成）、
budget-limited
（预算不足）。
监控运行中的 
/goal
时，每次检查都应向用户提供一行简洁更新：当前代理正在执行的操作以及是否处于正轨。内容需极度精简。
注意： 这不是预算命令、安全边界、“永久运行”按钮，也不能替代 
/plan
。它是一个带有验证循环的契约执行工具。

Requirements

要求

  • An agent with the 
    /goal
    feature — right now: Codex, Claude Code, or Hermes Agent
  • The goals feature enabled in the agent's config
  • Subscription auth — API-key auth does not work. A pro-tier plan is the realistic minimum for long runs.
  • 支持 
    /goal
    功能的代理——目前为：Codex、Claude Code或Hermes Agent
  • 代理配置中已启用目标功能
  • 订阅认证——API-key认证无效。对于长期运行，专业级套餐是实际所需的最低配置。

When to use it

使用场景

Use only when all three are true:
  1. Task is >30 min of mechanical work.
  2. There's a verifiable stop condition (tests pass, coverage hit, eval ≥ X, build green).
  3. Repo is agent-ready (working build, decent tests, 
    AGENTS.md
    present).
Fits: migrations, coverage lifts, TDD feature builds, refactors with contract tests, prompt/eval optimization, deploy retry loops, bug-repro-then-fix.
Bad fits: exploratory work, vague "improve this", anything without a "done" definition, prod credentials, destructive shared-infra ops.
仅当以下三个条件全部满足时使用：
  1. 任务需要超过30分钟的机械性工作。
  2. 存在可验证的停止条件（测试通过、覆盖率达标、评估分数≥X、构建成功）。
  3. 代码库已准备好供代理处理（构建正常、测试完善、存在
    AGENTS.md
    文件）。
适用场景：迁移、覆盖率提升、TDD功能开发、带契约测试的重构、提示词/评估优化、部署重试循环、复现并修复bug。
不适用场景：探索性工作、模糊的“优化此内容”、无“完成”定义的任务、生产环境凭证操作、破坏性共享基础设施操作。

The 5-part contract (every goal needs this)

5部分契约（每个目标都需要包含）

  1. Objective — one sentence, one concrete outcome.
  2. Constraints — what must NOT change (public API, files, libs, conventions).
  3. Validation command — the exact shell command that proves progress (
    pytest -q
    , 
    pnpm test
    , etc.).
  4. Stop condition — verifiable: "Stop when X passes" OR "when further changes need human/product input."
  5. Documentation — one sentence instructing the agent to write concise, targeted docs for every change, either creating new 
    .md
    files or updating existing ones.
Plus: tell the agent what to read first, ask it to work in checkpoints with a short progress log.
  1. 目标——一句话描述一个具体成果。
  2. 约束条件——哪些内容绝对不能修改（公开API、文件、库、约定）。
  3. 验证命令——可证明进度的精确Shell命令（如
    pytest -q
    、
    pnpm test
    等）。
  4. 停止条件——可验证的条件：“当X通过时停止”或“当后续变更需要人工/产品输入时停止”。
  5. 文档要求——一句话指示代理为每个变更编写简洁、针对性的文档，可创建新的
    .md
    文件或更新现有文件。
额外要求：告知代理首先需要阅读的内容，要求其分 checkpoint 工作并记录简短进度日志。

Writing a goal (the core deliverable)

编写目标（核心交付物）

When the user wants a quick 
/goal
instruction, produce a structured markdown block with one line per contract item (proper newlines, not flowing prose). Do not prefix the output with 
/goal
 — the user adds the slash command himself in the composer. Emit only the contract body. Template:
**Objective:** <one-sentence objective>
**Read first:** <files/PLAN.md/issue>
**Constraints:** <what not to change, libs, conventions>
**Validate:** `<exact command>` after each change
**Document:** Write concise, targeted documentation for all changes — create new `.md` files or update existing docs as needed.
**Checkpoints:** work in checkpoints and log progress briefly
**Stop when:** <verifiable condition>, OR when further changes require human/product input
当用户需要快速的 
/goal
指令时，生成结构化的Markdown块，每个契约项占一行（使用正确换行，而非连贯 prose）。不要在输出前添加
/goal
前缀——用户会在输入框中自行添加斜杠命令。仅输出契约主体。模板：
**Objective:** <一句话目标>
**Read first:** <文件/PLAN.md/问题>
**Constraints:** <不可修改的内容、库、约定>
**Validate:** `<精确命令>` after each change
**Document:** Write concise, targeted documentation for all changes — create new `.md` files or update existing docs as needed.
**Checkpoints:** work in checkpoints and log progress briefly
**Stop when:** <可验证条件>, OR when further changes require human/product input

Example (migration)

示例（迁移）

**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:** `pytest -q` after each change
**Checkpoints:** work in checkpoints; log progress briefly
**Stop when:** full suite passes with zero deprecation warnings, OR when a change requires architecture decisions
**Objective:** 将本项目从Pydantic v1迁移到v2。
**Read first:** pyproject.toml, src/, tests/
**Constraints:** 不修改公开API；如有需要，通过垫片保持导入向后兼容；不添加新依赖
**Validate:** `pytest -q` after each change
**Checkpoints:** work in checkpoints; log progress briefly
**Stop when:** 全量测试通过且无弃用警告，或当变更需要架构决策时

Example (coverage lift)

示例（覆盖率提升）

**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
**Objective:** 将src/auth/的覆盖率从约38%提升至≥75%。
**Read first:** src/auth/, tests/auth/, AGENTS.md
**Constraints:** 不添加新依赖；遵循现有测试风格；除非为了可测试性严格需要，否则不修改生产代码
**Validate:** `pytest --cov=src/auth --cov-report=term-missing`
**Checkpoints:** work in checkpoints; log coverage delta each one
**Stop when:** 覆盖率≥75%且所有测试通过，或当未覆盖代码需要设计变更时

Writing rules

编写规则

  • One objective, one stop condition. Not a backlog.
  • Documentation is mandatory. Every 
    /goal
    prompt must include a single sentence committing the agent to concise, targeted docs — new 
    .md
    files or focused updates to existing docs.
  • Never instruct the agent to create new ADRs — ADRs require the user's explicit approval, so goal prompts must not pre-approve or encourage them.
  • Forbid reward-hacking explicitly: "Do not delete, skip, weaken, or narrow tests to make the goal pass." Otherwise the agent may game the stop condition.
  • 4,000-char limit on the objective. If longer, put detail in a file (
    PLAN.md
    /
    GOAL_BRIEF.md
    ) and make the goal point to it — keep the goal itself compact.
  • Use literal strings for paths, commands, issue numbers — exact.
  • Forbid scope creep explicitly: "Do not refactor unrelated code. Do not add dependencies."
  • Tell the agent when to pause: "If <condition>, pause and ask before proceeding."
  • Short, vague goals burn tokens for no extra value vs. a normal prompt.
  • 一个目标，一个停止条件。不要写成待办清单。
  • 文档是强制要求。每个
    /goal
    提示词必须包含一句话，承诺代理编写简洁、针对性的文档——创建新的
    .md
    文件或针对性更新现有文档。
  • 绝不指示代理创建新的ADR——ADR需要用户明确批准，因此目标提示词不得预先批准或鼓励创建ADR。
  • 明确禁止奖励破解：“不得删除、跳过、弱化或缩小测试范围以达成目标。”否则代理可能会钻停止条件的空子。
  • 目标的字符限制为4000。如果内容过长，将细节放在文件中（如
    PLAN.md
    /
    GOAL_BRIEF.md
    ），并让目标指向该文件——保持目标本身简洁。
  • 路径、命令、问题编号使用字面字符串——确保精确。
  • 明确禁止范围蔓延：“不得重构无关代码。不得添加依赖。”
  • 告知代理何时暂停：“如果<条件>，请暂停并询问后再继续。”
  • 简短、模糊的目标相比普通提示词，只会白白消耗token却无法带来额外价值。

Meta-prompting trick (highest-leverage)

元提示技巧（最高杠杆）

Hand-written goals under-specify. Ask a second AI session (Claude with the codebase loaded, ChatGPT with project connected, or a separate agent thread in the same dir) to: (1) inspect the codebase, (2) surface hidden assumptions/constraints/edge cases, (3) emit a structured 
/goal
markdown block using the 4-part contract. Paste that into the agent. Order-of-magnitude better runs.
Claude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking.
手动编写的目标往往规格不足。可启动第二个AI会话（加载了代码库的Claude、连接了项目的ChatGPT，或同一目录下的单独代理线程），让其：(1)检查代码库，(2)发现隐藏的假设/约束/边缘情况，(3)使用4部分契约生成结构化的
/goal
Markdown块。将该内容粘贴到代理中，运行效果会提升一个数量级。
Claude Code cmux注意事项：Claude完成后可能会预填充预测的下一条用户消息；该草稿是Claude生成的，而非用户输入。

Self-goal setting

自动设置目标

The agent can now write and set its own goal natively (the 
create_goal
tool). Instead of crafting the contract yourself, give it your high-level intent and tell it to set the goal: "Inspect this repo, then write yourself a 
/goal
with a verifiable stop condition and pursue it." It's the meta-prompting trick done inline — the agent turns your intent into the contract. Still give it the same raw materials (files to read, constraints, the validation command) so the goal it writes is grounded. Add: "ask clarifying questions before committing if the intent is underspecified" — catches ambiguity up front and prevents the self-set goal from drifting.
代理现在可以原生编写并设置自己的目标（通过
create_goal
工具）。无需自行编写契约，只需告知代理你的高层意图并让它设置目标：“检查此代码库，然后为自己编写一个带有可验证停止条件的
/goal
并执行。”这相当于将元提示技巧内联——代理会将你的意图转换为契约。仍需提供相同的原始素材（需要阅读的文件、约束条件、验证命令），以便它编写的目标有依据。添加：“如果意图不明确，请在确认前提出澄清问题”——提前消除歧义，防止自动设置的目标偏离方向。

Launching

启动步骤

  1. cd <repo>
    (goals run scoped to the working directory).
  2. Launch the agent bare (opens the TUI). Not exec/headless mode — 
    /goal
    is a TUI slash command only.
  3. Sign in with subscription auth (not an API key).
  4. Type 
    /goal <your contract>
    in the composer, Enter.
  5. Walk away.
  1. cd <repo>
    （目标运行范围限定为当前工作目录）。
  2. 启动裸代理（打开TUI）。不要使用exec/无头模式——
    /goal
    仅支持TUI斜杠命令。
  3. 使用订阅认证登录（不要使用API key）。
  4. 在输入框中输入
    /goal <你的契约>
    ，按回车。
  5. 等待执行即可。

Controlling a running goal

控制运行中的目标

CommandEffect
/goal
(alone)		Status: current checkpoint, what's verified, what remains, blockers
/goal pause
Freeze
/goal resume
Unfreeze (paused goals never auto-resume)
/goal clear
Kill the goal
/goal <new>
Replace the current goal
Ctrl+C / any typed messageAuto-pauses; user input always wins priority
Resuming across sessions: goal state is persisted server-side. 
cd
back into the repo, launch the agent, 
/goal
for status, 
/goal resume
.
Budget-limited state: the agent doesn't stop abruptly — it summarizes, notes what's left, saves state. 
/goal resume
works after budget refresh or upgrade.
命令效果
/goal
（单独输入）		查看状态：当前checkpoint、已验证内容、剩余任务、阻塞点
/goal pause
冻结目标
/goal resume
解除冻结（暂停的目标不会自动恢复）
/goal clear
终止目标
/goal <new>
替换当前目标
Ctrl+C / 任何输入的消息自动暂停；用户输入始终优先
跨会话恢复：目标状态在服务器端持久化。回到代码库目录，启动代理，输入
/goal
查看状态，输入
/goal resume
恢复运行。
预算不足状态：代理不会突然停止——它会总结进度、记录剩余任务、保存状态。预算刷新或升级后，可使用
/goal resume
恢复运行。

When a goal drifts

当目标偏离时

  • Minor drift: just type a correction in the composer (auto-pauses, folds it in, resumes).
  • Loose objective: 
    /goal pause
    , read status, then 
    /goal <tighter version>
    — replaces the contract. Don't pile instructions on a vague goal.
  • Bad mess: 
    /goal clear
    , 
    git status
    or 
    git stash
    , rewrite with the meta-prompting trick, restart.
Don't let a drifting goal keep running "to see where it goes." Tokens burn, diffs compound.
  • 轻微偏离：只需在输入框中输入修正内容（自动暂停、整合修正、恢复运行）。
  • 目标松散：
    /goal pause
    ，查看状态，然后输入
    /goal <更严格的版本>
    ——替换契约。不要在模糊的目标上叠加指令。
  • 混乱情况：
    /goal clear
    ，执行
    git status
    或
    git stash
    ，使用元提示技巧重写目标，重新启动。
不要让偏离的目标继续运行“看看结果”。token会被消耗，差异会不断累积。

Operational tips

操作技巧

  • Inspect status periodically with bare 
    /goal
    .
  • Always review the diff before merging — long autonomy means more code to validate, not less. Human oversight becomes more critical, not optional.
  • Keep approvals/sandboxing tight; default permissions are correct.
  • First run: pick a 30-min scoped task so you learn how 
    /goal
    actually stops before trusting it overnight.
  • Bake recurring policy into 
    AGENTS.md
    so every goal inherits it without restating: adversarial self-review before declaring done, an extra QA pass even when tests pass, and the standard validation command. Saves repeating it in each goal paragraph.
  • 定期输入裸
    /goal
    查看状态。
  • 合并前务必检查差异——长期自主运行意味着需要验证的代码更多，而非更少。人工审核变得更加关键，而非可选。
  • 保持审批/沙箱限制严格；默认权限设置是正确的。
  • 首次运行：选择一个30分钟内的限定任务，以便在信任它通宵运行前了解
    /goal
    的实际停止机制。
  • 将重复策略写入
    AGENTS.md
    ，以便每个目标无需重复说明即可继承：完成前进行对抗性自我审查，即使测试通过也要额外进行QA检查，以及标准验证命令。这样可以省去在每个目标段落中重复说明的麻烦。

Troubleshooting

故障排除

SymptomFix
/goal
missing from slash popup		Update the agent to a version that supports 
/goal
Feature flag on but command missingQuit and restart the agent fully
Typed 
/goals
It's singular: 
/goal
Doesn't activateSign out, sign back in with subscription auth (not API key)
Stopped with progress summaryBudget-limited — 
/goal resume
after refresh, or tighten scope
/goal resume
says no active goal		Terminal state or cleared — start fresh with 
/goal <new>
Goal looks active but won't auto-continueStuck in Plan mode — plan-only work doesn't trigger continuation. Draft the plan, then switch to Goal execution
症状修复方法
斜杠弹出菜单中缺少
/goal
将代理更新到支持
/goal
的版本
功能标志已开启但命令缺失完全退出并重新启动代理
输入了
/goals
正确命令是单数形式：
/goal
无法激活登出后使用订阅认证重新登录（不要使用API key）
停止并显示进度摘要预算不足——刷新预算后使用
/goal resume
，或缩小范围
/goal resume
提示无活跃目标		已进入终端状态或已被清除——使用
/goal <new>
重新开始
目标显示活跃但无法自动继续卡在计划模式——仅计划工作不会触发继续。完成计划后，切换到目标执行模式

Mental model

思维模型

/goal
is a contract enforcer with a verification loop, not a "run forever" button. The shift: stop writing prompts, start writing specifications with stop conditions. Spend the time upfront defining "done"; the run takes care of itself.
/goal
是一个带有验证循环的契约执行工具，而非“永久运行”按钮。核心转变：停止编写提示词，开始编写带有停止条件的规范。提前花时间定义“完成”标准，运行过程会自行推进。