learn-harness-engineering 的 CLAUDE.md 模板：为长期 Agent 任务设计的会话契约与操作规范

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文以开源仓库 learn-harness-engineering 中韩文资源库docs/ko/resources/templates/CLAUDE.md为骨架剖析这份面向 Claude Code 的 Harness 模板它定义了每次会话开始时的运营循环Operating Loop、五条行为铁律、四个必需文件、完成门Completion Gate与收尾规程目标是把一次一个功能、证据驱动完成、会话间可续跑的纪律固化进 Agent 的工作流。读完本文你将理解模板每一节的工程动机掌握如何把它复制进自己的项目并替换为项目专属命令与路径同时看到它在仓库内 project-03 等真实工程中的落地形态。模板的定位harness 资源库中的可复制操作规范该模板开篇即说明自身性质它是包含在 Harness 资源库中的一个示例模板sample template使用方式是复制到实际项目中再按项目独有的命令与路径进行修改。模板还强调它与AGENTS.md结构完全相同只是按照 Claude Code 的指令风格instruction style做了格式化。这一点对使用者非常重要模板文件本身不是一成不变的咒语而是一个结构骨架——AGENTS.md面向通用 AgentCLAUDE.md则针对 Claude Code 调整措辞与强调点但二者共享同一套 Harness 设计哲学。仓库中projects/project-03/solution/AGENTS.mdAGENTS.md就是该哲学在真实工程中的实现其中写道 This is the core discipline of Project 03并把一次只实现一个功能称为项目的核心纪律。模板随之给出总纲性定位使用者正在一个为长期实现任务long-term implementation work设计的仓库中工作因此要把可靠地完成reliable completion、会话间连续性continuity、显式验证verification置于速度之上。这句话是整个模板的灵魂后面所有小节都是对这三个词的展开。一、运营循环Operating Loop每次会话的固定开场模板要求每次会话开始时按顺序执行以下六步运行pwd确认位于预期的仓库根目录读取claude-progress.md读取feature_list.json运行git log --oneline -5检查最近提交运行./init.sh确认基线baseline的 smoke 或端到端路径是否已经损坏。这套循环的设计动机是先恢复上下文再动手写代码Agent 在跨会话工作时没有人类那样的长期记忆唯一可靠的记忆载体是仓库本身因此每一轮都从我上次停在哪里、功能处于什么状态、依赖是否可构建、基线是否健康四个问题开始。仓库中的真实实例完整展示了这套循环的执行产物pwd校验了路径前提避免在错误目录中运行后续命令claude-progress.md承载会话日志。以 claude-progress.md 为例它按 Session 组织记录了每个功能的实现时间、改动文件、验证命令与结果例如 metadata-extraction 一节明确写有 Verified:npm run checkpassesfeature_list.json是当前所有功能的状态表详见下文必需文件git log --oneline -5让 Agent 快速感知仓库最近发生过什么避免基于过期认知决策./init.sh负责把环境恢复到可构建状态。仓库中 project-03 的 init.sh 是一个典型的短小实现set -euo pipefail保证任一步失败即终止依次执行npm install、npm run check、npm run build最后输出 Init complete. All checks passed. 提示npm run dev启动第 6 步要求 Agent 在开工前先探测基线是否已损坏——若基线已坏说明上一会话留下了不干净的状态修复基线应先于开发新功能。在通用性上仓库还提供了更健壮的初始化脚本模板 skills/harness-creator/templates/init.sh它会根据pnpm-lock.yaml、yarn.lock、bun.lock自动选择包管理器然后按check/typecheck/type-check、lint、test、build的顺序只运行 package.json 中实际存在的脚本通过node -e探测 scripts 字段并对 Pythonpytest与compileall、Gogo test ./...、Rustcargo test、Javamaven/gradle、.NETdotnet test等生态给出对应的验证分支最后提示 Read feature_list.json … Pick ONE unfinished feature。这解释了模板中./init.sh这一步为什么可以被抽象为任何语言项目的统一开工仪式。完成六步后模板给出指令精确选择一个未完成的功能只做这一个直到验证完成或被明确记录为受阻blocked为止。这与 AGENTS.md 的一次一个功能策略完全同构——见 AGENTS.md 中 One-Feature-at-a-Time Policy 一节它甚至给出了功能依赖图metadata-extraction → document-chunking → indexing-status-ui / grounded-qa把选哪个功能也变成了有据可依的决策。二、规则Rules五条行为铁律模板用五条规则约束 Agent 的行为边界每条都对应一个常见失败模式一次只允许一个活跃功能One active feature at a time对应 lecture-07 why-agents-overreach-and-under-finish 所讨论的过度越界问题。仓库中 AGENTS.md 将其升格为策略并明确惩罚逻辑在同一轮中实现多个功能或编辑当前功能范围之外的文件是这个项目最常见的 bug 与回归来源没有可执行的证据evidence不得声称完成这是证据驱动完成的直接落地。feature_list.json 的每条记录都要求填写evidence字段详见下文而 lecture-09 why-agents-declare-victory-too-early 正是讨论 Agent 过早宣布胜利的问题不得为了隐藏未完成工作而重写功能列表防止 Agent 通过篡改feature_list.json把not-started改成pass来作弊不得为了看起来已完成而删除或弱化测试防止 Agent 删测试、加skip、把断言改宽松来通过验证以仓库产物作为系统记录system of record所有状态与结论都沉淀到仓库文件里而不是依赖模型记忆或对话历史。这与 lecture-03 why-the-repository-must-become-the-system-of-record 的主题一脉相承。这五条规则本质上构成一个反作弊 可审计契约状态只能通过真实验证推进仓库本身是唯一可信账本。三、必需文件Required FilesHarness 的最小文件集模板明确列出四个必需文件并说明各自职责文件职责仓库中的对应实例feature_list.json功能清单与状态机project-03/solution/feature_list.jsonclaude-progress.md会话进度日志project-03/solution/claude-progress.mdinit.sh环境初始化与基线验证project-03/solution/init.shsession-handoff.md会话交接文档在简短交接有用时project-03/solution/session-handoff.md3.1 feature_list.json功能状态机仓库实例展示了该文件的完整结构顶层包含project、description、features数组每条 feature 记录含id、name、description、status、evidence、testedAt六个字段。例如{ id: grounded-qa, name: Grounded QA with Citations, description: QaService returns answers with document citations, excerpts, and confidence scores, status: pass, evidence: QaService.ask() retrieves chunks via IndexingService.getAllChunks(), scores by keyword overlap, returns top 2 as citations ... Confidence: 0.85 with citations, 0.30 without., testedAt: 2026-03-30T13:00:00Z }从结构可以推断status至少存在pass与not-started两种取值AGENTS.md 明确要求选择not-started的功能去实现而evidence字段的存在正是为了满足无可执行证据不得声称完成的规则——每条记录都要写清做了什么、如何验证、结果如何。testedAt提供了时间维度让跨会话审计成为可能。仓库还提供了带 schema 校验的模板 skills/harness-creator/templates/feature-list.json 与 feature-list.schema.json说明该文件在 Harness 体系中是一个结构化、可校验的原语与 lecture-08 why-feature-lists-are-harness-primitives 的观点一致。3.2 claude-progress.md可续跑的会话日志模板规定每次会话都要读它而收尾时还要更新它。仓库实例 claude-progress.md 展示了理想结构按Session N组织每个功能一节包含目标、改动清单、验证证据如 Verified:npm run checkpasses、以及对feature_list.json的同步更新记录。它解决的是 lecture-05 why-long-running-tasks-lose-continuity 中的长任务连续性问题——进度不放在对话里而放在文件里任何新会话都能无缝续跑。3.3 init.sh可重复的开工仪式见上文运营循环第 5 步的源码分析。核心价值是可重复性无论谁来、什么时候来./init.sh的输出都代表环境是否就绪的同一把标尺。3.4 session-handoff.md跨会话的上下文接力模板将其定位为当简短交接有用时的补充文件。仓库实例 session-handoff.md 展示了标准结构What Was Accomplished按功能列出成果与文件、What Remains、Decisions Made记录关键决策及其理由例如 Metadata is extracted at import time rather than lazily、Files Modified逐文件列出改动、Blockers、Next Steps。它与 skills/harness-creator/templates/session-handoff.md 以及 progress.md提供更细粒度的 Current State / Whats Done / In Progress / Next / Blockers / Decisions / Evidence of Completion 结构共同构成上一会话 → 下一会话的交接管线。四、完成门Completion Gate验证是状态的唯一推进器模板规定只有在必要验证成功且结果被记录之后功能才能被移动到passing状态。这句话把完成定义为两个条件的合取验证成功——代码真的通过了构建/检查/行为验证而不是我觉得可以了结果已记录——验证证据写入了feature_list.json的evidence字段和/或claude-progress.md的会话日志。仓库实例忠实地执行了这一门禁feature_list.json中 11 条 feature 全部处于pass且每条都有具体证据例如 indexing-status-ui 的证据描述了 StatusBar 的颜色编码逻辑与 App.tsx 的轮询机制而claude-progress.md的每个功能小节都以 Updatedfeature_list.json: xxx - pass 收尾正好对应验证 → 记录 → 推进的顺序。这一机制直接对抗 lecture-09 讨论的过早宣布胜利问题没有完成门Agent 的完成只是口头承诺有了完成门完成变成仓库中的一个可验证状态迁移。同时AGENTS.md 要求提交信息引用 feature IDCommit the change with a message referencing the feature ID进一步把每次状态迁移都固化进 git 历史形成可审计的链条。五、停止前Before You Stop为下一次会话留下干净的退出路径模板规定停止工作前必须完成五步更新进度日志progress log——对应更新claude-progress.md更新功能状态feature state——对应更新feature_list.json记录仍然损坏或未经验证的内容——把已知问题显式写出来而不是装作不存在当仓库处于可恢复resumable状态时提交——用 git 固化一个可续跑的检查点为下一次会话留下干净的重新开始路径clean restart path。这五步合起来构成离开时仓库必须比到来时更有序的纪律与 lecture-12 why-every-session-must-leave-a-clean-state 的主题完全一致。仓库中的 clean-state-checklist.md 是这条纪律的检查清单化产物它把干净状态拆解为可勾选的条目例如Build Verificationnpm install无错误、npm run check零 TypeScript 错误、npm run build产出 dist/Feature Verification功能清单全部通过、状态栏指示正确、答案包含引用与置信度、数据跨重启持久化等Scope Control Verificationfeature_list.json 全部为 pass、每条有证据、无 fail/not-started、依赖关系被记录DocumentationARCHITECTURE.md / PRODUCT.md / session-handoff.md / claude-progress.md 均已更新。第 3 步记录仍损坏或未验证的内容尤其关键——它允许 Agent 诚实地说没做完但禁止它不留下任何痕迹地消失从而保证下一个会话不会基于错误假设开工。六、从模板到项目四步落地法结合模板自身说明与仓库实例把这份 CLAUDE.md 落到真实项目的完整流程是第 1 步复制模板。将模板复制为项目根目录的CLAUDE.md若同时使用多 Agent可连同等价的AGENTS.md一起维护二者结构相同。第 2 步替换命令与路径。这是模板明确要求的修改动作——把./init.sh换成项目实际的初始化命令把读取 feature_list.json / claude-progress.md替换为项目实际文件名若沿用默认名则无需改动把 smoke/端到端路径替换为项目真实的基线路径。第 3 步补齐四个必需文件。参考 skills/harness-creator/templates/ 下的 feature-list.json、progress.md、init.sh、session-handoff.md 模板创建项目自身的版本。通用 init.sh 模板的优势在此显现它能自动识别包管理器与语言生态并只运行存在的脚本因此几乎无需定制即可使用。第 4 步按运营循环跑通第一个会话。从pwd到基线检查全部执行一遍确认模板中的每一步在项目里都有对应物随后严格按一次一个功能策略开始第一个功能并以实现 → 验证 → 记录 evidence → 更新 feature_list.json → 提交的闭环推进。仓库中 project-01 至 project-08 的 solution 目录都是这套模板在不同阶段工程中的产物project-03 展示了最完整的四件套feature_list.json、claude-progress.md、init.sh、session-handoff.md 全部齐备而 project-04 起逐步引入 clean-state-checklist.md 与更复杂的验证脚本体现了模板随项目成熟而演化的过程。学习资料可配合 docs/ko/lectures 中对应讲座阅读lecture-03仓库作为系统记录、lecture-05长任务连续性、lecture-06初始化阶段、lecture-08功能列表原语、lecture-09过早胜利、lecture-12干净状态它们分别解释了模板各小节的底层动因。结语这份 CLAUDE.md 模板看起来只有几十行但每一节都对应一个真实的 Agent 失败模式不确认目录导致命令跑错位置、不读进度导致重复劳动、不验证就声称完成、偷偷改状态掩盖未完成、离开时留下一堆未提交的混乱。运营循环解决如何开始五条规则解决如何行为四个必需文件解决状态存哪里完成门解决怎样才算完成停止前规程解决如何离开。把这些纪律固化进模板并在每个项目里一致执行正是 learn-harness-engineering 所倡导的从 0 到 1 构建 Harness的第一步——也是让长期、多会话的 Agent 工程真正可交付、可审计、可续跑的基础设施。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 的 CLAUDE.md 模板解读为长期运行 Agent 会话设计可靠操作循环learn harness engineering 的 CLAUDE.md 模板解读为长期运行 Agent 会话设计可靠操作循环 导读 本文基于 docs/e面向长期执行任务的 Agent 会话模板解读 learn-harness-engineering 仓库中的 CLAUDE.md 设计面向长期执行任务的 Agent 会话模板解读 learn harness engineering 仓库中的 CLAUDE.md 设计 导读 本文剖析 learlearn-harness-engineering 的 CLAUDE.md 模板为长时间 Agent 实现任务设计可靠的操作循环learn harness engineering 的 CLAUDE.md 模板为长时间 Agent 实现任务设计可靠的操作循环 本篇技术指南以 docs/j上一篇如何用dedao-dl高效管理得到APP学习资源完整实战指南下一篇Unpaywall终极指南3分钟破解学术付费墙的免费解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考