loop-design-check
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLoop Design + Review
循环设计与审查
Premise. An LLM is a feed-forward system: prompt in → tokens out, with no built-in "steer toward the goal" across turns. To make it behave like a goal-oriented system, you wrap a feedback loop around it. This skill helps you write that loop correctly and review it so it won't run away.
前提。LLM是一种前馈系统：输入提示词→输出Token，跨轮次没有内置的“向目标靠拢”机制。要让它表现得像一个面向目标的系统，需要在其外部构建一个反馈循环。本技能可帮助你正确编写该循环并进行审查，避免其失控。
When to use / not
适用场景与非适用场景
Use it when:
- You want to hand a repeating task to an agent that runs over and over (write→test, test→fix, fix→verify…).
- You already have a loop and worry it spins, cheats, or runs a wrong answer to completion.
Don't use it for:
- A one-off task → just do it; don't wrap a loop around it.
- A plain timer / poll → use ; no design needed.
/loop - How to wire the loop architecture (pipelines → DAGs, long-run recovery) → that's the mechanism layer; see /
autonomous-loops. This skill only covers "is the goal right, and will it run away" — it does not re-explain mechanism.continuous-agent-loop
适用场景：
- 你希望将重复性任务交给Agent持续执行（编写→测试、测试→修复、修复→验证……）。
- 你已拥有一个循环，但担心它出现卡顿、作弊或持续执行错误答案直至完成。
非适用场景：
- 一次性任务→直接执行即可，无需构建循环。
- 简单的定时器/轮询→使用即可；无需设计。
/loop - 循环架构的搭建方法（流水线→DAG、长期运行恢复）→属于机制层内容；请参考/
autonomous-loops。本技能仅覆盖“目标是否合理、是否会失控”——不重复讲解机制层面内容。continuous-agent-loop
Red-line premise: two levels of feedback
红线前提：两层反馈机制
| Level | Who owns it | What it does |
|---|---|---|
| Execution (low) | machine / agent | Measures "how far from the literal goal" and grinds it to zero. The machine is strong here. |
| Judgment (high) | human | Decides "is this goal itself right, should it change, should it stop." The machine can't step outside its own loop to question the goal. |
A thermostat can feed back "how far from 26°C," but when you have a fever and want 28°C it can't judge whether 26 is the right target — it just grinds toward 26. "What to set today" is always the human's call. Handing judgment / sign-off / the last switch to the machine = removing the high-level feedback = it sprints, fast and hard, toward a goal no one questioned → wrong output.
| 层级 | 负责主体 | 功能 |
|---|---|---|
| 执行层（低层级） | 机器/Agent | 衡量“与字面目标的差距”并将其缩小至零。机器在这方面表现出色。 |
| 决策层（高层级） | 人类 | 判断“目标本身是否正确、是否需要调整、是否应该停止”。机器无法跳出自身循环来质疑目标。 |
恒温器可以反馈“与26℃的差距”，但当你发烧需要28℃时，它无法判断26℃是否是正确的目标——只会一味向26℃靠拢。“今天设置多少度”始终由人类决定。 将决策/审批/最终控制权交给机器=移除高层级反馈=机器会快速且坚定地朝着无人质疑的目标冲刺→输出错误结果。
Action 1 — Write a loop (5 steps)
操作1：编写循环（5个步骤）
Step 0 · Subtract first: should you even build it? (4-condition gate, any miss = veto)
步骤0：先做减法：是否真的需要构建循环？（4项条件，任意一项不满足则否决）
① the task repeats weekly or more ② verification can be automated ③ the token budget can take it ④ the agent has tools that actually run and see the result
Miss any one → don't build a loop; do it by hand or another way.
What stops most people isn't "can I write a loop," it's "does my repo deserve one." A repo that deserves a loop has a reconciliation baseline (golden sample / upstream total) + tests + a lint guard. A repo that doesn't deserve a loop will only have its errors amplified by one.
① 任务每周重复一次或更频繁 ② 验证过程可自动化 ③ Token预算可支撑 ④ Agent拥有能实际运行并查看结果的工具
任意一项不满足→不要构建循环；手动执行或采用其他方式。
阻碍大多数人的不是“我能否编写循环”，而是“我的项目是否值得构建循环”。值得构建循环的项目需具备对账基准（黄金样本/上游总计）+测试+代码检查守卫。不值得构建循环的项目只会被循环放大错误。
Step 1 · Define a machine-decidable goal (the hard part — the loop lives or dies here)
步骤1：定义机器可判定的目标（核心环节——循环的成败取决于此）
The whole loop rides on the comparator's "is it done yet?" The comparator can only work if your exit condition can be judged yes/no by a machine.
- Bad: Vague ("make it good," "write it sharper") → the comparator can't judge → either it never passes (stuck retrying) or it guesses (passes/blocks at random).
- Good: Decidable ("all 96 unit tests green AND a change-list is produced," "module-02 fields filled, pytest passes, business logic untouched") → one check settles it; the loop converges cleanly.
Five-point goal framework:
- Done-criterion is machine-verifiable.
- Boundary conditions defined alongside the done-criterion ("what it must NOT do") — anti-Goodhart; missing boundaries = a license to cheat.
- Has a failure fallback — retry cap N + escalate to a human when exceeded.
- Goal is layered.
- Prefer reconciliation over assertion for the done-criterion — anchor to external fact (golden sample / upstream total / financial tie-out / platform back-office numbers) before your own assertions. "All tests pass" can be gamed (loosen asserts, fake mocks, swallow exceptions); "diff vs the reference < 0.01" can't.
Self-check: read the goal to someone who doesn't know the domain — can they run one command and tell whether it's done? If not, it isn't decidable enough. Go back.
整个循环的运行依赖于比较器的“是否完成？”判断。只有当退出条件可由机器判定是/否时，比较器才能正常工作。
- 错误示例：模糊表述（“做得更好”、“写得更犀利”）→比较器无法判断→要么永远无法通过（陷入重试循环），要么随机猜测（随机通过/阻断）。
- 正确示例：可判定表述（“全部96个单元测试通过且生成变更列表”、“module-02字段填写完成，pytest测试通过，业务逻辑未改动”）→一次检查即可确定；循环会平稳收敛。
五点目标框架：
- 完成标准可由机器验证。
- 完成标准需同时定义边界条件（“绝对不能做的事”）——防止投机取巧；缺少边界条件相当于允许作弊。
- 具备故障回退机制——重试次数上限N+超过上限时升级给人类处理。
- 目标分层。
- 完成标准优先采用对账而非断言——先锚定外部事实（黄金样本/上游总计/财务对账/平台后台数据），再进行自我断言。“所有测试通过”可被投机取巧（放宽断言、伪造模拟数据、吞掉异常）；“与参考值的差异<0.01”则无法作弊。
自我检查： 将目标描述给不懂该领域的人——他们能否通过执行一个命令判断是否完成？如果不能，说明目标的可判定性不足。返回上一步重新调整。
Step 2 · Pick the loop type
步骤2：选择循环类型
| Your task | Loop type (cybernetic) | How it stops |
|---|---|---|
| Has a clear "done" test (write to done / a batch of images processed) | servo ( | stops on reaching the goal |
| No endpoint, must keep maintaining a state (inventory alert / scheduled health check) | regulator ( | never stops; acts only on change (dead-band suppresses noise) |
| Periodic sampling, stop on a condition (watch a PR until CI is green) | regulator with an exit | stops when the exit condition holds |
| Must "ensure something happens on time" | wrap the above in | cron fires it |
Rule of thumb: clear "done" test → servo; must keep maintaining, no endpoint → regulator; must "happen on time" → wrap a regulator in schedule.
| 任务类型 | 循环类型（控制论） | 停止方式 |
|---|---|---|
| 有明确的“完成”测试（编写至完成/处理一批图片） | servo（ | 达成目标时停止 |
| 无终点，需持续维护状态（库存警报/定期健康检查） | regulator（ | 永不停止；仅在状态变化时触发（死区抑制噪声） |
| 定期采样，满足条件时停止（监控PR直至CI通过） | 带退出条件的regulator | 满足退出条件时停止 |
| 需“确保某事按时发生” | 将上述循环包装在 | cron定时触发 |
经验法则：有明确“完成”测试→servo；需持续维护、无终点→regulator；需“按时发生”→将regulator包装在调度器中。
Step 3 · Pick a skeleton
步骤3：选择循环框架
Maintenance type (tend something that exists) → document-driven dispatch.
The loop isn't "run a fixed check on a timer," it's "read a doc on a timer, and dispatch only when the doc changed." The doc is the task queue + state machine + human interface.
Three disciplines: ① the problem column is human-write-only, the result column is loop-write-only, state advances one-way and never rolls back; ② the exit code is final (if the script says exit 1, the script wins); ③ state advances only as far as "awaiting verification" — the "done" cell is flipped by a human only. The loop is the worker, not the acceptance officer.
Greenfield type (build from scratch) → plan / build / judge, three roles.
| Role | Does | Key |
|---|---|---|
| Plan | break the goal into a spec + decidable acceptance conditions | acceptance must be script-judgeable |
| Build | write to the spec | must not change the acceptance conditions |
| Judge | run acceptance independently; pass → stop, fail → return with the failure reason to Build | independent + deterministic |
Three iron rules (all bet on the judge): ① the judge must be independent — not the same agent as Build (grading your own homework always inflates); ② deterministic rules — pytest / reconciliation diff / type check / diff, never "looks right"; ③ Build may not edit the acceptance conditions to pass. Three failed retries → escalate to a human.
维护类任务（维护现有事物）→文档驱动调度。
循环并非“定时运行固定检查”，而是**“定时读取文档，仅在文档变更时调度执行”。文档同时作为任务队列+状态机+人机交互界面。
需遵循三个原则：① 问题列仅允许人类编写，结果列仅允许循环写入，状态单向推进且永不回滚；② 退出码具有最终权威性（若脚本返回exit 1，则以脚本结果为准）；③ 状态仅推进至“待验证”阶段——“完成”状态仅由人类手动标记**。循环是执行者，而非验收者。
全新构建类任务（从零开始构建）→规划/构建/判定，三个角色。
| 角色 | 职责 | 核心要求 |
|---|---|---|
| 规划 | 将目标拆解为规范+可判定的验收条件 | 验收条件必须可由脚本判定 |
| 构建 | 按照规范编写内容 | 绝对不能修改验收条件 |
| 判定 | 独立执行验收检查；通过→停止，失败→将失败原因返回给构建角色 | 独立+确定性 |
三条铁则（均围绕判定角色）：① 判定角色必须独立——不能与构建角色为同一Agent（自己批改作业总会放水）；② 规则必须具有确定性——采用pytest/对账差异/类型检查/文件对比，绝不能用“看起来没问题”；③ 构建角色不得修改验收条件以通过检查。三次重试失败→升级给人类处理。
Step 4 · Add damping (against oscillation / runaway)
步骤4：添加阻尼机制（防止振荡/失控）
Retry cap, hard stop, human flips the last switch = damping. Negative feedback with no damping oscillates (the Ralph-Wiggum loop: spinning in place, burning tokens).
重试次数上限、强制停止、人类最终确认=阻尼机制。无阻尼的负反馈会引发振荡（即Ralph-Wiggum循环：原地卡顿，消耗Token）。
Step 5 · Land in three stages (don't go fully automatic on day one)
步骤5：分三个阶段落地（不要第一天就完全自动化）
① Run it once by hand (forces you to state exactly "how the judge decides") → ② harden into a skill / Claude Code sub-agents (a main Claude loops, dispatching plan/build/judge) → ③ hang it on cron for full automation.
① 手动运行一次（迫使你明确“判定角色如何判断”）→② 固化为技能/Claude Code子Agent（主Claude负责循环调度，分发规划/构建/判定任务）→③ 挂载到cron实现完全自动化。
Action 2 — Review a loop (checklist = five failure modes)
操作2：审查循环（检查清单=五种故障模式）
Run the loop past each row. Hitting any one = this loop will misfire; send it back. These five are negative experience (gotchas) — worth more than positive rules.
| # | Failure mode (how it breaks) | Review question (a hit = red) | Antibody |
|---|---|---|---|
| 1 | Goal is a correct platitude → spins, burns money | Can the exit condition be machine-judged yes/no? Or is it "manage it well / make it good"? | Replace with a decidable result condition (Action 1·Step 1) |
| 2 | "Verification" written as "check if it looks ok" → agent confidently says fine and stops | Is the judge the defendant itself? Does verification rest on "looks right" or deterministic rules? | Reconcile + exit code rules + independent judge |
| 3 | (worst) Only gates on "all tests pass" → agent deletes the tests | Is there a boundary ("what it must NOT do")? Or only a done-criterion? | Done-criterion + boundary together (the Goodhart antibody) |
| 4 | Counts on the agent asking mid-run → it won't; it runs the wrong answer to the end | Is there any "clarify only at runtime" point? | Front-load every clarification; settle it once before launch |
| 5 | Bloated CLAUDE.md + stale memory → the faster it loops, the more it errs | Are the docs/memory it depends on fresh? Who maintains them? | Layered memory + periodic lint |
Plus three red lines (violate any = not allowed to go automatic):
- Keep judgment with the human. Acceptance / the "done" cell is flipped by a human; the loop is not the acceptance officer.
- Responsibility doesn't transfer. Anything whose failure you can't afford (merge the wrong PR / publish the wrong thing / misallocate money) → don't hand over the authority automatically.
- Counter-intuitive warning. The more "self-improving / rewrites-its-own-rules" a loop is, the stricter the human review it needs (to see what it rewrote the rules into) — not looser. The machine is too fast to intercept after the fact, so the human's judgment must sit before the action (a hard gate), not as a post-hoc patch.
针对每一项检查循环。**只要命中任意一项→该循环会失效；返回修改。**这五种是负面经验（陷阱）——比正面规则更有价值。
| 序号 | 故障模式（失效方式） | 审查问题（命中=红线） | 解决方法 |
|---|---|---|---|
| 1 | 目标是正确但空泛的表述→卡顿、消耗资金 | 退出条件能否由机器判定是/否？还是类似“妥善管理/做得更好”的表述？ | 替换为可判定的结果条件（操作1·步骤1） |
| 2 | “验证”被定义为“检查是否看起来没问题”→Agent自信地表示没问题并停止 | 判定角色是否就是执行任务的Agent？验证是否依赖“看起来没问题”而非确定性规则？ | 采用对账+退出码规则+独立判定角色 |
| 3 | （最严重）仅以“所有测试通过”为判断标准→Agent删除测试用例 | 是否定义了边界（“绝对不能做的事”）？还是仅定义了完成标准？ | 同时设置完成标准和边界条件（防止投机取巧的解决方案） |
| 4 | 依赖Agent在运行过程中提问→Agent不会提问；会持续执行错误答案直至完成 | 是否存在“仅在运行时澄清”的环节？ | 提前完成所有澄清；在启动前一次性解决所有模糊点 |
| 5 | CLAUDE.md文档冗余+内存数据过时→循环运行越快，错误越多 | 循环依赖的文档/内存数据是否是最新的？由谁维护？ | 分层内存+定期代码检查 |
额外三条红线（违反任意一条=不允许自动化）：
- 保留人类决策权。验收/“完成”状态由人类手动标记；循环不是验收者。
- 责任不可转移。任何你无法承担失败后果的任务（合并错误PR/发布错误内容/资金分配错误）→不要自动移交权限。
- 反直觉警告。循环越“自我改进/自我修改规则”，就越需要严格的人类审查（检查其修改后的规则）——而非放宽审查。机器运行速度过快，事后无法拦截，因此人类决策必须置于操作之前（作为硬性门槛），而非事后补救。
Worked example — reviewing a "nightly green-keeper" loop
实战示例：审查“夜间测试修复”循环
You want a loop that runs every night and fixes whatever tests are failing.
- Naive goal: "make all tests pass." → Step-1 self-check fails: this is the bait for failure mode #3.
- Decidable goal (fixed): "all tests green AND no test file deleted or weakened AND coverage not lowered AND a change-list produced." Boundary now defined alongside the done-criterion.
- Type: servo with a retry cap of 3 (Step 2 + Step 4).
- Skeleton: plan/build/judge — the judge is CI run independently, never the fixing agent (Step 3).
Now run the review checklist, and it catches what the naive version would have missed:
- #3 hit → the naive "all tests pass" lets the agent delete a failing test to "win." Fixed by the boundary "no test file deleted/weakened."
- #2 hit → if the fixing agent also judged its own fix, it would pass itself. Fixed by "judge = independent CI, deterministic."
- #4 hit → if a fix is ambiguous, the agent won't stop to ask at 2 a.m.; it'll commit a guess. Fixed by front-loading: ambiguous fixes are left for the human, not guessed.
- Red line → the loop opens a PR but does not auto-merge; the human flips the last switch (responsibility doesn't transfer).
The naive loop and the reviewed loop differ by four lines of constraint — and that's the difference between "wakes you to a deleted test suite" and "wakes you to a clean PR."
你需要一个每晚运行、修复所有失败测试的循环。
- 初始目标：“让所有测试通过。”→步骤1自我检查不通过：这是故障模式#3的陷阱。
- 修正后的可判定目标：“所有测试通过且未删除或弱化测试文件且覆盖率未下降且生成变更列表**。”现在完成标准同时定义了边界条件。
- 循环类型：带3次重试上限的servo（步骤2+步骤4）。
- 循环框架：规划/构建/判定——判定角色为独立运行的CI，绝不是修复Agent（步骤3）。
现在运行审查清单，会发现初始版本遗漏的问题：
- 命中#3→初始的“所有测试通过”会让Agent删除失败的测试用例来“达标”。通过添加“未删除/弱化测试文件”的边界条件解决。
- 命中#2→如果修复Agent同时判定自己的修复结果，它会自行通过。通过“判定角色=独立CI，规则具有确定性”解决。
- 命中#4→如果修复存在歧义，Agent不会在凌晨2点停下来提问；会直接提交猜测的修复方案。通过提前澄清解决：歧义修复留给人类处理，不允许Agent猜测。
- 红线→循环仅创建PR但不会自动合并；由人类最终确认（责任不可转移）。
初始循环与审查后的循环仅相差四条约束——但这就是“让你在凌晨看到被删除的测试套件”和“让你在凌晨看到干净的PR”的区别。
One-line close
总结
The hard part of writing a loop isn't "can I write a loop," it's defining a goal a machine can reconcile — decidable, bounded, reconciliation-based. The controller must be deterministic and external; keep judgment and the standard with the human; the system tends toward entropy, so maintain it. A loop only rewards someone who has already thought it through. Count on it to think for you, and it will happily think wrong, with you, at scale.
Lineage: Wiener's two-level feedback (The Human Use of Human Beings, 1950) for the judgment/execution split and red lines; the plan/build/judge pattern from Anatoli's Loops explained and Addy's Loop Engineering. Mechanism layer (how to wire the loop architecture): see/autonomous-loops. This skill does not re-implement mechanism; it covers goal definition and runaway prevention only.continuous-agent-loop
编写循环的难点不在于“我能否编写循环”，而在于定义机器可对账的目标——可判定、有边界、基于对账。控制器必须具有确定性且独立于执行环节；将决策和标准制定权留给人类；系统倾向于熵增，因此需要持续维护。 只有提前深思熟虑的人才能从循环中获益。若指望循环替你思考，它会愉快地和你一起大规模地做出错误判断。
来源：Wiener的两层反馈机制（《人有人的用处》，1950），用于区分决策/执行层级和红线规则；规划/构建/判定模式来自Anatoli的《Loops explained》和Addy的《Loop Engineering》。 机制层内容（循环架构搭建方法）：请参考/autonomous-loops。本技能不重复实现机制层内容；仅覆盖目标定义和失控预防。continuous-agent-loop