AGENTS.md:AI 编码代理的指导格式

AGENTS.md:AI 编码代理的指导格式

AGENTS.md

AI 编码代理的指导格式

AGENTS.md 是一个简单的、开放的格式,用于指导编码代理(AI coding agents),已被超过 20,000 个开源项目使用。它被描述为“代理的 README”,为 AI 编码代理提供上下文和指令。

20k+
开源项目使用
1
简单格式
代理兼容

lightbulb原理

为什么需要 AGENTS.md?

check_circle
README.md 文件是为人类准备的:快速入门、项目描述和贡献指南。
check_circle
AGENTS.md 通过包含编码代理需要的额外、有时是详细的上下文来补充这一点:构建步骤、测试和约定。
check_circle
这些信息可能会使 README 变得杂乱或与人类贡献者无关。

architecture架构

文件结构与组织

folder
AGENTS.md 与 README.md 并存于项目根目录,各自服务不同的受众。
sync_alt
与现有文档和 README 协同工作,而不是替代它们。
settings
包含项目特定的设置命令、代码风格约定和开发环境提示。

psychology设计思想

核心理念与原则

visibility
为代理提供一个清晰、可预测的指令位置。
format_align_left
保持 README 简洁并专注于人类贡献者。
precision_manufacturing
提供精确的、专注于代理的指导,补充现有的 README 和文档。
public
选择一个任何人都可以使用的名称和格式,而不是引入另一个专有文件。

integration_instructions应用场景

兼容性与优势

devices
一个 AGENTS.md 文件可适用于多种代理和工具: OpenAI 的 Codex、Google 的 Jules、Cursor、Factory 和 RooCode 等。
speed
提高编码代理的工作效率,减少理解项目结构的时间。
auto_fix_high
使代理能够更好地遵循项目约定和最佳实践。

AGENTS.md 文件示例

# AGENTS.md ## 设置命令 – 安装依赖:`pnpm install` – 启动开发服务器:`pnpm dev` – 运行测试:`pnpm test` ## 代码风格 – TypeScript 严格模式 – 使用单引号,不使用分号 – 尽可能使用函数式编程模式 ## 开发环境提示 – 使用 `pnpm dlx turbo run where ` 跳转到包,而不是使用 `ls` 扫描。 – 运行 `pnpm install –filter ` 将包添加到工作区,以便 Vite、ESLint 和 TypeScript 可以看到它。 – 使用 `pnpm create vite@latest — –template react-ts` 快速创建带有 TypeScript 检查的 React + Vite 包。
AGENTS.md:AI 编码代理的指导格式 – 原理

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 的工作流程

search
发现文件

AI 编码代理首先在项目根目录中查找 AGENTS.md 文件

parse
解析内容

代理解析文件中的指令、约定和配置信息

integration_instructions
应用指导

代理根据指导执行代码生成、修改或测试任务

starsAGENTS.md 的核心优势

precision_manufacturing
精确指导

为 AI 编码代理提供精确、详细的项目特定指导,提高代码质量和一致性

speed
提高效率

减少代理理解项目结构和约定的时间,加速开发流程

hub
广泛兼容

一个 AGENTS.md 文件可适用于多种 AI 编码代理和工具

diversity_3
人机协作

使人类开发者与 AI 编码代理能够更有效地协作

lightbulb为什么需要专门的 AGENTS.md?

check_circle
AI 编码代理需要比人类更详细、更结构化的项目信息
check_circle
传统 README.md 包含过多对代理无用的信息,如项目背景和宣传内容
check_circle
AGENTS.md 提供了一个专门为代理设计的、可预测的信息源
check_circle
分离人类和代理的文档,使两者都能获得最适合的信息
AGENTS.md:AI 编码代理的指导格式 – 架构

AGENTS.md 架构设计

文件结构与组织方式

folder_open项目文件结构

典型项目中的 AGENTS.md 位置

folder project-root/
description README.md 面向人类的项目概述
smart_toy AGENTS.md 面向 AI 编码代理的指导
folder src/
code index.js
folder tests/
science app.test.js
settings package.json

share文件交互关系

AGENTS.md 与项目文件的协同工作

README.md

人类开发者阅读

AGENTS.md

AI 编码代理读取

arrow_downward
源代码

遵循约定和规范

view_moduleAGENTS.md 核心组件

build

设置命令

提供项目特定的构建、测试和开发命令
  • terminal 依赖安装命令
  • play_arrow 开发服务器启动命令
  • science 测试运行命令
format_paint

代码风格

定义项目的编码规范和风格约定
  • text_format 缩进和格式规则
  • code 命名约定
  • architecture 设计模式偏好
tips_and_updates

开发环境提示

提供优化开发工作流的技巧和建议
  • speed 性能优化技巧
  • extension 推荐工具和扩展
  • troubleshoot 常见问题解决方案
integration_instructions

项目约定

描述项目特定的结构和组织约定
  • folder_special 目录结构约定
  • merge_type 分支管理策略
  • commit 提交消息格式

starAGENTS.md 最佳实践

check_circle
保持简洁明了,避免冗余信息
check_circle
使用一致的格式和结构
check_circle
包含实际可执行的命令示例
check_circle
定期更新以保持与项目同步
check_circle
避免与 README.md 内容重复
check_circle
针对不同代理提供特定指导
AGENTS.md:AI 编码代理的指导格式 – 设计思想

AGENTS.md 设计思想

为 AI 编码代理量身定制的设计理念

psychology核心设计原则

visibility

可预测性

为代理提供一个清晰、可预测的指令位置,使 AI 编码代理能够轻松找到并理解项目特定的指导信息,减少理解成本。
format_align_left

专注性

保持 README 简洁并专注于人类贡献者,将代理需要的详细信息分离到专门的文件中,避免信息过载和混淆。
precision_manufacturing

精确性

提供精确的、专注于代理的指导,补充现有的 README 和文档,确保 AI 编码代理能够准确理解项目约定和最佳实践。
public

开放性

选择一个任何人都可以使用的名称和格式,而不是引入另一个专有文件,促进广泛的采用和互操作性。

lightbulb设计哲学

AGENTS.md 的设计理念

people
人机分离

将人类和 AI 编码代理的文档需求分离,各自获得最适合的信息

extension
补充而非替代

AGENTS.md 补充现有文档,而不是替代 README 或其他文档

auto_awesome
简洁高效

提供必要的信息,避免冗余,使代理能够高效工作

emoji_objects满足 AI 编码代理需求

architecture
结构化信息

AI 编码代理需要结构化、格式一致的信息,AGENTS.md 提供了这种结构

settings
技术细节

提供代理需要的技术细节,如构建命令、测试流程和代码风格

trending_up
性能优化

减少代理解析和理解项目的时间,提高工作效率

sync_alt
一致性

确保代理生成的代码与项目约定保持一致

hub
互操作性

一个文件适用于多种代理和工具,提高兼容性

update
可维护性

随着项目发展,易于更新和维护代理指导信息

AGENTS.md 的设计思想体现了以人为本代理友好的平衡,通过分离人类和代理的信息需求,使两者都能获得最适合的指导,从而提高整个开发流程的效率和质量。

AGENTS.md:AI 编码代理的指导格式 – 应用场景

AGENTS.md 应用场景

实际应用与优势

devices兼容多种 AI 编码代理

一个 AGENTS.md 文件适用于多种代理和工具

smart_toy
Codex

OpenAI

code
Jules

Google

cursor
Cursor

Cursor

precision_manufacturing
Factory

Factory

pets
RooCode

RooCode

add_circle
更多工具

持续增长中

cases实际应用场景

integration_instructions

代码生成与修改

AI 编码代理可以根据 AGENTS.md 中的代码风格和约定,生成符合项目标准的新代码或修改现有代码,确保一致性和质量。
build

构建与测试

代理能够准确执行项目特定的构建命令和测试流程,减少配置错误和构建失败,提高开发效率。
bug_report

调试与修复

当遇到问题时,AI 编码代理可以参考 AGENTS.md 中的开发环境提示和约定,更快地定位和修复问题。
auto_stories

文档生成

代理可以根据 AGENTS.md 中的项目结构和约定,自动生成或更新技术文档,保持文档与代码同步。

trending_up核心优势

使用 AGENTS.md 的主要优势

speed
提高效率

减少代理解读项目的时间,加速开发流程

verified
保证质量

确保生成的代码符合项目标准和最佳实践

sync
一致性

保持代码风格和结构的一致性,提高可维护性

groups
团队协作

促进人类开发者与 AI 编码代理的有效协作

20k+
开源项目使用
5+
兼容代理工具
1
简单格式

tips_and_updates成功案例

check_circle
大型开源项目通过 AGENTS.md 使新贡献者(包括 AI 代理)能够快速上手
check_circle
企业开发团队使用 AGENTS.md 提高代码生成和审查效率
check_circle
教育机构利用 AGENTS.md 帮助学生理解项目结构和编码规范
AGENTS.md:AI 编码代理的指导格式 – 示例

AGENTS.md 示例

如何编写有效的 AGENTS.md 文件

codeAGENTS.md 文件示例

典型 AGENTS.md 文件结构

# AGENTS.md # 设置命令部分 – 提供项目特定的构建、测试和开发命令 ## Setup commandsInstall deps: `pnpm install`Start dev server: `pnpm dev`Run tests: `pnpm test` # 代码风格部分 – 定义项目的编码规范和风格约定 ## Code styleTypeScript strict modeSingle quotes, no semicolons – Use functional patterns where possible # 开发环境提示部分 – 提供优化开发工作流的技巧和建议 ## Dev environment tips – Use `pnpm dlx turbo run where ` to jump to a package instead of scanning with `ls`. – Run `pnpm install –filter ` to add the package to your workspace so Vite, ESLint, and TypeScript can see it. – Use `pnpm create vite@latest — –template react-ts` to spin up a new React + Vite package with TypeScript checks ready. – Check the name field inside each package’s package.json to ensure naming consistency.

description示例解析

build

设置命令

设置命令部分提供了项目特定的构建、测试和开发命令,使 AI 编码代理能够准确执行这些任务。这些命令通常包括:

  • 依赖安装命令
  • 开发服务器启动命令
  • 测试运行命令
  • 构建和部署命令

这些命令应使用精确的语法,避免歧义,确保代理能够正确执行。

format_paint

代码风格

代码风格部分定义了项目的编码规范和风格约定,确保 AI 编码代理生成的代码与项目保持一致。常见的约定包括:

  • 缩进和格式规则(如使用空格还是制表符)
  • 命名约定(如变量、函数和类的命名)
  • 语法偏好(如使用单引号还是双引号)
  • 设计模式偏好(如函数式编程或面向对象)

这些约定应简洁明了,避免冗长的解释。

tips_and_updates

开发环境提示

开发环境提示部分提供了优化开发工作流的技巧和建议,帮助 AI 编码代理更高效地工作。这些提示可能包括:

  • 项目特定的快捷方式或别名
  • 推荐的工具或扩展
  • 常见问题的解决方案
  • 性能优化技巧

这些提示应实用且具体,提供明确的操作步骤。

integration_instructions

项目约定

项目约定部分描述了项目特定的结构和组织约定,帮助 AI 编码代理理解项目的整体架构。这些约定可能包括:

  • 目录结构约定
  • 文件命名规则
  • 组件或模块的组织方式
  • 分支管理策略

这些约定应清晰一致,与项目的实际结构保持同步。

lightbulb编写有效 AGENTS.md 的技巧

check_circle
保持简洁明了,避免冗余信息
check_circle
使用一致的格式和结构
check_circle
包含实际可执行的命令示例
check_circle
定期更新以保持与项目同步
check_circle
避免与 README.md 内容重复
check_circle
针对不同代理提供特定指导

发表评论

人生梦想 - 关注前沿的计算机技术 acejoy.com 🐾 步子哥の博客 🐾 背多分论坛 🐾 知差(chai)网 🐾 DeepracticeX 社区 🐾 老薛主机 🐾