AGENTS.md实战：10个顶级项目教你怎么写

简瑞_Jerry
1,270 阅读26分钟

AGENTS.md实战：10个顶级项目教你怎么写

深度解析AutoGPT、LangChain等GitHub Top 10项目的AGENTS.md配置，提供可直接使用的AI生成工具

前言

在上一篇文章《告别配置地狱：AGENTS.md如何统一AI编程规则》中，我们介绍了AGENTS.md的基本概念和它在解决AI编程工具配置碎片化中的价值。

但理解概念只是第一步，更重要的是：如何为自己的项目编写一份高质量的AGENTS.md？

这篇文章将通过分析GitHub上Star数最高的10个包含AGENTS.md的顶级项目（AutoGPT、Transformers、LangChain、Dify、Ant Design等），提炼出核心的编写模式和最佳实践。更重要的是，我们会提供一套经过实战验证的AI生成提示词（快速跳转），让你能在几分钟内为任何项目创建专业的AGENTS.md配置文件。

AGENTS.md应该包含什么

通过分析GitHub上Star数最高的10个包含AGENTS.md的开源项目（AutoGPT 179k⭐、Transformers 151k⭐、LangChain 117k⭐、Dify 116k⭐、Ant Design 96k⭐等），我们提炼出AGENTS.md的5大核心模块：

项目基本信息

让AI助手快速了解项目类型、技术栈和整体架构。

来自 Dify 的示例

## Project Overview
Dify is an open-source platform for developing LLM applications with an intuitive interface combining agentic AI workflows, RAG pipelines, agent capabilities, and model management.

The codebase is split into:

- Backend API (/api): Python Flask application organized with Domain-Driven Design
- Frontend Web (/web): Next.js 15 application using TypeScript and React 19
- Docker deployment (/docker): Containerized deployment configurations

开发命令

具体的、可直接执行的命令，而非抽象描述。

来自 Dify 的示例

## Backend Workflow

- Run backend CLI commands through `uv run --project api <command>`.

- Backend QA gate requires passing `make lint`, `make type-check`, and `uv run --project api --dev dev/pytest/pytest_unit_tests.sh` before review.

- Use Makefile targets for linting and formatting; `make lint` and `make type-check` cover the required checks.

代码规范

项目特有的编码约定和风格要求。

来自 LangChain 的示例

## Core Development Principles

### 1. Maintain Stable Public Interfaces ⚠️ CRITICAL

**Always attempt to preserve function signatures, argument positions, and names for exported/public methods.**

**Before making ANY changes to public APIs:**

- Check if the function/class is exported in `__init__.py`
- Look for existing usage patterns in tests and examples
- Use keyword-only arguments for new parameters: `*, new_param: str = "default"`
- Mark experimental features clearly with docstring warnings

测试策略

测试框架、运行方式和质量要求。

来自 Dify 的示例

## Testing & Quality Practices

- Follow TDD: red → green → refactor.
- Use `pytest` for backend tests with Arrange-Act-Assert structure.
- Enforce strong typing; avoid `Any` and prefer explicit type annotations.
- Write self-documenting code; only add comments that explain intent.

项目特有约定

区分项目的独特规范和工作流程。

来自 Bun 的示例

## Important Development Notes

1. **Never use `bun test` or `bun <file>` directly** - always use `bun bd test` or `bun bd <command>`. `bun bd` compiles & runs the debug build.
2. **All changes must be tested** - if you're not testing your changes, you're not done.
3. **Get your tests to pass**. If you didn't run the tests, your code does not work.

编写原则：三个核心要点

具体胜过抽象

AI助手需要具体的指令，而非模糊的描述。

  • ❌ "遵循良好的代码规范"

  • ✅ "使用2空格缩进，变量名采用camelCase，常量使用UPPER_SNAKE_CASE"

  • ❌ "确保代码质量"

  • ✅ "npm test 运行单元测试，npm run lint 检查代码风格，覆盖率要求>80%"

可执行性优先

每个命令都应该可以直接复制运行，每个规则都应该可以直接应用。

Bun: "Never use bun test or bun <file> directly - always use bun bd test or bun bd <command>"

Transformers: "After making changes, you should usually run make fixup to ensure any copies and modular files are updated"

LangChain: "Use keyword-only arguments for new parameters: *, new_param: str = 'default'"

这些都是具体的、可执行的指令，AI助手能够直接理解和应用。

突出项目特色

通用的开发规范放在团队文档中，AGENTS.md重点说明项目独特的约定。

不同项目会强调各自独特的工作方式：

Transformers: "Functions or entire classes can have a comment at the top like this: # Copied from transformers.models.llama.modeling_llama.rotate_half"

Ant Design: Props命名要求使用完整名称而非缩写，初始化属性使用 default + PropName，面板开启使用 open 而非 visible

PyTorch: "This is the only AGENTS.md, there are no recursive AGENTS.md"

针对不同项目类型的侧重点：

项目类型核心关注点典型代表
开源库API稳定性、向后兼容、发布流程Transformers、Ant Design
Web应用环境配置、架构说明、部署流程AutoGPT、Dify
开发工具构建优化、平台兼容、调试技巧Bun、PyTorch

使用AI生成AGENTS.md

基于对Top 10顶级项目的深度分析，我们提炼出一套经过实战验证的AI生成提示词。

快速开始：Trae和Cursor用户可以直接一键导入，无需复制粘贴

Trae用户 - 一键导入Agent

点击链接即可直接导入配置好的AGENTS.md生成Agent：

Cursor用户 - 一键导入Prompt

点击任一链接，自动在Cursor中打开配置好的生成提示词：

其他AI工具用户

如果使用Claude、ChatGPT等其他AI工具，可以复制下面的标准版提示词使用。

标准版提示词（适合大多数项目）

你是AGENTS.md生成专家，基于GitHub Top 10开源项目（AutoGPT、Transformers、LangChain、Dify等）的最佳实践，为我的项目生成专业的AGENTS.md配置文件。

## 生成要求

### 核心原则
1. **具体胜过抽象** - 提供具体命令而非模糊描述
2. **可执行性优先** - 每个命令都能直接运行
3. **突出项目特色** - 重点说明项目独特的约定和工具

### 必须包含
- **项目概述**：项目类型、核心功能、技术栈、架构说明
- **开发命令**：安装、启动、测试、构建、检查的具体命令（带包管理器）
- **项目结构**：核心目录说明，重要模块职责
- **代码规范**：命名约定、风格要求、项目特有的编码标准
- **测试策略**：测试框架、运行命令、覆盖率要求

### 格式规范
- 使用Markdown格式
- 命令使用代码块标注，如 `npm install`
- 重要提示使用加粗，如 **关键**
- 严重警告使用 ⚠️ 标记
- 目录结构使用代码块展示

### 质量标准
✅ 优秀实践：
- 具体命令：`pytest tests/` 而非 "运行测试"
- 清晰结构：按重要性排序，常用信息在前
- 项目特色：明确说明与其他项目不同的地方

❌ 避免问题：
- 模糊表述："遵循良好规范"、"确保代码质量"
- 通用内容：千篇一律的模板文字
- 过度复杂：冗长说明和深层嵌套

## 我的项目信息

[在这里粘贴你的项目信息：
- 项目类型和主要功能
- 技术栈（语言、框架、数据库）
- package.json、requirements.txt等配置文件
- 项目特有的工具和约定]

## 输出格式

请直接生成AGENTS.md文件内容，从 `# AGENTS.md` 标题开始。

高级版提示词（针对特定项目类型）

如果你的项目属于以下类型，可以在标准版基础上追加特定要求：

## 项目类型：开源库（如React组件库、npm包）

额外关注：
- **API稳定性**：如何保持函数签名不变，新参数使用策略
- **向后兼容**：版本管理和breaking change处理
- **贡献指南**：代码审查流程、PR规范、发布流程
- **文档维护**：API文档更新要求

参考示例：Transformers的"Copied from"机制、Ant Design的命名规范

## 项目类型：Web应用（如React/Vue应用、Node.js后端）

额外关注：
- **环境配置**：开发/生产环境差异，环境变量管理
- **部署流程**：构建命令、部署步骤、容器化配置
- **服务架构**：前后端分离、微服务、数据流说明
- **数据库配置**：迁移脚本、连接配置

参考示例：Dify的DDD架构说明、AutoGPT的Docker配置

## 项目类型：开发工具（如CLI工具、构建工具）

额外关注：
- **构建优化**：编译配置、性能优化技巧
- **平台兼容**：跨平台注意事项、平台特定命令
- **调试技巧**：debug模式启动、日志管理
- **特殊限制**：环境要求、已知问题、避免事项

参考示例：Bun的"Never use bun test directly"、PyTorch的环境说明

## 项目类型：Monorepo（多包项目）

额外关注：
- **包管理**：工作空间配置（pnpm、yarn、lerna、nx）
- **依赖关系**：跨包依赖、共享包使用
- **构建流程**：独立构建、批量构建、增量构建
- **测试策略**：包级测试、集成测试

参考示例：LobeChat的packages结构、多包测试命令

快速使用三步骤

第1步：收集项目信息

  • 项目根目录的package.json、requirements.txt、go.mod等
  • README.md中的技术栈说明
  • 常用的开发命令（从package.json的scripts或Makefile）
  • 团队内部的特殊约定

第2步：选择合适的提示词

  • 一般项目：使用标准版提示词
  • 特定类型：标准版 + 对应的高级版追加内容

第3步：生成和优化

  1. 将提示词和项目信息复制到AI工具
  2. 生成初版AGENTS.md
  3. 验证所有命令可执行性
  4. 补充AI可能遗漏的项目特有约定
  5. 让团队review并持续更新

常见问题快速解答

文件位置和长度

Q: AGENTS.md应该放在哪里？

A: 项目根目录，与README.md同级。AI助手会优先在这里查找。

Q: 文件应该多长？

A: 建议200-500行。太短缺乏必要信息，太长影响AI解析效率。PyTorch的AGENTS.md只有20行，Ant Design有400多行，根据项目复杂度调整。

高级场景处理

Q: 大型项目如何组织？

A: 采用分层方式：

# AGENTS.md（根目录）

## 项目概述
[整体介绍]

## 核心模块
- 用户服务：`services/user/AGENTS.md`
- 订单服务：`services/order/AGENTS.md`

## 通用规范
[所有模块共享的规范]

总结

通过分析GitHub上Star数最高的10个包含AGENTS.md的开源项目，本文提炼出AGENTS.md编写的核心方法论。

AGENTS.md的本质是AI助手理解项目的"说明书"，而非传统的人类文档。一份高质量的AGENTS.md能让AI准确执行开发命令、理解项目特有的编码约定，从而生成符合项目实际规范的代码。

三个核心原则贯穿整个编写过程：

  • 具体胜过抽象：提供可执行的命令而非模糊描述
  • 可执行性优先：每个指令都能直接应用
  • 突出项目特色：重点说明项目独特的约定

本文提供了经过实战验证的生成提示词工具，涵盖通用项目的标准版本，以及针对开源库、Web应用、开发工具、Monorepo等特定场景的高级版本。这些提示词基于AutoGPT、Transformers、LangChain、Dify、Ant Design等顶级项目的实际配置提炼而成。

配合上篇文章《告别配置地狱：AGENTS.md如何统一AI编程规则》中介绍的设计理念和跨工具兼容性，AGENTS.md正在成为AI编程时代项目配置的统一标准。

写在最后

如果你已经为自己的项目创建了AGENTS.md，欢迎在评论区分享使用体验：

  • 你的项目类型是什么？（开源库/Web应用/工具/Monorepo）
  • 使用了哪个AI工具？（Cursor/Trae/Claude/ChatGPT）
  • AGENTS.md给你的开发带来了哪些改变？

遇到问题？ 如果在编写或使用AGENTS.md时遇到困难，也可以在评论区提问，我会尽力解答。

想深入了解？ 如果你对AI编程工具或AI应用实战感兴趣，可以关注我的AI应用实战专栏，持续更新技术深度文章。

最后，如果这篇文章对你有帮助，别忘了点赞和收藏，让更多开发者了解AGENTS.md这个统一的AI编程配置标准。

avatar
文章
阅读
粉丝