个人知识库

2026-05-28-agents-md-coding-standard

10分钟阅读

一份 AGENTS.md，让 AI 代码规范率从 60% 飙升到 95%

5 分钟写一份 AGENTS.md（写给 AI 看的项目规范文件），六章结构覆盖技术栈、目录、编码规范、构建命令、Never 规则和协作约定，让 AI 代码规范遵循率从 60% 提升到 95%+，一次通过率从 40% 提升到 80%+

基本信息

  • 来源类型：网页文章（掘金）
  • 原文位置：raw/articles/2026-05-28-103256-tg-941b46.md
  • 原文 URL：https://juejin.cn/post/7639561816260886571
  • 作者：莪_幻尘
  • 发布日期：2026-05-15
  • 消化日期：2026-05-28

核心观点

  1. AGENTS.md 是写给 AI 看的项目规范文件：类比 .eslintrc（给 ESLint 看）、tsconfig.json（给 TypeScript 看），AGENTS.md 给 AI 编程助手看——告诉它项目的目录结构、编码约定、禁止事项。没有它，AI 就是一个能力很强但不知道团队规矩的新人

  2. 六章结构是最小可用框架：技术栈声明（必填）→ 目录结构（必填）→ 编码规范（必填）→ 构建命令（建议写）→ Never 规则（最重要！）→ 约定与协作。最小可用版本 30 行，推荐 60-100 行，不建议超过 200 行

  3. Never 规则是价值最高的章节：告诉 AI “绝对不能做什么”比告诉它”应该怎么做”更重要——人类改错 src/.umi/ 会很快意识到不对，AI 会认认真真改完然后构建炸掉。建议”每次 AI 犯了一个你不希望它犯的错，就往 Never 规则里加一条”，持续演进

  4. 量化效果数据惊人（基于实际项目 3 周 / 50+ 次 AI 代码生成人工抽检）：AI 代码规范遵循率 60%→95%+（↑35%），一次通过率 40%→80%+（↑40%），每次手动修正时间 8 分钟→1 分钟（↓87.5%），新人上手时间 3-5 天→1 天（↓70%+）

  5. AGENTS.md 不仅给 AI 看，也是项目文档的超级浓缩版：新人读 AGENTS.md 5 分钟就知道技术栈、目录结构、编码规范和禁止事项。已验证兼容 Cursor、Claude、GitHub Copilot、Windsurf

  6. DESIGN.md 联动 + AGENTS.local.md 个人偏好：AGENTS.md 管代码规范，DESIGN.md 管视觉规范（品牌色、文字色、间距系统），AGENTS.local.md（加入 .gitignore）管个人偏好（回复语言、组件写法偏好）。三文件形成完整的 AI 上下文工程体系

实操内容保留

代码/配置

完整的 AGENTS.md 模板（开箱即用）：

# 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

DESIGN.md 联动模板：

# 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

AGENTS.local.md 个人偏好模板：

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

Never 规则演进日志模板：

2026-04-15  新增：Never 修改 src/.umi/ 目录
            原因：AI 把自动生成的路由配置改了，构建报错
 
2026-04-18  新增：Never 在 Less 中硬编码颜色值
            原因：AI 用了 #333 而不是主题变量，切主题时全崩了
 
2026-04-22  新增：Never 使用 git stash
            原因：多 Agent 并发时，一个 Agent stash 了另一个的改动

操作步骤

写 AGENTS.md 的六步流程：

  1. 第一步：写技术栈声明 — 用列表形式列出框架、包管理器、样式方案、UI 组件库、构建工具，写明版本号
  2. 第二步：写目录结构 — 列到一级目录就够，每个目录加注释说明用途和命名规范
  3. 第三步：写编码规范 — 越具体越好（“使用 interface 不用 type”而非”遵循最佳实践”），给出正确用法示例
  4. 第四步：写构建命令 — 开发服务器、生产构建、格式化三个命令
  5. 第五步：写 Never 规则 — 从项目实际踩坑中积累，每条规则对应一个真实事故
  6. 第六步：写协作约定 — Commit 规范（Conventional Commits）和多 Agent 并发规则

适配不同技术栈：

  • Vue 3 项目：Vue 3 + TypeScript / Vite 5 / Pinia / Ant Design Vue 4
  • Next.js 项目：Next.js 14 + TypeScript / App Router / Tailwind CSS v3

关键概念

  • AGENTS.md 规范文件 — 写给 AI 编程助手看的项目规范文件，六章结构 + Never 规则持续演进
  • Claude Code — 已验证兼容 AGENTS.md，是 Skill 跨平台扩散的源头节点
  • Cursor — 已验证兼容 AGENTS.md
  • Skill — AGENTS.md 的姊妹概念：AGENTS.md 管项目静态规范，Skill 管程序性知识包

与其他素材的关联

  • 与 2026-05-27-pm-vibe-coding-5-products 的关系：那篇提到”CLAUDE.md 入职手册”（# 指令沉淀个人规则，目标 150 行），与本文的 AGENTS.md 是同一个思路的不同叫法——Claude Code 中叫 CLAUDE.md，通用场景叫 AGENTS.md
  • 与 2026-05-13-ai-agent-productivity-20x 的关系：那篇提出”AI 编程从提示词技巧升级为上下文资产管理”，AGENTS.md 正是上下文资产的核心载体之一（与 memory.md、Skill 文件、MCP 连接并列）
  • 与 2026-05-27-woshipm-central-skill-symlink 的关系：多 Agent 并存时 Skill 统一管理 + AGENTS.md 统一规范 = 完整的 AI 编程上下文工程体系
  • 与 2026-05-27-woshipm-yunshu-skill-practical-guide 的关系：Skill 是程序性知识包（“会做某件事”），AGENTS.md 是声明性知识（“应该怎么做”），两者互补

原文精彩摘录

没有它，AI 就是一个能力很强但不知道团队规矩的新人。 有了它，AI 知道你的规矩，按你的规矩来。.eslintrc 让 ESLint 知道”用单引号还是双引号”。AGENTS.md 让 AI 知道”组件放哪个目录、样式用什么方案、哪些文件绝对不能动”。

一条 Never 规则，能避免一次灾难性的误操作。 因为 AI 犯错的成本远高于人类。人类改错了 src/.umi/，会很快意识到”哦，这个目录不应该改”。但 AI 不会——它会认认真真地把自动生成的代码改了，然后你下次构建就炸了。我的建议是：每次 AI 犯了一个你不希望它犯的错，就往 Never 规则里加一条。 这是一个持续演进的过程。我现在的 Never 规则有 11 条，都是从真实踩坑中积累出来的。

以上数据基于实际项目 3 周使用期间，对 50+ 次 AI 代码生成的人工抽检统计。AGENTS.md 对新人也有用——因为它不仅是给 AI 看的，也是一份精简的项目开发规范。新人读 AGENTS.md，5 分钟就知道项目的技术栈、目录结构、编码规范和禁止事项。它是项目文档的一个超级浓缩版。

相关页面

关系图谱

快速导航

反向链接