/loop 是 Claude Code 自带的 skill,把一个 prompt 或 slash command反复执行。 看似只是定时器,但它真正的价值是把"何时再来一遍"这个决策交给模型—— Claude 可以自己判断该 60 秒后再看一次,还是 30 分钟后再来。

两种节奏模式

Dynamic 模式怎么选 delay

三种典型用法

# A · 用户驱动 + 固定 cron 节奏
/loop 10m /babysit-prs     # 每 10 分钟检查 PR 状态

# B · 用户驱动 + 动态自适应节奏(无间隔参数)
/loop "盯着 dev.log,出现 ERROR 就告诉我并停下"

# C · 自主循环(autonomous loop)— Claude 主动给自己派活
# cron 模式调用 CronCreate,prompt 设为 sentinel: <<autonomous-loop>>
# dynamic 模式调用 ScheduleWakeup,prompt 设为: <<autonomous-loop-dynamic>>
# 两个 sentinel 不要混用

何时不用 /loop

CronCreate 排一个 prompt 在未来某个 wall-clock 时间被注入会话。 它不是 Linux crontab——会话不在跑就不会触发,且仅在 REPL idle 时点火。 理解它的本地时区、jitter 和 7 天 TTL,你就能写出可预期、不踩坑的定时器。

5 字段语法 · 本地时区

# 字段顺序: 分 时 日 月 星期 — 全部按本机时区计算,不要做 UTC 换算
CronCreate(
  cron="57 8 * * *",             # 每天 8:57(避开 9:00 高峰)
  prompt="做一次今日 standup 整理",
  recurring=True
)

# 常见模式
"*/5 * * * *"     # 每 5 分钟
"7 * * * *"       # 每小时第 7 分钟(不要写 0 * * * *)
"0 9 * * 1-5"     # 工作日 9 点(若坚持整点)
"30 14 22 5 *"    # 5 月 22 日 14:30 触发一次

recurring vs 一次性

为什么避开 :00 和 :30

完整生命周期

# 1. 创建 — 返回 job ID
id = CronCreate(cron="7 * * * *", prompt="巡检 prod", recurring=True)

# 2. 查看所有定时任务
CronList()
# → [{id: "cron_abc", cron: "7 * * * *", next_fire: "14:07", ...}]

# 3. 删除某一条
CronDelete(id="cron_abc")

# 4. 跨会话存储(可选)— durable=True 会写到 .claude/scheduled_tasks.json
CronCreate(cron="57 8 * * 1-5", prompt="早会准备",
           recurring=True, durable=True)
# 用户明确要求"跨会话存活"时才打开,默认 False

会话级的"并发":把长任务推到后台,Claude 接着干别的,任务完成时自动叫回。 Bash 和 Agent 都支持 run_in_background:true, 关键是知道什么时候开后台、怎么拿结果、什么时候停。

四种后台模式对比

"等单次完成"惯用法

# 反例: tail -f | grep "Ready" 永不退出,后台一直挂
$ tail -f dev.log | grep "Ready in"   # ❌

# 正解: until 循环,grep 命中即退出,会话立刻收到 1 次完成通知
$ until grep -q "Ready in" dev.log; do sleep 0.5; done

# 配合 Bash(run_in_background=true) 推到后台
# → Claude 干别的,直到看到 <task-notification> 就读 dev.log 后续

回调架构

主动停止与查询

# 后台任务跑歪了想中止
TaskStop(task_id="shell_abc123")

# 想阶段性看一眼(不阻塞)
TaskOutput(task_id="shell_abc123", block=False)

# 强行同步等到完成(慎用,失去后台的意义)
TaskOutput(task_id="shell_abc123", block=True, timeout=60000)

# Agent 后台任务: 不要 Read .output 文件(那是 jsonl 转录)
# 直接用工具返回的 result 字段;子 agent 完成时会触发同样的通知

Monitor 不是定时器,也不是后台任务——它是事件流。 启动一段长跑脚本,它的每一行 stdout 都自动作为一条通知注入会话。 Claude 在等待你打字时,事件流可以并行进来——这才是"实时"的本意。

核心比喻 — 一行 = 一个事件

# 监听日志,每条 ERROR 都成为一个通知
Monitor(
  description="errors in deploy.log",
  command="tail -f /var/log/deploy.log | grep --line-buffered ERROR",
  persistent=True
)

# 监听文件变化
Monitor(
  description="watching schema files",
  command="inotifywait -m --format '%e %f' src/schemas/",
  persistent=True
)

# 远端轮询 → 每条新评论一条事件
Monitor(
  description="new PR 123 comments",
  command="""last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
            while true; do
              now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
              gh api 'repos/o/r/issues/123/comments?since='$last \\
                --jq '.[] | \"\\(.user.login): \\(.body)\"' || true
              last=$now; sleep 30
            done""",
  persistent=True
)

覆盖率铁律 · 沉默不等于成功

何时用 Monitor、何时用别的

事件密度与节流

四件套各有所长,真正的力量在组合。 这一节给一张"看症状选工具"决策图,再用三个真实场景演示怎么把它们串起来—— 理解了之后,你就能为自己的工作流写一张属于自己的 SOP。

决策图 — 看症状选工具

三个组合模板

通知用户的纪律

# PushNotification: 把用户从其他事抓回来,代价是注意力
PushNotification(
  status="proactive",
  message="build failed: 2 auth tests · main.py:42"
)

# 该推:
  · 长任务完成、有等他做决定的事、用户明确要求 ping

# 不该推:
  · 例行进度、刚问完的事的回答、几秒钟就完的任务

# 信息密度: "build failed: 2 auth tests"  比 "任务完成"信息量大 10 倍

四个递进的实验——从最简单的一次性闹钟,到完整的"训练 + 监控 + 推送"组合。 预计 50 分钟,每个 Lab 结束后用 CronList / 查后台任务 ID 自检, 避免无意中留下后台跑的脏数据。

1. /loop 的 cron 模式和 dynamic 模式有什么区别?分别在什么场景下用?
2. CronCreate 的 5 字段语法用的是什么时区?为什么要避开整点和半点?7 天 TTL 意味着什么?
3. "等单次完成"为什么应该用 Bash + run_in_background + until,而不是 Monitor + tail -f?
4. Monitor 写过滤器时"覆盖率铁律"是什么?给出一个反例和一个正例。
5. 设计一个"24×7 监督 prod 错误率"的工作流:用上 Cron + /loop + Monitor + PushNotification,说出每个工具承担什么角色。