Loop State Template：为 Agent 循环构建外部状态记忆的实战指南

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇文章基于 learn-harness-engineering 仓库中 loop-state-template.md 展开。仓库为只读资源文中所有分析与示例均用于帮助读者理解、查看与运行不涉及对仓库本身的修改。导读在循环工程Loop Engineering中每个 Agent 循环都必须有一个持续跟踪当前进度的状态文件——这就是 Loop State Template循环状态模板存在的意义。本篇文章带你逐段拆解这份模板的完整结构说明它如何在每轮结束更新、每轮开始读取的节律中充当循环的外部状态记忆并结合仓库中配套的 Goal / Maker / Checker 模板讲清楚如何在真实项目中落地一个带状态、可追溯、可干预的 Maker-Checker 循环。读完本文你将能够直接复制这套模板到自己的循环工程里并用累计统计与阻塞列表驱动是否需要人工介入的判断。循环为什么需要状态文件外部状态原语在 第13讲手动提示到自主循环 中作者将循环工程拆解为六个原语自动化Automation、Worktree 隔离、技能Skills、连接器Connectors、子代理Sub-agents与外部状态External State。其中外部状态被单独强调为循环的骨架——其他所有原语都依赖它。原因很简单模型在每次执行之间会忘记一切。记忆不能存放在上下文窗口里而必须存放在磁盘上。Loop State Template 正是这一理念的最小落地物——它用一份 Markdown 文件回答循环最核心的三个问题循环现在进行到哪了Basic Info / Cumulative Stats每一轮发生了什么Round Log下一步该做什么、卡在哪里Next round plan / Blocker List正如模板开篇注释所写Every loop should have a state file tracking current progress. Update at the end of each round; read at the start of the next round. 每个循环都应该有一个状态文件跟踪当前进度。每轮结束时更新它下一轮开始时读取它。这一轮末写入、轮初读取的节律正是循环摆脱单次会话记忆限制、实现跨轮连续性的关键。模板总览六个板块构成一份完整状态Loop State Template 由六个板块组成各自承担不同的职责。完整模板原文如下可直接复制使用# Loop State Template Every loop should have a state file tracking current progress. Update at the end of each round; read at the start of the next round. ## Basic Info - **Loop name**: !-- e.g. Unit test completion loop -- - **Started**: 2026-07-09 10:00 - **Current round**: Round 1 / N total - **Current status**: In progress !-- In progress / Completed / Blocked / Failed -- - **Total elapsed**: 0h 0m ## Goal !-- What this loop is trying to achieve -- ## Round Log ### Round 1 - **Started**: - **What the Maker did**: - **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial - **Issues found**: - - **Next round plan**: - **Human intervention needed**: Yes / No ### Round 2 - **Started**: - **What the Maker did**: - **Verification result**: ✅ Pass / ❌ Fail / ⚠️ Partial - **Issues found**: - - **Next round plan**: - **Human intervention needed**: Yes / No !-- Copy the format above and keep adding -- ## Cumulative Stats | Metric | Value | |--------|-------| | Rounds completed | 0 | | Passed rounds | 0 | | Failed rounds | 0 | | Total issues found | 0 | | Human interventions | 0 | | Files changed | 0 | ## Blocker List !-- Record recurring issues so the next round is aware -- - ## Final Result !-- Fill in when loop ends -- - **Final status**: Completed / Failed / Manually stopped - **Finished at**: - **Summary**: - What was done - How it went - What was learned - How to improve next time下面逐板块讲解其设计意图与使用要点。Basic Info循环的元数据与心跳Basic Info 是循环的身份证回答我是谁、跑到哪了、还活着吗Loop name循环的唯一标识例如 Unit test completion loop单测补全循环。建议使用与任务强相关的命名便于多循环并行时区分。Started启动时间戳。它是计算 Total elapsed 的起点。Current round当前轮次如Round 1 / N total。N可以是预算上限也可以先写为占位循环结束后回填实际总轮数。Current status循环的四态枚举——In progress进行中/Completed已完成/Blocked阻塞/Failed失败。这一字段是循环控制逻辑判断是否继续的首要依据。Total elapsed累计耗时。长时间运行的循环数小时甚至数天尤其需要它用于判断是否超出时间预算。这五个字段共同构成了循环的心跳任何外部观察者人类或另一个代理只需读取 Basic Info 就能快速判断循环的健康状况。Goal把目标固化到磁盘Goal 板块只有一行注释占位!-- What this loop is trying to achieve --但它承担着最重要的作用把循环要达成的最终状态固化下来。在 goal-template.md 中仓库给出了更完整的目标文档写法包含四个部分Goal一句话目标、Acceptance Criteria机器可验证的验收标准、ScopeFair game / Hands off 边界、Stop Conditions停止条件。Loop State Template 中的 Goal 板块正是 goal 文档的浓缩版——它不重复全部细节而是确保每个循环的每一轮都能看到我们最终要达成什么。一个可参考的填写示例## Goal 为所有 API 模块补齐单元测试使模块覆盖率 ≥ 80%且 lint 零错误、TypeScript 类型检查通过。目标越具体、越可机器验证循环质量越高——这与 goal-template.md 开头强调的 The more specific and verifiable, the higher the loop quality 一脉相承。Round Log逐轮事实记录Round Log 是模板中最核心、也是篇幅最大的板块。每一轮都是一个### Round N小节包含六个字段Started本轮开始时间。What the Maker didMaker实现代理本轮实际做了什么——改动了哪些文件、实现了什么逻辑。注意这里的Maker指代循环中的实现角色与 maker-prompt.md 中定义的 Maker Agent 一致。Verification result验证结果三态——✅ Pass通过/ ❌ Fail失败/ ⚠️ Partial部分通过。部分通过通常意味着主路径通了但存在边缘用例或质量问题。Issues found本轮发现的问题清单逐条列出。若验证者是 Checker 角色这些问题应当来自 checker-prompt.md 中要求的每个问题必须包含描述、位置、证据与严重级别的输出。Next round plan下一轮的计划。这是循环自主决策的书面化——上一轮结束时把下一步计划写下来下一轮开始时直接按计划执行避免每次重新头脑风暴。Human intervention needed是否需要人工介入Yes / No。这是状态文件与人类之间的信号接口。Round Log 的设计要点在于只记事实、不写评价。每轮记录做了什么、验证结果如何、发现什么问题让整条时间线完全可追溯。模板通过注释!-- Copy the format above and keep adding --提示使用者按此格式持续追加### Round N小节直到循环结束。Cumulative Stats把散落数据汇成决策指标Cumulative Stats 是一张六行指标表把 Round Log 中散落的记录汇总为可决策的累计数据Metric指标含义Rounds completed已完成轮数Passed rounds通过的轮数Failed rounds失败的轮数Total issues found累计发现的问题总数Human interventions累计人工介入次数Files changed改动的文件总数这六项指标让循环的运行轨迹一眼可见如果 Failed rounds 持续增长而 Passed rounds 停滞说明循环正在原地打转应该触发人工介入或停止条件如果 Human interventions 频繁为 Yes说明任务的自动化边界还没设计好。在 project-07 项目文档 的实验3Maker-Checker 循环中作者要求每个循环的loop-state.md至少记录 5 轮且每轮都要记录轮次编号、Maker 做了什么、Checker 发现了什么问题、通过/失败、你是否介入以及为什么介入——这正是 Cumulative Stats 与 Round Log 组合使用的规范操作。Blocker List跨轮记忆的关键Blocker List 是模板中最容易被忽略、却最体现外部状态价值的板块它专门用来记录反复出现的问题让下一轮开始时对已知障碍心中有数。例如## Blocker List - 构建环境缺少 Python 3.11需人工安装第 2、4 轮均因此失败 - src/main.ts 与 src/xx/ 存在未声明的隐式依赖改 xx/ 会破坏构建它的意义在于模型每一轮都会失忆但如果把反复踩到的坑写进 Blocker List下一轮读到状态文件时就会带着这些记忆开始——这正是模型会忘记但仓库不会忘记的具体体现。Final Result循环的收尾与复盘当循环结束时无论 Completed / Failed / Manually stopped在 Final Result 板块填写最终结果Final status终态枚举——Completed完成/ Failed失败/ Manually stopped人工停止。Finished at结束时间。Summary四段式总结——做了什么What was done、进展如何How it went、学到了什么What was learned、下次如何改进How to improve next time。四段式总结的价值在于把一次循环的经验沉淀为下次循环的输入。改进点可以回填到下一份 Goal 模板或 Maker / Checker 提示词中形成组织级的学习闭环。实战落点与 Maker / Checker / Goal 模板的配合Loop State Template 不是孤立存在的。在仓库的 lecture-13 code 目录 中它与其他三份模板构成了一套完整的循环工具箱模板角色与状态文件的关系goal-template.md定义目标、验收标准、范围与停止条件决定 Loop State 中 Goal 板块与停止判断的依据maker-prompt.md定义 Maker 实现代理的角色与产出格式每轮Maker 做了什么的来源checker-prompt.md定义 Checker 验证代理的角色与问题清单每轮验证结果 / 发现的问题的来源loop-state-template.md记录循环全程的状态串联所有角色的公共记忆层一个典型循环的运转方式如下轮初读取新一轮开始时循环控制逻辑或下一个代理读取loop-state.md获取上一轮结果、当前轮次、Next round plan 与 Blocker ListMaker 执行Maker 按 maker-prompt.md 实现本轮任务产出修改文件清单 实现摘要 基础验证结果 不确定区域Checker 验证Checker 按 checker-prompt.md 逐项核对清单并运行验证命令输出总体裁决 问题清单含位置、证据、严重级别 验证命令结果轮末写入根据 Checker 结果更新loop-state.md——追加 Round Log、刷新 Cumulative Stats、必要时更新 Blocker List 与 Current status停止判断对照 goal-template.md 中的停止条件验收全部通过 / 达到最大轮数 / 连续 3 轮无进展 / 遇到无法独立解决的阻塞决定继续还是终止。其中Checker 的每个问题必须附带证据要求直接保证了写入 Round Log 的 Issues found 是可信的——这正是循环工程中最重要原则Maker 与 Checker 必须分离代码的作者不能为自己的作业打分在状态层的体现。落地建议与最佳实践综合模板本身与 第13讲 的论述以下是使用 Loop State Template 的几条实战建议文件命名统一将状态文件命名为loop-state.md并放在循环工作目录的固定位置便于每个代理稳定读取project-07 实验3 即采用此约定。每轮必更新、更新必完整六项 Basic Info、本轮 Round Log、Cumulative Stats 必须在轮末一次更新到位切忌拖延——状态文件一旦滞后循环就失去了记忆。用三态而非二态判断验证✅ Pass / ❌ Fail / ⚠️ Partial 比简单的对/错更能反映真实情况Partial 通常意味着需要 Maker 下一轮聚焦修复已知问题。Blocker List 及时沉淀只要某个问题出现两次就写入 Blocker List下一轮读到即绕开能显著减少无效重试。以累计指标驱动人工介入不要每轮都盯着屏幕而是设定规则——例如连续 2 轮 Fail 或 Partial 即触发人工介入Human interventions 达到预算上限即 Manually stopped。让状态文件替你决定何时需要你而不是你替循环决定每一步。从最小状态开始如第13讲主なまとめ所言先从一个/goal、一个 cron、一份 Markdown 内存文件开始看到收益后再向上叠加。Loop State Template 的哲学可以浓缩为一句话模型会忘记但仓库不会忘记。把循环的进度、问题与决策写进磁盘上的状态文件你的循环才能真正脱离你的键盘、自主运转。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐为 Agent 循环建立持久化记忆Loop State Template 循环状态文件实战指南learn-harness-engineering为 Agent 循环建立持久化记忆Loop State Template 循环状态文件实战指南learn harness engineering 循环状态Loop State 模板实战为自动化循环装上记忆中枢——learn-harness-engineering 循环工程状态文件全解Loop State 模板实战为自动化循环装上记忆中枢——learn harness engineering 循环工程状态文件全解 循环状态文件Loopjcode Todo 语义化评估迁移指南从 0-100 数值分到语义枚举状态机jcode Todo 语义化评估迁移指南从 0 100 数值分到语义枚举状态机 本文是 jcode 仓库中 .jcode/semantic todo migr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考