现代前端开发中的 Harness 工程化：构建自主 Agent 的可靠运行环境

在软件工程的演进历程中，开发者与工具之间的关系正经历着从“辅助编写”到“自主执行”的根本性转变。随着大语言模型（LLM）能力的增强，尤其是像 Claude 4 Sonnet 和 GPT-5 等模型的出现，业界开始意识到，制约 AI Agent 生产力的瓶颈已不再仅仅是模型本身的逻辑推理能力，而是 Agent 所处的运行环境 。这一背景下，“Harness Engineering”（框架/支架工程）的概念应运而生。它主张通过工程化的手段为 Agent 构建一套完整的、包含约束和反馈的支撑体系，从而彻底消除 Agent 重复犯错的可能性 。   

对于前端开发这一高熵、多变且极度依赖视觉反馈的领域，Harness 工程化不仅是提升效率的工具，更是确保代码质量和系统长期可维护性的核心基础设施。本报告将深入探讨如何将最新的研究与社区实践应用于前端开发，构建一套让 Agent 能够可靠交付的“Harness”。

引言：从指令工程到环境工程的范式转移

传统的 AI 辅助开发侧重于提示词工程（Prompt Engineering），即如何通过更巧妙的描述让模型写出正确的代码。然而，当工程规模达到百万行级别，或者当 Agent 需要在没有人工干预的情况下自主完成端到端任务时，单次的提示词优化显得力不从心 。OpenAI 的 Codex 团队在 2025 年末的实验中发现，通过构建一个包含结构化文档、架构约束和反馈回路的环境，一支仅由三名工程师驱动的 Agent 团队在五个月内交付了超过一百万行代码，且交付速度比纯人工开发快了 10 倍 。   

这种新型的开发模式被称为 Harness 工程化。其核心公式可以表达为：

Coding Agent = AI Model + Harness

其中，模型提供推理引擎，而 Harness（支架/环境）则提供了控制逻辑、操作工具、执行策略和验证机制 。从工程师的角度来看，工作重心已经从“告诉 Agent 怎么写代码”转移到了“定义产品规格、设计约束、搭建反馈系统”这些支撑结构上。   

维度	提示词工程 (Prompt Engineering)	Harness 工程化 (Harness Engineering)
关注点	输入文本的技巧	Agent 运行的环境与基础设施
目标	一次性输出的准确性	长期、大规模交付的可靠性
处理错误方式	反复纠正 Agent 的输出	工程化消除错误的根源
人类角色	代码的最终编写者/修改者	意图的定义者与系统的架构师
核心组件	System Prompt, Few-shot samples	AGENTS.md, 自动化脚本, 闭环反馈

Harness 的核心架构：控制、代理与运行时 (CAR 模型)

为了系统化地理解 Harness 工程化，研究者提出了 CAR 架构模型，将 Agent 的支撑环境分解为三个关键层次：控制层（Control）、代理层（Agency）和运行时层（Runtime） 。   

控制层 (Control)：约束与意图的载体

控制层决定了哪些指令具有权威性，以及 Agent 在执行过程中必须遵守的规范。这包括了结构化的文档体系，如 product-specs/（产品规格）、design-docs/（设计文档）和 exec-plans/（执行计划） 。在前端开发中，控制层还负责定义组件库的使用规范、设计系统的令牌（Tokens）以及状态管理的决策逻辑 。   

代理层 (Agency)：操作环境的媒介

代理层定义了模型如何与外部世界交互。这包括了文件系统访问、终端命令执行、浏览器自动化（如 Playwright）以及集成第三方服务的 MCP（Model Context Protocol）服务器 。对于前端 Agent 而言，代理层的核心能力在于能够通过 headless 浏览器观察渲染结果，或通过 Figma API 获取设计稿的原始元数据 。   

运行时层 (Runtime)：策略与故障恢复

运行时层负责管理 Agent 的会话生命周期，处理执行过程中的失败，并确保状态的持久化。当 Agent 在前端构建过程中遇到类型错误或 Lint 警告时，运行时层会自动截获错误并将其作为反馈推回给模型，强制其进行自我修正 。   

意图与规范的结构化：Docs-as-Brain 体系

Harness 工程化的核心哲学是“把意图和规范写进仓库”。Agent 的输出质量有一个简单的上限：它的输入质量 。如果输入是模糊的口述需求，输出必然是充满猜测和技术债的代码。   

规格说明书 (Specs) 的新定义：一张地图

在 Harness 体系中，Spec 不应是一本冗长的百科全书，而应是一张指向明确的地图。它必须包含“WHEN/THEN Scenario”结构化场景，为 Agent 提供明确的判据 。例如，在描述一个搜索组件时：   

• WHEN: 用户输入关键词并按下回车。
• THEN: 系统应显示加载状态，调用 /api/search 接口，并根据返回结果更新列表。

这种结构化的场景描述使得 Agent 的实现可以被自动对照验证。有了判据，反馈回路才能闭合；没有判据，“发现错误”这一步只能靠人类的运气 。   

三类结构化文档的协同

仓库中应维护以下三类文档，以分层管理不同粒度的信息 ：   

1. 产品规格 (product-specs/) : 定义“做什么”。它是业务意图的最高准则，关注用户故事和验收标准。
2. 设计文档 (design-docs/) : 定义“怎么做”。记录跨服务的约定、数据库 Schema 以及前端架构选择（如：为什么选择 React Server Components 而不是传统的客户端渲染）。
3. 执行计划 (exec-plans/) : 定义“步骤”。将复杂的开发任务拆解为原子级的技术步骤，Agent 按需深入读取，避免因上下文过载而导致逻辑漂移 。   

AGENTS.md 的进化：从规则手册到导航中心

AGENTS.md（或 CLAUDE.md）是 Agent 进入代码库后的“入职指南”。早期的实践倾向于将所有规则塞进这个文件，导致文件迅速膨胀并失效 。最新的研究建议，AGENTS.md 应保持在 100 行左右，作为一个轻量级的导航中心 。   

执行约束与语义约束的分离

AGENTS.md 失败的一个重要原因是混淆了两类性质不同的约束 ：   

• 执行约束: “不要使用 npm，只用 pnpm”、“文件大小不超过 300 行”、“严禁修改 public/ 目录”。这些是确定性的规则，应直接在 AGENTS.md 或 Linter 中强制执行。
• 语义约束: “状态管理的边界在哪里”、“错误码在跨服务场景下如何处理”。这些是深层次的逻辑，应留在 design-docs/ 中。

前端开发中的 AGENTS.md 最佳实践

在前端项目中，AGENTS.md 应作为 specs/ 体系的入口。它告诉 Agent：“如果你要写组件，去查看 docs/ui-conventions.md；如果你要修改接口，去参考 docs/api-patterns.md。”

案例：一个高效的前端 AGENTS.md 示例

Agent 指导手册 (Frontend Focus)

角色定位

你是一名精通 Next.js 15 和 React Server Components 的高级工程师。你优先考虑性能、可访问性（a11y）和类型安全。

导航指南 (Source of Truth)

• 产品规格见 docs/product-specs/*.md
• UI 组件规范见 docs/ui-patterns.md (优先复用 Shadcn/UI)
• API 合约见 packages/api/schema.zod.ts

核心约束 (MUST/MUST NOT)

• MUST: 所有的业务数据获取必须在 Server Components 中完成。
• MUST: 所有的用户输入必须使用 Zod 进行 Schema 验证。
• MUST NOT: 严禁在未经过 use client 声明的文件中使用 useState 或 useEffect。
• MUST NOT: 禁止安装任何第三方 CSS 库，仅使用 Tailwind CSS。

坏行为模式记录 (基于真实错误)

• 错误记录 2025-08-10: Agent 在 Server Component 中使用了浏览器 API。

  • 解决: 任何访问 window 或 localStorage 的逻辑必须封装在 useEffect 或 dynamic(() =>..., { ssr: false }) 中。

• 错误记录 2025-09-12: Agent 编写了重复的 Table 组件。

  • 解决: 在创建新 UI 前，必须运行 grep -r "Table" src/components 检查现有组件。

常用命令

• 类型检查: pnpm typecheck
• 视觉回归测试: pnpm test:visual

前端特定挑战的工程化消除方案

前端开发中的许多错误具有重复性和模式化特征。Harness 工程化的目标不是训练开发者不犯错，而是通过环境工具让 Agent “无法”犯错 。   

消除 Next.js 水合 (Hydration) 错误

水合错误是 Next.js 开发中最常见的“幽灵” Bug。Agent 往往会写出诸如 <div>{new Date().toLocaleTimeString()}</div> 这样在服务器和客户端生成不同内容的代码 。 工程化解决方案:   

1. 约束: 在 AGENTS.md 中明确禁止直接在渲染路径中使用非确定性函数（如 Math.random 或 new Date） 。   
2. 工具: 编写一个自定义 Linter 脚本，扫描 JSX 中可能引起水合不一致的模式。
3. 反馈: 接入 Chrome DevTools MCP，当 Agent 在 Preview 环境运行时，一旦 Console 抛出水合警告，Agent 能自动捕获堆栈信息并修复 。   

消除 React Server Component (RSC) 的误用

Agent 容易混淆服务器和客户端组件的边界，例如在服务器组件中调用 onClick 处理器 。 工程化解决方案:   

1. 架构约束: 使用目录隔离法。规定 src/components/server 下严禁出现交互逻辑，并配置 eslint-plugin-react-server-components 进行强制校验。
2. 执行计划: 在 exec-plans/ 中明确标注每个组件的渲染类型，Agent 在编写代码前必须先同步更新执行计划 。   

消除可访问性 (Accessibility) 缺失

模型在生成 HTML 时往往忽略 aria-label 或 role 属性 。 工程化解决方案:   

1. 专用工具脚本: 开发一个自动化脚本，使用 axe-core 对生成的预览页面进行扫描，如果不通过 a11y 测试，禁止 Agent 提交 PR 。   
2. Skill 注入: 为 Agent 配置专门的“A11y Skill”，使其在生成组件时自动查阅 WCAG 标准库 。   

验证回路与反馈系统：从视觉回归到类型守卫

反馈回路是 Harness 的“中枢神经”。没有反馈，Agent 就是在黑暗中航行。

视觉回归测试 (Visual Regression Testing)

前端代码的正确性不仅在于逻辑，更在于视觉呈现。Agent 可能会为了修复一个 Bug 而破坏了另一个页面的布局 。 工具脚本实现: 编写一个基于 Playwright 或 Cypress 的专用脚本，在 Agent 完成修改后自动拍摄组件截图，并与 docs/screenshots/baseline 中的基准图进行像素比对 。   

• 如果像素差异 > 1%，脚本返回失败信息及差异对比图。
• Agent 必须解析该图片（通过 Vision 模型能力）并调整 CSS，直到比对通过 。   

Zod 驱动的类型守卫

Agent 在处理 API 数据时经常忽略边界情况。通过将 Zod 与 TypeScript 结合，Harness 可以建立起一道坚固的类型守卫 。 工程化实践: 要求 Agent 必须为所有 API 接口定义外部 Spec。使用工具根据这些 Spec 自动生成 Zod Schema。当 Agent 尝试访问不存在的字段时，TypeScript 编译器会立即报错，这种即时的反馈流是 Agent 高效工作的核心驱动力 。   

反馈工具	反馈类型	解决的问题
Custom Linter	静态语法/架构约束	防止违背项目架构决策（如 RSC 误用）
Vitest / Jest	业务逻辑验证	确保功能实现符合 Spec 定义的 Scenario
Playwright Pixel-diff	视觉回归验证	防止 CSS 样式漂移和布局破坏
Zod safeParse	运行时数据校验	消除未定义字段引发的页面崩溃
Sentry MCP	运行时错误日志	实时捕获预览环境中的异常并回传给 Agent

规范驱动开发 (SDD) 与 Spec-Code 一致性检测

规范驱动方法（Specification-Driven Development, SDD）的核心是提高“正确交付的总成本”而非“初次写代码的速度” 。   

意图的精化过程

人类不再直接编写 Spec 文件，而是通过与 AI 的引导式对话，从模糊的原始意图提取、精化出结构化的 Spec 。例如，人类口述“我想要一个带搜索功能的导航栏”，AI 会引导人类明确：   

• 搜索是实时的吗？
• 需要历史记录功能吗？
• 在移动端如何呈现？

精化后的 Spec 被写进 product-specs/ 目录，作为长期有效的 scaffolding。

主动的一致性检测

Spec 与代码的脱节（漂移）是工程管理的顽疾。未来的 Harness 建设重点应在于“主动检测机制” 。   

• 接口一致性: 对照 Spec 中的接口定义与代码中的实际调用。
• Schema 一致性: 定期检测数据库 Schema 或 API 返回值是否与 Spec 描述一致。
• 自动更新提案: 一旦发现漂移，Harness 会自动发起一个更新提案（PR），要求开发者确认是修改代码还是同步更新 Spec 。   

角色重塑：人类作为意图源与审计者

在 Harness 完备的体系下，人类的工作重心发生了剧变。工程师不再是体力劳动者，而是成了审计员和决策者 。   

审查 Spec 比审查代码更重要

人类必须意识到，审查 Spec 的收益远大于审查代码。因为 Spec 代表了意图的结构化表达，如果 Spec 错了，代码即便写得再优雅也是无用功 。   

• 审查重点: 验收标准是否完备？异常流程是否覆盖？是否违背了现有的架构约束？

解决 Bug 的首要追问

当 Agent 遇到 Bug 或阻塞时，首要的追问不是“怎么让你把这件事做对”，而是“你在完成这件事时还缺什么” 。   

• 是否缺少了某个工具脚本（如：无法查看隐藏的 DOM 元素）？
• 是否缺少了某个上下文（如：不知道这个 API 的限流规则）？
• 是否缺少了明确的反馈（如：测试报错信息太模糊）？

总结：工程化消除错误的未来图景

Harness 工程化本质上是将“人的经验”转化为“系统的支撑结构”。它承认 Agent 作为一个推理引擎，其稳定性受限于环境的熵值。通过在仓库中建立起以 AGENTS.md 为导航、以结构化 Spec 为大脑、以自动化反馈回路为感官的 Harness 系统，我们可以将 AI 从一个“偶尔出错的助手”转变为一个“持续交付的专家” 。   

对于前端工程师而言，构建好让 Agent 工作的环境——文档、约束、反馈回路——正是未来十年最核心的职业竞争力。我们不再为每一行代码负责，而是为那个能够自主产生高质量代码的“生产系统”负责。Harness 是让 Agent 可靠工作的系统，而不只是模型本身 。规范虽然会带来短期的成本增加，但它通过降低长期的沟通成本和重构成本，优化了软件交付的终极曲线 。在这个体系中，人可以换，AI session 可以换，但 Spec 留下来——这才是软件资产长期有效的前提。