【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本指南以 learn-harness-engineering 仓库中的docs/ru/resources/templates/CLAUDE.md模板为核心骨架讲解如何为一类面向长期实现工作的仓库编写 Agent 指令文件。文章将覆盖会话启动操作循环、单功能推进规则、feature_list.json/claude-progress.md/init.sh/session-handoff.md四类必备文件的作用与结构以及完成门控与停前收尾的实现细节同时结合仓库内skills/harness-creator的模板与projects/下真实项目如 project-03的落地文件给出可直接复制使用的结构。读完本文你将能够为自己或团队的仓库搭建一套可验证、可恢复、抗自欺的 Agent 协作基线。一、这份 CLAUDE.md 模板解决什么问题普通项目的 CLAUDE.md 往往只回答这个项目是什么、怎么构建、关键文件在哪而 learn-harness-engineering 仓库中的这份模板docs/ru/resources/templates/CLAUDE.md面向的是另一种场景你工作在一个为长期实现工作而设计的仓库中。请把可靠收尾reliable completion、会话间连续性continuity between sessions和显式验证explicit verification置于速度之上。它的核心设计判断是Agent 不可靠的本质问题不是能力不足而是上下文断裂、越界发挥、过早宣称完成。因此模板不追求给 Agent 塞满项目信息而是用极短的篇幅定义五件事每次会话开头必须做什么操作循环工作推进的行为规则一次只做一个功能、禁止粉饰仓库里必须有哪几个文件作为系统账本功能从进行中到通过的完成门控停止工作前的收尾清单保证下一次会话能原地重启。这套思路与仓库中skills/harness-creator/SKILL.md提出的五子系统模型完全同构指令Instructions、状态State、验证Verification、范围Scope、生命周期Lifecycle。CLAUDE.md 模板正是指令子系统的最小载体其余子系统由它引用的文件承载。二、操作循环每次会话开头的六步模板在## Операционный цикл操作循环一节中规定了每次会话开始时的固定顺序。这六步的作用是在 Agent 动手改代码之前先把我在哪、上次做到哪、哪些已验证、当前基线是否健康重新装进上下文。1. 运行 pwd确认位于预期的仓库根目录。 2. 阅读 claude-progress.md进度日志。 3. 阅读 feature_list.json功能清单与状态。 4. 查看最近提交git log --oneline -5。 5. 运行 ./init.sh初始化/验证脚本。 6. 检查基础 smoke 或 end-to-end 路径是否已被破坏。逐步解释如下第 1 步pwd防止 Agent 在错误目录例如被拉起的子目录或临时副本中工作导致后续所有文件路径错位。第 2、3 步读状态文件这是仓库作为系统账本system of record原则的体现。会话之间唯一可靠的记忆载体是磁盘上的文件而不是聊天历史——skills/harness-creator/SKILL.md的 Design Rules 中明确要求 Prefer append/update state files over relying on chat history。第 4 步git log --oneline -5让 Agent 快速感知最近变更轨迹避免与上一次会话的提交发生冲突或重复实现。第 5 步运行./init.sh在开始任何编辑前先证明仓库是可验证的干净基线。init.sh的具体形态见下文必备文件一节。第 6 步检查 smoke / end-to-end 路径如果基础路径已经损坏那么本次会话的第一优先级就是修复它而不是叠加新功能。完成六步之后模板给出最关键的一句指令然后选择恰好一个未完成的功能只推进它直到完成验证或记录下阻塞原因。这一句把会话目标从模糊的继续干活收敛为完成一个可验证的功能是整套模板防止半途而废和越界发挥的核心机制。三、行为规则四条硬约束模板的## Правила规则一节只有四条全部是负向约束禁止什么因为它们比正向建议更可执行、更易被审计规则含义对应仓库佐证一次只推进一个活动功能One active feature at a time避免上下文在多个半成品间切换skills/harness-creator/SKILL.md同样规定 Use one active feature unless the harness has explicit multi-agent ownership boundaries没有可运行证据不得宣称完成No done without runnable evidence完成了必须伴随命令输出、测试通过等可复现结果project-03 的feature_list.json中每个 pass 条目都带evidence字段不得重写功能清单来掩盖未完成工作禁止把失败项悄悄改成已删除/已合并feature_list.json的 schema 与证据字段设计见skills/harness-creator/templates/feature-list.schema.json不得仅为了让任务看起来完成而删除或弱化测试测试是完成门控的裁判不能由选手改写模板init.sh会实际执行 check/lint/test/build 全套验证第四条规则的现实背景可以参考skills/harness-creator/references/gotchas.md中记录的 Agent 常见失败模式模型倾向于宣布胜利太早对应仓库讲座 lecture-09-why-agents-declare-victory-too-early而删测试是掩盖未完成最隐蔽的手段。最后一条规则使用仓库工件作为系统账本Use repository artifacts as system of record统摄全局所有结论必须落到文件里才有跨会话的可审计性。四、必备文件四个账本级工件模板在## Обязательные файлы一节列出仓库必须维护的文件文件职责模板位置feature_list.json功能清单id、名称、描述、依赖、状态、证据skills/harness-creator/templates/feature-list.jsonclaude-progress.md会话进度日志做了什么、在做什么、下一步、阻塞skills/harness-creator/templates/progress.mdinit.sh一键验证脚本安装依赖 跑类型检查/lint/test/buildskills/harness-creator/templates/init.shsession-handoff.md可选多会话时建议紧凑的交接摘要目标、证据、变更、下一步启动步骤skills/harness-creator/templates/session-handoff.md4.1 feature_list.json功能的单一事实来源模板skills/harness-creator/templates/feature-list.json给出了五个占位功能每个条目包含五个字段并刻意用dependencies串成一条链{ features: [ { id: feat-001, name: Project Setup, description: Confirm the project can install dependencies, run verification, and start from a clean checkout, dependencies: [], status: not-started, evidence: }, { id: feat-002, name: First User-Facing Feature, dependencies: [feat-001], status: not-started, evidence: } ] }关键设计status是受控词表not-started→ 进行中 →pass模板完成门控规定只有通过验证才能进入passing/pass状态evidence必须填写可复现证据不能留空声称完成dependencies显式建模依赖图强制基础设施先行防止 Agent 跳过前置验证直接实现上层功能——这与仓库讲座 lecture-08-why-feature-lists-are-harness-primitives 的主题一致。真实项目示例见 projects/project-03/solution/feature_list.json其中grounded-qa的 evidence 写明了QaService.ask()如何取 chunk、按关键词重叠打分、返回 top 2 引用及置信度0.85 有引用 / 0.30 无引用还附带了testedAt时间戳。4.2 claude-progress.md会话进度日志模板 skills/harness-creator/templates/progress.md 规定日志必须包含当前状态Last Updated / Session ID / Active Feature、已完成/进行中/下一步、阻塞与风险、会话中做过的决策含背景与备选方案、本会话修改的文件、完成证据、给下次会话的备注。project-03 的真实日志 projects/project-03/solution/claude-progress.md 展示了一个好范例它按会话记录每个功能的起止时间、改动文件、验证方式如 Verified:npm run checkpasses、以及feature_list.json的同步更新。这种改一行代码记一行账的节奏正是跨会话连续性的物质基础。4.3 init.sh可复现的基线验证模板 skills/harness-creator/templates/init.sh 是一个健壮的多语言验证脚本值得注意的实现细节通过检测package.json、pyproject.toml、go.mod、Cargo.toml、pom.xml、build.gradle、*.csproj自动分派到 npm/pnpm/yarn/bun、pytest、go test、cargo test、mvn test、gradle、dotnet test在 JS 分支中它读取package.json的 scripts 并按存在性依次执行check/typecheck/type-check、lint、test、build即有什么验证跑什么验证对 Python 分支做了两个细节处理pytest 退出码 5无测试可收集不算失败compileall用-x排除 venv/node_modules 等目录避免语法检查编译依赖。project-03 的简化版 projects/project-03/solution/init.sh 采用set -euo pipefail并分步打印[1/3] npm install、[2/3] npm run check、[3/3] npm run build结尾提示Run npm run dev to launch the application。这说明了 init.sh 的两层价值对新会话是干净起点证明对旧会话是破坏检测器。4.4 session-handoff.md紧凑交接可选模板 skills/harness-creator/templates/session-handoff.md 用于多会话工作包含当前目标与状态、本次完成项、验证证据表格Check / Command / Result / Notes、变更文件、决策、阻塞风险以及固定的Next Session Startup步骤读AGENTS.md→ 读feature_list.json与progress.md→ 复习交接 → 运行./init.sh再动手。模板把它定位为当 compact handoff 有用时使用与claude-progress.md的分工是progress 是持续追加的流水账handoff 是给下一次会话的压缩摘要。五、完成门控只有验证通过才能标记 pass模板的## Шлюз завершения完成门控一节只有一句话但它是整套系统的安全闸门只有所需的验证成功通过、且结果被记录之后功能才能转入passing状态。拆解这句话的三个约束所需验证必须先行定义在 feature_list 中创建功能时就该知道它对应的验证是什么测试、类型检查、手动核对而不是做完再补成功通过是客观标准依赖./init.sh或文档化的验证命令而非 Agent 的自我评估结果被记录要求落盘evidence 字段、progress 日志、必要时 commit 记录三者缺一不可。这与仓库中 lecture-09-why-agents-declare-victory-too-early 和 lecture-10-why-end-to-end-testing-changes-results 两讲的论点相互印证Agent 的直觉完成感不可信只有可复现的验证输出才是完成定义definition of done。从工程实现看feature_list.json的status词表not-started → … → pass配合evidence字段就是把完成门控落成机器可读约束的关键。而skills/harness-creator/SKILL.md的审计脚本node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project会从五子系统维度打分其中验证与证据的完备性正是评分重点。六、停止前的收尾五步可恢复性流程模板的## Перед остановкой停止之前一节规定任何会话结束前必须依次完成1. 更新进度日志claude-progress.md。 2. 更新功能状态feature_list.json。 3. 记录还有什么坏了 / 什么还没验证。 4. 一旦仓库处于可安全恢复的状态立即提交commit。 5. 为下一次会话留下干净的重启路径。各步的意图第 1、2 步把本会话的所有事实沉淀为磁盘状态——这正是四类必备文件的闭环使用**第 3 步记录损坏与未验证项**是反直觉但极其重要的它防止下一次会话带着一切正常的错误假设开工也与不得重写功能清单掩盖未完成的规则互为犄角第 4 步强调可安全恢复即提交而不是全部完成才提交——这保证了任何中断点都是一个可回退、可接续的快照**第 5 步干净重启路径**对应skills/harness-creator/references/lifecycle-bootstrap-pattern.md中的 bootstrap 思想下一次会话应当能以确定性顺序重新获得全部上下文而不是依赖残留在聊天窗口中的记忆。真实执行范例见 project-03 的收尾记录claude-progress.md的 Wrap-up 段落依次完成了更新docs/ARCHITECTURE.md、docs/PRODUCT.md、填写session-handoff.md、核对clean-state-checklist.md最终 All 11 features at status pass。七、如何把这个模板用进你自己的仓库根据skills/harness-creator/SKILL.md的交付清单一个可用的最小 harness 应当包含以下文件模板均在skills/harness-creator/templates/目录下可直接参照AGENTS.md或CLAUDE.md指令入口即本文主题模板feature_list.json功能与状态账本progress.md进度日志init.sh验证脚本可选session-handoff.md多会话工作已记录的验证证据或下一步动作落地方案有两种方案 A手工复制。把 feature-list.json、progress.md、init.sh、session-handoff.md 复制进目标仓库把占位功能feat-001 … feat-005替换为真实功能按本文第二节的操作循环修改 CLAUDE.md 即可。方案 B使用仓库脚本生成。在本地执行node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project常用选项--agent-file CLAUDE.md面向 Claude 的项目、--package-manager npm|pnpm|yarn|bun包管理器检测错误时手动指定、--commands cmd one,cmd two自定义验证命令、--force确认允许覆盖时才使用。脚本生成后再人工替换功能占位条目。常见失败模式与规避skills/harness-creator/references/gotchas.md记录了一些与本文主题直接相关的坑记忆索引静默失效索引条目标签设了硬上限多行摘要会命中字节上限而被截断。规避索引里只放一行钩子细节放进专题文件——对应本文状态文件必须短而准的原则上下文构建器被 memoize 但不失效Agent 启动时缓存了git log等上下文会话中途变更后不失效会导致整段会话读到过期数据。规避在每次变更点显式失效对应缓存异步工作跳过 pending 状态状态机里定义了 pending 但实际直接进入 running。规避不要假设 UI 可以依赖 pending 状态——这与完成门控只信可验证结果一致。八、小结这份 CLAUDE.md 模板的实质是把长周期实现任务拆解为可重复的启动循环 → 单功能推进 → 证据化完成 → 可恢复收尾四个阶段并用feature_list.json、claude-progress.md、init.sh、session-handoff.md四个文件把阶段产物落成仓库内的持久状态。它的价值不在于指令写得更多而在于把 Agent 的不可靠性约束成可审计、可恢复、可验证的流程。如果要在你的仓库复刻这套体系记住三句话即可会话开头先证明基线干净init.sh工作中一次只做一个功能feature_list.json停下来之前把一切写进账本progress handoff commit。仓库中的相关实现与模板——模板目录、SKILL 说明、project-03 落地实例——都可以作为你动手时的直接参照。赞分享【免费下载链接】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/elearn-harness-engineering 实战用 CLAUDE.md 模板为长期 Agent 会话构建稳定运行循环learn harness engineering 实战用 CLAUDE.md 模板为长期 Agent 会话构建稳定运行循环 导读 本文以 learn halearn-harness-engineering 的 CLAUDE.md 模板为长期 Agent 任务设计的会话契约与操作规范learn harness engineering 的 CLAUDE.md 模板为长期 Agent 任务设计的会话契约与操作规范 导读 本文以开源仓库 lea上一篇3步掌握跨平台系统部署打造专属离线安装包的完整指南下一篇第一次把K线交给AIKronos金融时间序列预测模型上手全记录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考