Loop Engineering：把提示词变成可验证的工程循环

让 Agent 连续完成工作，不等于把一条更长的提示词交给它。真正可持续的自动化，需要把“发现什么值得做、怎样隔离执行、如何判定完成、下一次从哪里继续”变成系统能力。Loop Engineering 讨论的正是这件事：人不再逐轮催促模型，而是设计一个能自行推进、能在失败后停下并留下痕迹的控制循环。

从单轮对话到控制系统

普通的使用方式是：人提出任务，Agent 改代码，人检查结果，再补充下一条提示。循环式工作流把这个过程外置成状态机：定时任务发现待办，执行器领取一项工作，验证器检查产物，状态存储记录结果，调度器再决定是否进入下一轮。模型负责不确定性较高的推理；系统负责节奏、边界和证据。

一个循环至少要回答四个问题：目标是什么、当前处于什么阶段、什么证据可以宣布完成、什么情况必须交还给人。没有最后两个问题，所谓“自动完成”通常只是模型停止输出。

# .agent/tasks/fix-flaky-test.yaml
id: fix-flaky-test-142
goal: 修复 tests/auth/login.spec.ts 的偶发失败
acceptance:
  - pnpm test tests/auth/login.spec.ts --repeat=20 退出码为 0
  - pnpm lint 退出码为 0
  - 不修改认证接口的公开响应结构
state: queued
attempts: 0
artifacts: []

验收条件应该是可执行或可审阅的断言，而不是“修好它”“写得优雅一些”。一项任务越长，越要把完成定义从主观感受变成可重复检查。

一个闭环需要的部件

第一是触发器。它可以是每天扫描 CI 失败、每小时汇总新增 issue，或在合并请求创建后启动检查。触发器只负责发现和分流，不应顺手执行危险动作。

第二是隔离工作区。多个 Agent 并行修改同一目录，很快会把正确的思考变成错误的文件状态。Git worktree 让每项工作拥有独立分支与目录：

git fetch origin main
git worktree add ../worktrees/fix-flaky-test -b agent/fix-flaky-test origin/main
cd ../worktrees/fix-flaky-test
pnpm test tests/auth/login.spec.ts

第三是项目知识。构建命令、目录约束、禁止改动的接口、发布前检查，不应靠每次重新描述。把它们写入简短的 AGENTS.md 或按需加载的 skill；每一条规则都要能追溯到真实约束或真实事故。

第四是连接器与工具。文件系统、Git、测试命令和浏览器是代码任务的基础面；问题跟踪、文档、数据库与部署平台则通过受控接口接入。工具越多不一定越好：名称相近、职责重叠的工具会迫使模型猜测。一个清楚的读取工具、一个受审批保护的写入工具，通常优于十个模糊的万能工具。

第五是角色分离。生成代码的 Agent 不适合独自判定代码正确。将探索、实现和验证拆开，验证器只读取任务契约、变更和测试证据，不继承实现者的“我已经做对了”的叙述。

最后是外部记忆。对话结束后模型不会可靠地保留进度，仓库与任务文件才是跨轮次事实。状态文件不应堆满聊天原文，而要保存决策、证据、失败原因和下一步。

{
  "task": "fix-flaky-test-142",
  "phase": "verify",
  "last_commit": "8f1c2ab",
  "checks": { "repeat_test": "passed", "lint": "passed" },
  "next": "open_pr",
  "blocked_by": null
}

调度器只推进已被证明的状态

循环的核心不复杂：读取状态、选择动作、执行、观察、写回状态。关键在于不要把“模型说完成了”当作状态迁移的依据。

def advance(task):
    if task["state"] == "queued":
        return start_isolated_worker(task)

    if task["state"] == "implemented":
        report = run_acceptance_checks(task["worktree"], task["acceptance"])
        return mark(task, "verified" if report.ok else "repair", evidence=report.to_dict())

    if task["state"] == "verified":
        return request_human_approval(task)

    return task

这里的 run_acceptance_checks 是确定性代码，模型不能绕过它。对于发布、付费、删除数据、推送主分支等外部副作用，循环应在动作前进入 awaiting_approval，而不是凭“置信度很高”继续。

长循环的成本与刹车

自动循环最容易被忽略的是成本失控。每轮都应有最大尝试次数、时间预算、Token 预算和相同错误的熔断条件。连续三次得到同一测试失败，系统不该第四次用不同措辞重试，而应收集日志、保留工作区并生成需要人判断的阻塞项。

同时要区分“可并行”与“值得并行”。搜索不同文件、检查不同日志适合并发；修改共享配置、迁移数据库、合并同一分支则需要串行或显式锁。worktree 解决文件碰撞，不解决语义冲突；最终吞吐量往往由人能审多少变更决定。

高质量循环的价值不是把工程师移出回路，而是把工程师从重复轮询、复制日志和机械追问中移出。人仍然定义目标、约束和风险阈值；系统把这些判断稳定地执行下去。

让任务发现与任务执行解耦

把“找问题”和“改问题”放在同一个 Agent 里，往往会得到一串难以审计的连锁动作。发现器应只输出候选任务，并为每个候选项带上证据、影响范围和建议优先级；执行器只领取已经入队的任务。这样既能限制一次运行的权限，也能让团队回看：这个改动究竟由哪一次 CI 失败、哪个 issue 或哪条监控异常触发。

def triage(ci_failures, open_issues):
    candidates = []
    for failure in ci_failures:
        if failure.is_reproducible and failure.owner is not None:
            candidates.append({
                "kind": "ci_failure",
                "title": failure.title,
                "evidence": failure.url,
                "priority": "high" if failure.blocks_main else "normal",
            })
    return deduplicate_and_enqueue(candidates, open_issues)

去重很关键。定时任务每十分钟看到同一个报错，不应创建六份同样的工作；任务 ID、指纹和租约能保证同一时刻只有一个执行器拥有写权限。任务卡还应记录依赖关系：升级依赖与修复测试可能可以并发，数据库迁移与上线校验则必须有先后顺序。

完成条件需要独立裁判

循环里的一个常见陷阱是让执行 Agent 自己回答“是否完成”。它知道自己做过什么，也会自然地偏向把不确定处解释为成功。更稳妥的做法是把完成判定交给独立进程或独立 Agent，并只给它任务契约、变更集与验证证据。

def judge(task, diff, evidence):
    prompt = {
        "acceptance": task["acceptance"],
        "diff": diff,
        "evidence": evidence,
        "instruction": "逐项判断通过、失败或证据不足；不要修改代码。",
    }
    verdict = reviewer_model(prompt)
    return verdict if verdict.status != "pass" else require_machine_checks(evidence)

模型裁判也不是终点：能被命令验证的条件仍应由命令验证，能被类型系统、测试、静态分析或策略引擎覆盖的风险不应交给语言理解。独立裁判的价值在于发现“测试通过但需求没满足”“改动越界”“缺少回归测试”这类语义问题。

记忆文件应像交接班，而不是聊天记录

跨上下文恢复时，下一位执行者最需要的不是完整对话，而是可行动的交接信息。一个实用模板可以是：目标与非目标、已确认事实、已尝试方案及结果、当前工作区和提交、剩余步骤、阻塞原因、可验证命令。每项都尽量指向仓库文件、日志路径或 issue，而不是复制大段内容。

## 当前阶段
- 已完成：为登录重试增加固定时钟；提交 `8f1c2ab`
- 已验证：`pnpm test tests/auth/login.spec.ts --repeat=20`
- 未完成：全量 e2e 在 Linux runner 上仍有一次超时
- 下一步：读取 `.agent/evidence/linux-e2e-142.log` 的失败用例
- 禁止：不要提高全局测试超时，不要修改生产重试策略

这种文件同时服务人和 Agent。模型换代、会话重置、任务被转交时，项目事实仍留在可版本化的介质里；需要追责或回滚时，也能知道某个决定来自哪里。

从低风险循环开始扩展

最适合率先自动化的是只读、可重复、低副作用的工作：归类 issue、提取 CI 失败摘要、生成变更说明、检查依赖漏洞、跑固定测试。等到证据链、告警和审批流程稳定后，再把能力扩大到创建分支、提交 PR 或触发部署。每提高一级权限，都应新增对应的回滚与审计设计。

循环工程不是一台永远开着的许愿机。它是一组有预算、有证据、有暂停按钮的控制系统。把“何时继续”设计清楚，和把“如何开始”同样重要。