企业官网建设流程全解析

本文以 learn-harness-engineering 仓库中第 01 讲的配套文档 underspecified-task.md 为骨架，拆解一个「能力强大但任务描述近乎空白」的典型提示词，结合同目录下的 failure-pattern-demo.ts 仿真代码、failure-signals-checklist.md 检查清单，以及 Project 01 的弱 Harness / 显式 Harness 对照实验，说明为什么「换更强的模型」不是第一优先动作，以及如何用显式的任务契约、Definition of Done 和 AGENTS.md 堵住失败缺口。读完本文，你将掌握：如何识别任务描述中的隐性缺口、如何用五层诊断法定位失败、以及如何把一句模糊需求改写成可验证的任务契约。

一、原文案例：一个「任务描述不充分」的完整样本

underspecified-task.md给出的提示词极其简洁，全文如下：

Build a desktop knowledge base app with AI question answering.

翻译过来就是：「构建一个带 AI 问答功能的桌面知识库应用」。它给出的约束是：

• 未指定任何约束（None specified）
• 未给出启动命令（No startup command given）
• 未提供目录结构指引（No folder structure guidance）
• 未定义数据模型（No data model defined）
• 没有显式的完成标准（No explicit completion criteria）

这正是第 01 讲 index.md 所说的「日常需求」的极端形态：含糊的规格、没有现成测试、业务规则散落在代码库各处。当 Agent 拿到这样的任务时，它只能靠猜。

二、这类提示词的典型结局：四条可预期的失败轨迹

原文档列出了这类提示词的典型产出，这是理解「Harness-Induced Failure」的第一手证据：

• Agent 临时发明一套结构（the agent invents a structure ad hoc）：没有目录结构指引时，Agent 会按自己的习惯拍脑袋建目录，而不会与团队既有约定对齐；
• 应用可能能编译，但无法稳定启动（the app may compile but not start consistently）：没有启动命令说明，Agent 不知道npm run dev、vite还是别的入口才是「正确启动方式」，于是它可能交付一个能编译、却跑不起来的工程；
• UI 先于可用的导入/问答路径出现（the UI may appear before there is any usable ingest/query path）：没有数据模型定义，Agent 倾向于先做出「看起来像产品」的界面外壳，而真正核心的文档导入（ingest）与问答（query）链路却是空的；
• Agent 常在「外观成功」后就停下来（the agent often stops after cosmetic success）：没有完成标准，Agent 会以「界面能显示、看起来差不多」作为完成标志，而不是以「数据能进、问题能答、测试能过」作为完成标志。

这四条轨迹不是猜测，而是第 01 讲 index.md 总结的五大失败模式在该提示词上的具体投影：需求含糊 → Agent 只能猜；约定未落盘 → Agent 无从遵守；环境不完整 → Agent 把精力耗在环境修复上；没有验证手段 → Agent 自我感觉良好即宣布完成；会话间状态丢失 → 每个新会话都要重新探索。

三、源码佐证：四步失败模式的仿真（failure-pattern-demo.ts）

同目录下的 failure-pattern-demo.ts 把这个过程具象化为一个可运行的仿真。它的核心是一个modelDecide函数——一个只依据「当前可见上下文」做决策的简化「模型」：

function modelDecide(context: string[], task: string): string { const has = (s: string) => context.some((c) => c.includes(s)); // The task is to "add a search endpoint to the API". // Correct answer requires knowing about auth middleware and rate limiting. if (!has("auth")) { return "Created new route handler /search without authentication checks"; } if (!has("rate-limit")) { return "Added search route with auth but forgot rate limiting"; } if (!has("test-standards")) { return "Implemented search with auth and rate-limit, but no tests"; } return "Fully implemented search endpoint with auth, rate-limit, and tests"; }

仿真把失败展开为四个步骤，每一步在局部看都「合理」，叠加起来却是坏交付物：

仿真结尾还会打印一张对比表，统计「Agent 实际拥有的上下文」与「任务真正需要的上下文」之间的缺口（GAP）。运行方式在文件头注释中给出：

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

注意：这个路径是文件头注释里针对仓库原位置的写法，在当前仓库根目录下对应文件为 docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts。这个仿真的价值在于：它证明了「Agent 在局部上下文缺失时做出的每一步决定都有内在合理性」——问题从来不是模型不聪明，而是它根本没看见它需要看见的东西。

四、复盘清单：用 failure-signals-checklist 审查一次弱 Harness 运行

当一次运行结果不理想时，不要急着说「模型不行」。failure-signals-checklist.md 提供了五个可操作的自检问题：

1. Agent 是询问了如何启动应用，还是自己猜错了？（Did the agent ask, or infer incorrectly, how to start the app?）——对应「没有启动命令」这一约束缺失；
2. 它是否创建了与预期产品不符的目录或抽象？（Did it create directories or abstractions that do not match the intended product?）——对应「没有目录结构指引」；
3. 它是否在做出一个可见的 UI 外壳后、在完整工作流尚未成型时就停了下来？（Did it stop after making a visible UI shell without a complete workflow?）——对应「UI 先于 ingest/query 路径出现」；
4. 它是否留下了能让后续运行接续的笔记或产物？（Did it leave notes or artifacts that help a future run continue?）——对应「跨会话状态丢失」；
5. 一个新会话能否在五分钟内理解此前发生了什么？（Could a fresh session understand what happened in under five minutes?）——这是对「可接续性」的量化检验。

把这五个问题对照underspecified-task.md的约束列表，会发现它们是一一对应的：每一个缺失的约束，都会在检查清单里命中一个问题。这说明失败不是随机的，而是结构性的——只要任务描述不充分，失败轨迹就高度可预测。

五、为什么会失败：Capability Gap 与 Harness 的定义

第 01 讲 index.md 给出了几个理解上述现象的关键术语：

• Capability Gap（能力落差）：模型在基准测试上的表现与真实任务表现之间的巨大鸿沟。截至 2025 年底，最强编码 Agent 在 SWE-bench Verified 上也只有约 50–60% 的通过率，而那是「精心挑选、带现成测试」的任务；日常含糊需求只会更低。
• Harness（马具/驭具）：模型权重之外的一切工程基础设施——指令、工具、环境、状态管理、验证反馈。「不是模型权重，就是 Harness。」
• Harness-Induced Failure（Harness 引发的失败）：模型能力足够，但执行环境存在结构性缺陷。Anthropic 的控制实验（同一提示词、同一模型 Opus 4.5：裸跑 20 分钟 $9 核心功能不可用；带 planner/generator/evaluator 三 Agent 架构的完整 Harness 跑 6 小时 $200 游戏完整可玩）已经证明了这一点。
• Verification Gap（验证落差）：Agent 对自身输出的信心与实际正确性之间的差距。「Agent 说完成而实际没完成」是最常见的失败模式。
• Diagnostic Loop（诊断循环）：执行 → 观察失败 → 归因到具体 Harness 层 → 修复该层 → 重新执行。这是 Harness 工程的核心方法论。
• Definition of Done（完成定义）：一组可以用命令验证的条件（测试通过、lint 干净、类型检查通过）。没有显式的完成定义，Agent 就会发明一个自己的完成定义——这正是underspecified-task.md中「agent often stops after cosmetic success」的根源。

六、修复方案：从「一句话需求」到「可验证任务契约」

underspecified-task.md的教训指向一条明确出路：把缺失的约束一项一项补齐。第 01 讲给出的最低限度方案包含三件事：

1. 写出显式的 Definition of Done

不要只说「加个搜索功能」，要把它说清楚：

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)

回到原案例，一个「桌面知识库 + AI 问答」应用的最小完成定义至少应该覆盖：启动命令是什么、窗口能否正常打开、文档导入路径（ingest）是否可用、问答路径（query）是否可用、数据目录如何创建与持久化、类型检查与测试是否通过。

2. 在仓库根目录放一个 AGENTS.md

AGENTS.md告诉 Agent 项目的技术栈、架构约定和验证命令。第 01 讲的结论非常直接：一份AGENTS.md可能比升级到更贵的模型更有效——这不是玩笑。

3. 建立诊断循环并记录日志

把每次失败归因到五层防御层之一：任务说明层、上下文提供层、执行环境层、验证反馈层、状态管理层。用一张简单日志记录「成功/失败 + 失败层」，几轮之后就能看出瓶颈在哪一层，把精力集中在那里。

七、仓库实证：Project 01 把「弱 Harness vs 显式 Harness」做成了可重复实验

仓库里的 Project 01（Baseline vs Minimal Harness）把这个修复方案做成了可重复的对照实验，其任务与underspecified-task.md几乎同构——同样是「桌面应用 + 文档 + 问答」：

• starter/task-prompt.md 全文只有一句话："Build an Electron app that can show documents and answer questions."这正是「弱 Harness」版本——没有 AGENTS.md、没有 feature_list.json、没有启动命令、没有完成标准；
• solution/ 是同一应用代码的「显式 Harness」版本，补上了四件套：AGENTS.md、feature_list.json、init.sh、claude-progress.md。

对照实验的用法（见 README.md）：

# 1. 先用 starter（弱 Harness）跑一次任务 cd starter npm install # 把 task-prompt.md 的内容作为提示词交给 Claude Code / Codex # 要求 Agent 完成：窗口启动、文档列表、问答面板、数据目录 # 本轮不得给 Agent 任何 solution 文件 # 2. 用 solution（显式 Harness）跑同一个任务 cd ../solution npm install # 要求 Agent 动代码前先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md # 3. 对比两次结果：任务完成了吗？重试了几次？Agent 是否过早宣称完成？

显式 Harness 具体补上了什么

• solution/AGENTS.md：明确「写任何代码前按顺序完成 5 步」（读本文件 → 读 docs/ARCHITECTURE.md → 读 docs/PRODUCT.md → 运行bash init.sh验证构建 → 读 feature_list.json），并定义了严格的 Electron 四层边界（main / preload / renderer / services）与代码约定（严格 TypeScript、具名导出、IPC 通道统一在src/shared/types.ts定义）。
• solution/feature_list.json：把「知识库应用」这个含糊目标拆成 4 个可验收特性——window-launch（窗口 1200x800、contextIsolation=true、nodeIntegration=false）、document-list（文档列表面板）、question-panel（问答面板）、data-directory（数据目录持久化）——每个特性都带status字段（pass/fail/not-started）和可核验的evidence字段。这就是「功能列表即 Harness 原语」的落地。
• solution/init.sh：一条命令完成npm install→npm run check（类型检查）→npm run build（构建）三件事，直接消除「环境不完整」这一类失败。
• Definition of Done（AGENTS.md 中明确列出）：TypeScript 编译无错（npm run check）→ 应用能启动且窗口可见（npm run dev）→ 特性在 feature_list.json 中标记为"pass"并附证据 → 遵守四层边界 → 运行期无 console 错误。

把 starter 的一句话需求与 solution 的完整契约放在一起，正好回答了underspecified-task.md提出的全部问题：启动命令（npm run dev）、目录结构（四层边界）、数据模型（data-directory / PersistenceService）、完成标准（feature_list.json + Definition of Done）——一个都不缺。

八、结论与关键要点

underspecified-task.md虽短，却是理解 Harness 工程的完美入口：它用最小篇幅展示了「任务描述不充分」如何系统性触发 Agent 的失败模式，而仓库中的仿真代码、检查清单和 Project 01 对照实验则给出了证据链与修复路径。

• 模型能力与执行可靠性是两回事——同一模型在裸环境与完整 Harness 下产出天差地别，Anthropic 控制实验与 OpenAI 百万行实验都证明了这一点；
• 失败时先查 Harness，再换模型——换模型是最贵的选项，而且多数时候根本不是模型问题；
• 每次失败都是信号——你的 Harness 有结构性缺陷，找到它、修好它；
• 按五层系统排查——任务未说清、上下文不足、环境配置错、缺少验证、会话间状态丢失，十次有九次问题出在这五层之一；
• 一份AGENTS.md可能比升级到更贵的模型更有效——这正是 Project 01 要你亲自验证的结论。

如果想继续深入，可以阅读 lecture-01 完整讲义、动手运行 failure-pattern-demo.ts，或按 Project 01 实验指南 亲自跑一遍弱 Harness 与显式 Harness 的对照实验。