AGENTS.md 规范文件
写给 AI 编程助手看的项目规范文件——告诉 AI 项目的目录结构、编码约定和禁止事项，让它按团队的规矩写代码
简介
AGENTS.md 是一种放置在项目根目录的 Markdown 文件，专门供 AI 编程助手（Cursor、Claude Code、GitHub Copilot、Windsurf 等）读取。它解决的核心问题是：AI 有很强的代码生成能力，但不知道你的团队规矩。没有 AGENTS.md 时，AI 写出的代码规范遵循率只有约 60%——用 any 类型、内联样式、裸 fetch、随意的 commit message；有了 AGENTS.md 后，遵循率飙升到 95%+，一次通过率从 40% 提升到 80%+。
AGENTS.md 的本质是**上下文工程（Context Engineering）**的一部分。与 memory.md（AI 的长期记忆）、Skill 文件（程序性知识包）、MCP 连接（工具接口）并列，是 AI 编程”四大上下文资产”中的一种。在 Claude Code 生态中对应 CLAUDE.md，在通用场景中叫 AGENTS.md。
值得注意的是，AGENTS.md 不仅是给 AI 看的——它也是项目文档的超级浓缩版。新人读 AGENTS.md，5 分钟就能了解项目的技术栈、目录结构、编码规范和禁止事项，上手时间从 3-5 天缩短到 1 天。
关键信息
- 类型：概念 / 工程规范
- 领域：AI 编程 / 前端工程化 / 上下文工程
- 放置位置：项目根目录（与
package.json、tsconfig.json同级） - 兼容工具：Cursor ✅、Claude Code ✅、GitHub Copilot ✅、Windsurf ✅
- 相关概念：Claude Code（CLAUDE.md）、Skill（程序性知识包）、MCP 模型上下文协议（工具接口）、上下文工程
核心特性
定义
AGENTS.md 是写给 AI 编程助手看的声明性项目规范。类比关系：
| 文件 | 给谁看 | 管什么 |
|---|---|---|
.eslintrc | ESLint | 代码风格 |
.prettierrc | Prettier | 格式化规则 |
tsconfig.json | TypeScript | 类型检查 |
| AGENTS.md | AI 助手 | 项目规范、目录结构、编码约定、禁止事项 |
核心组成：六章结构
一份合格的 AGENTS.md 包含六个核心章节：
- 技术栈声明（必填） — 用列表形式列出框架、包管理器、样式方案、UI 库，写明版本号。AI 解析列表的准确率高于段落
- 目录结构（必填） — 只列一级目录，每个目录加注释说明用途和命名规范（如 PascalCase）
- 编码规范（必填） — 越具体越好。“使用 interface 不用 type”优于”遵循最佳实践”。给出正确用法示例
- 构建命令（建议写） — 开发/构建/格式化命令，避免 AI 给出错误的命令指导
- Never 规则（最重要！） — 告诉 AI “绝对不能做什么”，比”应该怎么做”更重要
- 约定与协作（团队建议写） — Commit 规范（Conventional Commits）和多 Agent 并发规则
最小可用版本 30 行，推荐 60-100 行，不建议超过 200 行。
Never 规则：持续演进机制
Never 规则是 AGENTS.md 中价值最高的部分。核心理念是：
- AI 犯错的成本远高于人类：人类改错
src/.umi/会很快意识到不对，AI 会认认真真改完然后构建炸掉 - 一条 Never 规则避免一次灾难性误操作
- 建议”每次 AI 犯了一个你不希望它犯的错，就往 Never 规则里加一条”
- 维护一个 Never 规则演进日志，记录每条规则的新增日期和踩坑原因
典型 Never 规则示例：
- Never 修改框架自动生成的目录（如
src/.umi/） - Never 修改
dist/构建产物 - Never 使用
any类型 - Never 使用内联样式
- Never 在渲染路径中执行耗时操作
- Never 使用
git stash（多 Agent 并发时会互相覆盖）
三文件体系
AGENTS.md 通常与其他文件配合形成完整的 AI 上下文工程体系：
| 文件 | 职责 | 是否共享 |
|---|---|---|
AGENTS.md | 项目级代码规范 | 提交到 Git，团队共享 |
DESIGN.md | 视觉规范（品牌色、文字色、间距） | 提交到 Git |
AGENTS.local.md | 个人偏好（语言、写法偏好） | 加入 .gitignore |
典型应用
场景 1：写组件 — 没有 AGENTS.md 时 AI 用 any 类型、内联样式、错误目录；有 AGENTS.md 后 AI 用 interface 定义 Props、CSS Modules、正确目录结构，代码质量从”实习生第一天”变成”3 年经验同事”
场景 2：调 API — 没有 AGENTS.md 时在组件里裸写 fetch；有 AGENTS.md 后 API 封装在 services/ 目录，使用框架 request，有类型定义和 useRequest Hook
场景 3：提交代码 — 没有 AGENTS.md 时 "fix button"；有 AGENTS.md 后 "fix(components): 修复 CopyButton 在 Safari 下复制失败的问题"
常见误区
- 误区 1：写”遵循最佳实践”就够了 — AI 不知道你的”最佳实践”是什么，必须写具体规则
- 误区 2：AGENTS.md 写一次就完事 — 它应该随项目演进持续更新，尤其是 Never 规则
- 误区 3：只有 AI 需要它 — 新人读 AGENTS.md 也能 5 分钟上手项目
不同素材中的观点
- 2026-05-28-agents-md-coding-standard：本文作者莪_幻尘从前端团队实战角度出发，提供了完整的六章结构模板和三个真实场景对比。核心贡献是量化了 AGENTS.md 的效果数据（50+ 次人工抽检），并提出”Never 规则持续演进”的方法论——建议维护演进日志，每条规则对应一个真实踩坑故事。同时指出 AGENTS.md 的隐性价值：它是项目文档的超级浓缩版，对新人同样有用
实用信息
快速上手步骤
- 在项目根目录创建
AGENTS.md（与package.json同级） - 复制通用模板，替换
[方括号]中的内容为实际技术栈 - 根据项目实际情况补充 Never 规则
- 提交到 Git（团队共享）
- 创建
AGENTS.local.md（加入.gitignore）写个人偏好
常用模板
React + TypeScript 项目：
- 框架：React 19 + TypeScript
- 包管理器：yarn
- 样式：Less + CSS Modules
- UI 库：antd v6
Vue 3 项目：
- 框架：Vue 3 + TypeScript
- 构建工具：Vite 5
- 状态管理：Pinia
- UI 库：Ant Design Vue 4
Next.js 项目：
- 框架：Next.js 14 + TypeScript
- 路由方案：App Router
- 样式方案：Tailwind CSS v3
注意事项
- 长度控制：最小 30 行可用，推荐 60-100 行，不超过 200 行
- 越具体越好：写”使用 interface 不用 type”，不要写”遵循 TypeScript 最佳实践”
- 给出示例：AI 读示例比读规则更准确
- 用列表不用段落：AI 解析列表的准确率更高
- 版本号要写：React 18 和 React 19 的写法不同
- 兼容性：已验证 Cursor、Claude Code、GitHub Copilot、Windsurf 均可识别