用失败信号检查清单定位 Agent 失效根因：learn-harness-engineering 第 01 讲实战指南-171主机测评

用失败信号检查清单定位 Agent 失效根因：learn-harness-engineering 第 01 讲实战指南

【免费下载链接】learn-harness-engineering Harness engineering beginner tutorial, from 0 to 1 项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering

本文围绕 learn-harness-engineering 第 01 讲（Lecture 01: Why Capable Agents Still Fail）配套的失败信号检查清单（failure-signals-checklist）展开，讲解如何用 5 个可复现的观察点，在复盘一次弱 harness 的 Agent 运行结果时，快速把"模型不行"的直觉判断，替换成可归因到具体 harness 层的工程判断。读完本文，你将掌握一份可直接用于项目复盘的自查清单，理解清单背后每一问对应的失败模式与 harness 防护层，并能在当前仓库的 project-01 对照实验中实际落地使用。

为什么需要一份"失败信号"检查清单

在 learn-harness-engineering 项目中，第 01 讲的核心命题是：强模型不等于可靠执行（capable agents still fail）。Anthropic 的受控实验中，同一个提示词（"构建一个 2D 复古游戏构建器"）、同一个模型（Opus 4.5），在裸环境下运行 20 分钟、花费 $9、关键游戏机制不可用；而在完整 harness（planner + generator + evaluator 三 Agent 架构）下运行 6 小时、花费 $200、游戏可玩。模型没有变，变的是 harness——也就是"模型权重之外的一切工程基础设施"（指令、工具、环境、状态管理、验证反馈）。

正因失败往往不是模型能力问题，而是 harness 的结构性缺陷（harness-induced failure），复盘时就不能笼统地说"模型太笨"。失败信号检查清单（failure-signals-checklist）就是为此设计的：它把一次弱 harness 运行中最典型的五种失败征兆固化为 5 个可勾选的观察点，让复盘从"主观归因"变成"结构化取证"。该清单位于 docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md（中文版见 docs/zh/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md），同目录下还有配套的 failure-pattern-demo.ts 与 underspecified-task.md。

检查清单原文：5 个观察点

在审查一次弱 harness 的运行结果时，按下面 5 个问题逐项核对（原文为俄文，此处给出中文对照）：

Agent 是否询问了如何启动应用，或者做出了错误的推断？

它是否创建了与预期产品不匹配的目录或抽象？

它是否在完成一个可见的 UI 外壳后就停止了，而没有完成完整的工作流？

它是否留下了有助于后续运行继续的笔记或产物？

一个全新的会话是否能在五分钟内理解之前发生了什么？

前两问针对"任务定义与环境上下文"层的缺陷，第三问针对"验证反馈"层的缺失，后两问针对"状态管理/会话连续性"层的断裂。下面逐条拆解其判据、典型信号与对应防护手段。

逐条拆解：每一条信号对应哪种失败模式

信号 1：没有询问如何启动应用，或做出错误推断

这是"任务规格不明确 + 环境上下文缺失"的最直接征兆。清单背后的原因在于：启动方式、命令、脚本往往是仓库里"只存在于人类脑中"的隐式约定（implicit conventions），Agent 无从得知就会猜测，而猜测就意味着偏差。

对照实验中可以看 projects/project-01/starter/task-prompt.md：整个任务提示词只有一句 "Build an Electron app that can show documents and answer questions."——没有启动命令、没有目录结构、没有数据模型、没有完成标准。而 projects/project-01/solution/AGENTS.md 的 "Startup Rules" 明确要求 Agent 动手写代码前按顺序完成 5 步：完整读取本文件、阅读 docs/ARCHITECTURE.md、阅读 docs/PRODUCT.md、运行 bash init.sh 验证构建、阅读 feature_list.json 了解特性状态。两者对比，starter 版本几乎必然触发信号 1。

防护手段：把"如何启动、如何验证"写进仓库根目录的 AGENTS.md，把启动命令固化为可执行脚本（如 init.sh）。如果 Agent 在弱 harness 下连"问一句怎么启动"都做不到，说明它的上下文里根本没有这个信息源——这是 harness 缺陷，不是模型缺陷。

信号 2：创建了与预期产品不匹配的目录或抽象

这是"隐式架构约定缺失"的典型表现。代码库往往有严格的目录边界和抽象分层，但这些约束如果不显式告诉 Agent，它就会按自己的默认习惯发明结构。

以本仓库的 Electron 工程为例，projects/project-01/solution/AGENTS.md 用 "Electron Layer Boundaries" 一节把代码强制划分为四层：

主进程（src/main/）：管理 BrowserWindow 生命周期与 IPC 注册，可以 import services，绝不 import renderer 代码；所有文件系统访问经由 services 发生。
预加载（src/preload/）：主进程与渲染进程之间唯一的桥，使用 contextBridge.exposeInMainWorld 暴露类型化 API，绝不 import React 或 renderer 代码。
渲染进程（src/renderer/）：React + TypeScript UI 层，只通过 window.knowledgeBase API 与主进程通信，绝不 import Node.js 模块（fs、path、electron）。
服务层（src/services/）：在主进程运行的类型化业务逻辑，可 import src/shared/ 但绝不 import src/renderer/，每个服务通过构造函数注入 PersistenceService。

再配合约定：TypeScript strict 模式开启、禁止无注释的 any、使用具名导出、IPC 通道名在 src/shared/types.ts 中统一定义、渲染进程禁止同步 I/O。这些边界就是防止 Agent"发明目录与抽象"的显式护栏。

防护手段：把架构边界写成 Agent 可读的规则文件。当复盘发现 Agent 在 src/ 之外新建了 helpers/、utils/ 之类的自创目录，或把文件系统访问直接写进了渲染层，就可以确认：架构约定从未进入它的上下文。

信号 3：完成可见的 UI 外壳后就停止，未完成完整工作流

这是"验证反馈缺失"导致的经典失败——Agent 把"看起来完成"误判为"真正完成"，即验证差距（verification gap）。检查清单的 underspecified-task.md 明确列出这类任务的典型结局：UI 可能在可用的数据摄入/问答路径之前就出现；Agent 经常在"表面成功"（cosmetic success）之后停下。

配套的 failure-pattern-demo.ts 用 4 步模拟了这一完整失败链条：

上下文不完整（Incomplete Context）：modelDecide 因缺少 auth 中间件信息，直接生成不带认证的 /search 路由；

局部合理的改动（Locally Reasonable Changes）：补上 auth 后仍缺限流策略，路由"局部看起来完整"；

无全局验证（No Global Verification）：缺测试标准，特性"看起来完全实现"；

过早宣布完成（Premature Completion）：Agent 输出 "Done. Added search endpoint."，但任务实际不完整。

运行方式（源码注释中的命令）：npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts，它最终会输出一张对比表，显示 5 项必需上下文中 Agent 缺失了哪几项——每一站在局部看都合理，但全局看都是缺陷，这正是该失败模式的核心。

防护手段：为每个任务显式写出机器可校验的完成标准（Definition of Done）。第 01 讲给出的模板：

Критерии готовности（完成标准）:
– 新增端点 GET /api/search?q=xxx
– 支持分页，默认 20 条
– 结果带高亮片段
– 所有新代码通过 pytest
– 类型检查通过（mypy –strict）

没有显式 DoD，Agent 就会发明自己的 DoD——而它的 DoD 通常就是"UI 能显示出来"。

信号 4：没有留下帮助下一轮继续的笔记或产物

这是"会话连续性/状态管理"层的信号。长任务跨多个会话时，上一会话的所有发现都会丢失，每个新会话都要重新探索项目结构。第 01 讲指出：无持久状态的 Agent 在超过 30 分钟的任务上失败率急剧上升。

在 project-01 的对照设计中，solution 侧恰恰把"留下产物"固化成 harness 的一部分：feature_list.json 就是"项目进度的唯一事实来源"（source of truth）。以 projects/project-01/solution/feature_list.json 为例，每个特性都带 id、name、description、status（pass / fail / not-started）、evidence（证据）和 testedAt 时间戳：

{
"id": "window-launch",
"name": "Window Launch",
"description": "Electron app opens a BrowserWindow with correct dimensions and preload script",
"status": "pass",
"evidence": "npm run dev launches window at 1200×800 with contextIsolation=true and nodeIntegration=false",
"testedAt": "2026-03-30T10:00:00Z"
}

projects/project-01/solution/AGENTS.md 还规定：实现特性时把状态更新为 pass 并附证据；受阻则置为 fail 并写明原因；永远不要删除特性。

防护手段：强制 Agent 以机器可读文件（如 feature_list.json）记录进度与证据，并让 AGENTS.md 声明该文件为唯一事实来源。下一轮会话读到它，就能在几分钟内恢复上下文。

信号 5：全新会话无法在 5 分钟内理解之前发生了什么

这是信号 4 的最终验证标准，也是整个清单的"验收门"。它把"是否留下笔记/产物"从形式检查升级为效果检查：产物不仅要有，还必须让一个零上下文的新会话快速恢复。如果 5 分钟内新会话仍在重新探索目录结构、重新猜测启动命令，说明状态管理层彻底失效。

防护手段：用清单信号 5 作为每次会话结束的自检（clean-state 检查）。跨会话的交接产物应当包含：启动与验证命令、已完成与未完成事项、当前阻塞点、下一步建议。这也呼应了第 01 讲强调的诊断循环（diagnostic loop）：执行 → 看到失败 → 归因到具体 harness 层 → 修复该层 → 重新执行。

五层防护映射：把每条信号归因到 harness 层

第 01 讲定义了一个核心诊断模型——五层防护（five defensive layers），每条失败信号都能映射到其中一层：

失败信号（检查清单）对应防护层典型修复

信号 1：不问启动方式/错误推断	任务规格（task specification）	写显式 DoD；固化启动脚本
信号 2：自创目录/抽象	上下文供给（context provisioning）	写 AGENTS.md 架构边界
信号 3：UI 外壳即停	验证反馈（verification feedback）	提供测试/lint/类型检查命令
信号 4：不留产物	状态管理（state management）	引入 feature_list.json 类进度文件
信号 5：新会话无法恢复	状态管理（state management）	交接文档 + clean-state 自检

这五层同时也是第 01 讲诊断循环中的"归因层"：复盘时不要把失败笼统记为"模型不行"，而是逐层排查——任务是否模糊？上下文是否缺项？环境是否完整？有无验证手段？状态是否延续？养成这个习惯后，"模型不够好"这条日志会越来越少，取而代之的是可修复的 harness 缺陷。

在仓库中实操：用 project-01 对照实验验证清单

清单的价值需要在真实对照实验中检验，而 projects/project-01/README.md 正是为"弱 harness vs 显式 harness"设计的 A/B 实验：

弱 harness 组：在 starter/ 下运行，仅把 task-prompt.md（那句模糊的 "Build an Electron app that can show documents and answer questions."）作为提示词交给 Claude Code / Codex，不提供任何 solution 文件。

显式 harness 组：在 solution/ 下运行，要求 Agent 动代码前先读 AGENTS.md、init.sh、feature_list.json 等 harness 产物。

用检查清单对比两轮结果：

任务完成了吗？
重试了几次？
Agent 是否过早宣称"完成"？
对照清单 5 条逐项勾选，记录每条信号在两组中是否出现。

两组的产物差异可直接对比：starter 组看 src/main/main.ts、src/renderer/components/DocumentList.tsx、src/renderer/components/QuestionPanel.tsx、src/services/persistence-service.ts 是否如期实现；solution 组则以 projects/project-01/solution/feature_list.json 中的 window-launch、document-list、question-panel、data-directory 四项 pass 状态与证据为准。

实验预期会复现第 01 讲的主结论：模型相同，harness 不同，结果本质不同。而检查清单的价值在于——它把"结果不同"从印象变成了逐条可勾选、可归因、可复现的证据。

核心要点

强模型 ≠ 可靠执行：能力差距（capability gap）真实存在，但很多失败是 harness-induced failure，而不是模型问题。
先查 harness，再怀疑模型：同一模型在裸环境与完整 harness 下表现迥异，升级模型是最昂贵的选项，且往往并非正确选项。
用清单替代直觉：5 条失败信号分别对应任务规格、上下文供给、验证反馈、状态管理各层，逐条核对即完成结构化归因。
显式 DoD 是最高性价比的修复：一份显式的完成标准（测试通过、lint 干净、类型检查通过）直接压缩验证差距。
一份 AGENTS.md 可能比换更贵的模型更有效：把栈版本、架构边界、验证命令写进仓库根目录，就是 harness engineering 的第一步。
每次都留下可恢复的产物：让新会话在 5 分钟内理解之前发生什么，是对状态管理层的硬性验收标准。

用失败信号检查清单定位 Agent 失效根因：learn-harness-engineering 第 01 讲实战指南