LOOPS.md: Field Notes on Agents That Run for Days

This file exists because most agent systems die not from a weak model but from a weak harness. The model can write code; the model can review code; the model can verify its own output against a rubric it agreed to ten minutes ago. What it cannot do, on its own, is decide when to stop, when to restart, and where to write the result. That is the work of the loop.

这篇文章的核心判断是：agent 系统失败，常常不是因为模型太弱，而是因为承载模型运行的 harness 太弱。模型可以写代码、review 代码、按 rubric 验证输出，但它不能天然知道什么时候停止、什么时候重启、结果该写到哪里。这些都属于 loop 的职责。

The pattern in this note treats the loop as a first-class object: roles are separated, state lives on disk, contracts are negotiated between agents before the first line of code is written, and the harness is read like a stack trace whenever something goes wrong.

这里的关键是把 loop 当作一等对象：角色要分离，状态要写到磁盘，开始写代码前先协商 contract，出错时要像读 stack trace 一样读 harness 和原始过程。

agentic loops, Claude Code, harness design, generator-evaluator pattern, sprint planning, file-system state, contract negotiation, trace reading, deletable scaffolding.

这些是文章的主题索引词，不是正文论证。它们帮助读者快速判断文章讨论的技术范围：agent 循环、代码 agent、harness 设计、生成器-评估器模式、任务拆解、文件系统状态、契约协商、trace 阅读，以及可删除脚手架。

A prompt is a thing you type once and forget. A loop is a thing that runs while you sleep. The unit of leverage stopped being the prompt the moment models became good enough to follow a procedure without supervision; what matters now is the procedure.

prompt 是你输入一次然后忘掉的东西；loop 是你睡觉时还在运行的东西。当模型已经足够好，可以在无人监督下遵循流程时，真正产生杠杆的不再是某一句 prompt，而是流程本身。

The loop is short: gather, reason, act, verify, repeat.

最小闭环是：收集信息、推理判断、执行动作、验证结果、重复循环。

Three roles, three context windows, three system prompts. A planner that turns a vague human sentence into a sprint spec and never touches code. A generator that writes everything and is forbidden from grading its own work. An evaluator that reads diffs, launches playwright, plays the app, and is told from the first message that the code is broken and its job is to prove it.

三个角色、三个上下文窗口、三个 system prompt。planner 把人类模糊的一句话转成 sprint spec，但不碰代码。generator 负责产出，但不能评价自己的作品。evaluator 负责读 diff、跑 Playwright、实际操作 app，并从一开始就带着“代码可能是坏的，我要证明它”的心态。

Mixing the roles is the most common failure I see; the model becomes sycophantic the moment it grades itself, and the loop quietly converges on slop.

最常见的失败是角色混合。模型一旦自己给自己打分，就容易变得讨好、宽松、自我合理化；整个 loop 会悄悄收敛到低质量结果。

Before the generator writes a single line, it proposes what done looks like and the evaluator pushes back. The two argue via markdown files on disk until they agree on a checklist of testable assertions.

generator 在写第一行代码前，先提出“完成是什么样子”；evaluator 负责反驳和补充。它们通过磁盘上的 Markdown 文件协商，直到形成一份可测试断言清单。

Twenty-seven criteria is a reasonable size for a small app; ten is usually too few and the evaluator rubber-stamps. The original spec from the planner is the boundary, but the contract is what gets graded.

对一个小 app 来说，二十七条 criteria 是合理规模；十条通常太少，evaluator 很容易走过场式通过。planner 的原始 spec 定义边界，但真正被评分的是 contract。

Context windows lie. They compact, they rot, they hide what you said an hour ago behind a summary you did not write. A file on disk does not lie.

context window 会压缩、腐烂、隐藏早先的信息；磁盘上的文件更稳定。长任务不要只依赖模型上下文。

Keep feature_list.json, progress.md, contract.md, and an append-only log.md with ## [YYYY-MM-DD] op | title entries.

保留功能清单、进度文件、验收协议，以及只追加不改历史的日志文件。这样 agent 崩溃、换 session、丢上下文后，也可以通过读文件恢复状态。

Counter-intuitively, the best behavior I see from current frontier models is the willingness to throw everything away and start over when a run goes sideways.

有点反直觉的是，当前强模型的一个好行为，是当一次运行跑偏时，愿意把已有东西扔掉并从头再来。

Insert a human only when the contract itself is wrong, not when the build is.

只有当 contract 本身错了，人类才应该介入；如果只是 build 坏了，应该让 loop 自己修复、重启、再验证。

Taste is gradable if you write it down. Four axes, weighted: design, originality, craft, functionality. Calibrate on three reference sites the evaluator is told are good and three it is told are slop.

品味也可以评分，前提是写下来。可以按设计、原创性、工艺、功能性四个维度加权，并用三个好参考和三个差参考校准 evaluator。

The model will not invent taste; it will only converge toward the taste you described. The whole game is writing the rubric carefully enough that converging toward it is what you actually wanted.

模型不会凭空发明品味，它只会朝你描述出的品味收敛。关键是把 rubric 写得足够准确，让模型优化到那个方向时，得到的正是你想要的东西。

Every debugging insight I have about agent loops came from reading the raw transcript, not from running another experiment.

关于 agent loop 的调试洞察，来自阅读原始运行记录，而不是盲目再跑一次实验。

This is the same muscle as reading a stack trace; the difference is that the trace is written in English and most of it is the model talking to itself. Skip this step and you are tuning by vibe.

这和读 stack trace 是同一种能力：从一长串执行记录里找出问题从哪里开始发生。区别只是 agent 的 trace 是英文写的，而且大部分是模型在自我对话。跳过这一步，就是凭感觉调参。

The harness exists to compensate for the model. As the model improves, half of what you wrote last quarter becomes overhead.

harness 的存在是为了补偿模型能力不足。随着模型进步，上一季度写下的一半辅助结构可能都会变成额外负担。

Context resetting between sessions was load-bearing for one model generation and dead weight for the next; sprint decomposition was the only thing keeping a four-hour build coherent and is now a constraint on a model that holds two hours in one head.

session 之间重置上下文，对上一代模型可能是承重结构；对下一代模型可能就是死重。sprint decomposition 曾经让四小时构建保持连贯，但当模型已经能在一个上下文里保持两小时任务状态时，过度拆解反而可能变成限制。

The harness that grows monotonically is a harness you have stopped reading.

如果 harness 只会单调增长、从来不删东西，说明你已经不再认真审视它了。

When coding stops being the bottleneck, planning becomes the bottleneck. When planning is solved, verification becomes the bottleneck. When verification is automated, taste becomes the bottleneck.

当 coding 不再是瓶颈，planning 会成为瓶颈；planning 解决后，verification 会成为瓶颈；verification 自动化后，taste 会成为瓶颈。

The whole point of the loop is to make the next bottleneck visible.

loop 的意义，不是让事情一次性完美完成，而是让当前最大的限制暴露出来，让下一个瓶颈变得可见。

当 agent 结果不好时，可以先发这段，而不是直接要求重做：

先不要重做。请基于刚才完整过程做一份可读审计报告：1. 我原始需求是什么？2. 你第一次偏离我需求发生在哪里？3. 你当时做了什么错误假设？4. 哪些验证没做或做得太弱？5. 哪些失败被你忽略、淡化或自我合理化了？6. 如果重来，contract 应该新增/修改哪几条？最后只给我下一轮最小改动建议，不要直接执行。