玄同 765大语言模型 (LLM) 开发工程师 | 中国传媒大学 · 数字媒体技术智能交互与游戏设计CSDN · 个人主页 | GitHub · Follow关于作者深耕领域大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调技术栈Python | RAG (LangChain / Dify Milvus) | FastAPI Docker工程能力专注模型工程化部署、知识库构建与优化擅长全流程解决方案「让 AI 交互更智能让技术落地更高效」欢迎技术探讨与项目合作解锁大模型与智能交互的无限可能一、AGENTS.md 诞生背景1.1 问题现状随着 AI 开发工具的快速发展各种基于 VSCode 的 AI 编辑器、插件和 CLI 工具如雨后春笋般涌现。然而这些工具的配置文件管理却存在严重问题配置文件分散不同工具使用不同的配置文件位置和命名方式项目混乱团队协作中使用不同工具会生成多种配置文件维护困难需要为不同工具维护各自的配置规则1.2 主流工具配置文件对比工具配置文件位置格式兼容性Cursor.cursor/rules/多个规则文件仅支持自身Claude CodeCLAUDE.md单个 Markdown 文件仅支持自身Gemini CLIGEMINI.md单个 Markdown 文件仅支持自身RooCode.roo/rules/多个规则文件仅支持自身AGENTS.mdAGENTS.md单个 Markdown 文件跨工具兼容二、AGENTS.md 核心概念2.1 什么是 AGENTS.mdAGENTS.md 是一种开放性倡议旨在创建一个标准化的配置文件用于给 AI 智能体提供上下文信息和操作指南。它具有以下特点厂商中立由 OpenAI、谷歌的 Jules、Cursor、Amp、Factory 等共同参与制定跨平台兼容支持多种 AI 开发工具简单易用标准 Markdown 文件无特定格式要求服务于 AI区别于服务人类的 README.md专门为 AI 智能体设计2.2 AGENTS.md 工作原理支持的工具开发者创建 AGENTS.mdAI 工具加载 AGENTS.md解析配置规则应用到开发流程跨工具统一行为CursorCopilotGemini CLIRooCodeTraeClaude Code三、AGENTS.md 内容结构3.1 基本内容框架AGENTS.md 通常包含以下内容章节内容说明示例项目概述项目基本信息、技术栈、目标React TypeScript Tailwind CSS 网站项目构建和测试命令项目构建、测试、部署命令pnpm run build、pnpm test代码风格指南编码规范、命名约定、格式要求优先使用函数式组件和 Hooks测试说明测试框架、测试策略、覆盖率要求使用 Jest 进行单元测试安全注意事项敏感信息处理、安全最佳实践禁止硬编码 API 密钥其他规则项目特定的额外规则分支管理策略、提交规范3.2 规则扩展方案对于复杂项目可以使用目录结构扩展 AGENTS.md项目根目录/ ├── AGENTS.md # 主配置文件 └── .ai/rules/ # 规则目录 ├── project-architecture.md # 项目架构设计 ├── code-style.md # 代码风格规范 └── security.md # 安全规则在 AGENTS.md 中引用这些规则文件### 开发规则 项目的规则存放于目录 .ai/rules/ 下。 - 项目架构设计请看 [.ai/rules/project-architecture.md](.ai/rules/project-architecture.md) - 代码风格规范请看 [.ai/rules/code-style.md](.ai/rules/code-style.md) - 安全规则请看 [.ai/rules/security.md](.ai/rules/security.md)四、主流工具配置指南4.1 Cursor 配置默认支持Cursor 默认会识别并加载项目中的 AGENTS.md 文件将其视为.cursor/rules的简化替代方案。配置步骤在项目根目录创建 AGENTS.md 文件填写规则内容Cursor 会自动加载并应用这些规则4.2 Copilot 配置试验性支持Copilot 目前处于试验性支持阶段需要手动启用。配置步骤打开 VSCode 设置搜索chat.useAgentsMdFile将其设置为true在项目根目录创建 AGENTS.md 文件4.3 Gemini CLI 配置手动配置需要在设置文件中指定 AGENTS.md 作为上下文文件。配置步骤在项目根目录创建.gemini/settings.json文件添加以下配置{contextFileName:AGENTS.md}在项目根目录创建 AGENTS.md 文件4.4 RooCode 配置自动加载RooCode 默认会自动加载项目中的 AGENTS.md 文件。可选配置打开 VSCode 设置搜索roo-cline.useAgentRules确保其设置为true4.5 Claude Code 配置间接支持Claude Code 本身不支持自动读取 AGENTS.md但可以通过引用实现。配置步骤在项目根目录创建 AGENTS.md 文件在 CLAUDE.md 中添加引用项目概况、规则相关内容请在 AGENTS.md 中维护和查看。4.6 Trae 配置支持方式Trae 作为新一代 AI 开发环境提供了对 AGENTS.md 的原生支持。配置步骤在项目根目录创建 AGENTS.md 文件填写项目规则和配置Trae 会自动识别并应用这些规则五、AGENTS.md 最佳实践5.1 内容编写建议保持简洁明了使用清晰的标题和结构具体明确提供详细的命令和规则实时更新随着项目发展及时更新规则使用 AI 辅助让 AI 帮助编写和维护 AGENTS.md5.2 示例模板# 项目 AGENTS.md ## 项目概述 这是一个使用 React、TypeScript 和 Tailwind CSS 构建的网站项目主要功能包括用户管理、内容展示和数据可视化。 ## 项目指令 - 使用 pnpm run build 构建项目 - 使用 pnpm run test --filter project_name 对指定包运行测试用例 - 在提交前必须运行 pnpm lint 和 pnpm test 并确保全部通过 - 开发环境启动命令pnpm dev ## 代码风格 - 优先使用函数式组件和 Hooks避免使用类组件 - 使用 TypeScript 严格模式确保类型安全 - 代码缩进使用 2 个空格 - 变量命名使用驼峰命名法 - 组件命名使用 PascalCase ## 测试说明 - 使用 Jest 进行单元测试 - 测试文件与被测试文件放在同一目录下命名为 *.test.tsx - 测试覆盖率目标80% 以上 ## 安全注意事项 - 绝不能在前端代码中硬编码任何 API 密钥或敏感凭证 - 所有 API 调用必须通过后端代理 - 密码必须使用 bcrypt 等安全算法加密存储 ## 其他规则 - 分支管理使用 Git Flow 工作流 - 提交规范遵循 Conventional Commits 标准 - 代码审查所有 PR 必须经过至少一名团队成员审查5.3 版本控制建议将 AGENTS.md 纳入版本控制与项目代码一起提交和更新在团队协作中统一使用 AGENTS.md定期检查和优化规则内容六、常见问题与解决方案6.1 工具不支持 AGENTS.md问题某些工具不支持自动读取 AGENTS.md解决方案参考 Claude Code 的方式在工具的配置文件中引用 AGENTS.md联系工具开发者建议添加对 AGENTS.md 的支持暂时保持双配置逐步过渡到 AGENTS.md6.2 规则冲突问题不同工具对同一规则的理解不同解决方案在 AGENTS.md 中明确说明规则的适用范围为特定工具添加专用规则章节测试不同工具的规则执行效果调整规则表述6.3 复杂规则管理问题项目规则复杂单个 AGENTS.md 文件难以管理解决方案使用.ai/rules/目录结构扩展规则在 AGENTS.md 中使用引用链接按功能模块组织规则文件七、未来展望7.1 生态系统发展AGENTS.md 作为一个开放标准正在不断发展壮大工具支持越来越多的 AI 开发工具开始支持 AGENTS.md社区贡献开发者可以通过 PR 改进标准功能扩展未来可能支持更复杂的规则定义和工具集成7.2 行业影响标准化推动 AI 开发工具配置的标准化效率提升减少配置文件管理的时间和精力协作改善团队成员可以使用不同工具但共享相同配置最佳实践传播通过标准化配置促进开发最佳实践的传播八、总结AGENTS.md 的出现为我们提供了一个优雅的解决方案用以应对 AI 工具多样化带来的配置文件混乱问题。通过使用 AGENTS.md我们可以统一配置使用单一文件管理所有 AI 工具的配置跨平台兼容支持多种主流 AI 开发工具简化维护减少配置文件的数量和复杂性提高效率让 AI 工具更好地理解和适应项目需求在团队协作和个人开发中AGENTS.md 都能为我们带来显著的好处。我倡导所有开发者都去维护一份标准化的 AGENTS.md并与项目代码一起版本控制让 AI 辅助开发变得更加高效和有序。参考链接AGENTS.md 官方倡议Cursor 官方文档Copilot 官方文档Gemini CLI 文档RooCode 官方文档Trae 官方文档