AGENTS.md：你的AI代码助手，需要一份"项目说明书"

🔢 前言

Hello~大家好，我是秋天的一阵风

最近看到不少人吐槽AI编程助手：明明教过它项目规范，下次还是犯同样的错误；让它跑个测试，命令都能瞎编一个出来；改完代码往main分支一推了事...

这些问题的根源，不是AI不够聪明，而是它缺少一份"项目说明书"。

这篇文章就来聊聊AGENTS.md------这个正在成为AI编程标配的配置文件，到底该怎么用好它。

一、AI为什么会"失忆"

用过AI编程助手的同学应该都有这个体验：同一个模型，换个会话就像换了个人似的。上一轮教它的规矩，下一轮全忘光。

这不是bug，而是大语言模型的天然特性------它本质上是无状态的。每次对话都是独立的，没有跨会话的记忆能力。

打个比方：你每天都在带一个新来的实习生，而且这个实习生每天早上都会失忆。你昨天教他"我们项目用pnpm不用npm"，今天他又会问"用npm还是yarn"。

AGENTS.md要解决的就是这个问题------把项目的关键信息写成文件，让AI每次启动时自动读取，相当于给这个"失忆实习生"装一个外部记忆。

---

二、AGENTS.md是什么来头

这个概念最早是 Anthropic在 Claude Cod里推的，当时叫CLAUDE.md。后来各家AI编程工具都跟进了自己的版本，一度五花八门：

• Claude Code用CLAUDE.md
• Cursor用.cursorrules或.cursor/rules/
• Copilot用.github/copilot-instructions.md
• Gemini CLI用GEMINI.md
• Cline用.clinerules

这种碎片化很头疼------同一个项目，换不同工具就得维护不同配置文件。

2025年5月，OpenAI牵头把大家拉到一起，统一用AGENTS.md这个名字。 现在这个格式已经由Linux Foundation托管，GitHub上有超过6万个开源项目在用。

• Claude Code虽然还保留CLAUDE.md这个名字，但内容和AGENTS.md通用，一个软链接就能搞定兼容问题。

---

三、它和README.md有什么不同

有人可能会问：我已经有README.md了，为什么还要写AGENTS.md？

简单来说：README.md是给人看的，AGENTS.md是给AI看的。

• README.md 面向的读者是新加入的开发者、开源贡献者，内容侧重项目介绍、快速上手、贡献指南。

• AGENTS.md 面向的读者是AI工具，内容侧重技术栈细节、构建命令、编码规范、架构约束。

举个例子：README.md里写"本项目基于React开发"就够了，但AGENTS.md里需要写"React 18 + TypeScript + Vite，禁止使用class component，hooks必须用自定义wrapper"。

判断标准很简单：如果AI自己能从代码里推断出来的信息，不用写；推断不出来的，才需要写。

四、写AGENTS.md的三个原则

原则一：写成导航图，不要写成百科全书

AGENTS.md应该是精简的导航，告诉AI"去哪里找什么"，而不是把所有细节都塞进去。

有个很形象的比喻：给新员工一张组织架构图，而不是把公司所有文件都倒给他。

一般来说，控制在200行以内比较合适。超过这个长度，AI的注意力会被稀释，反而抓不住重点。

原则二：只写AI自己推断不出来的内容

这是最核心的判断标准。AI能自己推断的不用写，比如：

• 项目用了什么框架（看package.json就知道）
• 目录结构（ls一下就知道）
• 代码风格规范（linter能管的交给linter）

需要写的是那些"不写就会出错"的信息：

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

原则三：从实际错误中迭代

不要试图一次写完。最好的方式是：AI犯了一个错，就往AGENTS.md里加一条规则。

这样积累下来，每一条规则都是从真实错误中提炼出来的，针对性很强。

五、AGENTS.md应该包含哪些内容

根据实践经验，建议包含以下六个模块：

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容易犯的错）

不用把整个编码规范抄进来，只写AI反复犯、而且linter抓不住的错。

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

5. 文档索引

把详细文档的路径告诉AI，需要时它会自己去读。

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

6. Git工作流

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

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

---

六、不同工具的适配细节

虽然AGENTS.md正在统一，但各家工具还是有一些特色功能。

Claude Code

Claude Code支持条件语法，可以根据场景加载不同规则：

<important if="writing or modifying tests">
- 测试文件放在源文件同目录
- 使用createTestApp()辅助函数
</important>

还支持Hooks机制，可以在AI执行操作前后插入检查脚本，用exit 2可以阻止操作执行。

Cursor

Cursor用.mdc文件，支持通过globs匹配自动激活规则：

---
description: "测试相关规范"
globs:
  - "src/**/*.test.ts"
alwaysApply: false
---

当上下文中出现匹配的文件时，规则自动加载。

Codex

Codex的AGENTS.md是纯Markdown，没有条件语法。但支持层级合并------在子目录放单独的AGENTS.md，AI在该目录工作时会自动读取。

跨工具通用方案

如果团队用多种工具，可以用软链接统一管理，或者在CLAUDE.md里写一行引用AGENTS.md。

七、一些进阶技巧

分层管理

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

• 根目录放全局规则（精简到100行以内）
• 各模块目录放模块专属规则
• docs/目录放详细文档

AI进入某个目录工作时，会自动读取该目录的规则。

引入源码作为参考

对于私有组件库或者第三方库的定制版本，文档总是容易过时。更好的做法是直接把源码放进项目，让AI需要时直接读源码。

源码就是最准确的文档，永远不会过时。

---

八、常见误区

误区一：自动生成后就不管了

很多工具提供/init命令自动生成AGENTS.md，但生成的内容往往大而全，不够精准。研究表明，直接用自动生成的版本反而可能降低AI的表现。

自动生成的版本应该当作草稿，需要人工审核和精简。

误区二：写得越多越好

AGENTS.md的每一行都会占用AI的上下文窗口。写太多反而会让AI抓不住重点，重要规则被淹没在大量信息里。

误区三：写成给人看的文档

AGENTS.md是给AI看的，不需要优美的措辞和详细的背景解释。

// 错误示范
"我们建议在可能的情况下尽量使用命名导出，因为这有助于tree-shaking和代码可读性。"

// 正确示范
"使用命名导出，禁止默认导出。"

AI不需要知道为什么，只需要知道规则是什么。

---

九、一个精简的模板

# AGENTS.md

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

## 常用命令
- <安装依赖>
- <启动开发>
- <运行测试>
- <代码检查>

## 架构约束
- <最重要的3-5条硬性规则>

## 编码规范
- <AI容易犯的错>

## 文档索引
- <关键文档路径>

## Git工作流
- <分支和提交规范>

## 已知陷阱
- <从实际错误中积累的规则>

建议控制在40-60行。随着使用，"已知陷阱"部分会自然增长。

十、写在最后

AGENTS.md不是写完就不管的文档，而是一个需要持续维护的"活文档"。

最好的维护方式是：每次AI犯错，不要只是在对话里纠正它，而是把正确的规则写进AGENTS.md。这样下次就不会再犯同样的错。

有个开发者说得很到位："维护AGENTS.md三个月了，最大的收获不是AI变聪明了，而是逼着自己把脑子里的隐性知识都讲清楚了。"

从今天开始，给你的AI助手写一份项目说明书吧。

参考资料

• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• How to Write a Great agents.md
• Claude Code Hooks文档
• Cursor Rules文档