编写可验证的 Goal 模板learn-harness-engineering 中从/goal到 Maker–Checker 循环的实战指南【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering在 harness 工程中把一次手动提示升级为一条自律循环的关键是先把任务写成一个「可验证的 Goal 文档」。本文以 learn-harness-engineering 仓库第 13 讲配套模板 goal-template.md 为主体逐步拆解 Goal 模板的每一个字段——Goal、Acceptance Criteria、Scope、Verification Method、Stop Conditions、How to Work——并结合仓库中的 maker-prompt.md、checker-prompt.md、loop-state-template.md 以及 项目 07 实验文档给出可直接复制使用的完整模板与配套工作流。读完本文你将掌握如何把一个模糊需求改写成机器可验证的 Goal、如何定义不会让循环失控的停止条件、如何设计「生成者/检验者分离」的闭环以及如何用循环状态文件记录每一轮迭代。Goal 模板是什么一个循环的最小骨架在 第 13 讲主文档 中/goal被定义为最简单的循环它由且仅由三个部分组成Goal目标——最终状态应该是什么样Verification验证方法——如何确认目标已达成Stop Conditions停止条件——何时停下来包括成功与失败两种情况。模板的引言把这一点说得非常直白Write your goal as a document like this, then hand it to/goalor a maker agent. The more specific and verifiable, the higher the loop quality.也就是说goal-template.md 不是写给人类看的任务单而是直接交给/goal或 Maker 智能体的输入文档。模板中的每一节注释!-- ... --都在提醒你同一个原则写得越具体、越可验证循环的质量就越高。这也是「循环工程」的核心思想——你不给智能体一条一条的指令而是给它一个最终状态和一套裁判规则让它在规则内自主迭代。逐节拆解 Goal 模板1. Goal一句话说清「做什么」模板的第一个区块只有一行示例## Goal Implement the XX feature with complete unit test coverage.这里的关键不是示例本身而是注释里的一句话One sentence describing what to do用一句话描述要做什么。写 Goal 时要避免动词堆砌「分析代码、写实现、补测试、跑测试、修 bug……」——这是过程不是目标没有完成边界「改进 XX 模块」——什么叫改进无法判断让智能体自行解释「把支付系统做好」——好的 Goal 应当让智能体无需猜测完成标准。一个合格 Goal 的检验方法是把它交给一个完全不了解上下文的智能体它能否仅凭这句话和验收标准就知道自己在做什么、做到什么程度算完。从 项目 07 文档 给出的示例看仓库推荐的写法是「所有模块的单元测试覆盖率达到 80%」或「为所有 API 端点添加输入校验」这类带有明确完成度量的任务。2. Acceptance Criteria全部能被命令验证验收标准是 Goal 模板里信息密度最高的部分模板给出的完整清单是## Acceptance Criteria !-- Machine-verifiable completion conditions — each one can be checked with a command -- - [ ] npm test passes fully - [ ] Coverage report shows XX module coverage ≥ 80% - [ ] npm run lint has zero errors - [ ] TypeScript type check passes (npx tsc --noEmit) - [ ] All new code follows project coding standards注意注释中的限定词Machine-verifiable机器可验证。每一条验收标准都必须能用一条命令去检查。这条规则在第 13 讲中被总结为「验证的债务」verification debt的解法——停止条件必须由机器判定「差不多对了」永远不算数。对照本仓库的实际项目这些命令不是凭空想象的npm test对应各项目的 vitest 测试套件例如 project-06/solution/CLAUDE.md 中明确记录了npm test # Run vitest suitenpx tsc --noEmit对应所有 TypeScript 项目的tsconfig.json类型检查覆盖率、lint 与类型检查共同构成 project-06/solution/AGENTS.md 中「feature 出现在feature_list.json且状态为pass、附有证据」这一判定标准的前置条件。在项目 07 中这套标准会进一步落到goal.md里与「手动执行 vs/goal执行」的对比实验结合两次执行使用同一套验证标准才能公平比较轮数与质量见 项目 07 实验 1。3. Scope明确「可以碰」和「不许碰」模板把范围分成两个清单## Scope ### Fair game - All files under src/xx/ - Test files under tests/ - Related type definition files ### Hands off - src/main.ts entry file - Database schema migrations - Dependency versions in package.json (unless explicitly needed) - CI/CD config files这个区块的价值在于提前划定主权边界。自律循环的智能体在没有约束时倾向于过度扩张——这正是第 7 讲「智能体越界与欠完成」问题的循环版本。Hands off列表写的是「即使看起来顺手也不要动」的部分入口文件如src/main.ts改动影响全局启动流程数据库 schema 迁移数据层变更风险不可由智能体单方面承担依赖版本除非任务明确要求否则升级依赖可能引发连锁失败CI/CD 配置外部流水线属于人治范围。同样地Fair game写得越具体越好。与其写「相关文件」不如像模板那样列出目录与文件类型。这个习惯与仓库中feature_list.json的用法一致——project-06/solution/AGENTS.md 要求智能体「先读feature_list.json了解所有功能的当前状态」因为明确的功能边界是智能体不越界的前提。4. Verification Method规定每一步之后的验证顺序模板给出的验证流程是一个串行门禁## Verification Method 1. After implementation, run these commands in order: 1. npx tsc --noEmit — type check 2. npm run lint — code style 3. npm test — unit tests 4. npx vitest --coverage — coverage check 2. Fix any failures before moving to the next step. 3. When everything passes, run the full end-to-end test suite (if available).设计要点有两条按成本从低到高排列类型检查最快、能拦截绝大多数低级错误放在最前覆盖率检查最重放在最后。任何一步失败都立即回头修复而不是带着错误继续往下跑——这能显著降低「在错误代码上叠错误」的概率。以端到端测试收尾单测与 lint 全部通过后再运行完整的端到端测试套件如果项目里有。这呼应了第 10 讲「端到端测试会改变结果」的结论单元层面通过不等于集成层面正确。这个门禁顺序在项目 07 中同样被复用goal.md的「验证方法」一栏就是回答「怎么确认完成」——跑测试跑 lint查覆盖率见 项目 07 实验 1 步骤 1。5. Stop Conditions循环的刹车系统模板中的停止条件是循环能否「自主收尾」的关键## Stop Conditions - All acceptance criteria pass ✅ - Max turns reached: 20 - No progress for 3 consecutive rounds (same error keeps appearing) - Blocking issue that cannot be resolved independently (e.g., missing dependency, environment problem)四类停止条件各有分工停止条件类型含义所有验收标准通过成功终止循环正常完成进入 Checker/人工审查达到最大轮数20预算上限防止无限消耗 token 与时间连续 3 轮无进展同一错误反复出现停滞检测识别「原地打转」并主动放弃无法独立解决的阻塞问题环境例外缺依赖、环境故障等需要人工介入的情况设计停止条件的核心原则是让循环在「做完」和「做不下去」两种情况下都能体面退出。只写成功条件会导致智能体永远不承认失败只写预算上限会导致它在死胡同里浪费 20 轮。第 13 讲中提到的「独立裁判」思想在这里同样适用——停止条件不应由执行者自说自话而应由模板事先固化最好由独立的 Checker 会话或命令执行结果来触发详见 第 13 讲生成者/检验者的分离。6. How to Work给执行者的操作约定模板最后一段定义了执行者Maker的行为准则## How to Work 1. Read AGENTS.md and feature_list.json first to understand the project structure and existing features. 2. Write out the design approach before touching code. 3. Verify after each sub-task is done. 4. If stuck for more than 2 rounds, switch approach or simplify. 5. Update progress at the end of each round.这五条把第 13 讲之前所有讲座的成果串了起来第 1–4 讲建立的AGENTS.md是项目规则的唯一权威来源第 8 讲的feature_list.json是「哪些功能已存在」的权威数据源project-06/solution/feature_list.json 即为此类文件的实际示例「先写设计再动代码」为 Checker 提供了可对照的意图基线「每完成一个子任务就验证一次」把验证债务消灭在萌芽「卡住超过 2 轮就换方案」与停止条件中的「3 轮无进展」互为表里「每轮结束更新进度」让循环状态可被外部读取这正是循环状态模板存在的意义。模板的循环上下文Maker、Checker 与状态文件Goal 模板不是孤立存在的。在仓库的code/目录中它与另外三个模板配套使用共同构成一条完整的自律循环对应 第 13 讲中「完整的循环解剖」一节的流程图maker-prompt.md——实现者提示词。Maker 的职责是理解需求、设计方案、写代码、跑基础验证build / lint / 单测然后把结果交给 Checker 审查。模板明确要求 Maker 输出修改文件清单、实现摘要、基础验证结果、以及「自己不确定的部分供 Checker 重点审查」。checker-prompt.md——检验者提示词。Checker 的职责与 Maker 完全相反「你不是来表扬的你是来找茬的没找到问题就是你的失职。」其检查清单覆盖功能正确性、代码质量、测试有效性、验证命令、安全与影响五个维度并且要求每个问题都附上位置file:line、证据和严重级别Critical / Medium / Minor最后给出 Pass / Fail / Minor issues 的总体裁决。loop-state-template.md——循环状态模板。每条循环都应有一个状态文件每轮结束时更新下一轮开始时读取。其结构包含循环基本信息、Goal、逐轮日志Maker 做了什么、验证结果、发现的问题、下一轮计划、是否需要人工介入、累计统计轮数、通过/失败、问题数、人工介入次数、变更文件数、阻塞列表与最终结果。这三者与 goal-template.md 的关系可以概括为Goal 模板回答「做什么、做到什么程度、何时停」——是循环的输入Maker 提示词回答「怎么干」——执行者行为契约Checker 提示词回答「怎么判」——独立裁判的审查契约状态模板回答「现在到哪了」——跨轮记忆载体对应第 13 讲的「外部状态」原语模型每轮都会遗忘记忆必须落在磁盘上。项目 07 的第三个实验把这一整套落到了实操设计 Maker / Checker / 状态文件 / 停止条件四件套写三个提示词跑至少 5 轮并逐轮记录「Maker 做了什么、Checker 发现了什么问题、你是否介入」见 项目 07 实验 3。落地实操把模板变成goal.md并跑起来基于仓库文档将 goal-template.md 落地为一条真实循环的完整路径如下第一步选任务。找一个你每周至少手动做两次的中等规模任务完成标准必须清晰例如「为所有模块补充单元测试使覆盖率 ≥ 80%」项目 07 实验 1。第二步填写模板。把任务按 goal-template.md 的六个区块改写为goal.md一句话 Goal、可命令验证的验收标准、明确的 Fair game / Hands off 边界、串行验证命令、四类停止条件、五条 How to Work。项目 07 要求goal.md必须包含四类信息Goal何谓完成、验证方法如何确认、停止条件何时止步、约束哪里不许碰。第三步跑基线。先手动把任务交给智能体记录轮数、介入次数与结果质量再用同一个goal.md走/goal模式让智能体自行循环到目标达成或停止条件触发。两次使用同一验证标准对比项目 07 实验 1 步骤 3–4。第四步加裁判。把循环升级为 Maker–Checker 结构Maker 实现 基础验证Checker 独立复核并给出带证据的问题清单状态文件记录每轮进展项目 07 实验 3。第五步挂定时器。用/loop或系统 cron 让循环定时启动例如每 10–30 分钟跑一次测试套件并自动修复失败项目 07 实验 2。常见误区与设计原则结合 goal-template.md 与第 13 讲的配套内容编写 Goal 模板时有几条高价值原则值得反复对照验收标准必须可命令化。每条验收标准都应能映射到npm test、npx tsc --noEmit、npm run lint、npx vitest --coverage这类命令的结果。「看起来不错」「基本能用」这类主观描述会直接转化为验证债务。停止条件要覆盖失败路径。只写「全部通过」的循环永远不会承认失败必须同时给出轮数上限、停滞检测和环境阻塞三类失败出口。写代码的人不能给自己打分。这正是模板把 Goal 与 Checker 提示词拆开的根本原因——生成者/检验者分离是第 13 讲强调的「循环设计中最重要的可靠性保证」本仓库通过 maker-prompt.md 与 checker-prompt.md 两个独立模板实现了这一点。范围清单越具体越界越少。Hands off列表中的每一项入口文件、schema、依赖版本、CI/CD都对应现实中智能体最容易顺手改坏的地方。状态文件是循环的续命符。每一轮结束更新、下一轮开始读取的循环状态文件见 loop-state-template.md让多轮循环不至于在模型每轮遗忘的背景下原地打转。小结goal-template.md 看似只是一份 Markdown 模板实则是「从手动提示走向自律循环」的最小落地工具。它用六个区块——Goal、Acceptance Criteria、Scope、Verification Method、Stop Conditions、How to Work——把/goal的三个核心目标、验证、停止展开为可直接执行的文档再与仓库中的 Maker 提示词、Checker 提示词、循环状态模板组合构成一条完整的 Maker–Checker 自律循环。仓库的项目 07 提供了从手动到/goal、再到定时与 Maker–Checker 的递进实验路径而第 13 讲主文档则从循环工程的高度解释了这些模板背后的设计原理。对希望让智能体在无人值守下持续产出可靠代码的团队而言从填写一份可验证的goal.md开始是最快也最稳妥的第一步。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考