AGENTS.md编码规则实测：代码质量不变，开发效率提升显著

背景

近期，有开发者将受 Andrej Karpathy 启发、由 @jiayuan_jy 整理的编码规则添加到 AGENTS.md 文件中，并通过 40 个 OpenClaw 项目的 PR（Pull Request）在三个不同的编码 Agent 上进行了实际测试。这一实验旨在验证：为 AI 编码代理提供明确的编码规范指导，是否能够改善其工作表现？

Andrej Karpathy 与其编码哲学

Andrej Karpathy 是前特斯拉 AI 总监、OpenAI 创始成员之一，也是深度学习领域最具影响力的教育者之一。他倡导的编码规则强调简洁性、可读性和明确性——例如避免过度抽象、优先使用简单直接的实现、保持函数短小精悍、减少不必要的依赖等。这些原则本质上是对"防御性编程"和"KISS 原则"（Keep It Simple, Stupid）的现代化诠释，特别适合作为 AI 编码代理的约束条件，因为它们提供了明确的、无歧义的决策边界。

什么是 AGENTS.md？

AGENTS.md 是一种新兴的实践方式，开发者通过在项目根目录放置一个专门的 Markdown 文件，向 AI 编码代理（如 Cursor、Copilot Workspace、Devin 等）传达项目的编码规范、架构偏好和工作流程要求。它类似于传统的 CONTRIBUTING.md，但专门面向 AI Agent 设计，帮助它们更好地理解项目上下文和期望的代码风格。

简单来说，AGENTS.md 就是你写给 AI 编码助手的「项目说明书」，告诉它该遵循哪些规则、采用什么代码风格、避免哪些反模式。

这一实践的兴起与"上下文工程"（Context Engineering）的理念密切相关。从早期的提示工程（Prompt Engineering）到如今的上下文工程，AI 应用开发的方法论正在快速演进。提示工程关注如何措辞单次指令以获得更好的输出；而上下文工程则关注如何系统性地组织和提供信息——包括项目结构、代码规范、历史决策等——使 AI 在整个工作流程中保持一致性和高效性。AGENTS.md 正是上下文工程在软件开发领域的具体实践，它将项目的隐性知识显性化，让 AI Agent 无需通过反复试探来"猜测"项目的期望。

实验设计

此次实验的核心设计包括：

• 测试规模：40 个来自 OpenClaw 项目的真实 PR
• 测试对象：三个不同的编码 Agent
• 变量控制：在添加 Karpathy 风格编码规则前后，对比 Agent 的表现
• 评估维度：代码质量、工具调用次数、完成时间和成本

关于 OpenClaw 项目

OpenClaw 是一个开源项目，常被用作 AI 编码能力的基准测试平台。选择真实项目的 PR 作为测试用例，相比人工构造的编程题目，能更好地反映 AI Agent 在实际开发场景中的表现——包括处理现有代码库的上下文理解、遵循项目既有模式、以及与其他代码的兼容性等复杂因素。这种基于真实工程任务的评估方式，比 HumanEval 或 MBPP 等纯算法题基准更贴近开发者的日常使用场景。

这种对照实验的设计方式，确保了结果具有一定的可信度和参考价值。

核心发现：质量持平，效率提升

代码质量基本不变

实验结果显示，添加编码规则后，AI Agent 生成的代码质量与之前基本持平。这意味着这些规则并没有让 Agent 写出"更好"的代码——至少在可衡量的质量指标上没有显著差异。

这一结果其实并不意外。当前主流大语言模型（如 GPT-4、Claude 等）经过海量代码训练，已经具备了相当高的代码生成基线能力。编码规则无法突破模型本身的能力天花板，但可以帮助模型更快地收敛到正确答案。

效率显著提升

真正有意义的变化体现在效率层面：

• 更少的工具调用：Agent 不再需要反复试探和修正，减少了不必要的中间步骤
• 更低的时间消耗：完成同样任务所需的时间明显缩短
• 更低的成本：由于 token 消耗和 API 调用减少，整体运行成本降低

理解 AI 编码 Agent 的工作机制

要理解为什么减少工具调用如此重要，需要了解现代 AI 编码代理的工作方式。它们通常采用"规划-执行-验证"的循环模式：首先分析任务需求，然后通过工具调用（如读取文件、搜索代码库、运行测试、执行终端命令等）收集信息，接着生成代码，最后验证结果。每一次工具调用都消耗时间和 token，因此减少不必要的工具调用直接等同于降低成本和缩短完成时间。一个典型的复杂任务可能涉及 10-30 次工具调用循环，如果编码规则能将其减少 20%-30%，累积效果相当显著。

Token 计费与成本影响

当前主流的大语言模型 API 采用按 token 计费的商业模式，输入和输出的每个 token 都有对应价格。对于 AI 编码代理而言，一次完整的任务执行可能涉及数万甚至数十万 token 的消耗——包括系统提示词、上下文文件内容、多轮对话历史、工具调用结果等。因此，即使单次调用成本看似微小，在高频使用场景下，累积成本相当可观。减少一次不必要的工具调用循环，可能节省数千 token，这在团队规模化使用时意味着每月数百甚至数千美元的成本差异。

换句话说，AGENTS.md 中的编码规则让 AI 编码代理「少走弯路」，直接按照预期方向输出结果。

为什么编码规则能提升AI Agent效率？

规则的作用是"减少摩擦"而非"提升上限"

这个实验揭示了一个重要洞察：为 AI Agent 提供明确的编码规范，其价值不在于让它写出超越自身能力的代码，而在于减少它在探索和决策过程中的浪费。

当 Agent 清楚地知道项目期望什么样的代码风格和模式时，它可以更直接地到达目标，而不是在多种可能的实现方式之间犹豫。这与提示工程（Prompt Engineering）的核心理念一致——给 AI 更明确的约束，往往能获得更高效的输出。

从信息论的角度理解，编码规则本质上是在减少 AI Agent 决策空间的熵值。没有规则时，Agent 面对"用 camelCase 还是 snake_case？""用类还是函数？""错误处理用 try-catch 还是 Result 类型？"等无数微决策，每个决策点都可能触发额外的上下文查询。明确的规则将这些开放性问题转化为确定性指令，从而压缩了搜索空间。

类比理解

想象你给一位新入职的工程师布置任务。如果你只说"把这个功能做出来"，他可能需要反复确认代码风格、命名规范、架构选择。但如果你提前给他一份详细的编码规范文档，他就能直接动手，省去大量沟通成本。AGENTS.md 对 AI Agent 的作用与此类似。

对开发者的实践建议

1. 投入时间编写 AGENTS.md 是值得的：虽然不会让代码变得更好，但能节省实际的时间和金钱
2. 规则应该具体且可操作：Karpathy 风格的规则之所以有效，是因为它们提供了清晰的、可遵循的指导，而非模糊的原则性描述。例如，"保持函数在 50 行以内"比"写简洁的代码"更有效，因为前者给出了明确的判断标准
3. 关注 ROI 而非完美：在 AI 辅助编程的场景下，效率提升可能比质量微调更有实际价值
4. 持续迭代规则内容：随着项目演进，定期更新 AGENTS.md 中的规则，确保 AI Agent 始终获得最新的上下文信息
5. 区分不同层级的规则：可以将规则分为"必须遵守"（如安全相关）、"强烈建议"（如架构模式）和"偏好"（如格式风格）三个层级，帮助 Agent 在约束冲突时做出正确的优先级判断

更广泛的意义

这一实验也暗示了 AI 编码工具发展的一个方向：与其不断追求模型本身的能力提升，不如优化人机协作的"接口"。良好的上下文提供机制（如 AGENTS.md）可以在不改变模型的情况下，显著改善实际使用体验和经济效益。

这一发现与软件工程领域的一个经典认知相呼应：在复杂系统中，接口设计往往比组件性能更重要。正如 Fred Brooks 在《人月神话》中所指出的，软件开发中最大的困难不是技术实现，而是沟通和协调。AGENTS.md 本质上是在解决人与 AI Agent 之间的"沟通"问题——它将团队的隐性知识编码为 AI 可消费的显性规则。

从行业趋势来看，我们正在见证一个从"模型中心"到"系统中心"的范式转移。单纯提升模型参数和训练数据的边际收益在递减，而通过更好的上下文管理、工具集成和工作流编排来释放现有模型潜力，正在成为更具性价比的优化路径。

对于团队而言，维护一份高质量的 AGENTS.md 文件，可能是当前性价比最高的 AI 编程效率优化手段之一。

总结

这项基于 40 个 PR 的实测实验传递了一个清晰的信号：为 AI 编码代理提供结构化的编码规则指导，是一种低成本、高回报的优化手段。它不会让 AI 变得更聪明，但会让它工作得更高效——而在按 token 计费的时代，更少的调用次数和更短的完成时间，就是实实在在的成本节约。

如果你正在使用 AI 编码代理进行日常开发，不妨花半小时为项目编写一份 AGENTS.md，这笔投入很可能在几次使用后就能收回成本。

核心要点

• 将Karpathy风格编码规则添加到AGENTS.md后，AI编码代理的代码质量基本不变
• 效率显著提升：工具调用次数减少，完成时间和成本均降低
• 编码规则的核心价值在于减少Agent的探索摩擦，而非提升代码质量上限
• 实验覆盖40个真实PR和三个不同编码Agent，具有一定参考价值
• 为AI Agent提供结构化上下文指导是一种低成本高回报的优化策略
• AGENTS.md代表了从提示工程到上下文工程的演进方向，是人机协作接口优化的具体实践