25-AGENTS.md最佳实践

25 · AGENTS.md 最佳实践

概述

前面三篇文章详细介绍了 AGENTS.md 的机制、高级用法和配置灵活性。这一篇，我们将回归到最本质的问题：怎样写出能让 AI 真正高效工作的 AGENTS.md？

本文不是理论的堆砌，而是从真实踩坑经验中提炼出来的实战规则。这些规则来自大量 AGENTS.md 的编写、调试和迭代过程——既有成功的经验，也有痛苦的教训。

核心原则：写给 AI 看，不是写给人看

AGENTS.md 最常见的错误是把它写成一份面向人类的"团队文化手册"。但实际上，AGENTS.md 的唯一读者是 AI 编程助手。这意味着你需要调整写作方式：

面向 AI 的写作原则：

• 指令要精确：AI 喜欢精确、无歧义的陈述。不要说"代码要写好"，要说"所有函数必须有类型注解，返回类型必须显式声明"。
• 避免修辞和情感：不需要"我们坚信代码质量是团队的基石"这样的空洞表述。直接说"测试覆盖率必须 ≥ 80%"。
• 使用列表和层级结构：Markdown 的列表（- 或 1.）和标题（##、###）对 AI 解析特别友好。AI 相比段落文本更能准确解析结构化内容。
• 命令式语气：使用祈使句（“必须”、“应该”、“禁止”）而不是描述句（“我们倾向于…”）。

哪些内容该写

1. Codex 反复踩过的坑

这是 AGENTS.md 最高价值的内容之一。当你或你的团队在使用 Codex 开发时，如果发现 AI 反复在同一个问题上犯错，就把这个教训记录下来。

示例：

## 常见陷阱（重要）
- **不要使用已废弃的 API**：本项目曾多次踩坑 axios 旧版 API。
  请使用 axios@1.x 的 API 格式，不要使用 .then() 链式调用。
- **数据库迁移必须用 Prisma**：禁止直接修改数据库表结构。
  所有 schema 变更必须通过 `prisma migrate dev` 生成迁移文件。
- **时区处理**：后端所有时间存储为 UTC，前端展示时转换为用户时区。
  AI 曾多次在时区转换中引入 bug。

这种"踩坑记录"对 AI 特别有效，因为它直接告诉 AI"这个坑我们之前踩过了，你别再踩"。

2. 项目特定约束

AI 不自动知道项目的特殊约定。如果你不告诉它，它可能会按照自己的"最佳实践"生成与项目完全不符的代码。

示例：

## 项目特定约束
- 本项目使用 pnpm（不是 npm/yarn），安装依赖使用 `pnpm add`
- 不要安装新的依赖包，除非在 Issue 中讨论过
- 项目中所有 React 组件使用 `function` 声明，禁止使用 `const Component = () => {}`
- API 路由使用 `/api/v1/` 前缀
- 错误处理使用统一的 `AppError` 类，禁止直接 `throw new Error()`

3. 构