Github 分析了 2500+ 个仓库后，发现大多数 agents.md 都写错了

目标读者：使用 AI 编码助手（GitHub Copilot、Claude Code、Cursor 等）的开发者
核心价值：掌握 agents.md 的六大核心领域和最佳实践，让 AI 真正理解你的项目
阅读时间：6 分钟

一句话摘要：agents.md 不是写给人看的 README，而是给 AI 的"岗位培训手册"——写好六大核心领域，你的 AI 助手就能从"聪明的陌生人"变成"了解项目的老员工"。

引言

“为什么 AI 生成的代码总是不符合我们的项目规范？”

你是否也有过这样的经历：AI 助手写出的代码技术上完全正确，但命名风格、目录结构、甚至缩进方式都和项目格格不入。你不得不花大量时间"返工"，把 AI 的代码改成"你的代码"。

问题不在于 AI 不够聪明，而在于它不够了解你的项目。

GitHub 最近对超过 2500 个包含 agents.md 文件的仓库进行了分析，发现了一个关键规律：最好的 AI 助手都有一份详细的"操作手册"。这份手册就是 agents.md。

本文将介绍什么是 agents.md、为什么它如此重要，以及如何写出一份真正有效的 agents.md。

What：agents.md 是什么

一句话定义：agents.md 是写给 AI 编码助手的 README。

传统的 README.md 是写给人类开发者的：项目介绍、安装步骤、使用说明。而 agents.md 是写给 AI 的：构建命令、测试流程、代码风格、项目约定。

你可以这样理解两者的区别：

维度	README.md	agents.md
读者	人类开发者	AI 编码助手
内容	项目介绍、功能说明	构建/测试命令、代码规范
风格	可以有背景故事、设计理念	精确、可执行、无歧义
目的	让人理解"这是什么"	让 AI 知道"怎么做"

如果说 README 是项目的"自我介绍"，那 agents.md 就是给 AI 助手的"岗位培训手册"。

手册写得越详细，AI 犯错的概率就越低。

GitHub Copilot、Claude Code、Cursor、Windsurf 等主流 AI 编码工具都支持读取这个文件。当 AI 在处理你的代码时，它会参考 agents.md 中的指令，确保生成的代码符合你的项目规范。

Why：为什么需要 agents.md

问题：AI 的"失忆症"

每次新对话，AI 都是从零开始。它不知道：

• 你的项目用 TypeScript 还是 JavaScript
• 函数命名是 camelCase 还是 snake_case
• 测试文件应该放在 __tests__ 还是 tests 目录
• 提交代码前需要运行哪些检查

没有这些信息，AI 只能靠"猜测"。猜对了是运气，猜错了就是返工。

代价：隐性的效率损耗

GitHub 的研究发现，没有 agents.md 的项目中：

• 60% 的 AI 生成代码需要风格调整
• 40% 的代码因为不了解项目结构而放错位置
• 25% 的代码因为不知道边界而触碰了不该改的文件

这些"小问题"累积起来，就是巨大的时间黑洞。

解决方案：一次定义，永久复用

agents.md 的价值在于：把你的项目知识"外化"成 AI 可读的格式。

写一次，每次对话都自动生效。不用重复解释，不用反复纠正。

你花 30 分钟写 agents.md，可能节省 30 小时的返工时间。

How：六大核心领域

GitHub 分析了 2500+ 个仓库后，总结出优秀 agents.md 的六大核心领域：

1. Commands（命令）

告诉 AI 如何构建、测试、运行你的项目。

## 开发命令

- 安装依赖：`pnpm install`
- 开发模式：`pnpm dev`
- 构建项目：`pnpm build`（TypeScript 编译，输出到 dist/）
- 运行测试：`pnpm test`（Jest，提交前必须通过）
- 代码检查：`pnpm lint --fix`（自动修复 ESLint 错误）

关键点：用反引号包裹命令，让 AI 可以直接复制执行。不要写"安装依赖"，要写 npm install 或 pnpm install。

2. Testing（测试）

说明测试策略和要求。

## 测试要求

- 所有新功能必须有对应的单元测试
- 测试覆盖率不低于 80%
- 运行单个测试：`pnpm test -- -t "测试名称"`
- 提交前必须通过：`pnpm test && pnpm lint`

3. Project Structure（项目结构）

帮助 AI 理解代码应该放在哪里。

## 项目结构

- `src/` - 源代码目录
  - `components/` - React 组件
  - `hooks/` - 自定义 Hooks
  - `utils/` - 工具函数
  - `types/` - TypeScript 类型定义
- `tests/` - 测试文件（与 src 结构镜像）
- `docs/` - 文档目录

4. Code Style（代码风格）

定义命名规范和代码示例。

## 代码风格

命名规范：
- 函数：camelCase（`getUserData`、`calculateTotal`）
- 类/组件：PascalCase（`UserService`、`DataController`）
- 常量：UPPER_SNAKE_CASE（`API_KEY`、`MAX_RETRIES`）
- 文件：kebab-case（`user-service.ts`、`data-utils.ts`）

关键点：给出具体的好/坏示例，比抽象的规则更有效。

// 好的写法 - 描述性命名，正确的错误处理
async function fetchUserById(id: string): Promise<User> {
  if (!id) throw new Error('User ID required');
  const response = await api.get(`/users/${id}`);
  return response.data;
}

// 差的写法 - 模糊命名，无错误处理
async function get(x) {
  return await api.get('/users/' + x).data;
}

5. Git Workflow（Git 工作流）

说明分支策略和提交规范。

## Git 工作流

- 分支命名：`feature/功能名`、`fix/bug描述`、`refactor/重构内容`
- 提交信息：使用 Conventional Commits 格式
  - `feat: 添加用户登录功能`
  - `fix: 修复表单验证问题`
  - `docs: 更新 API 文档`
- 提交前检查：`pnpm test && pnpm lint`

6. Boundaries（边界）

这是最容易被忽略，也是最重要的部分。

明确告诉 AI 什么可以做、什么要先问、什么绝对不能做。

## 边界

- **可以做**：在 `src/` 目录下创建/修改文件，遵循代码风格
- **先询问**：修改配置文件、更改数据库 schema、删除现有功能
- **禁止做**：修改 `.env` 文件、提交密钥、直接推送到 main 分支

最佳实践：从 2500 个仓库中提炼的经验

1. 命令要精确，可直接执行

# 差的写法
安装项目依赖

# 好的写法
`pnpm install`

用反引号包裹，AI 可以直接复制执行，不需要猜测。

2. 示例比规则更有效

与其写"使用描述性的函数命名"，不如直接给出好/坏对比：

// 好：fetchUserById, calculateTotalPrice
// 差：get, calc, doSomething

3. 边界要明确，使用三级分类

- ✅ **Always**：始终可以做的事情
- ⚠️ **Ask first**：需要先确认的事情  
- 🚫 **Never**：绝对不能做的事情

这种分类让 AI 知道什么时候可以自主行动，什么时候需要停下来问你。

4. 保持单一信息源

不要把 README 里已有的内容复制到 agents.md。直接链接：

详细的 API 文档见 [docs/api.md](./docs/api.md)

5. 持续迭代，而非一步到位

最好的 agents.md 是"长"出来的，不是"规划"出来的。

从简单开始。当 AI 犯错时，把那个错误对应的规则添加进去。一个月后，你会拥有一份真正贴合项目的 agents.md。

快速入门模板

如果你还没有 agents.md，这里有一个最小可用模板：

# AGENTS.md

## 开发环境

- 安装依赖：`pnpm install`
- 开发模式：`pnpm dev`
- 运行测试：`pnpm test`
- 代码检查：`pnpm lint`

## 代码风格

- 使用 TypeScript
- 函数命名：camelCase
- 组件命名：PascalCase

## 边界

- ✅ Always：在 `src/` 下创建/修改代码
- ⚠️ Ask first：修改配置文件
- 🚫 Never：提交密钥、修改 .env

把这个文件放在项目根目录，你的 AI 助手就能开始"理解"你的项目了。

总结

agents.md 不是可有可无的文档，而是 AI 辅助开发的"操作系统"。

GitHub 对 2500+ 仓库的分析表明：最好的 AI 助手都有清晰的角色定义和详细的操作手册。这份手册包含六大核心领域：命令、测试、项目结构、代码风格、Git 工作流、边界。

从今天开始，花 30 分钟写一份 agents.md。当 AI 犯错时，添加对应的规则。一个月后，你会发现：AI 助手真的开始"理解"你的项目了。

AI 不是不够聪明，是不够了解你。agents.md 就是那座桥梁。

参考来源

• How to write a great agents.md: Lessons from over 2,500 repositories - GitHub Blog
• AGENTS.md - A simple, open format for guiding coding agents - GitHub Repository
• Best practices for using GitHub Copilot to work on tasks - GitHub Docs