企业官网建设流程全解析

运行 Agent 任务时，模型能力只是必要条件，工程化交付的可靠性取决于 harness（提示、规则、环境、验证与状态管理）。本文围绕 learn-harness-engineering 仓库 Lecture 01 配套的失败信号检查清单，逐条拆解五个可观测的失败信号，并结合仓库中的失败模式演示代码与 Project 01 对照实验，给出"定位信号 → 归因层 → 修复 harness"的完整诊断方法。读完你将能：用五分钟清单快速审查一次 Agent 执行质量，把"模型不行"的直觉判断转化为对 harness 五层结构的精准归因。

一、信号清单：给 Agent 执行质量做体检

失败信号检查清单 是一份法语的轻量诊断工具，原文只有五个问题，用于审查"一次较弱的 harness 执行"。它的设计哲学是：不评价模型能力，只观察可验证的执行痕迹。完整清单如下：

1. 启动方式：Agent 是否错误地询问或自行推断如何启动应用？
2. 结构与产品匹配：是否创建了与预期产品不符的目录或抽象？
3. 完成度：是否在只做出可见 UI 外壳、没有完整流程时就停了下来？
4. 延续性：是否留下了能帮助未来执行继续下去的笔记或工件？
5. 可理解性：一个新会话能否在五分钟内弄清楚发生了什么？

这五个问题看似简单，却分别对应 Lecture 01 核心论述中"能力强的 Agent 依然失败"的最常见成因：欠定义的任务、缺失的上下文约定、缺失的验证回路，以及长期任务中的状态断裂。下面逐一展开，并结合仓库源码给出识别与修复方法。

二、信号 1：启动方式不明——环境层的隐性问题

信号：Agent 是否错误地询问或推断如何启动应用？

这是环境层（environment）失败的最典型表征。在 欠定义任务示例 中，任务只写了一句"构建一个带 AI 问答的知识库桌面应用"，约束明确写着：没有提供启动命令、没有目录结构指南、没有数据模型、没有明确的完成标准。文档还预判了典型结果："应用可以编译，但无法稳定启动""UI 先出现，却没有可用的导入/查询路径"。

当 Agent 不知道npm run dev还是electron .才能启动时，它会消耗大量上下文在pip install、Node 版本、依赖缺失等环境排错上，而不是解决真正的问题——这正是 Lecture 01 中"环境是陷阱"一节的描述。仓库的 Project 01 说明 给出了对照：starter/只有一句task-prompt.md（内容 全文为"Build an Electron app that can show documents and answer questions."），而solution/则通过init.sh把启动链路固化为可执行脚本。

修复方法：把启动与验证命令写进仓库根目录的规则文件。Project 01 的 init.sh 是一个可以直接复用的模板，它用set -euo pipefail保证任一步失败即中止：

#!/usr/bin/env bash # init.sh -- Verify the project builds cleanly before starting work. set -euo pipefail echo "[1/3] Installing dependencies..." npm install echo "[2/3] Running type checks..." npm run check echo "[3/3] Building project..." npm run build echo "=== Init complete. All checks passed. ===" echo "Run 'npm run dev' to launch the application."

有了这类脚本，信号 1 就不会出现：启动方式已被显式声明，Agent 无需猜测。

三、信号 2：结构与产品不匹配——欠定义任务的必然产物

信号：是否创建了与预期产品不符的目录或抽象？

当任务缺少约束时，Agent 会"发明"目录结构和抽象层。这与信号 1 同源，但后果更隐蔽：本地看起来合理的结构，放到产品语境里就是错位的。

仓库配套的 failure-pattern-demo.ts 用可运行代码模拟了这一过程。它定义了一个模拟"模型"的决策函数modelDecide：给定"添加搜索端点"任务，模型只依据已提供的上下文做决定——没有auth就写不带认证的路由，没有rate-limit就漏掉限流，没有test-standards就不写测试。运行方式：

npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts

从源码结构看，该演示刻意复刻了四步失败模式（文件头注释failure-pattern-demo.ts中写明）：上下文不完整 → 局部合理的改动 → 无全局验证 → 过早完成。每一步单独看都"看起来没问题"，这正是结构失配的根源：Agent 基于它看到的局部上下文做局部决策，产品结构是否合理需要全局标准来判定，而全局标准恰恰缺失。

修复方法：用架构约定约束结构。Project 01 solution 的 AGENTS.md 是教科书式的例子——它把 Electron 项目强制划分为四个严格层：

• src/main/：主进程，负责BrowserWindow生命周期与 IPC 注册，禁止引入渲染层代码；
• src/preload/：唯一桥接层，只用contextBridge.exposeInMainWorld暴露类型化 API；
• src/renderer/：React + TypeScript UI 层，只能通过window.knowledgeBase与主进程通信，禁止直接importNode 模块；
• src/services/：主进程内的纯业务逻辑，只能依赖src/shared/。

把这类边界写进规则文件后，"创建与产品不符的抽象"就会在结构上被规则直接拦截。

四、信号 3：只有 UI 外壳就停下——缺少验证回路的标志

信号：是否在做出可见 UI 外壳、没有完整流程后就停止？

这是"验证差距"（verification gap）的典型外显。Lecture 01 指出：没有测试、没有 lint、或验证命令从未被传达时，Agent 写代码、看一眼、觉得没问题、宣布"完成"——就像学生没有答案就交卷。更值得警惕的是 Anthropic 观察到的"context anxiety"（上下文焦虑）：当 Agent 感到上下文快被耗尽时，会加速收尾、跳过验证、选简单方案而非最优方案。

欠定义任务示例 对此的预测是"agent 经常在获得表面成功后就停止"。UI 能渲染，但导入/查询的完整数据流没打通——这就是"只有外壳"。

修复方法：写显式的 Definition of Done，且必须是机器可验证的条件。Lecture 01 给出了通用模板：

Completion criteria: - New endpoint GET /api/search?q=xxx - Supports pagination, default 20 items - Results include highlighted snippets - All new code passes pytest - Type checking passes (mypy --strict)

仓库中的落地形态则是 feature_list.json：它把"窗口启动""文档列表面板""问答面板""数据目录"四个功能拆成条目，每个条目带status（pass/fail/not-started）和evidence（证据字符串）。question-panel的条目写明证据是"QuestionPanel 渲染文本输入与 Ask 按钮，在回车或点击时提交到window.knowledgeBase.qa.ask"——这就是把"UI 外壳"升级为"完整流程"的证据要求。而 AGENTS.md 中 DoD 的第一条TypeScript compiles without errors (npm run check)则是把验证命令直接绑定到完成定义上。

五、信号 4 与 5：状态断裂与不可延续——长期任务的致命伤

信号 4：是否留下帮助未来执行继续的笔记或工件？ 信号 5：新会话能否在五分钟内理解发生了什么？

这两个信号针对的是跨会话任务。Lecture 01 明确警告：超过 30 分钟的任务，若没有持久状态，失败率会大幅上升——上一次会话的发现全部丢失，每个新会话都要重新探索项目。

Project 01 的 solution 展示了状态工件应该长什么样：除AGENTS.md、feature_list.json、init.sh外，还有claude-progress.md（会话进度记录）。它的使用流程是：先读规则文件，再跑init.sh确认构建干净，然后读feature_list.json看功能当前状态，最后对照进度文件继续工作。这套流程让一个新会话能在几分钟内重建上下文——这正是信号 5 的合格标准"五分钟内理解发生了什么"。

修复方法：让"延续性"成为显式产物，而不是 Agent 的自觉。Lecture 01 的"诊断循环"（diagnostic loop）把每次失败当作 harness 缺陷信号：运行 → 观察失败 → 归因到某个层 → 修复该层 → 重跑。信号 4/5 修复的落点就是"状态层"：把探索结论、已完成项、下一步计划持久化到仓库内的文件中。

六、把五个信号接入五层归因模型

Lecture 01 给出的是五个诊断层：specification（规格）、context（上下文）、environment（环境）、verification feedback（验证反馈）、state（状态）。五个失败信号与五层之间存在稳定的映射关系，可用作归因表：

这条表的核心判断来自 Lecture 01 的中心论点：如果同一个模型在结构良好的相似任务上能成功，就假设是 harness 问题。像修车先查油路而不是怪发动机一样，归因顺序永远是"先查 harness，后换模型"。

七、实战演练：用 Project 01 跑一次信号驱动的对照实验

仓库的 Project 01 是这一清单的最佳练兵场，它是一个基线 vs 最小 harness 的对照实验：

# 1. 先用弱 harness（仅 prompt）跑一遍 cd projects/project-01/starter npm install # 把 starter/task-prompt.md 的内容作为 prompt 交给 Agent # 要求它完成：窗口启动、文档列表、问答面板、数据目录 # 2. 再用显式 harness（完整规则）跑同一任务 cd ../solution npm install # 要求 Agent 在动代码前先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md # 3. 对照评估 # - 任务完成了吗？ # - 重试了几次？ # - Agent 是否过早宣布"完成"？

README 给出了精确的对照特征表：window-launch对应src/main/main.ts与src/preload/preload.ts，document-list对应src/renderer/components/DocumentList.tsx，question-panel对应src/renderer/components/QuestionPanel.tsx，data-directory对应src/services/persistence-service.ts。检查时，把五次信号清单逐项打在两次运行的结果上，就能量化"prompt-only 运行"与"从显式规则与验证工件出发的运行"之间的完成率差距。

八、把清单固化为日常习惯

最后，把这份清单变成每个任务结束时的固定收尾动作：

1. 运行后立即过清单：按五个信号逐项打勾，任何一个为"是"，即判定本次执行存在 harness 缺陷；
2. 归因到层：用第六节的映射表，把信号落到 specification / context / environment / verification / state 五层之一；
3. 修复后留痕：在AGENTS.md、feature_list.json或进度文件中记录本次缺陷与修复，避免同一失败模式复发；
4. 量化追踪：像 Lecture 01 建议的那样，记一份简单日志（成功/失败、责任层），几轮之后瓶颈自然显现。

如 Lecture 01 所总结：模型能力与执行可靠性是两回事；失败时先检查 harness，再怀疑模型；每一次失败都是 harness 存在结构性缺陷的信号。这份五问清单，就是把这些原则落到每次执行审查中的最小可行工具。