AGENTS.md的核心结构

手把手教你写第一个AGENTS.md

先上个模板

不整虚的，直接给一个我一直在用的基础模板。你把这个复制到项目根目录，就能直接用。

# AGENTS.md - 项目AI助手配置

## 项目概览

一句话描述这个项目是干什么的，用什么技术栈。

## 开发环境

### 安装依赖
```bash
npm install

启动开发服务器

npm run dev

运行测试

npm test

代码检查

npm run lint

代码规范

• 使用 TypeScript 严格模式
• 使用 ES6+ 语法
• 使用单引号，不使用分号
• 优先使用箭头函数
• 禁止使用 any 类型

测试要求

• 测试文件放在 tests 目录
• 使用 Jest 测试框架
• 提交前必须通过所有测试
• 新功能必须包含对应的测试用例

注意事项

• 禁止在代码中硬编码敏感信息
• 生产环境构建使用 npm run build
• 更新依赖后需要重启开发服务器

把这个文件扔到项目根目录，命名为 AGENTS.md，基本上主流的 AI 编程工具都能自动识别。Cursor 会读，Aider 会读，Claude Code 也会读。

## 三个核心要素

上面那个模板已经能用了，但如果你想用得更顺手，得理解 AGENTS.md 的三个核心要素。

### 1. 能力范围

这一部分要告诉 AI：这个项目能做什么，怎么做。你需要把开发命令、构建流程、测试方式这些写清楚。

为什么要写这个？因为 AI 不知道你的项目是怎么跑起来的。你不告诉它 "npm run dev" 是启动开发服务器，它可能以为直接 "node index.js" 就能跑。然后写出来的代码各种报错，你还得帮它擦屁股。

具体来说，能力范围通常包括：依赖怎么安装、开发服务器怎么启动、测试怎么运行、打包构建用什么命令、部署流程是什么。这些看似简单的东西，AI 真的不知道。

### 2. 约束条件

这一部分要告诉 AI：什么能做什么不能做，哪些规矩必须遵守。

最常见的是代码规范。你得告诉 AI 你用什么语法、怎么命名、禁止用什么写法。要不然它给你生成出来的代码，可能和你的项目风格完全不在一个频道上。

还有一些项目特定的约束。比如某些接口需要认证、某些操作需要管理员权限、某些数据不能存本地。这些东西你不说，AI 根本不知道。

### 3. 交互约定

这一部分要告诉 AI：怎么和人类协作。比如分支怎么管理、PR 标题什么格式、提交信息怎么写。

这个对团队项目特别重要。每个人和 AI 配合的方式可能不一样，但如果你在 AGENTS.md 里定好了规矩，大家都能遵守，代码质量至少在流程层面是有保障的。

## 文件放在哪里

最简单的方式：直接扔项目根目录。绝大多数 AI 工具都会自动扫描项目根目录，找 AGENTS.md 这个文件。

如果你的项目是 Monorepo 架构，还可以更细致一点：在每个子项目里放一个 AGENTS.md。AI 在处理某个子项目的时候，会自动读取那个子项目里的配置文件。

比如你的项目结构是这样的：

my-monorepo/
├── packages/
│ ├── frontend/
│ │ └── AGENTS.md # 前端项目配置
│ └── backend/
│ └── AGENTS.md # 后端项目配置
└── AGENTS.md # 全局配置

这样前端和后端可以有不同的配置，互不干扰。

## 什么时候该更新

AGENTS.md 不是写完就扔一边的静态文件。它应该随着项目一起成长。

当你引入新的技术栈时，更新。比如从 JavaScript 切到 TypeScript，你得把相关规范写进去。

当你改变开发流程时，更新。比如开始用 ESLint 了，得把 lint 命令加进去。

当你踩到新的坑时，更新。比如某次 AI 生成的代码有问题，你解决了之后，最好把这个经验也写进去，省得下次再踩。

我个人的习惯是：每次项目有比较大的变化，就顺带把 AGENTS.md 更新一下。不求一步到位，但求持续改进。

## 写给 Claude Code 用户

如果你用的是 Claude Code，还有个更省事的办法：直接用它的 /init 命令。

/init

这货会扫描你的项目，分析项目结构和技术栈，然后自动生成一个 CLAUDE.md 文件。虽然名字不一样，但作用差不多。而且因为是自动生成的，很多基础信息它能帮你补齐，省得自己手写。

不过自动生成的东西毕竟只是起点，你还是需要根据自己的项目实际情况做一些调整。毕竟只有你自己最了解你的项目。

## 小结

AGENTS.md 核心就三个东西：能力范围、约束条件、交互约定。把这三个写清楚，一个基础的 AGENTS.md 就完成了。

别想太复杂，先搞一个能用的版本出来，然后随着项目一起迭代。完美主义害死人，行动最重要。

下期我会讲具体开发场景下的 AGENTS.md 怎么写，包括前端、后端、测试等等。有兴趣的兄弟别错过。

---