企业官网建设流程全解析

“harness（约束框架）”是 AI 编程 Agent 讨论中被滥用最多的词之一：多数人说起 harness 时，指的只是一个 prompt 文件，但一个 prompt 文件并不是 harness。本篇文章以 learn-harness-engineering 仓库第二讲（Lecture 02: What a Harness Actually Is）及配套组件清单文档（code/harness-components.md）为核心，给出 harness 的精确定义、五个子系统的职责划分、可量化的评估方法，并结合仓库中的 TypeScript 示例与真实项目工程，帮助你在自己的仓库里从零搭建一套可验证、可迭代的 harness。

一、什么是 Harness：模型之外的一切工程基础设施

先看本讲给出的最直接定义——对于一个在本地仓库中工作的编码 Agent，harness 组件清单如下（原文见 code/harness-components.md）：

• Model：LLM 本身（这是唯一不属于 harness 的部分）；
• Harness包含：
  • prompt 系统（system prompt）
  • AGENTS.md
  • bash 工具（bash tool）
  • 文件读写工具（file read/write tools）
  • git 访问（git access）
  • 本地文件系统（local filesystem）
  • 启动脚本（startup scripts）
  • 测试命令（test commands）
  • 停止钩子（stop hooks）
  • lint 检查（lint checks）
  • 评估循环（evaluator loop）

清单末尾有一句被很多人忽略的关键结论：“If you change any of the above harness pieces, you change the effective agent.”（你改动上面任何一件 harness 组件，就等于改动了实际的 Agent。）这句话是 harness engineering 的出发点——模型的权重是固定的，但决定模型能力被兑现多少的，是这套外部基础设施。

本讲原文进一步把 harness 收拢成一个可执行的公式：

Harness = 指令（Instructions）+ 工具（Tools）+ 环境（Environment）+ 状态（State）+ 反馈（Feedback）

五个子系统缺一不可。缺失任何一个，意味着 harness 不完整，Agent 用起来总会“别扭”。

二、五个子系统的职责与落地要点

本讲用一张流程图描述五个子系统之间的数据流（见 index.md）：

1. 指令子系统（Instructions）

为项目创建AGENTS.md（或CLAUDE.md），内容应包含：项目概览与目的、技术栈与版本、首次运行命令、不可妥协的硬性约束、指向更详细文档的链接。

关键原则是“给地图，而不是给手册”（Give a map, not a manual）：AGENTS.md应该像导航页，而不是百科全书，100 行左右通常足够；装不下就拆分到docs/目录，让 Agent 按需查阅。

仓库里projects/project-01/solution/AGENTS.md是一个很好的示范——它只有五节（Startup Rules、Electron Layer Boundaries、Conventions、Definition of Done、Working with the Feature List），其中 Startup Rules 用有序步骤约束 Agent 开工前的固定动作：先读本文件、再读docs/ARCHITECTURE.md与docs/PRODUCT.md、执行bash init.sh验证构建、最后读取feature_list.json。这正是“指令子系统”在真实项目中的形态。

2. 工具子系统（Tools）

确保 Agent 拥有足够的工具访问权。不要以“安全原因”禁用 shell——如果 Agent 连pip install都执行不了，它如何完成任务？但也不要毫无节制地全开，应遵循最小权限原则（least privilege）。

在本讲的配套代码 code/minimal-harness-loop.ts 中可以看到工具子系统的最小形态：一个runTool(name, input)分发函数，目前只实现了read_file，未知工具直接返回ok: false与错误信息——这就是“用代码约束 Agent 能力边界”的最小可运行样例。

3. 环境子系统（Environment）

让环境状态“自描述”（self-describing）：用pyproject.toml或package.json锁定依赖，用.nvmrc或.python-version指定运行时版本，用 Docker 或 devcontainers 保证环境可复现。环境的不可复现，正是很多 Agent 失败报告中“能在我机器上跑”的真正根源。

4. 状态子系统（State）

长任务必须有进度追踪。用一个简单的PROGRESS.md记录三件事：已完成（what is done）、进行中（what is in progress）、被阻塞（what is blocked）。每次会话结束前更新，下次会话开始时读取。这与本讲后续项目（Project 03 多会话连续性、Project 12 每次会话留下干净状态）的思想一脉相承。

5. 反馈子系统（Feedback）

这是投资回报率最高的子系统。在AGENTS.md中显式列出验证命令（原文示例）：

Verification commands: - Tests: pytest tests/ -x - Type check: mypy src/ --strict - Lint: ruff check src/ - Full verification: make check (includes all above)

仓库中projects/project-01/solution/AGENTS.md的 “Definition of Done” 一节同样把“可验证”作为完成标准：TypeScript 编译无错误（npm run check）、应用能启动且窗口可见（npm run dev）、功能在feature_list.json中标记为"pass"并附上证据、遵守分层边界、运行期无 console 错误。这五条就是该项目的“验证命令集”。

三、用代码看懂 harness 如何改变 Agent 行为

本讲的配套代码 code/harness-vs-no-harness.ts 用同一个任务执行器做了“有 harness”与“无 harness”的对照实验，可以直接运行：

npx tsx docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts

任务集包含 5 个任务，每个任务有requiresAuth、hasTests、withinScope三个属性：

const tasks: Task[] = [ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true }, { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true }, { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false }, { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true }, { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true }, ];

无 harness 版本（runWithoutHarness）的执行逻辑是“Agent 干完活就宣布完成”——passed恒为true，即使“需要鉴权的端点没有测试”“任务超出当前范围”这类问题已经发生，也没有任何机制让 Agent 察觉。

有 harness 版本（runWithHarness）则引入了两条可执行规则和一次验证步骤：

const rules = { requireTestsForAuth: true, enforceScope: true, }; // 规则 1：鉴权端点必须有测试，否则 BLOCKED // 规则 2：超出当前范围的任务被跳过，标记 BLOCKED // 验证：通过后才检查 "没有测试" 并给出 WARNING

运行后，程序会输出一个对照表和一个汇总指标（printComparison），其中“假阳性（通过了但有缺陷）”一栏最能说明问题：无 harness 时所有任务都“通过”，而 harness 版本能把真实缺陷暴露出来。脚本最后两行注释点明了结论：

“The harness catches problems the no-harness run silently ignores. Without a harness, every task 'passes' even when it shouldn't.”（harness 捕获了无 harness 运行会静默忽略的问题；没有 harness，每个任务都会“通过”，即使它本不该通过。）

这个例子完美呼应了组件清单中的“evaluator loop（评估循环）”——反馈不是靠 Agent 自觉，而是靠外部的检查机制强制闭环。

四、量化 harness 的价值：控制变量排除实验

harness 组件这么多，怎么知道哪个最有价值？本讲给出的方法论是**“控制变量排除测试”**（controlled variable exclusion test）：

1. 保持模型固定不变；
2. 一次只移除五个子系统中的一个（删除AGENTS.md、不提供验证命令、去掉进度文件……）；
3. 测量移除后性能下降的幅度。

移除后下降最大的组件，就是当前任务边际贡献最高的组件，值得优先强化。但有两个重要的限定条件：

• 下降幅度不等于瓶颈位置：这个实验只能回答“当前哪个组件最有价值”，不能单独证明“瓶颈在哪里”。要定位真正瓶颈，必须结合失败记录与失败归因（failure attribution）：任务本身定义不清？上下文不足？环境不可复现？缺少验证反馈？还是状态管理坏了？组件消融结果只能作为佐证。
• 接近零影响的组件不要急着删：它们可能只是冗余、设计不佳，或者只是“当前任务没用到”。随着模型变强，一些组件会不再关键，但新的关键组件总会出现——这正是 Anthropic 在实际消融中观察到的现象。

五、一个真实团队的演进案例：20% → 近 100%

本讲记录了一个真实团队用 GPT-4o 开发 TypeScript + React 前端应用（约 2 万行代码）的四个阶段，本质上是“一次加一个 harness 组件”：

四次迭代，模型从未更换，成功率却从 20% 提升到接近 100%。你没有换更强的模型——换的是 harness。

这个案例在仓库中并非孤例：projects/project-01/solution/feature_list.json就展示了“把验证结果固化成证据”的落地方式——每个功能条目都带status（pass/fail/not-started）、evidence和testedAt时间戳，例如window-launch的 evidence 是“npm run devlaunches window at 1200x800 with contextIsolation=true and nodeIntegration=false”。这相当于把上面案例里的“阶段 3 + 阶段 4”合并成了一种可审计的工程实践：不是 Agent 声称完成了，而是有可复现的证据表明完成了。

六、工具对比：为什么说“是 harness 不行，不是 Agent 不行”

本讲用几个读者都熟悉的工具印证 harness 思想（此处仅作项目事实引用，不提供外部链接）：

• Claude Code：会读取仓库中的CLAUDE.md、能执行 shell 命令、运行在本地环境、维护会话历史、可运行测试。但如果你不告诉它测试怎么跑，它就无法验证自己做得对不对——反馈子系统缺失。
• Cursor：.cursorrules是指令来源，终端是工具，能读取项目结构与 lint 配置。但状态管理较弱——关闭 IDE 再打开，之前的上下文就没了。
• Codex（OpenAI 的编码 Agent）：用 git worktrees 隔离每个任务的运行环境，配合本地可观测性栈（日志、指标、trace），每次改动都在独立环境中验证。在带AGENTS.md和清晰验证命令的仓库中，表现远好于“裸”仓库。
• AutoGPT：反面教材。缺少结构化状态管理导致长任务中上下文无限累积，缺少精确反馈机制导致 Agent 进入死循环。很多人说“AutoGPT 不好用”，实际上是它的 harness 不好用。

本讲还引用了两个行业共识作为理论锚点：OpenAI 将 harness engineering 的核心原则概括为“the repo IS the spec（仓库即规格）”——所有必要上下文都应存在于仓库内，通过结构化指令文件、显式验证命令和清晰的目录组织交付；Anthropic 的长时运行 Agent 文档则强调状态持久化、显式恢复路径和结构化进度追踪。两家公司侧重不同，但说的是一件事：模型之外的一切工程基础设施，决定了模型能力被真正兑现多少。

七、核心要点与实践练习

关键结论

• Harness = 指令 + 工具 + 环境 + 状态 + 反馈，五个子系统缺一不可；
• 只要不是模型权重，就是 harness。你的 harness 决定模型能力被兑现多少；
• 五个子系统中，反馈子系统通常成本最低、回报最高——先从验证命令开始；
• 用控制变量排除测试量化各子系统的边际贡献；要定位真正瓶颈，依赖失败记录与归因，而不是仅靠消融；
• Harness 会像代码一样腐烂。定期审计，像偿还技术债一样偿还 harness 债。

三个可直接上手的练习

1. 五维审计：选一个你正在用 AI Agent 的项目，用五子系统框架做完整审计，为每个子系统打 1–5 分；找到最低分子系统，花 30 分钟改进它，观察 Agent 表现变化。
2. 控制变量排除测试：固定一个模型和一个有挑战性的任务，依次只移除指令（删AGENTS.md）、移除反馈（不提供验证命令）、移除状态（无进度文件），每次只删一项并测量性能下降；同时记录失败日志做根因归因。
3. Affordance 分析：找出项目中 Agent“想做但做不到”的场景（例如知道应该用参数化查询，却不了解项目的 ORM 模式），分析它是 Gulf of Execution（不知道如何操作）还是 Gulf of Evaluation（不知道自己做对了没有），然后设计一个 harness 改进来弥合该差距。

配套的动手项目是 Project 01: Baseline vs Minimal Harness，其完整工程（含AGENTS.md、feature_list.json、分层架构文档）位于 projects/project-01/solution，可作为你对照练习的参考基线。