AGENTS.md 入门：给 AI 编程助手一份项目说明书

AI 编程工具越来越能干，但在陌生项目里还是会犯低级错误：改错目录、用错包管理器、跑错测试命令。这些错误有个共同点——不是模型不会，而是它不知道。AGENTS.md 就是为了解决这个问题。

它是什么

AGENTS.md 是一个放在仓库根目录的 Markdown 文件，内容是给 AI 编程代理看的「项目说明书」。Claude Code、Codex、Cursor 等主流工具都会在开工前读取它。它的出现也顺带解决了一个碎片化问题：此前各家各有一套配置文件名，现在逐渐向这个统一约定收敛。

值得写进去的五类信息

• 构建与运行命令：怎么装依赖、怎么起本地环境、怎么构建产物。写清楚比让模型猜要省一半 token。
• 测试命令与约定：跑全量测试、跑单个文件的命令分别是什么，测试数据怎么准备。
• 代码风格与命名：缩进、命名习惯、错误处理惯例、注释语言。
• 项目结构地图：哪个目录放什么，改动通常从哪里入手。
• 禁区：不许动的目录、不许引入的依赖、必须保持兼容的旧接口。

不该写什么

两个常见的反面做法：一是塞进大段过期信息，模型会照着过期说明行事，比没有说明更糟；二是把模型本来就知道的通用常识（比如「请写整洁的代码」）写成长篇，这类内容不产生信息量，只稀释重点。文件越短、越准，效果越好。

一份最小模板

# 项目约定

- 包管理：pnpm（不要用 npm install）
- 启动：pnpm dev（端口 3001）
- 测试：pnpm test src/xxx.test.ts 跑单文件
- 风格：2 空格缩进，组件用 PascalCase
- 禁区：不要改 legacy/ 目录下任何文件

和 CLAUDE.md、.cursorrules 的关系

它们定位相同：都是「给 AI 看的项目说明」。区别只在各工具的默认读取优先级。务实做法是维护一份内容，其余文件用一行引用或软链指向它，避免多份说明各自漂移。