一份 AGENTS.md让 AI 代码规范率从 60% 飙升到 95%前端 AI Skill 体系 · 实战篇5 分钟写一份 AGENTS.md让 AI 从此按你的规矩写代码。目录从评论区最多的一个问题说起AGENTS.md 到底是什么没有 AGENTS.md vs 有 AGENTS.md场景 1写一个复制按钮组件场景 2调用一个 API 接口场景 3提交代码手把手教你写一份 AGENTS.md第一章技术栈声明第二章目录结构第三章编码规范第四章构建命令第五章Never 规则第六章约定与协作通用模板5 分钟开箱即用进阶技巧效果数据常见问题从评论区最多的一个问题说起上篇文章《基于四层 Skill 体系的前端团队 AI 提效 50%》发出后评论区问得最多的问题是“AGENTS.md 到底怎么写能不能给个模板”今天安排。但在给模板之前我想先回答一个更根本的问题——为什么一个 Markdown 文件就能让 AI 写出的代码质量发生质变AGENTS.md 到底是什么一句话定义AGENTS.md 是写给 AI 编程助手看的项目规范文件。你可以把它类比成文件给谁看管什么.eslintrc给 ESLint 看代码风格.prettierrc给 Prettier 看格式化规则tsconfig.json给 TypeScript 看类型检查AGENTS.md给 AI 看项目规范、目录结构、编码约定、禁止事项.eslintrc让 ESLint 知道用单引号还是双引号。AGENTS.md让 AI 知道组件放哪个目录、样式用什么方案、哪些文件绝对不能动。没有它AI 就是一个能力很强但不知道团队规矩的新人。有了它AI 知道你的规矩按你的规矩来。一份真实的 AGENTS.md 长什么样以下是我从实际项目中提取的 AGENTS.md已脱敏你可以直接感受它的结构# AGENTS.md - 本项目为 React 19 TypeScript 前端应用 - 包管理器yarnNode 22.12.0 - 样式方案Less CSS Modules - UI 组件库antd v6 ## Project Structure src/ ├── components/ # 通用组件PascalCase ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── services/ # API 请求封装 ├── models/ # 全局状态 ├── utils/ # 工具函数 ├── typings/ # 类型定义 └── constants/ # 常量 - Never edit src/.umi/ — 框架自动生成 - Never edit dist/ — 构建产物 ## Coding Style - 使用 interface 定义 Props - 组件命名PascalCase文件名 index.tsx - Never 使用 any 类型 - Never 使用内联样式 ## Build Commands yarn serve # 开发服务器 yarn build # 生产构建 yarn lint # 格式化看起来很简单对吧就是一个 Markdown 文件。但它的效果是惊人的。没有 AGENTS.md vs 有 AGENTS.md我用三个真实场景给你看差距。场景 1写一个复制按钮组件❌ 没有 AGENTS.md 时AI 写的代码export default function CopyBtn({ text }: any) { return ( button style{{ color: blue, padding: 4px 8px }} onClick{() navigator.clipboard.writeText(text)} Copy /button ) }问题清单❌any类型——完全没有类型定义❌ 内联样式——团队用的是 CSS Modules❌CopyBtn命名——团队规范是完整的CopyButton❌ 没有用 antd 的message组件做成功提示❌ 文件没有放在src/components/CopyButton/目录下✅ 有 AGENTS.md 后AI 写的代码// src/components/CopyButton/index.tsx import React, { useCallback } from react import { message } from antd import styles from ./index.less interface CopyButtonProps { text: string onSuccess?: () void } const CopyButton: React.FCCopyButtonProps ({ text, onSuccess }) { const handleCopy useCallback(async () { await navigator.clipboard.writeText(text) message.success(已复制) onSuccess?.() }, [text, onSuccess]) return ( button className{styles[copy-button]} onClick{handleCopy} 复制 /button ) } export default CopyButton差距一目了然✅ 明确的interface定义 Props✅ CSS Modules 引入样式✅ 用了 antd 的message组件✅CopyButton完整命名✅ 放在正确的目录src/components/CopyButton/后者像团队里有 3 年经验的同事写的代码前者像实习生第一天写的。场景 2调用一个 API 接口❌ 没有 AGENTS.md 时// 直接在组件里裸写 fetch const [data, setData] useState(null) useEffect(() { fetch(/api/customers) .then(res res.json()) .then(data setData(data)) }, [])✅ 有 AGENTS.md 后// src/services/customer.ts import { request } from umi export async function fetchCustomerList( params: API.CustomerListParams ): PromiseAPI.ResponseAPI.Customer[] { return request(/api/customers, { params }) } // 组件中使用 import { fetchCustomerList } from /services/customer const { data, loading } useRequest(fetchCustomerList)区别✅ API 调用封装在src/services/下✅ 使用框架提供的request而非裸fetch✅ 有完整的 TypeScript 类型定义✅ 使用useRequestHook 管理请求状态场景 3提交代码❌ 没有 AGENTS.md 时git commit -m fix button✅ 有 AGENTS.md 后git commit -m fix(components): 修复 CopyButton 在 Safari 下复制失败的问题一个随意的描述 vs 一个符合 Conventional Commits 规范的 commit message。手把手教你写一份 AGENTS.md看完效果现在教你怎么写。一份合格的 AGENTS.md 包含6 个核心章节。逐个教你写每个章节都有模板。第一章技术栈声明必填这是 AGENTS.md 的开场白告诉 AI 你的项目用了什么。# AGENTS.md - 本项目为 React 19 TypeScript 前端应用 - 包管理器yarn - 样式方案Less CSS Modules - UI 组件库antd v6 - 构建工具类 umi 框架写法要点用列表而非段落——AI 解析列表的准确率更高写明版本号——React 18 和 React 19 的写法不同写明包管理器——否则 AI 可能给你npm install而不是yarn add适配不同技术栈# Vue 3 项目 - 本项目为 Vue 3 TypeScript 前端应用 - 构建工具Vite 5 - 状态管理Pinia - UI 组件库Ant Design Vue 4 # Next.js 项目 - 本项目为 Next.js 14 TypeScript 全栈应用 - 路由方案App Router - 样式方案Tailwind CSS v3第二章目录结构必填AI 最需要的信息之一——知道文件放哪里。## Project Structure src/ ├── components/ # 通用组件PascalCase 命名 ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── services/ # API 请求封装 ├── models/ # 状态管理 ├── utils/ # 工具函数 ├── typings/ # 类型定义 └── constants/ # 常量写法要点每个目录后面加注释说明用途只列到一级目录就够了——太深了 AI 反而会困惑写清楚命名规范——比如PascalCase第三章编码规范必填告诉 AI “在这个项目里代码该怎么写”。## Coding Style **TypeScript/React** - 使用 interface 定义 Props 类型 - 组件使用 React.FCProps - 组件命名PascalCase文件名 index.tsx **样式Less CSS Modules** - 正确用法import styles from ./index.less - 使用方式className{styles[my-class]} **路径别名** - /* → src/*写法要点越具体越好——不要写遵循最佳实践要写使用 interface 不用 type给出正确用法示例——AI 读示例比读规则更准确第四章构建命令建议写## Build Commands yarn serve # 启动开发服务器 yarn build # 生产构建 yarn lint # 代码格式化AI 帮你调试问题时可能需要运行命令。如果它不知道你用yarn serve而不是npm start就会给你错误的指导。第五章Never 规则最重要这是 AGENTS.md 中价值最高的章节。Never规则告诉 AI “绝对不能做什么”——这比告诉它应该怎么做更重要。## Never 规则 - Never 修改 src/.umi/ 或 src/.umi-production/ 目录 - Never 修改 dist/ 目录 - Never 在组件内使用 any 类型 - Never 使用内联样式style{{ }}除非需要动态计算 - Never 在 Less 中使用硬编码颜色值——使用主题变量 - Never 在渲染路径中执行耗时操作 - Never 在列表渲染中省略 key 属性 - Never 在 node_modules/ 中安装依赖 - Never 修改 lock 文件 - Never 使用 git stash - Never 切换分支写这类规则有个底线可判定。“Never 使用 any”、“Never 修改 src/.umi/”——每条都能在代码里对上号注意代码风格统一这种描述句无法判定做没做到约等于没写。模型对明确禁令的执行率远高于建议句。为什么 Never 规则如此重要因为 AI 犯错的成本远高于人类。人类改错了src/.umi/会很快意识到哦这个目录不应该改。但 AI 不会——它会认认真真地把自动生成的代码改了然后你下次构建就炸了。一条 Never 规则能避免一次灾难性的误操作。我的建议是每次 AI 犯了一个你不希望它犯的错就往 Never 规则里加一条。这是一个持续演进的过程。我现在的 Never 规则有 11 条都是从真实踩坑中积累出来的。第六章约定与协作团队项目建议写## Commit 规范 - 格式type(scope): description - 类型feat / fix / docs / style / refactor / test / chore ## 多 Agent 并发 - 禁止 git stash - 禁止切换分支 - 只 commit 自己修改的文件通用模板5 分钟开箱即用如果你不想从零写这里有一份通用模板覆盖 React TypeScript 项目的最常见场景。直接复制到你的项目根目录改掉 [方括号] 里的内容就行# AGENTS.md - 本项目为 [React/Vue/Next.js] TypeScript 前端应用 - 包管理器[yarn/pnpm/npm] - 样式方案[Less/Sass/Tailwind CSS] CSS Modules - UI 组件库[antd/Arco Design/Element Plus] v[版本号] ## Project Structure src/ ├── components/ # 通用组件PascalCase 命名 ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── services/ # API 请求封装 ├── models/ # 状态管理 ├── utils/ # 工具函数 ├── typings/ # 类型定义 └── constants/ # 常量 ## Coding Style **TypeScript** - 使用 interface 定义 Props - 组件使用 React.FCProps 或函数声明 - Never 使用 any 类型 **样式** - import styles from ./index.less - Never 使用内联样式 - Never 硬编码颜色值 **路径别名** - /* → src/* ## Build Commands [你的开发命令] # 启动开发服务器 [你的构建命令] # 生产构建 [你的格式化命令] # 代码格式化 ## Never 规则 - Never 修改框架自动生成的目录 - Never 修改 dist/ 构建产物 - Never 在组件内使用 any 类型 - Never 使用内联样式 - Never 在渲染路径中执行耗时操作 - Never 在列表渲染中省略 key - Never 硬编码敏感信息 - Never 修改 lock 文件 ## Commit 规范 - 格式type(scope): description - 类型feat / fix / docs / style / refactor / test / chore进阶技巧技巧 1DESIGN.md 联动视觉规范AGENTS.md管的是代码怎么写DESIGN.md管的是UI 长什么样# DESIGN.md ## 品牌色 - 主色#1677FF - 主色悬浮#4096FF - 主色背景rgba(22, 119, 255, 0.1) ## 文字色 - 主文字rgba(0, 0, 0, 0.88) - 次要文字rgba(0, 0, 0, 0.65) ## 间距系统 - 基础单位8px - 组件间距16px / 24px有了 DESIGN.mdAI 在写样式时就不会用color: blue这种硬编码颜色值。技巧 2AGENTS.local.md 个人偏好创建一个AGENTS.local.md加入.gitignore写你的个人偏好# AGENTS.local.md不入仓库 - 回复语言中文 - 代码注释语言中文 - 组件写法偏好函数声明 - 类型定义偏好interfaceAI 会同时读取项目规范和你的个人偏好输出更符合你习惯的代码。技巧 3Never 规则的持续演进我的建议是维护一个Never 规则演进日志2026-04-15 新增Never 修改 src/.umi/ 目录 原因AI 把自动生成的路由配置改了构建报错 2026-04-18 新增Never 在 Less 中硬编码颜色值 原因AI 用了 #333 而不是主题变量切主题时全崩了 2026-04-22 新增Never 使用 git stash 原因多 Agent 并发时一个 Agent stash 了另一个的改动每一条 Never 规则背后都是一个真实的踩坑故事。效果数据指标没有 AGENTS.md有 AGENTS.md变化AI 代码规范遵循率~60%95%↑ 35%AI 代码一次通过率~40%80%↑ 40%每次手动修正时间~8 分钟~1 分钟↓ 87.5%新人上手时间3-5 天1 天↓ 70%以上数据基于实际项目 3 周使用期间对 50 次 AI 代码生成的人工抽检统计。不同项目和技术栈可能有差异。最后一个数据可能出乎意料——AGENTS.md 对新人也有用。因为它不仅是给 AI 看的也是一份精简的项目开发规范。新人读 AGENTS.md5 分钟就知道项目的技术栈、目录结构、编码规范和禁止事项。它是项目文档的一个超级浓缩版。常见问题Q1AGENTS.md 放在哪里项目根目录。和package.json、tsconfig.json同级。但不同工具读取方式不同AGENTS.md更适合作为统一规范源文件Cursor 用 Rules 接入Claude Code 用CLAUDE.md引用GitHub Copilot 用.github/copilot-instructions.mdWindsurf 用 Rules /.windsurfrules。AI 编程助手会自动扫描项目根目录读取。Q2需要提交到 Git 吗需要。团队共享的规范文件。但AGENTS.local.md个人偏好应该加入.gitignore。Q3写多长合适最小可用版本30 行技术栈 目录 3 条 Never 规则推荐长度60-100 行不建议超过200 行Q4多个 AI 工具都能识别吗已验证Cursor ✅ | Claude ✅ | GitHub Copilot ✅ | Windsurf ✅更准确地说AGENTS.md是统一规范源文件不是所有工具都原生直接读取它。不同工具需要接入自己的规则入口Cursor 用 RulesClaude Code 用CLAUDE.mdGitHub Copilot 用copilot-instructions.md。Q5已有项目怎么加在项目根目录创建AGENTS.md复制本文模板5 分钟填好提交。不需要改任何代码不需要安装任何工具。Q6不做计算机方向比如土木、交通科研也能用吗能它不挑领域。AGENTS.md本质是写给 AI 编程助手看的项目规矩把本文的前端示例换成自己的场景即可技术栈Python pandas或 MATLAB / R目录结构data/raw原始数据、data/processed处理后数据、scripts、resultsNever 规则Never 修改data/raw原始数据、Never 覆盖已有结果只要平时用 AI 写代码数据处理、仿真、画图脚本都算就能直接套用。科研场景里不改原始数据、不覆盖结果这类规则尤其值钱——可复现性从规矩层面就兜住了。Q7AGENTS.md 会不会过时项目结构改了怎么办会而且这是它最大的隐性坑。目录重构之后旧规则还躺在文件里AI 拿着过时的结构硬套比没有这份文件还糟。对策不是靠自觉而是把项目结构变更必须同步更新 AGENTS.md写进提交前 checklist或 PR 检查项——文件不用天天维护但改结构的那一刀必须带上它。一个彩蛋如果你觉得手动写还是太麻烦——下篇教程我会分享如何《用一行命令自动生成 AGENTS.md DESIGN.md》脚本会读取package.json自动识别技术栈、UI 库、包管理器5 秒搞定。但即使不用任何工具手写的 AGENTS.md 也能达到 80% 的效果。工具只是让最后的 20% 更自动化。核心永远是那个 Markdown 文件本身。总结你可能在想我的回答“一个 Markdown 文件真能有这么大效果”是的AI 缺的不是能力是上下文“写起来会不会很复杂”6 个章节30-100 行5 分钟“团队不愿意用怎么办”提交到 Git 就行团队无需额外操作“要花多少时间维护”初次 5 分钟之后每踩一个坑加一条 Never 规则与其每次手动修正 AI 写的代码不如花 5 分钟告诉它规矩。如果你按照本文的方法创建了 AGENTS.md欢迎在评论区分享你的效果数据——特别是规范遵循率和一次通过率的变化。觉得有用点个赞 收藏一下