Claude Code /goal 命令实操指南

一次设定，自动执行，直到条件满足才停下。

它解决什么问题

日常开发中你经常遇到这类场景：修一组 bug、跑通一批测试、批量重构文件。每一步都需要你按回车、敲 “continue”，人被困在终端前。/goal 把这个过程自动化——你只说”什么时候算完”，Claude 自己一轮一轮干到条件达成。

前置要求

Claude Code v2.1.139 或更高版本。低于此版本该命令不可用。

检查版本：

claude --version

---

一、基本语法

/goal <完成条件>

输入后 Claude 立刻开始第一个回合，不需要额外按回车。

实战示例

/goal all tests in test/auth pass and the lint step is clean
/goal 修复 user.controller.ts 里的所有 type 错误，直到 npm run typecheck 通过
/goal 把 docs/api/ 下所有 .md 文件的标题翻译成中文，且 markdownlint 不报错
/goal src/parser.ts 的单元测试覆盖率达到 90% 以上

---

二、工作机制

关键细节：

1. Fast Model 充当裁判——每个回合结束后，一个轻量模型判断条件是否已满足，不是 Claude 自说自话。
2. 替换式设定——新的 /goal 直接替换旧的，无需先清除。
3. 跨模式通用——交互模式、-p 脚本模式、Remote Control 模式都能用。

---

三、管理命令速查

命令	效果
/goal	不带参数：查看当前 goal、已花费回合数和 token 数
/goal <条件>	设定新 goal（自动替换旧 goal）
/goal clear	提前终止当前 goal
/goal stop	同上（别名）
/goal off	同上
/goal reset	同上
/goal none	同上
/goal cancel	同上
/clear	开新对话，也会顺带清掉 goal

---

四、/goal vs /loop——千万别搞混

维度	/goal	/loop
触发节奏	连续不间断，上一回合完立刻下一回合	按固定间隔（如 /loop 5m）或自定节奏
停止条件	Fast model 判断”条件是否满足”	你手动停，或 session 关闭
典型用途	一次性把活干完：修 bug、跑通测试、批量重构	周期性轮询：查部署状态、监控指标
示例	/goal 所有测试通过	/loop 5m 看看部署完了没

记忆口诀：goal = “干到完成”，loop = “定时巡检”。

---

五、如何写出好的完成条件

Fast model 是个轻量模型，条件写得越具体、可机器验证，判断越准，Claude 越不会假装完成。

好的条件

• 所有 test/auth/ 下的测试 pass，且 npm run lint 退出码为 0
• git diff --stat 显示 src/parser.ts 有改动，且 npm run typecheck 无错
• README.md 里的"安装"小节包含 Windows 步骤，且字数不少于 200
• pytest tests/ -q 输出 0 failed

特征：有命令、有预期输出、可自动验证。

不好的条件

• 把代码优化好 —— “好”没有定义
• 修一下这个 bug —— 没有验收信号
• 让性能更快 —— 没有量化阈值
• 确保没问题 —— “没问题”是主观判断

特征：模糊、主观、无法用命令行验证。

写条件的心法

把条件想象成你要写在 CI 脚本里的 if 判断——它必须是一条机器能返回 true/false 的语句。

---

六、三种运行模式

交互模式（日常开发最常用）

直接在终端里输入：

/goal src/api/ 下所有路由都有对应的集成测试，且 npm test 全部通过

你可以随时 /goal 查看进度，中途 /goal clear 叫停。

-p 脚本模式（CI/自动化）

claude -p "/goal 修复 lint 报告中的所有 error 级别问题，直到 npm run lint 退出码为 0"

无人值守，适合跑在 CI pipeline 里。

Remote Control 模式

从手机或网页端远程触发，出门在外让 Claude 自己跑。

---

七、实战场景

场景 1：修一组相关 bug

/goal issues #101 #103 #105 中报告的所有 bug 已修复，且相关测试全部通过

Claude 会逐个修复，每修完一个跑测试，直到三个 issue 都解决且测试全绿。

场景 2：代码迁移

/goal src/legacy/ 下所有 .js 文件已迁移为 TypeScript，且 tsc --noEmit 无错误

Claude 逐文件迁移，每迁移一批就跑类型检查，确保不引入新问题。

场景 3：文档补全

/goal src/utils/ 下每个导出函数都有 JSDoc 注释，且 npm run docs:check 不报缺失

Claude 会逐函数补注释，完成后用文档检查命令验证。

场景 4：性能优化

/goal API 端点 /api/users 的 P99 响应时间降至 200ms 以下，且 k6 load test 通过

Claude 会分析瓶颈、优化代码、跑负载测试，循环直到达标。

---

八、进阶：用 Stop Hook 自定义判定逻辑

/goal 的 fast model 检查是通用方案。如果你想要更精细的控制（比如检查业务规则、调用外部 API），可以用 Stop 类型的 prompt hook：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains\"}."
      }]
    }]
  }
}

工作方式：

• hook 返回 {"ok": true} → 停止，任务完成
• hook 返回 {"ok": false, "reason": "..."} → Claude 把 reason 当作下一步指令继续干

这是 /goal 背后机制的”可定制版”，适合需要业务逻辑判断的场景。

---

九、常见问题与排查

现象	原因	对策
条件已满足但还在跑	fast model 判断保守	条件写得更明确，加具体命令和预期输出
Claude 偷懒提前宣告完成	条件太模糊，fast model 被忽悠	验证步骤（命令 + 期望输出）写进条件
Token 消耗太快	goal 无人值守，容易跑很多轮	定期 /goal 查回合/token 消耗，必要时 /goal clear
命令找不到	版本太旧	升级到 v2.1.139+
想中途换方向	直接 /goal <新条件> 就行	替换式，不需要先 clear
条件永远无法满足	写了不可能达成的条件	先手动跑一次验证命令，确认目标可达

---

十、最佳实践清单

1. 条件里包含验证命令——不要只说”修好”，要说”npm test 通过”。
2. 先手动验证目标可达——别设一个根本不可能的条件让 Claude 空转。
3. 定期查看消耗——/goal 不带参数能看到回合数和 token 数。
4. 复杂任务拆成多个 goal——一个大 goal 不如三个小 goal，每个条件更清晰。
5. 用 /loop 做轮询，用 /goal 做执行——别拿 goal 监控，别拿 loop 干活。
6. 善用别名——/goal stop 比 /goal clear 更直觉，用你顺手的。

---

参考资料

• /goal 官方文档 — 最权威，建议读原文
• All commands 总览 — /goal 在所有命令中的位置
• 2026-W20 What’s New — /goal 发布说明，fast model 检查机制的来源
• Hooks Guide — Stop hook — 自定义判定逻辑
• Scheduled Tasks — /loop — 对比理解 /loop