告别复制粘贴!用AGENTS.md让AI编程助手真正听懂你的项目

title: "告别复制粘贴！用AGENTS.md让AI编程助手真正听懂你的项目" digest: "手把手教你配置AGENTS.md，让Cursor、Codex等AI编程工具从'通用助手'变成'你的专属开发搭档'，附完整配置模板。"

你有没有遇到过这种情况：

用Cursor写代码，AI给的建议完全不对味——你用的是React，它给你写Vue的语法；你的项目有统一的错误处理规范，它非要自己发明一套；你团队用pnpm，它死活要npm install。

问题不在AI，在于它不了解你的项目。

今天教你一个被严重低估的技巧：写一份AGENTS.md文件，让AI编程工具真正理解你的代码库。

什么是AGENTS.md？

AGENTS.md是一个放在项目根目录的配置文件，专门给AI编程工具"读"的。它就像给新同事写的项目入门手册——告诉AI你的项目是什么、用什么技术栈、有什么规范、怎么跑起来。

目前支持AGENTS.md的工具包括：

Cursor（读取.cursor/rules或AGENTS.md）
Codex CLI（OpenAI的命令行编程助手）
Windsurf、Cline等主流AI编程工具

核心思路：把你脑子里的"项目常识"写下来，让AI也能学到。

为什么你的AI助手总是"不听话"？

我们做了个对比实验：

没有AGENTS.md时：

AI不知道你的包管理器，随意选择npm/yarn/pnpm
AI不了解你的代码规范，生成风格不统一的代码
AI不清楚你的项目结构，把文件放错位置
AI不理解你的业务术语，变量命名乱七八糟

有AGENTS.md后：

AI严格遵循你的技术栈选择
AI生成的代码和团队风格一致
AI知道在哪里创建新文件
AI能用你的业务语言命名变量

效果立竿见影。

实操：手把手配置你的AGENTS.md

第一步：创建文件

在项目根目录创建 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 工具
- 不要安装新的依赖包，除非我明确要求

进阶技巧：让AGENTS.md更强大

技巧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自动化你的代码审查流程。