AGENTS.md：AI编码的新标准

如果你和我一样，使用多个AI编码代理，你一定知道管理不同指令文件的烦恼。在各种格式之间保持所有内容更新是一件很麻烦的事情。但我有个好消息告诉你。一个新的简化标准已经出现，它叫做AGENTS.md。

1、竞争标准的问题

一段时间以来，与不同的AI代理一起工作意味着要处理多个配置文件。无论是claude.md、gemini.md还是.cursor/rules，每个代理都有自己的格式。这导致了冗余文件的混乱，所有文件都需要单独更新。这是低效且令人困惑的。

大公司意识到了这个问题。他们聚集在一起创建了一个统一的解决方案——AGENTS.md。目标是为所有AI代理建立一个单一、可预测的地方，让他们找到完成项目所需的指令。

2、什么是AGENTS.md？

可以将AGENTS.md视为一个机器用的README文件。它是一种简单、开源的格式，指导AI编码代理如何与你的项目互动。它已经被超过20,000个开源项目所使用。

这个文件提供了AI理解并处理你的代码所需的所有上下文，包括：

设置命令：安装依赖项和构建项目的说明。
代码风格：关于格式和设计模式的规则，以确保一致性。
测试：如何运行测试以验证更改。
提交指南：提交信息和 linting 规则的首选格式。
自定义备注：任何其他重要信息，如安全考虑或性能提示。

看看下面的例子。

# 示例 AGENTS.md 文件  

## 开发环境技巧  
- 使用 `pnpm dlx turbo run where <project_name>` 跳转到一个包，而不是使用 `ls` 进行扫描。  
- 运行 `pnpm install --filter <project_name>` 将包添加到你的工作区中，这样 Vite、ESLint 和 TypeScript 可以看到它。  
- 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 来启动一个带有 TypeScript 检查的新 React + Vite 包。  
- 检查每个包的 package.json 中的 name 字段以确认正确的名称—跳过顶层的那个。  

## 测试说明  
- 在 .github/workflows 文件夹中找到 CI 计划。  
- 运行 `pnpm turbo run test --filter <project_name>` 来运行该包定义的每一个检查。  
- 从包根目录你可以直接调用 `pnpm test`。提交前应该通过所有测试。  
- 要专注于某一步，添加 Vitest 模式：`pnpm vitest run -t "<test name>"`。  
- 修复任何测试或类型错误，直到整个套件都通过。  
- 移动文件或更改导入后，运行 `pnpm lint --filter <project_name>` 以确保 ESLint 和 TypeScript 规则仍然有效。  
- 为所修改的代码添加或更新测试，即使没有人要求这样做。  

## PR 指南  
- 标题格式：[<project_name>] <Title>  
- 始终在提交前运行 `pnpm lint` 和 `pnpm test`。

3、如何迁移到AGENTS.md

迁移到AGENTS.md非常简单。你可以通过终端仅用两个简单的步骤合并你现有的指令文件：

重命名你的文件：使用命令 mv AGENT.md AGENTS.md 重命名你的主指令文件。
创建符号链接：使用 ln -s AGENTS.md AGENT.md 创建一个符号链接。这确保与尚未更新到新标准的任何工具的向后兼容性。

4、如何使用AGENTS.md

开始使用AGENTS.md很简单：

添加文件：在你的仓库根目录创建一个AGENTS.md文件。
涵盖关键点：添加项目概述、构建和测试命令、代码风格指南以及其他相关说明。
添加额外说明：包括提交信息、拉取请求指南，以及新同事需要了解的任何其他信息。

5、最佳实践

为了充分利用AGENTS.md，请遵循以下一些最佳实践：

明确且简洁：保持你的指令清晰且简明。
保持指令最新：确保文件始终符合你项目的需求。
链接到现有文档：而不是重复信息，链接到你现有的文档。
为大型monorepos使用多个文件：对于大型monorepos，你可以为不同的子项目使用嵌套的AGENTS.md文件。

就是这样！通过采用AGENTS.md标准，你可以优化你的工作流程，确保一致性，并使AI代理更容易与你的项目合作。

原文链接：AGENTS.md: The New Standard for AI Coding Assistants

汇智网翻译整理，转载请标明出处