Harness Engineering：AI编程第三阶段与agents.md实践指南

一篇论文揭示的AI编程真相

最近一篇名为《Harness Engineering for Agentic AI Coding Tool》的论文在AI编程圈引发广泛关注。该论文作者团队系统扫描了 2853个GitHub代码仓库——这些并非随机选取，而是经过筛选的工程级项目：拥有多个贡献者、持有许可证、保持持续活跃。这种「用真实开源数据说话」的研究方法，采用了实证软件工程（Empirical Software Engineering）的经典范式，通过大规模挖掘GitHub公开仓库来分析真实开发实践。排除个人实验项目和僵尸仓库的干扰，2853个仓库的样本规模足以支撑统计显著性分析，使其结论对业界具有强参考价值。

扫描结果令人意外：85.5%的AI技能（Skills）配置只是空壳，定义了却从未执行过。但另一组数据更耐人寻味——有 493个仓库只使用了一个文件 agents.md，没有厂商绑定，没有工具锁定。开发者们用脚投票，自发选出了属于自己的配置标准。

这，正是 Harness Engineering（底座工程）的起点。

什么是 Harness Engineering？

AI编程范式的三次进化

如果你是第一次听说「Harness Engineering」，它的前身你一定熟悉。AI编程的实践范式经历了三个阶段：

• 第一阶段：Prompt Engineering（提示词工程）——核心是「写词」，把问题描述清楚。
• 第二阶段：Context Engineering（上下文工程）——核心是「设计上下文」，给AI提供恰当的背景信息。
• 第三阶段：Harness Engineering（底座工程）——把AI放进一个结构化框架里，明确告诉它能做什么、不能做什么、怎么找文件、怎么跑测试、出错时如何兜底。

Context Engineering是2024年以来AI工程实践中最重要的概念突破之一。它的核心洞察是：大语言模型的输出质量在很大程度上取决于输入上下文的质量，而非模型本身的能力上限。上下文工程关注如何系统性地构建输入——包括系统提示（System Prompt）、历史对话、检索增强（RAG）注入的外部文档、工具定义（Tool Schema）以及结构化示例（Few-shot Examples）。相比之下，Prompt Engineering更关注单次问题的表述技巧；而Harness Engineering则进一步将上下文管理从「每次手动构建」升级为「一次配置、持续生效」的工程化体系，使AI在整个项目生命周期内都能获得一致的结构化上下文。

这背后是开发者角色的深刻转变：从「写代码的人」变成「设计AI行为的人」。

两个核心概念：Agent 与 Tool

理解 Harness Engineering，需要先厘清论文中两个明确定义的概念：

• Agent（智能体）：目标驱动。给它一个目标，它自主拆解步骤、选择工具、执行、调整、再执行——形成自主循环。
• Tool（工具）：边界功能。一个确定性的能力单元，比如执行一条命令：调用一次、执行一次、结束。

Agentic AI（智能体AI）代表了大语言模型从「问答助手」向「自主执行者」的范式转变。与传统的单轮对话模型不同，Agentic AI具备规划（Planning）、工具调用（Tool Use）、记忆（Memory）和自我修正（Self-correction）四大核心能力。它能够将一个高层目标分解为多个子任务，依次调用文件读写、终端命令、网络请求等外部工具，并根据执行结果动态调整策略——形成「感知-决策-行动」的闭环循环。这一架构在技术上依赖于ReAct（Reasoning + Acting）等推理框架，使模型在每一步决策前都能生成可追踪的思维链。

关键区别在于：Agent 是自主的，Tool 是被动的。正因为 Agent 具备自主性，才需要为它设定边界——这正是 Harness 配置的核心价值。

单次问答 vs 持续执行

传统 Copilot 模式是：写一个 Prompt，得到一段代码，一次对话一次回答，结束。而新一代 Agent 模式完全不同：写一个配置文件，启动一个循环——读文件、跑测试、发现问题、自主修复、再跑测试，直到任务完成。

单次问答不需要配置，但持续执行必须有边界。 这正是 Harness Engineering 解决的核心问题。

八大配置机制详解

论文系统梳理了控制 AI 行为的八种配置机制，构成 Harness Engineering 的完整工具箱。

1. Context Files（上下文文件）

这是最基础也最重要的机制，核心文件有三个：

• agents.md：跨工具通用标准，无论你用 Claude、Copilot 还是 Cursor 均可识别。
• CLAUDE.md：Claude Code 专属配置文件。
• GEMINI.md：Gemini 专属配置文件。

这些文件相当于给 AI 写一份项目说明书：项目架构是什么、如何构建、如何测试、代码规范是什么。

2. Skills（技能包）

技能包采用文件夹结构：SKILL.md（核心指令）+ Scripts 目录（可执行脚本）+ References 目录（参考文档）+ Assets 目录（静态资源）。打包在一起便是一个可复用的能力单元。例如代码审查技能：指令写在 SKILL.md，审查脚本放 Scripts，审查标准放 References。

然而，85.5%的Skills处于「只有文档、没有脚本」的空壳状态，这一现象在软件工程领域有其深层原因。从认知负荷（Cognitive Load）理论来看，构建一个完整的技能包需要开发者同时掌握多个维度的知识：业务逻辑的抽象化、Shell脚本的编写、跨平台兼容性的处理，以及AI指令的设计——这一复合技能门槛对于大多数后端或前端开发者来说过高。这也反映了「配置即文档」的惰性陷阱：写Markdown几乎没有执行成本，但写可运行脚本需要调试和维护投入，与软件工程中「测试驱动开发（TDD）采用率低」「API文档过时」等经典问题如出一辙。

3. Subagents（子智能体）

高阶玩法：主 Agent 可以派出多个子 Agent，每个拥有独立的上下文、工具和状态，并行执行、互不干扰。比如主 Agent 写代码时，派一个子 Agent 跑测试，再派一个审查文档，最后汇总结果——本质是把复杂任务拆解分配给不同的专职执行单元。

4–5. Commands 与 Rules

• Commands（快捷命令）：定义命令别名，如 review 触发代码审查流程，deploy 触发部署流程。
• Rules（行为准则）：硬性约束规则，如「不允许删除生产数据库」「不允许提交未测试代码」「必须遵循 PEP8 规范」——相当于给 AI 套上「紧箍咒」。

6–7. Settings 与 Hooks

• Settings（运行时参数）：选用哪个模型、超时时长、日志级别等底层配置项。
• Hooks（生命周期钩子）：在特定时刻自动触发，如提交前运行测试、通过后自动部署、文件修改后发送通知，让 AI 行为可预测、可审计、可追溯。

Hooks是一种经典的软件设计模式，在Git、CI/CD流水线（如GitHub Actions）、前端框架（如React的useEffect）中均有广泛应用。其核心思想是「在特定事件发生时自动触发预定义逻辑」，从而将人工干预转化为系统化的自动响应。在AI编程场景中，Hooks的价值尤为突出：它使AI的行为从「不可预测的黑盒」变为「可审计的流水线」。Hooks几乎无人使用的现状，也意味着当前大多数AI编程实践仍停留在「人工监督」阶段，距离真正的自主化执行还有相当距离。

8. MCP（模型上下文协议）

最前沿的机制，解决 AI 如何访问外部数据的问题——数据库、API、Jira、Slack、GitHub 等系统不在代码库里，但 AI 的任务往往需要它们。

MCP（Model Context Protocol，模型上下文协议）由Anthropic于2024年11月正式开源，是当前AI工具生态中最具战略意义的标准化协议之一。MCP采用客户端-服务器架构：AI模型作为客户端，各类外部系统（数据库、API、文件系统等）作为MCP服务器，两者通过标准化的JSON-RPC协议通信。MCP定义了三类核心能力：Resources（结构化数据读取）、Tools（可执行操作调用）和Prompts（预设提示模板）。开发者只需为某个系统（如PostgreSQL或Jira）实现一次MCP服务器，所有兼容MCP的AI工具均可直接调用，从根本上解决了AI工具与外部世界的连接碎片化问题。MCP作为标准化桥梁，让 AI 安全地连接外部系统进行读写操作，且不绑定任何特定工具。

残酷的数据：理想与现实的落差

论文的数据分析部分最具冲击力，揭示了当前 AI 编程配置实践的真实现状。

大多数团队还没开始多工具协作

85.4% 的仓库只配置了一个工具，说明多工具协作尚未普及。其中 Claude Code 占比 45.2%，是目前最受欢迎的 AI 编程工具，Cursor 和 Copilot 紧随其后。但各工具之间几乎没有融合，基本各自为战。

agents.md 的自发崛起

时间线分析揭示了一个有趣趋势：CLAUDE.md 通常最先出现（因为 Claude Code 最早提供配置能力），随后开发者会追加 agents.md。原因很简单——agents.md 是通用的，无论换什么工具都能读取。最终，493 个仓库只用 agents.md，不用任何工具特定配置。

这折射出AI工具生态中「开放标准 vs 厂商锁定」的深层博弈。厂商锁定（Vendor Lock-in）是企业技术选型中的经典风险——一旦深度绑定某家厂商的专有格式，迁移成本将随配置复杂度指数级增长。历史上，云计算领域经历过相同的演化路径：从各厂商私有API，到OpenStack、Kubernetes等开放标准的崛起。agents.md的自发流行预示着类似的标准化趋势——开发者以实际行动表达了对可移植性和工具无关性的强烈偏好。这是一场自下而上的标准化运动。

高级特性集体荒废

然而理想与现实存在明显落差：

• 85.5% 的 Skills 是空壳，只有文档没有脚本，定义了但从未执行。
• Subagents 的持久内存功能零采用率。
• Hooks 和 MCP 几乎无人使用。

根本原因是配置成本过高：写一个简单的 SKILL.md 很容易，但构建一个带脚本、带引用、带资源的完整技能包门槛太高。于是大多数人选择了最简单的路径——只写文档，不写脚本。

三大工具的配置风格对比

论文对比了三大主流工具的配置生态，风格差异明显：

• Claude Code：最复杂，八种机制全覆盖，用户配置深度也最高。
• Cursor：强调 Rules 和 Commands，.cursorrules 文件是其标志性配置。
• Copilot：最简单，几乎只用 Context Files，鲜少扩展到其他机制。

三个工具、三种风格、三套生态，满足不同团队的配置偏好。各工具的专有配置能力必须显著优于通用标准，否则难以留住有长期规划的工程团队。

三条落地实践建议

论文最后给出三条可操作的建议，尤其适合刚起步的开发者：

1. 从 agents.md 开始。无论现在用什么工具，先写一个 agents.md，把项目架构、构建命令、测试规范写进去——这是最低成本的起点。
2. 多工具环境维护共享核心配置。如果你同时使用 Claude 和 Cursor，让它们读取同一个 agents.md，避免重复维护。
3. 用 Skills 打包重复性工作流。如果团队有固定的代码审查或发布流程，打包成 Skill 复用，降低重复配置成本。

配置文件将成为团队核心资产

Harness Engineering 的本质，是用配置文件管理 AI 行为——不靠 Prompt 猜测，不靠对话引导，而是写配置、定规则，让 AI 在明确边界内工作。

更重要的是，这不只是个人实践，更是团队协作的基础设施。想象这样一个场景：团队共享一个 agents.md，每次修改都要经过讨论并走代码评审流程——因为它决定了 AI 如何理解项目、如何执行任务、如何遵守规范。配置文件将和代码一样，成为团队不可或缺的核心资产。

趋势已经清晰：agents.md 正在成为事实标准，开发者们在用脚投票，选择通用标准、拒绝厂商绑定。这一演化路径与Kubernetes在容器编排领域的崛起如出一辙——社区的自发聚合力量，往往比任何顶层设计都更具持久性。如果你的 AI 编程助手效果不理想，或许不是工具的问题，而是配置方式还没跟上。不妨从今天开始，为你的项目写一个 agents.md，迈出 Harness Engineering 的第一步。

核心要点