AGENTS.md 使用指南：给 AI 编程助手一份"项目说明书"

什么是 AGENTS.md

AGENTS.md 是一个简单的开放格式，用来指导 AI 编程助手（Coding Agent）在你的项目中工作。你可以把它理解成「给 AI 看的 README」：

• README.md 是写给人类看的项目说明；
• AGENTS.md 是写给 AI Agent 看的项目指令，包含构建命令、编码规范、测试要求、安全注意事项等 Agent 需要知道的一切上下文。

它没有任何强制字段，就是标准 Markdown，用什么标题、写什么内容完全自由。Agent 在干活时会自动读取仓库根目录（以及上层目录）里的 AGENTS.md。

目前 AGENTS.md 由 Anthropic 等团队推动，已交由 Linux Foundation 下的 Agentic AI Foundation 维护，是一个不受单一厂商控制的开放标准。主流工具基本都支持：Claude Code、Codex、Cursor、Amp、Google Jules、Gemini CLI、Aider、CodeBuddy 等。

为什么需要它

很多团队吐槽过 AI 编程助手：明明教过项目规范，下次还犯同样的错；让它跑个测试，命令都能瞎编一个；改完代码直接往 main 一推了事。

这些问题的根源，往往不是 AI 不够聪明，而是它缺少一份「项目说明书」——那些不会写在代码里、但会直接决定代码对错的隐性约束：

• 为什么用 pnpm 而不是 npm（可能有历史原因）；
• 数据库迁移必须用哪个命令（AI 可能会瞎编）；
• 架构上的硬约束（比如禁止跨层调用）。

把这些约定写进 AGENTS.md 之后，AI 每次开工前都会先读一遍，犯错概率大幅下降。而且它是跨工具的：换一个 AI 编程工具，这份说明依然有效，不用重复配置。

如何创建一个 AGENTS.md

在仓库根目录新建一个 AGENTS.md 文件即可，内容就是普通 Markdown。

touch AGENTS.md

大多数 Coding Agent 都能帮你生成草稿——比如直接对 Claude Code 说「帮我生成一个 AGENTS.md」。但要注意：自动生成的内容往往「大而全」，不够精准，研究表明直接用自动生成的版本反而可能降低 AI 表现。正确做法是把它当作草稿，人工审核并精简。

推荐内容结构（六个模块）

不需要一次写全，建议从最有用的模块开始。下面是实践中投入产出比最高的结构：

1. 项目概览（3–5 行）

让 AI 快速建立项目心智模型，但不用写太多。

## 项目概览
- 技术栈：Next.js 15 + TypeScript + tRPC + Drizzle ORM
- 数据库：PostgreSQL 16
- 部署：前端 Vercel，后端 Railway

2. 常用命令（投入产出比最高）

AI 最容易被「瞎编命令」坑，把真实命令列清楚。

## 常用命令
- 安装依赖：pnpm install（禁止使用 npm 或 yarn）
- 启动开发：pnpm dev
- 运行测试：pnpm test
- 代码检查：pnpm lint（提交前必须通过）
- 类型检查：pnpm typecheck

3. 架构约束

告诉 AI 哪些事情绝对不能做。

## 架构约束
- 分层依赖：domain → application → infrastructure，不能反向依赖
- 数据库操作必须通过 Service 层，不能在路由里直接调 ORM
- 所有时间字段统一用 UTC，时区转换交给前端处理

4. 编码规范（只写 AI 容易犯、linter 抓不到的）

不要把整个编码规范抄进去，只写 AI 反复犯的错误。

## 编码规范
- 使用命名导出，禁止默认导出
- 错误处理用 Result 模式，Service 层不能 throw
- API 响应统一包装：{ data, error, meta }

5. 文档索引

把详细文档的路径告诉 AI，需要时用 @path 自己去读，而不是把所有细节塞进 AGENTS.md。

## 文档索引
- 架构决策记录：docs/adr/
- 数据库设计：docs/schema.md
- 认证流程：docs/auth-flow.md

6. Git 工作流

这个很多人会忽略，但一旦出错就很麻烦。

## Git 工作流
- 分支命名：feat/xxx、fix/xxx、refactor/xxx
- 提交信息：遵循 Conventional Commits 格式
- 禁止直接提交到 main 分支
- 提交前必须通过 lint 和类型检查

一个可直接套用的模板

把下面这份复制进 AGENTS.md，替换占位符即可：

# AGENTS.md

## 项目概览
- <技术栈>
- <核心依赖>
- <部署方式>

## 常用命令
- 安装依赖：<命令>
- 启动开发：<命令>
- 运行测试：<命令>
- 代码检查：<命令>（提交前必须通过）
- 类型检查：<命令>

## 架构约束
- <分层依赖规则>
- <禁止项>

## 编码规范
- <只写 AI 容易犯、linter 抓不到的错>

## 文档索引
- <详细文档路径>

## Git 工作流
- 分支命名：<规则>
- 提交信息：<规则>
- <禁止直推 main 等>

## 已知陷阱
- <随着使用，这里会自然增长>

小技巧：建议保留一个「已知陷阱」小节。随着使用，每次 AI 犯错就把正确的规则写进去，这份文件会越用越准。

与 CLAUDE.md / .cursorrules 的区别

文件	归属	特点
CLAUDE.md	Claude Code 专有	成熟稳定，支持 @import 语法、Hooks 机制
.cursorrules / .cursor/rules/*.mdc	Cursor 专有	支持 glob 匹配、条件应用，但只能 Cursor 用
AGENTS.md	开放标准	纯 Markdown、零学习成本、跨工具通用

如果你团队只用一种工具，CLAUDE.md 完全够用；但一旦混用多种工具，维护多份重复配置会很痛苦。

推荐做法：让 AGENTS.md 成为单一真相源（source of truth）。 其他工具的入口文件做成「薄壳」：

# 让 Claude Code 读取 AGENTS.md
# 在 CLAUDE.md 里只写一行：
@AGENTS.md

# 或用软链兼容旧版本
ln -s AGENTS.md CLAUDE.md

Gemini CLI 可在 .gemini/settings.json 配置：{ "context": { "fileName": "AGENTS.md" }}；Aider 可在 .aider.conf.yml 配置 read: AGENTS.md。

嵌套与分层（大型 monorepo）

当项目复杂到一定程度，单个 AGENTS.md 会力不从心。这时候可以分层：

• 根目录放全局规则（精简到 100 行以内）；
• 各模块/子目录放自己的 AGENTS.md，Agent 在该目录工作时会自动读取最近的那个，子目录的优先；
• 详细文档放 docs/，AGENTS.md 里只放索引。

OpenAI 自己的仓库就有 88 个 AGENTS.md 文件——这正是「每个子目录写自己的小 AGENTS.md」被原生支持的工作模式。

最佳实践

1. 写成导航图，不要写成百科全书。 控制在 200 行以内。给 AI 一张「组织架构图」，而不是把公司所有文件倒给它。
2. 只写 AI 自己推断不出来的内容。 框架、目录结构、linter 能管的风格，AI 看代码就知道，不用写；会写出错误代码的硬性约束才写。
3. 从实际错误迭代。 不要试图一次写完。AI 犯了一个错，就往 AGENTS.md 加一条规则。每一条都来自真实错误，针对性极强。
4. 用命令式、明确的措辞。 写「禁止默认导出」，而不是「我们建议在可能的情况下尽量使用命名导出，因为这有助于 tree-shaking」。AI 不需要知道为什么，只需要知道规则是什么。
5. 自动生成只是草稿。 用 /init 之类生成的版本要人工审核精简，别直接交差。

常见误区

• 自动生成后就不管了 — 生成的内容大而全，需要裁剪。
• 写得越多越好 — 每一行都占 AI 的上下文窗口，写太多会让真正重要的规则被淹没。
• 写成给人看的优美文档 — AGENTS.md 是给 AI 看的，不需要优美的背景铺垫，直接给规则。

写在最后

AGENTS.md 不是写完就不管的文档，而是一个需要持续维护的「活文档」。最好的维护方式就是：每次 AI 犯错，不要只在对话里纠正它，而是把正确的规则写进 AGENTS.md——这样下次它就不会再犯同样的错。

从一个精简的模板开始，比追求完美更重要。今天就给你的项目加上一份吧。