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()`
