为 Agent 定义“健康且可重启“契约：learn-harness-engineering 中 RELIABILITY.md 的完整落地指南

为 Agent 定义健康且可重启契约learn-harness-engineering 中 RELIABILITY.md 的完整落地指南【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读本篇文章聚焦 learn-harness-engineering 仓库中docs/fr/resources/openai-advanced/repo-template/docs/RELIABILITY.md这份模板文档它回答了一个 Agent 驱动开发中最容易被忽视的问题系统如何向 Agent 和人类证明自己健康、可重启、可诊断。读完本文你将掌握如何把这份模板中的标准路径引导/验证/启动/调试、运行信号要求、参考路径与四条可靠性规则具体化为你项目里可复制、可执行的命令与检查清单让每一个功能在能干净重启之前都不被宣称为完成。一、RELIABILITY.md 在 agent-first 仓库模板中的定位RELIABILITY.md 不是一份孤立的运维文档而是 OpenAI 风格agent-first 文档模板repo-template中三个首批必须填充的文件之一。在 模板使用说明 中官方给出的复制顺序是将AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制完整的docs/目录树优先填充docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md与docs/RELIABILITY.md在docs/exec-plans/active/下添加第一个活跃计划保持入口文件简短将细节路由到关联文档。这意味着 RELIABILITY.md 承担的是系统级健康证明的职责它定义系统如何证明自身是健康的sain且可重启redémarré。与之互补的文档包括ARCHITECTURE.md定义系统形态、领域地图、分层模型与严格依赖规则DESIGN.md记录产品与系统层面的持久设计决策SECURITY.md定义 Agent 不得猜测的安全与保密规则。其中 SECURITY.md 与 RELIABILITY.md 有一个共同的设计哲学重复出现的评审意见必须变成检查而不是部落知识——可靠性文档则把这一哲学延伸到运行信号与失败诊断上。二、标准路径Chemins standard四类命令契约原文档首先要求仓库为 Agent 定义四类标准路径。在模板阶段它们以[command]占位符呈现落地到真实项目时必须替换为实际命令。这四类路径共同构成 Agent 任何会话的可执行知识基座路径类别占位符落地示例用途引导Amorçage[command]./init.sh从零建立可运行环境幂等可重复验证Vérification[command]npm run test/npm run build证明当前状态满足门槛启动应用/服务Lancement[command]npm run dev/npm start进入运行态调试/检查运行Débogage[command]npm run dev -- --debug或日志跟踪命令对运行态进行诊断这一分类与本仓库多语言课程的核心论点高度一致引导不是可选项而是独立的初始化阶段参见 lecture-06 为什么初始化需要独立阶段 目录下的讲义。从 生命周期与引导模式 的源码级实现看可靠的引导还应具备三个特征依赖有序dependency-ordered阶段按依赖顺序执行最小上下文 → 加载工具 → 跨越信任边界 → 加载敏感子系统安全敏感子系统绝不能在信任建立前激活记忆化memoized已完成的阶段跳过重跑使重复初始化变快失败即停任何阶段失败引导立即中止会话停留在只读安全模式并以阶段名和失败原因记录错误。在真实项目中这四类路径应当保持最少且稳定——不要让 Agent 在每次会话开始时重新猜测如何验证系统。这也是本仓库理念仓库必须成为系统记录来源在可操作性层面的体现命令契约写进 RELIABILITY.mdAgent 与人类都从同一处读取。三、运行信号要求Signaux dexécution requis让健康可见、可证原文档列出了四类必需的运行信号这是证明健康的证据来源为启动流程和关键流程提供结构化日志journaux structurés日志必须有稳定格式如 JSON 键值对而不是 ad hoc 的console.log。这对应 ARCHITECTURE.md 中横切关注点必须经由明确边界进入的原则——日志与追踪应通过统一的 provider/utility 路径而不是散落在各层直接输出为关键服务提供健康检查vérifications de santé健康检查应覆盖服务的关键路径启动、验证、对外响应而不是只检查进程是否存活在可用时为慢路径提供追踪或计时数据données de trace / minutage慢路径必须能被定位否则慢无法被诊断和优化为可恢复故障提供用户可见的错误状态états derreur visibles可恢复的失败如索引重建中、外部 API 限流必须有显式的状态呈现而不是静默失败或假成功。这四类信号共同回答一个问题当系统异常时能否仅凭仓库本地的信号完成诊断这正是可靠性规则第二条的要求——运行时失败必须能从仓库本地信号诊断而非依赖某个人脑中的记忆。仓库中 质量文档模板 与之呼应它为每个产品域和架构层维护检查通过 / Agent 可读性 / 测试稳定性 / 主要缺口的快照评级 A–D让 Agent 与人类都能快速了解代码库哪里稳固、哪里需要工作——这本质上是健康状态在开发期的可视化。四、参考路径Parcours de référence可重复验证的基准原文档要求定义至少三条参考路径[parcours 1]、[parcours 2]、[parcours 3]并明确约束每条参考路径都必须有可重复的验证路径和清晰的失败信号。参考路径是系统的黄金流程——例如导入文档 → 索引 → 提问 → 获得带引用的答案这类端到端主线。落地时的要求可重复répétable验证命令可被反复执行结果稳定不依赖环境偶然性有清晰失败信号signaux déchec clairs路径失败时输出必须明确指出失败环节哪一步、什么原因、对应什么信号而不是笼统的测试失败。从模式库看这与 记忆持久化模式 中进度日志的设计一脉相承日志记录当前功能状态已完成 / 进行中 / 阻塞、下一步会话应做什么让状态在会话之间可交接、可验证。参考路径的验证结果也应写入类似记录形成已验证 / 未验证的真相而不是 Agent 自我声明的看起来完成了。五、可靠性四条规则逐条解析与落地原文档以四条规则收束全文它们是整个 RELIABILITY.md 的判定标准规则一系统无法干净重启的功能不算完成Aucune fonctionnalité nest terminée si le système ne peut pas redémarrer proprement ensuite.这是最强的一条门槛。判定完成的标准不是功能在当前进程里跑通了而是重启之后依然成立。落地方式把引导 → 验证 → 启动三条标准路径编入完成的验收条件任何改动都要经过重启后仍健康的验证。从引导模式的角度看这意味着引导必须幂等、可重复且能跨会话重建运行环境CLI / server / SDK 多个入口共享同一引导路径。规则二运行时失败必须能从仓库本地信号诊断Les défaillances dexécution doivent être diagnostiquables à partir de signaux locaux au dépôt.即失败时打开仓库就能从日志、健康检查输出、错误状态、追踪数据中定位问题不需要依赖离线记忆或外部黑盒。这一条直接决定第三小节四类信号的完整性——信号缺失等于放弃可诊断性。规则三重复出现的失败模式要固化为基准或防护Si un mode de défaillance répété apparaît, ajoutez un benchmark ou un garde-fou pour celui-ci.与 SECURITY.md 的重复评审意见必须变成检查是同一哲学把重复的教训自动化。当一个失败模式第二次出现就应该为其添加基准benchmark或防护garde-fou——例如新增一个回归测试、一条 lint 规则或一个 CI 检查而不是再次口头提醒。这与 工具注册表模式、上下文工程模式 中经验沉淀为可执行规则的取向一致仓库是系统记录来源规则应可执行而非仅可阅读。规则四清理是可靠性的一部分而不是独立的顾虑Le nettoyage fait partie de la fiabilité, pas dun souci séparé.清理cleanup不是有空再做的杂务而是可靠性契约的组成部分。这一条在 生命周期与引导模式 中有精确的实现对应长任务采用两阶段驱逐磁盘输出在到达终态时立即清理eager内存记录在父级收到通知后才惰性清理lazy会话级钩子在会话结束时即被清理ephemeral关闭时配置 drain-on-shutdown排空后退出避免任务泄漏。仓库中另有专门的 干净状态检查清单模板可直接并入可靠性落地流程- [ ] 标准启动路径仍然可用 - [ ] 标准验证路径仍然可执行 - [ ] 当前进度已记录在进度日志中 - [ ] 功能状态反映真实通过/未验证情况 - [ ] 没有未记录的半成品步骤 - [ ] 下一个会话无需人工修复即可继续这份清单把可重启、可续接、可清理从抽象原则变成逐项可勾选的验收动作与 RELIABILITY.md 的四条规则形成模板 → 清单的完整落地链。六、把模板落到真实项目一份可执行的填充流程综合原文档与仓库证据将 RELIABILITY.md 落地到具体项目可以按以下六步执行替换四类标准路径把[command]替换为真实命令如./init.sh、npm run verify、npm run dev、npm run inspect并在仓库中保证这些命令确实存在且幂等实现四类运行信号为启动与关键流程接入结构化日志、为关键服务添加健康检查、为慢路径埋计时点、为可恢复故障设计可见错误状态定义三条参考路径挑选系统最核心的三条端到端主线为每条写出可重复的验证命令与明确的失败判据把四条规则写进完成定义功能完成必须同时满足重启后健康可本地诊断重复失败已加防护清理动作已闭环挂接相关文档将 ARCHITECTURE.md 的边界规则、QUALITY_SCORE.md 的质量快照、SECURITY.md 的安全规则与 RELIABILITY.md 相互链接保持入口简短、细节路由化用干净状态清单做会话收尾每次会话结束时对照 干净状态检查清单 逐项确认把清理变成会话纪律。需要特别说明的是repo-template 中的[command]、[parcours 1..3]均为占位符模板使用说明 明确要求在使用前用项目的真实规范替换这些占位符、示例与命令。本文给出的落地命令均为示范实际应以你项目仓库中的真实脚本与配置为准。七、结语可靠性是 Agent 可以证明的东西RELIABILITY.md 的核心价值在于把系统健康从模糊的感受变成可复制、可验证、可诊断的契约四类标准路径定义了 Agent 每次会话的确定性起点四类运行信号提供了健康的证据参考路径给出了可重复的验证基准四条规则则划定了完成与失败的边界。当你把这份模板填充进真实仓库后Agent 不再需要猜测如何验证系统、如何诊断失败、何时算清理干净——一切都有据可查、有令可依。这正是 harness engineering 从0 到 1的进阶里最容易被忽视却最能决定长期可靠性的那一环。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考