AGENTS.md
AI 编码代理的指导格式
AGENTS.md 是一个简单的、开放的格式,用于指导编码代理(AI coding agents),已被超过 20,000 个开源项目使用。它被描述为“代理的 README”,为 AI 编码代理提供上下文和指令。
lightbulb原理
为什么需要 AGENTS.md?
architecture架构
文件结构与组织
psychology设计思想
核心理念与原则
integration_instructions应用场景
兼容性与优势
AGENTS.md 文件示例
AGENTS.md 工作原理
为 AI 编码代理提供专门指导的机制
compare_arrowsREADME.md 与 AGENTS.md 的区别
descriptionREADME.md
- person 面向人类开发者
- lightbulb 项目概述和快速入门
- handshake 贡献指南和规范
- public 项目展示和宣传
smart_toyAGENTS.md
- psychology 面向 AI 编码代理
- build 详细的构建步骤和命令
- rule 代码风格和约定
- developer_mode 开发环境提示和技巧
syncAGENTS.md 与 AI 编码代理的交互流程
AI 编码代理使用 AGENTS.md 的工作流程
发现文件
AI 编码代理首先在项目根目录中查找 AGENTS.md 文件
解析内容
代理解析文件中的指令、约定和配置信息
应用指导
代理根据指导执行代码生成、修改或测试任务
starsAGENTS.md 的核心优势
精确指导
为 AI 编码代理提供精确、详细的项目特定指导,提高代码质量和一致性
提高效率
减少代理理解项目结构和约定的时间,加速开发流程
广泛兼容
一个 AGENTS.md 文件可适用于多种 AI 编码代理和工具
人机协作
使人类开发者与 AI 编码代理能够更有效地协作
lightbulb为什么需要专门的 AGENTS.md?
AGENTS.md 架构设计
文件结构与组织方式
folder_open项目文件结构
典型项目中的 AGENTS.md 位置
share文件交互关系
AGENTS.md 与项目文件的协同工作
README.md
人类开发者阅读
AGENTS.md
AI 编码代理读取
源代码
遵循约定和规范
view_moduleAGENTS.md 核心组件
设置命令
- terminal 依赖安装命令
- play_arrow 开发服务器启动命令
- science 测试运行命令
代码风格
- text_format 缩进和格式规则
- code 命名约定
- architecture 设计模式偏好
开发环境提示
- speed 性能优化技巧
- extension 推荐工具和扩展
- troubleshoot 常见问题解决方案
项目约定
- folder_special 目录结构约定
- merge_type 分支管理策略
- commit 提交消息格式
starAGENTS.md 最佳实践
AGENTS.md 设计思想
为 AI 编码代理量身定制的设计理念
psychology核心设计原则
可预测性
专注性
精确性
开放性
lightbulb设计哲学
AGENTS.md 的设计理念
人机分离
将人类和 AI 编码代理的文档需求分离,各自获得最适合的信息
补充而非替代
AGENTS.md 补充现有文档,而不是替代 README 或其他文档
简洁高效
提供必要的信息,避免冗余,使代理能够高效工作
emoji_objects满足 AI 编码代理需求
结构化信息
AI 编码代理需要结构化、格式一致的信息,AGENTS.md 提供了这种结构
技术细节
提供代理需要的技术细节,如构建命令、测试流程和代码风格
性能优化
减少代理解析和理解项目的时间,提高工作效率
一致性
确保代理生成的代码与项目约定保持一致
互操作性
一个文件适用于多种代理和工具,提高兼容性
可维护性
随着项目发展,易于更新和维护代理指导信息
AGENTS.md 的设计思想体现了以人为本和代理友好的平衡,通过分离人类和代理的信息需求,使两者都能获得最适合的指导,从而提高整个开发流程的效率和质量。
AGENTS.md 应用场景
实际应用与优势
devices兼容多种 AI 编码代理
一个 AGENTS.md 文件适用于多种代理和工具
Codex
OpenAI
Jules
Cursor
Cursor
Factory
Factory
RooCode
RooCode
更多工具
持续增长中
cases实际应用场景
代码生成与修改
构建与测试
调试与修复
文档生成
trending_up核心优势
使用 AGENTS.md 的主要优势
提高效率
减少代理解读项目的时间,加速开发流程
保证质量
确保生成的代码符合项目标准和最佳实践
一致性
保持代码风格和结构的一致性,提高可维护性
团队协作
促进人类开发者与 AI 编码代理的有效协作
tips_and_updates成功案例
AGENTS.md 示例
如何编写有效的 AGENTS.md 文件
codeAGENTS.md 文件示例
典型 AGENTS.md 文件结构
description示例解析
设置命令
设置命令部分提供了项目特定的构建、测试和开发命令,使 AI 编码代理能够准确执行这些任务。这些命令通常包括:
- 依赖安装命令
- 开发服务器启动命令
- 测试运行命令
- 构建和部署命令
这些命令应使用精确的语法,避免歧义,确保代理能够正确执行。
代码风格
代码风格部分定义了项目的编码规范和风格约定,确保 AI 编码代理生成的代码与项目保持一致。常见的约定包括:
- 缩进和格式规则(如使用空格还是制表符)
- 命名约定(如变量、函数和类的命名)
- 语法偏好(如使用单引号还是双引号)
- 设计模式偏好(如函数式编程或面向对象)
这些约定应简洁明了,避免冗长的解释。
开发环境提示
开发环境提示部分提供了优化开发工作流的技巧和建议,帮助 AI 编码代理更高效地工作。这些提示可能包括:
- 项目特定的快捷方式或别名
- 推荐的工具或扩展
- 常见问题的解决方案
- 性能优化技巧
这些提示应实用且具体,提供明确的操作步骤。
项目约定
项目约定部分描述了项目特定的结构和组织约定,帮助 AI 编码代理理解项目的整体架构。这些约定可能包括:
- 目录结构约定
- 文件命名规则
- 组件或模块的组织方式
- 分支管理策略
这些约定应清晰一致,与项目的实际结构保持同步。