从评论区最多的一个问题说起

上篇文章《基于四层 Skill 体系的前端团队 AI 提效 50%》发出后，评论区问得最多的问题是：

"AGENTS.md 到底怎么写？能不能给个模板？"

今天安排。

但在给模板之前，我想先回答一个更根本的问题——

为什么一个 Markdown 文件，就能让 AI 写出的代码质量发生质变？

AGENTS.md 到底是什么

一句话定义：

AGENTS.md 是写给 AI 编程助手看的项目规范文件。

你可以把它类比成：

文件

给谁看

管什么

.eslintrc 让 ESLint 知道"用单引号还是双引号"。

AGENTS.md 让 AI 知道"组件放哪个目录、样式用什么方案、哪些文件绝对不能动"。

没有它，AI 就是一个能力很强但不知道团队规矩的新人。

有了它，AI 知道你的规矩，按你的规矩来。

一份真实的 AGENTS.md 长什么样

以下是我从实际项目中提取的 AGENTS.md（已脱敏），你可以直接感受它的结构：

markdown代码解读复制代码# AGENTS.md  - 本项目为 React 19 + TypeScript 前端应用 - 包管理器：yarn，Node >= 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 写的代码：

tsx代码解读复制代码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 写的代码：

tsx代码解读复制代码// 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.FC<CopyButtonProps> = ({ 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 时：

tsx代码解读复制代码// 直接在组件里裸写 fetch const [data, setData] = useState(null)  useEffect(() 
=> {   fetch('/api/customers')     .then(res => res.json())     .then(data => setData(data)) },
 []) 
 

✅ 有 AGENTS.md 后：

tsx代码解读复制代码// src/services/customer.ts import { request } from 'umi'  export async function
 fetchCustomerList(   params: API.CustomerListParams ): Promise<API.Response<API.Customer[]>> 
 {   return request('/api/customers', { params }) }  // 组件中使用 import { fetchCustomerList } from '
 @/services/customer'  const { data, loading } = useRequest(fetchCustomerList) 
 

区别：

• ✅ API 调用封装在 src/services/ 下

• ✅ 使用框架提供的 request 而非裸 fetch

• ✅ 有完整的 TypeScript 类型定义

• ✅ 使用 useRequest Hook 管理请求状态

场景 3：提交代码

❌ 没有 AGENTS.md 时：

bash代码解读复制代码git commit -m "fix button" 

✅ 有 AGENTS.md 后：

bash代码解读复制代码git commit -m "fix(components): 修复 CopyButton 在 Safari 下复制失败的问题" 

一个随意的描述 vs 一个符合 Conventional Commits 规范的 commit message。

手把手教你写一份 AGENTS.md

看完效果，现在教你怎么写。

一份合格的 AGENTS.md 包含 6 个核心章节。逐个教你写，每个章节都有模板。

第一章：技术栈声明（必填）

这是 AGENTS.md 的"开场白"，告诉 AI 你的项目用了什么。

markdown代码解读复制代码# AGENTS.md  - 本项目为 React 19 + TypeScript 前端应用 - 包管理器：yarn -
 样式方案：Less + CSS Modules - UI 组件库：antd v6 - 构建工具：类 umi 框架 
 

写法要点：

• 用列表而非段落——AI 解析列表的准确率更高

• 写明版本号——React 18 和 React 19 的写法不同

• 写明包管理器——否则 AI 可能给你 npm install 而不是 yarn add

适配不同技术栈：

markdown代码解读复制代码# 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 最需要的信息之一——知道文件放哪里。

markdown代码解读复制代码## Project Structure  src/ ├── components/     # 通用组件（PascalCase
 命名） ├── pages/          # 页面组件 ├── hooks/          # 自定义 Hooks ├── 
 services/       # API 请求封装 ├── models/         # 状态管理 ├── utils/        
   # 工具函数 ├── typings/        # 类型定义 └── constants/      # 常量 
   
  

写法要点：

• 每个目录后面加注释说明用途

• 只列到一级目录就够了——太深了 AI 反而会困惑

• 写清楚命名规范——比如"PascalCase"

第三章：编码规范（必填）

告诉 AI "在这个项目里，代码该怎么写"。

markdown代码解读复制代码## Coding Style  **TypeScript/React** - 使用 interface 定义 Props 类型 - 
组件使用 React.FC<Props> - 组件命名：PascalCase，文件名 index.tsx  **样式（Less + CSS Modules）** - 
正确用法：import styles from './index.less' - 使用方式：className={styles['my-class']}  **路径别名** -
 @/* → src/* 
 

写法要点：

• 越具体越好——不要写"遵循最佳实践"，要写"使用 interface 不用 type"

• 给出正确用法示例——AI 读示例比读规则更准确

第四章：构建命令（建议写）

markdown代码解读复制代码## Build Commands  yarn serve    # 启动开发服务器 yarn build    
# 生产构建 yarn lint     # 代码格式化 

AI 帮你调试问题时可能需要运行命令。如果它不知道你用 yarn serve 而不是 npm start，就会给你错误的指导。

这一节也是全文最容易过期的：包管理器一换（yarn → pnpm），命令就成了陷阱——AI 照着旧命令跑，失败几次后很可能开始乱改配置。命令变了记得同步这里；有条件的话，让 CI 直接执行下面列出的 lint / build / test，文档和脚本对不上就挂。

第五章：Never 规则（最重要！）

这是 AGENTS.md 中价值最高的章节。

Never 规则告诉 AI "绝对不能做什么"——这比告诉它"应该怎么做"更重要。

markdown代码解读复制代码## 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 条，都是从真实踩坑中积累出来的。

第六章：约定与协作（团队项目建议写）

markdown代码解读复制代码## Commit 规范  - 格式：type(scope): description - 类型：feat / fix / docs 
/ style / refactor / test / chore  ## 多 Agent 并发  - 禁止 git stash - 禁止切换分支 - 只 commit 自己
修改的文件 

通用模板：5 分钟开箱即用

如果你不想从零写，这里有一份通用模板，覆盖 React + TypeScript 项目的最常见场景。

直接复制到你的项目根目录，改掉 [方括号] 里的内容就行：

markdown代码解读复制代码# 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.FC<Props> 或函数声明
     - 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
         

进阶技巧

技巧 1：DESIGN.md 联动视觉规范

AGENTS.md 管的是"代码怎么写"，DESIGN.md 管的是"UI 长什么样"：

markdown代码解读复制代码# 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.md，AI 在写样式时就不会用 color: blue 这种硬编码颜色值。

技巧 2：AGENTS.local.md 个人偏好

创建一个 AGENTS.local.md（加入 .gitignore），写你的个人偏好：

markdown代码解读复制代码# AGENTS.local.md（不入仓库）  - 回复语言：中文 - 代码注释语言：中文 - 
组件写法偏好：函数声明 - 类型定义偏好：interface 

AI 会同时读取项目规范和你的个人偏好，输出更符合你习惯的代码。

技巧 3：Never 规则的持续演进

我的建议是维护一个 Never 规则演进日志：

yaml代码解读复制代码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

变化

以上数据基于实际项目 3 周使用期间，对 50+ 次 AI 代码生成的人工抽检统计。不同项目和技术栈可能有差异。

最后一个数据可能出乎意料——AGENTS.md 对新人也有用。

因为它不仅是给 AI 看的，也是一份精简的项目开发规范。新人读 AGENTS.md，5 分钟就知道项目的技术栈、目录结构、编码规范和禁止事项。

它是项目文档的一个超级浓缩版。

常见问题

Q1：AGENTS.md 放在哪里？

项目根目录。 和 package.json、tsconfig.json 同级。

但不同工具读取方式不同： AGENTS.md 更适合作为统一规范源文件；

• Cursor 用 Rules 接入

• Claude Code 用 CLAUDE.md 引用，

• GitHub Copilot 用 .github/copilot-instructions.md，

• Windsurf 用 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 用 Rules，Claude Code 用 CLAUDE.md，GitHub Copilot 用 copilot-instructions.md。

Q5：已有项目怎么加？

在项目根目录创建 AGENTS.md，复制本文模板，5 分钟填好，提交。不需要改任何代码，不需要安装任何工具。

Q6：不做计算机方向（比如土木、交通科研）也能用吗？

能，它不挑领域。 AGENTS.md 本质是"写给 AI 编程助手看的项目规矩"，把本文的前端示例换成自己的场景即可：

• 技术栈：Python + pandas（或 MATLAB / R）

• 目录结构：data/raw（原始数据）、data/processed（处理后数据）、scripts、results

• Never 规则：Never 修改 data/raw 原始数据、Never 覆盖已有结果

只要平时用 AI 写代码（数据处理、仿真、画图脚本都算），就能直接套用。科研场景里"不改原始数据、不覆盖结果"这类规则尤其值钱——可复现性从规矩层面就兜住了。

Q7：AGENTS.md 会不会过时？项目结构或命令变了怎么办？

会，而且这是它最大的隐性坑。 目录重构之后，旧规则还躺在文件里，AI 拿着过时的结构硬套，比没有这份文件还糟。

结构变更的对策不是靠自觉，而是把"项目结构变更必须同步更新 AGENTS.md"写进提交前 checklist（或 PR 检查项）——文件不用天天维护，但改结构的那一刀必须带上它。

命令变更更容易漏，而且后果更绕：包管理器从 yarn 换成 pnpm 之后，AI 还会照着旧命令跑；失败几次，它可能开始去改配置——错上加错。这类漂移最好交给机器守：让 CI 直接执行 AGENTS.md 里列出的 lint / build / test，文档和脚本对不上就直接挂，比人工定期对一遍靠谱。

两个边界：serve、watch 这类长驻命令不要放进 CI；校验的锚点始终是 package.json 的 scripts，AGENTS.md 只是引用。

一个彩蛋

如果你觉得手动写还是太麻烦——下篇教程我会分享如何《用一行命令自动生成 AGENTS.md + DESIGN.md》，脚本会读取 package.json 自动识别技术栈、UI 库、包管理器，5 秒搞定。

但即使不用任何工具，手写的 AGENTS.md 也能达到 80% 的效果。

工具只是让最后的 20% 更自动化。核心永远是那个 Markdown 文件本身。

作者：莪_幻尘
链接：https://juejin.cn/post/7639561816260886571
来源：稀土掘金
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。