夜雨聆风你有没有遇到过这种情况：
用Cursor写代码，AI给的建议完全不对味——你用的是React，它给你写Vue的语法；你的项目有统一的错误处理规范，它非要自己发明一套；你团队用pnpm，它死活要npm install。
问题不在AI，在于它不了解你的项目。
今天教你一个被严重低估的技巧：写一份AGENTS.md文件，让AI编程工具真正理解你的代码库。
AGENTS.md是一个放在项目根目录的配置文件，专门给AI编程工具"读"的。它就像给新同事写的项目入门手册——告诉AI你的项目是什么、用什么技术栈、有什么规范、怎么跑起来。
目前支持AGENTS.md的工具包括：
Cursor（读取.cursor/rules或AGENTS.md） Codex CLI（OpenAI的命令行编程助手） Windsurf、Cline等主流AI编程工具
核心思路：把你脑子里的"项目常识"写下来，让AI也能学到。
我们做了个对比实验：
没有AGENTS.md时：
AI不知道你的包管理器，随意选择npm/yarn/pnpm AI不了解你的代码规范，生成风格不统一的代码 AI不清楚你的项目结构，把文件放错位置 AI不理解你的业务术语，变量命名乱七八糟
有AGENTS.md后：
AI严格遵循你的技术栈选择 AI生成的代码和团队风格一致 AI知道在哪里创建新文件 AI能用你的业务语言命名变量
效果立竿见影。
第一步：创建文件
在项目根目录创建 AGENTS.md：
touch AGENTS.md
第二步：填写项目基本信息
# 项目概述
这是一个电商后台管理系统，使用 React + TypeScript 前端和 Node.js 后端。
## 技术栈
- 前端：React 18、TypeScript 5.x、Vite
- 后端：Node.js、Express、Prisma ORM
- 数据库：PostgreSQL 15
- 包管理器：pnpm（禁止使用npm或yarn）
- 代码规范：ESLint + Prettier
## 项目结构
/src
/components — 可复用UI组件
/pages — 页面组件
/hooks — 自定义hooks
/services — API调用层
/utils — 工具函数
/types — TypeScript类型定义
第三步：写明编码规范
## 编码规范
- 组件使用函数式组件 + hooks，禁止使用class组件
- 所有函数必须有TypeScript类型注解
- API请求统一通过 services 层，不要在组件里直接fetch
- 错误处理使用统一的 ErrorHandler 组件
- CSS使用Tailwind CSS，禁止写内联style
- 命名规范：组件用PascalCase，函数用camelCase，常量用UPPER_SNAKE_CASE
第四步：定义常见任务流程
## 常见任务
### 新建页面
1. 在 /src/pages 下创建页面文件夹
2. 创建 index.tsx 作为页面主组件
3. 在 router.ts 中添加路由配置
4. 如果需要API，在 /src/services 中添加对应接口
### 新建组件
1. 在 /src/components 下创建组件文件夹
2. 包含 index.tsx + styles.ts + types.ts
3. 组件必须导出Props类型定义
第五步：告诉AI"不要做什么"
## 禁止事项
- 不要使用 any 类型
- 不要直接修改 state，使用 setState
- 不要在组件里写业务逻辑，抽到 hooks 里
- 不要使用 console.log 调试，使用 logger 工具
- 不要安装新的依赖包，除非我明确要求
技巧1：加上示例代码
## 代码示例
创建新组件的标准模板：
```tsx
import { FC } from 'react';
import { ComponentProps } from './types';
export const MyComponent: FC<ComponentProps> = ({ title, onClick }) => {
return (
<div className="p-4">
<h2>{title}</h2>
<button onClick={onClick}>点击</button>
</div>
);
};
**技巧2：记录常见坑**
```markdown
## 已知问题
- Prisma在Windows上需要先运行 npx prisma generate
- 环境变量必须以 VITE_ 开头才能在前端使用
- 部署前必须运行 pnpm build:test 先验证
技巧3：用.cursor/rules做更细粒度控制
如果你用Cursor，还可以在 .cursor/rules 目录下创建多个规则文件，按文件类型或目录分别指定规则。
AGENTS.md本质上就是把你脑子里的项目知识外化成文件。
花30分钟写好一份AGENTS.md，能让你之后每次和AI对话都节省大量"纠正"的时间。这不是一次性的工作——随着项目演进，持续更新AGENTS.md，它会越来越懂你的项目。
今天就试试：打开你的项目，花15分钟写一份AGENTS.md，然后让AI帮你写个新功能，感受一下区别。
你会发现，AI从"一个聪明但不懂你项目的外人"，变成了"熟悉你项目的资深同事"。
关注「AI布道师」，获取更多AI编程实战技巧。下期预告：如何用AI Agent自动化你的代码审查流程。