为什么AI编程智能体需要与人类不同的使用手册

想象一下把一个代码库交给某人并说：“更新文档，但不要破坏任何东西。”一个人类开发者会阅读README，到处看看，然后弄清楚规则。AI编程智能体呢？它只能靠猜。

今天是2026年7月6日，AI智能体在编写代码方面越来越好——但它们仍然遇到了一个反复出现的问题。它们得到一个任务和一个README，然后必须即兴回答它们本来不应该问的问题：这个项目使用哪个包管理器？那些生成的文件能碰吗？什么算作“完成”？这就是AGENTS.md介入的地方，而且它出奇地实用。

README和智能体指令之间的差距

README回答了“这个项目是什么？”的问题。它是写给人类看的：你可以了解代码是做什么的，如何在本地运行它，以及在哪里可以找到其余的文档。

但是编程智能体需要不同的东西。它们需要回答“在我碰这个仓库之前我应该知道什么？”这就是AGENTS.md介入的地方。

根据格式指导，AGENTS.md是一个放置编程智能体指令的可预测位置：设置命令、测试命令、代码风格、安全注意事项以及针对大型单一代码库（monorepos）的嵌套指令。这种分离很有用，因为README和AGENTS.md文件服务于完全不同的读者。README是为构建和学习的人准备的。AGENTS.md是为执行工作的工具准备的。

究竟哪里出了问题

这里有一个具体的例子。想象你的项目把源文件和自动生成的文件放在同一个目录里。如果没有写下明确的边界，AI智能体可能会乐意修改它不该碰的东西。或者它可能会运行测试，但不是正确的测试——也许它跳过了代码检查（linting）步骤，因为没有什么告诉它代码检查很重要。

典型的解决方法？你写出更长、更详细的提示词：

“更新文档，但不要碰生成的文件，使用pnpm，运行lint和test命令，保持PR小巧，并告诉我你无法验证的内容。”

有了AGENTS.md，那个提示词缩小成了：

“为新的配置标志更新快速入门文档。”

智能体已经从文件中知道了剩下的内容。

Goose（以及其他智能体）如何使用它

这不仅是理论上的。一个叫做Goose的工具——一个拥有桌面应用、CLI、API、MCP扩展和技能的开源AI智能体——展示了为什么这在实践中很重要。如果没有AGENTS.md，每个任务都需要智能体询问你（或猜测）关于基础知识的问题。由于仓库中有AGENTS.md，Goose可以阅读一次常设规则并将其应用于每个任务。

这种模式不仅限于一个工具。任何足够聪明可以阅读文件的编程智能体，如果得到写下来的更清晰的指令，都可以遵循它们。

干净的分离：AGENTS.md和技能

一个重要的边界：AGENTS.md应该保持专注于常设规则——那些适用于仓库中几乎每个任务的事情。但是每个团队也有可重复的工作流。那些不应该把AGENTS.md膨胀成一个杂物抽屉。

更干净的方法：AGENTS.md保持简短并指向技能——针对特定类型工作的可重用指令集。对于后端服务，AGENTS.md可能会将数据库迁移、API更改和发布路由到单独的技能。文件保持可读，而详细的任务例程保存在合适的地方。

区别很简单：如果一条规则应该适用于几乎每个任务，就把它放在AGENTS.md中。如果它是一种工作的工作流，就把它做成一项技能。

实际上要在AGENTS.md里放什么

这里有一个实用的起点：

项目映射

告诉智能体什么东西放在哪里：

• src/ 包含应用程序代码。
• tests/ 包含测试。
• docs/ 包含面向用户的文档。
• generated/ 由工具生成；请勿手动编辑。

命令

列出执行操作的官方批准方式：

• 安装： pnpm install
• 测试： pnpm test
• 检查（Lint）： pnpm lint
• 类型检查： pnpm typecheck

工作规则

设定边界：

• 保持更改范围限定在用户的请求范围内。
• 在添加抽象之前，优先使用现有的辅助函数。
• 未经明确批准，请勿部署、发布、迁移或删除数据。
• 请勿在提交的文件中包含机密信息、私人数据或仅限本地的路径。

完成

定义“完成”是什么样子的：

• 运行相关的检查或解释为什么没有运行它们。
• 总结更改的行为。
• 列出剩余的风险或后续行动。

技能

路由到特定任务的工作流：

• 对于数据库迁移，使用迁移审查技能。
• 对于API更改，使用契约检查技能。
• 在发布之前，使用发布说明技能。

这已经足够有用了。它也足够短，有人可能真的会去维护它。避免架构文章、理想的价值观、仓库中的每一条命令，以及你不想在提示记录中看到的私人上下文。如果指令没有改变智能体的行为，就删掉它。

如何知道它是否有效

在一个你已经使用智能体的低风险仓库上尝试这个：

第1步：在没有AGENTS.md的情况下运行一个任务

给智能体一个简单的工作——比如，“为一个新的配置标志添加一个例子。”看看你在提示词中必须解释什么。

第2步：创建一个AGENTS.md文件

使用上面的模板。将它保持在五个部分。简短且可操作。

第3步：再次运行相同的任务

在你的提示词中只包含核心任务，把同样的工作交给智能体。

第4步：检查这三件事

智能体是否运行了正确的检查？它是否避开了生成的文件？你的提示词变短了吗？

如果这三个问题的答案都是“是”，那么仓库变得不那么模糊了。如果不是，这个文件可能需要更具体或更简单。

结论

AGENTS.md不是一个神奇的安全层，也不是一个时髦的新最佳实践。它是一个简单、乏味的地方，用来放置你已经重复过的指令：设置、检查、边界以及完成意味着什么。实用的标准是：智能体能用更少的提示完成一个小任务，并且仍然显示它运行的检查吗？如果可以，这个文件就在发挥它的作用。

优点

• 提示词变得更短，更集中在实际任务上。
• 智能体运行一致的检查而无需每次都被提醒。
• 文件和边界保持清晰——减少关于生成代码与源代码的猜测。
• 与任何编程智能体一起工作，不局限于一个工具。
• 只要保持简短和专注，就易于维护。
• 减少了智能体意外破坏东西的机会。

缺点

• 随着项目的发展，需要纪律来保持文件的最新状态。
• 已经在使用详细提示词的团队可能不会看到立竿见影的好处。
• 不能解决所有智能体可靠性问题——只是减少了不必要的猜测。
• 对于非常小的项目或一次性代码来说是大材小用。
• 需要实际读取并尊重文件格式的智能体工具。

注意

本文是教育性的，旨在解释编程智能体如何利用项目文档进行工作。如果你使用占位符值（如路径或命令）创建一个AGENTS.md文件，请用你的实际项目设置替换它们。在智能体对其采取行动之前，对照你的项目实际结构和工具验证所有指令。此处的示例具有说明性；你的仓库的特定规则可能会有所不同。

常见问题解答

• AGENTS.md和普通的README文件有什么区别？
• 我可以使用AGENTS.md与任何编程智能体，还是它特定于工具？
• 我怎么知道我的AGENTS.md文件是否足够清晰让智能体遵循？
• AGENTS.md应该包括安全策略和访问控制吗？
• 如果我的AGENTS.md文件变得太长，我该怎么办？
• AGENTS.md能代替代码注释和内联文档吗？
• 随着项目的发展，我应该多久更新一次AGENTS.md？
• 如果智能体在AGENTS.md中遇到它不理解的指令会发生什么？

标签

#AIAgents #CodingAutomation #Documentation #SoftwareDevelopment #DeveloperTools #CodingEfficiency #InstructionDesign