# Loop Harness

> 搭建并跑「高质量长期自主迭代 loop 任务」的方法论 + harness——优化/审计/迁移/深度打磨/持续调研这类**靠多轮累积、非一次成型**的工作。提供任务书/台账/日志三件套脚手架 + **外部客观验证门**（绑可执行二元成功检查·agent 报结果不报自评）+ **进度检测停止/升级判据**（非步数·停滞即求人）+ 记忆防漂移 + 多智能体协作。当用户要「建一个 loop 任务 / 自主迭代 / 持续优化 / 让 agent 自己跑多轮 / babysit 一个长期任务 / loop 工作法 / 这件事我想让它一直迭代」时用。建在 `/loop`（会话内）或 `/schedule`（云端 cron）的运行时之上——本 skill 管「怎么跑得高质量不漂移不注水不失控」，运行时只负责「定时触发」。

- Skill: `garveyhu/loop-harness` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add garveyhu/loop-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garveyhu/loop-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: garveyhu (https://skillmd.com/u/garveyhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/garveyhu/loop-harness

---


# loop-harness —— 高质量自主迭代 loop 的脚手架 + harness

> 让一个 agent **跑很多轮、自己选最高价值的事推进、不漂移、不注水、不失控、断了能续**。把「一次性做完」的任务，变成「持续累积逼近顶级」的 loop。
>
> 实证基础：一个 100 轮的自主优化 loop 跑下来，结构被验证与业界最佳实践**同构**——Ralph loop（文件即记忆+每轮 fresh context）+ BabyAGI（优先级与执行分离）+ Anthropic evaluator-optimizer（对抗验证）+ Reflexion（日志=言语反思记忆）。本 skill 是这套方法论的可复用封装。

## 1 · 何时用 / 不适用

**用**：一件事**靠多轮累积、不可能一次做到位**——持续优化某系统、审计大代码库、跑大迁移、把一条内容/产品打磨到顶级、长期调研追踪。特征：有**北极星**（长期目标）、有**会增长的 backlog**（开放项不断冒）、单轮做不完、越迭代越好。触发：「让它自己一直迭代 / 持续优化 / 建个 loop 任务 / babysit 这个」。

**不适用**：一次性能做完的任务（直接做，别套 loop）；目标模糊到无法定义「什么算做对了」的（先 brainstorm 出验证标准再说·见 [`brainstorming`](../../brainstorming/SKILL.md)）；纯执行确定步骤的（写个脚本）。

## 2 · 两个 harness 命门（先立这两根柱子，其余都是外壳）

研究的最高结论——**只保两件也能跑，缺这两件必翻车**：

### 命门 ① · 外部客观验证门（解决 客观验证 + 诚实 + 停止判据 三件事）
**每个 loop 任务必须绑一个「可执行的二元成功检查」**——脚本退出码 / 测试套件 / 真测产物 / 抽帧 / API 真调 / 数值实算。**agent 报这个检查说什么，不报它自己以为什么**（铁律原文：「report what the script says, not what it thinks」）。
- 为什么命门：研究证明 **LLM-as-judge 当唯一验证门，单个无意义 token 就能骗到 80% 假阳性**。agent 评判自己的产出 = 系统性注水的温床。
- 怎么落：立项时就为北极星写一个**可执行的成功判据**（哪怕粗）。每轮产出跑它、贴它的真实输出。**禁止**以「我觉得做完了 / 应该没问题」收尾。配 [`verification-before-completion`](../../verification-before-completion/SKILL.md)。

### 命门 ② · 进度检测驱动的停止/升级（非步数）
**靠「停滞检测」判停，不靠步数上限**——连续 N 轮无新进展 / 重复同一任务 2–3 次 / 本轮 state 与上轮相似度过高 → 判停滞 → **升级求人**（不是默默空转）。
- 为什么命门：纯 `max-iterations` 会让 agent 在上限内**空转烧钱不报警**（「你要的不是 step limit，是 progress detection」）。
- 怎么落：每轮结束自问「这轮有没有产生**可验证的新进展**（过了验证门的新东西 / 新发现 / 排除了一个选项）？」连续 2 轮没有 → 停下来把「卡在哪、试过什么、要什么」抛给人。

## 3 · 三件套文件（文件即记忆 · 每轮 fresh context）

loop 的状态**全在磁盘文件**，不靠 agent 记忆（每轮可以是全新上下文，靠重读文件还原）。固定三件套，放一个 loop 工作目录（如 `_<任务名>/`）：

| 文件 | 角色（记忆 scope） | 纪律 |
|---|---|---|
| **`00-任务书.md`** | **指挥中枢**·北极星 + 审视方向 + 边界铁律 + 每轮流程 + 验证门 + 停止判据（**semantic memory**·每轮第一必读） | **只战略级改**（改它=改方向）。**别让 agent 每轮重写它**（反复改写=语义漂移丢真） |
| **`01-台账.md`** | **backlog**·开放项 + 优先级 + 依赖 + 状态 + 价值（每轮选**最高优先未完成项**·BabyAGI 优先级表） | 完成项打勾/归档·新发现追加·**append 为主**·一处「当前轮次」滚动摘要 |
| **`02-迭代日志.md`** | **言语反思记忆**·每轮做了什么 + 验证结果 + 坑 + 下一步（**episodic memory**·Reflexion） | **append-only 倒序**（最新在最上·用 `date` 取时间）·**永不改写旧条目**（改写=漂移） |

> **为什么文件驱动够用、不用上向量库/MemGPT**：研究证实「文件系统当记忆 + 每轮 fresh context」对长跑足够且更稳，向量检索只在 backlog/知识超大才需要。三个 markdown 文件就是正解。

## 4 · 创建一个 loop 任务（scaffolding · 立项五步）

1. **定北极星 + 验证门**（最重要·别跳）：一句话长期目标 + **一个可执行的二元成功判据**（「什么算逼近了？跑什么能客观看出来？」）。验证门定不出来 = 目标太模糊，先 [`brainstorming`](../../brainstorming/SKILL.md)。
2. **写 `00-任务书.md`**（模板见 `reference/taskbook-template.md`）：北极星 / 每轮审视方向（多智能体并行防片面）/ **边界铁律**（不可逾越的红线·写死在 agent 改不到的位置）/ 每轮流程 / **停止判据三类**（见 §6）/ 产出去哪。
3. **建空 `01-台账.md` + `02-迭代日志.md`**（模板见 `reference/`）：台账先填初始 backlog（带优先级/价值）。
4. **挂运行时**（见 §7）：会话内连续跑用 `/loop`；要跨会话/云端定时用 `/schedule`。
5. **跑第一轮做样板**：亲自跑一轮，把「读→选→做→验→记」走通，校准验证门真能跑、台账格式顺手，再交给 loop 自动跑。

## 5 · 每轮协议（per-round · 严格按序）

```
① 读 00-任务书 + 01-台账 → 锚定北极星 + 边界铁律 + 验证门
② 选最高优先未完成项（优先级决策 ≠ 谁执行·分离·防挑软柿子见 §6.4）
③ 派多智能体协作（建造员/审视员/对抗评估员·防片面·见 dispatching-parallel-agents）
④ 落地（改/重构/真做）→ 能力沉淀到该沉淀的地方（不散落一次性脚本）
⑤ ★过验证门（跑那个可执行检查·贴真实输出·不报自评）+ 对抗评估
⑥ 更新 01-台账（翻牌/追加）+ append 02-迭代日志（倒序·date·诚实标完成度+坑）
⑦ 进度检测（§2②）：有可验证新进展？没有连续 2 轮 → 停下求人。否则下一轮。
```

## 6 · harness 六铁律（把命门 + 防坑固化成规则）

1. **外部客观验证门**（命门①）：报脚本不报自评·禁「我觉得做完了」收尾。
2. **进度检测停止/升级**（命门②）：停滞即求人·非步数。
3. **append-only 防漂移**：台账/日志倒序追加·**永不改写旧条目/反复重写摘要**（semantic drift 会逐次丢真）；单一事实源（任务书）只战略级动。
4. **反挑软柿子**：优先级决策独立于执行。规则——**连续 N 轮回避某高价值项 → 本轮强制处理、或在日志显式记录「为何跳」**（不许默默只挑容易的）。配反占位硬指令「要全实现不要占位/简化实现」。
5. **诚实铁律**：每项标**真完成度 + 真验证结果 + 坑**；做不到说做不到·**不注水**；负面结论（试了不成立）**照实记**——负面结论是有价值的 learning，不是失败。
6. **停止判据三类**（立项就定·写在 agent 改不到的位置）：① **success stop**（验证门过 + backlog 清）② **failure stop**（不可恢复错 / 重试 2–3 次超限 / 显式判卡住）③ **budget stop**（轮数/token/wall-clock 硬上限·兜底防失控烧钱）。**三类缺一就有 runaway 风险**。

## 7 · 运行时底座（本 skill 不重造调度·复用现成）

- **会话内连续跑** → `/loop`（递归把 prompt 喂回去·会话关了就停）。loop 的 prompt = 「读任务书+台账 → 按每轮协议推进一项 → 更新台账+日志 → 不喊停继续」。
- **跨会话/云端定时** → `/schedule`（CronCreate·云端 cron·关了会话还在跑）。**注意**：长跑 loop 烧 token，定时间隔别太密；budget stop 兜底。
- **停**：用户喊停 / 触达停止判据 → `CronDelete` 撤掉定时任务（别让它继续打断）。

## 8 · 记忆管理（三 scope · 防漂移）

| scope | 存哪 | 例 |
|---|---|---|
| **semantic**（事实/偏好/边界） | 任务书边界铁律 + 项目 `CLAUDE.md` + 持久 memory | 「这条频道无人设·固定音色」 |
| **episodic**（过往轮次发生了什么） | 迭代日志（倒序 append） | 「r92 试了 X·验证门抓到 Y·撤回」 |
| **procedural**（学到的命令/打法） | 任务书「每轮流程」+ 沉淀进 skill | 「死帧用 freezedetect -62dB 判」 |

**防 semantic drift 的两条**（研究重点警告）：① 日志/台账 **append-only**，别反复改写同一段摘要（增量改写逐次丢真）；② 单一事实源（任务书）只在**战略级**改，别每轮微调。

## 9 · 避开的三个坑（研究实锤）

- ❌ **把 LLM-judge / 「输出 'complete' 字符串」当唯一停止或验证门**——假阳性可达 80%、单 token 可骗、exact-string 公认不可靠。必须有客观可执行 gate 兜底。
- ❌ **只设步数上限、不做进度检测**——会在上限内空转烧钱不报警。
- ❌ **反复改写摘要/单一事实源**——semantic drift 逐次丢真。append-only + 单一事实源只战略级动。

## 10 · 配套 skill（组合用）

立项头脑风暴 [`brainstorming`](../../brainstorming/SKILL.md) · 写计划 [`writing-plans`](../../writing-plans/SKILL.md) · 多智能体并行 [`dispatching-parallel-agents`](../../dispatching-parallel-agents/SKILL.md) · 子agent 驱动 [`subagent-driven-development`](../../subagent-driven-development/SKILL.md) · 完成前验证 [`verification-before-completion`](../../verification-before-completion/SKILL.md) · 系统化调试 [`systematic-debugging`](../../systematic-debugging/SKILL.md)。

> 模板与深档见 `reference/`：`taskbook-template.md`（任务书模板）· `ledger-log-templates.md`（台账+日志模板）· `verification-gate.md`（怎么为不同任务设可执行验证门）· `field-notes.md`（100 轮实战踩坑笔记）。