AGENTS.md是一种简单、开放的格式，专为引导AI编码代理而设计，已被超过2万个开源项目使用。它类似于README.md，但专注于为AI代理提供详细的上下文和指令，如构建步骤、测试和代码风格，以帮助它们更好地处理项目。AGENTS.md与README.md分开，旨在保持README的简洁性，同时为代理提供精确的指导，确保其兼容多种AI代理，并易于广泛采用。

AGENTS.md：为AI编程助手设计的指南文件

AGENTS.md是一种简单、开放的格式，专为引导AI编程助手而设计，已被超过2万个开源项目使用。它类似于项目的README文件，但更专注于为AI助手提供所需的上下文和指令，帮助它们更高效地处理项目。

为什么需要AGENTS.md？

README.md文件主要面向人类开发者，提供快速入门、项目描述和贡献指南。而AGENTS.md则补充了AI编程助手所需的额外信息，如构建步骤、测试和代码规范等，这些内容可能会让README文件显得冗长或不适合人类开发者。通过将AGENTS.md与README分开，可以确保：

• 为AI助手提供一个清晰、可预测的指令来源。
• 保持README简洁，专注于人类开发者。
• 提供精确的、面向AI助手的指导，补充现有的README和文档。

AGENTS.md的设计初衷是成为一个通用的文件格式，适用于任何使用或构建AI编程助手的开发者。

AGENTS.md的跨平台兼容性

AGENTS.md的定义与不断增长的AI编程助手生态系统兼容，适用于多种工具和平台。

如何使用AGENTS.md？

1. 添加AGENTS.md文件：在项目根目录下创建AGENTS.md文件，许多AI助手甚至可以自动生成该文件。
2. 涵盖关键内容：添加有助于AI助手高效工作的部分，如项目概述、构建和测试命令、代码风格指南、测试指令和安全考虑等。
3. 补充额外指令：包括提交信息、拉取请求指南、安全注意事项、大型数据集处理步骤等，类似于你向新团队成员解释的内容。
4. 大型项目中的嵌套使用：在大型单体仓库中，可以为每个子项目创建嵌套的AGENTS.md文件，AI助手会自动读取最近的指令文件。

关于AGENTS.md

AGENTS.md的诞生源于AI软件开发生态系统的协作，包括OpenAI Codex、Amp、Google的Jules、Cursor和Factory等。我们致力于将其维护和发展为一个开放的格式，惠及整个开发者社区，无论你使用哪种AI编程助手。

常见问题

• 是否有必填字段？：没有，AGENTS.md是标准的Markdown文件，可以使用任何标题。
• 如果指令冲突怎么办？：最近的AGENTS.md文件优先，明确的用户聊天提示会覆盖所有指令。
• AI助手会自动运行测试命令吗？：是的，如果你列出了相关命令，AI助手会尝试执行并修复错误。
• 可以更新AGENTS.md吗？：当然，AGENTS.md应被视为动态文档。
• 如何将现有文档迁移到AGENTS.md？：将现有文件重命名为AGENTS.md，并创建符号链接以保持向后兼容性。

通过AGENTS.md，开发者可以为AI编程助手提供更精准的指导，提升项目开发的效率和协作效果。

评论主要围绕是否应该将README.md和AGENTS.md文件分离，以及AGENTS.md文件是否应该标准化展开。以下是主要观点和论据的总结：

反对分离和标准化的观点

1. 分离文件不必要：一些评论者认为分离README.md和AGENTS.md并不必要，甚至可能增加复杂性。

   • "I'm still not convinced that separating README.md and AGENTS.md is a good idea." (ivanjermakov)
   • "In what way is this a format or standard? It's just markdown in a namespace." (eats_indigo)

2. AI应适应人类格式：部分评论者认为AI应适应人类的文档格式，而不是人类为AI编写特定格式的文档。

   • "Isn't the promise of AI that we don't have to adhere to precise formats?" (alphazard)
   • "We should always write for humans. The LLM's whole shtick is that it can read and comprehend our writing." (blinkymach12)

支持分离和标准化的观点

1. 标准化有助于一致性：一些评论者认为标准化AGENTS.md文件有助于不同工具之间的一致性，减少重复劳动。

   • "It would be nice if it was standardized." (stingraycharles)
   • "I think this is a good thing - I would like to see the same pattern standardized for the memory system of all the different agents." (_mu)

2. 分层结构更有效：部分评论者建议采用分层结构来管理AGENTS.md文件，以提高可维护性和响应准确性。

   • "This should've been an .agents¹ with an index.md." (CharlesW)
   • "The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication." (prmph)

其他观点

1. 工具支持：一些评论者提到已有工具支持生成和管理AGENTS.md文件，如ruler和agentsmd。

   • "Right now I’m using ruler to automate generating these files for all standards." (stingraycharles)
   • "This is a command-line tool that lets you generate your AGENTS.md and CLAUDE.md files from common sources." (cortesi)

2. AI文档的局限性：部分评论者对AGENTS.md文件的实用性提出质疑，认为AI可能会忘记文件内容，且文件的管理和提交也存在问题。

   • "What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and again?" (prmph)
   • "Are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI?" (prmph)

总结来看，评论者对AGENTS.md文件的分离和标准化持有不同意见，支持者认为标准化有助于工具一致性，而反对者则认为AI应适应人类文档格式，且当前标准缺乏创新。