别再让AI瞎猜了！手把手教你为项目创建AGENTS.md文件（附Turbo monorepo实战模板）
别再让AI瞎猜了！手把手教你为项目创建AGENTS.md文件（附Turbo monorepo实战模板）
"AI生成的代码又跑偏了！"——这可能是现代开发者最常遇到的挫败场景之一。当你在Turborepo管理的monorepo中工作时，AI助手可能会给packages目录下的React组件加上分号，或者在TypeScript文件中使用双引号，甚至试图修改本应只读的vendor目录。这些看似微小的不一致性，实际上会显著拖慢团队协作效率。本文将带你从零构建一个真正可用的AGENTS.md文件，让AI代理从一开始就理解你的项目规则，而不是在反复试错中消耗你的耐心。
1. 为什么你的项目需要AGENTS.md？
在2025年的开发者调查中，73%的团队报告称AI生成的代码需要人工修正才能符合项目规范。这种"修正税"平均每天消耗开发者47分钟——相当于每年损失近200个工时。AGENTS.md的出现正是为了解决这一痛点：
- 明确边界：告诉AI哪些文件/目录绝对不能碰（如.env）
- 统一风格：锁定代码格式、命名规范等细节
- 加速协作：新成员（包括AI）能快速理解项目约定
- 降低维护成本：减少因风格不一致导致的代码审查往返
# 典型问题场景 原始需求： "添加一个React函数组件，接收name属性并显示问候语" AI可能生成： // 双引号 + 分号 + 类组件 class Greeting extends React.Component { render() { return <div style={{color:"blue"}}>Hello, {this.props.name}</div>; } } 你实际想要的： // 单引号 + 无分号 + 函数组件 interface Props { name: string } const Greeting = ({ name }: Props) => ( <div className='greeting'>Hello, {name}</div> )2. Turbo monorepo项目AGENTS.md实战模板
以下是为Turborepo项目量身定制的AGENTS.md模板，可直接复制到你的项目根目录：
# AGENTS.md <!-- 文件位置：项目根目录 --> ## 1. 开发环境 - **包管理器**: 使用 `pnpm` (版本 >=8.6.0) - **Node版本**: 通过 `.nvmrc` 指定 (当前为18.12.1) - **初始化**: ```bash pnpm install && pnpm build2. 代码风格规范
TypeScript
- 禁止使用
any类型 - 接口命名使用
PascalCase(如UserProfile) - 类型定义优先使用
interface而非type
React
- 组件使用函数式写法
- Props使用TS接口定义
- 禁止内联样式，使用CSS Modules
- 组件文件命名：
PascalCase.tsx
通用格式
- 字符串使用单引号
- 省略行尾分号
- 缩进：2个空格
- 最大行宽：100字符
3. 构建与测试
| 命令 | 作用 | 适用场景 |
|---|---|---|
pnpm dev | 启动开发服务器 | 日常开发 |
pnpm build | 生产环境构建 | 部署前 |
pnpm test | 运行所有测试 | CI/CD |
pnpm lint | 代码风格检查 | 提交前 |
4. Monorepo特定规则
- 包引用使用workspace协议：
"dependencies": { "@utils": "workspace:*" } - 跨包测试：
pnpm turbo run test --filter=@web/* - 禁止直接修改其他包的
dist目录
5. 安全边界
重要：以下内容AI代理绝对不应修改
.env*系列文件vendor/目录pnpm-lock.yamlturbo.json配置
## 3. 高级配置技巧：让AI更懂你的项目 基础的AGENTS.md能解决80%的问题，但这些进阶技巧能让协作更顺畅： **动态上下文注入**： ```markdown ## 6. 上下文提示 <!-- 这些内容会被AI作为背景知识 --> 当前技术栈： - 前端：React 18 + Vite - 状态管理：Zustand - 测试：Vitest + Testing Library 设计系统： - 使用内部的@design-system包 - 颜色变量前缀为`--ds-`代码生成模板：
## 7. 代码模板 ### React组件样板 ```tsx import { FC } from 'react' import styles from './Component.module.css' interface Props { // 在这里定义props } export const Component: FC<Props> = ({ /* props */ }) => { return ( <div className={styles.wrapper}> {/* 内容 */} </div> ) }错误预防：
## 8. 常见陷阱 - 不要使用`Date.now()`作为React key - 避免在循环中创建函数 - 服务端组件禁止使用浏览器API - 样式优先使用CSS变量而非固定值4. 验证与优化：让你的AGENTS.md真正生效
创建文件只是第一步，还需要验证其效果：
测试AI理解度：
- 在Cursor/Copilot中尝试指令："基于AGENTS.md创建一个新的React组件"
- 检查生成的代码是否符合所有规范
性能指标监控：
# 对比使用AGENTS.md前后的修正率 git diff --stat HEAD~10..HEAD | grep 'fixed' | wc -l渐进式优化：
- 每周审查AI生成的代码差异
- 将新发现的问题添加到AGENTS.md
- 使用版本控制跟踪文件变更
专业提示：在团队会议中定期review AGENTS.md，就像review代码一样。这是活的文档，应该随项目演进。