现在位置: 首页 / 免费干货 / 正文

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

说实话，我之前也被AI写代码气到过。明明项目全用Kotlin，它偏给你整Java。明明用了Retrofit，它给你上Volley。每次都要在prompt里反复强调，跟复读机一样。

后来我在项目根目录放了个 AGENTS.md，代码规范率从60%直接拉到95%。不是换模型，不是改prompt，就一个Markdown文件。

今天手把手教你写，看完直接抄。

AGENTS.md 到底在解决什么？

AI写代码的5大痛点

痛点 现象 后果
风格不统一 今天驼峰，明天下划线 代码可读性拉胯
架构混乱 不遵循项目分层 技术债越堆越多
重复踩坑 每次犯同样的错 反复修改浪费时间
上下文丢失 换会话就忘约定 沟通成本爆炸
规范靠吼 每次提醒"用Kotlin写" 效率低到离谱

传统做法说实话挺蠢的——每次提问都得把项目背景重新交代一遍，跟个复读机一样。

AGENTS.md 呢？写一次，AI每次自动读取，永久生效。

你猜怎么着？就这么一个文件，上面那五个问题基本全解决了。

AGENTS.md 的核心机制

简单到离谱。AGENTS.md 本质上就是一个放在项目根目录的 Markdown 文件，AI 工具每次干活前会自动扫描并读取它，相当于你给 AI 写的一份说明书。

工作原理分三层：

  • 自动加载——跟 .gitignore 一个思路，约定文件名和位置，AI 每次启动会话自动读取，不用你手动喂上下文。这个设计我觉得很聪明，把人的记忆负担直接砍掉了。
  • 指令持久化——你定一次规矩，全项目生效，换会话不丢。说实话这才是最值钱的地方，不然每次都得从零解释一遍"我们项目用的是什么风格、有什么约定"。
  • 多工具兼容——Cursor、Claude Code、Aider、OpenHands 这些主流工具都认它，一份文件到处能用。不用为每个工具单独配一套。

有点项目把它叫 AGENTS.md，也有叫 CLAUDE.md、.cursorrules 的，名字不一样但干的活儿差不多。

AGENTS.md 怎么写？

别想复杂了，结构就三部分：项目信息 → 技术规范 → 工作流规则。对吧，跟写README差不多。

1. 项目信息

让 AI 知道这是什么项目。几句话搞定。

# 项目概述
一个用 React + TypeScript 写的管理后台，UI 框架用的 Ant Design，
后端 API 走 RESTful 规范。

够直白就行，不用写得像文档那么正式。

2. 技术规范

这是核心部分。把你团队的开发习惯写清楚，AI 就不会每次瞎猜了：

  • 代码风格——命名用驼峰还是下划线？分号写不写？引号用单还是双？这些细节看着小，但每次让 AI 猜的话，猜对的概率老实讲不高。
  • 架构约定——哪个目录放组件、哪个放工具函数、状态管理用什么方案，写明白了AI就不会乱放文件。
  • 技术栈限制——比如"不用 class 组件""状态管理只用 Zustand，别引入 Redux"之类的。我之前有个项目就是因为没写这条，AI 自作主张给我加了三个多余依赖……

3. 工作流规则

你希望 AI 怎么干活，而不是光产出代码就行。这部分我觉得很多人会忽略，但其实特别重要：

  • 改代码前先分析需求，别上来就动手。
  • 优先复用现有工具函数，别自己造轮子。
  • 有拿不准的地方先问我，别自己瞎猜。

你定规矩，AI 照做。是不是比每次口头强调省事多了？

实战对比：有 vs 没有 AGENTS.md

光说不练假把式，看看实际效果差距有多大。

没有 AGENTS.md

我：帮我写一个用户列表组件
AI：好的，我用 Vue 写了一个……
我：等等，我们项目是 React！
AI：抱歉，我重新来……

过了很钟——
AI：（又用了下划线命名）
我：我们用驼峰的……

来来回回改三遍，时间全浪费了。

有 AGENTS.md

我：帮我写一个用户列表组件
AI：好的，用 React + TypeScript + Ant Design，
    组件放 src/components/UserList，命名用驼峰，
    优先复用 src/utils/request 里的 fetchUserList。
    你看这样可以吗？

一次到位。差距就在这儿。

说实话我自己第一次看到这个对比的时候有点被惊到——就一个文件，效率差这么多。

进阶技巧与避坑指南

让 AGENTS.md 越来越聪明

这文件不是一次写完就扔那儿的，它是个活的东西。用久了你会越来越清楚哪些该写进去。

几个我踩过坑之后总结的经验：

  • 别贪多——内容太多 AI 反而抓不住重点。控制在 200 行以内，把最关键的信息放进去就够了，废话少说。
  • 版本管理——AGENTS.md 跟着项目一起用 Git 管理，改了啥一目了然，别人也能看到。
  • 动态更新——发现 AI 又犯老毛病？别骂它，想想是不是 AGENTS.md 里漏了，然后补上。慢慢迭代，它会越来越懂你。

常见坑

这几个错误我见过太多次了：

坑 后果 解法
内容太长，写了500行 AI 抓不住重点，选择性忽略 精简到200行以内，优先级排好
写得太模糊 "写好一点" AI 根本不知道你要啥 给具体例子，比如"用 useState 不用 useReducer"
写完不更新 项目迭代了，规则还是旧的 每次大迭代回来检查一遍
一个文件塞所有 不同模块的规范互相冲突 拆成多个 .md 文件分模块写

AGENTS.md 模板

最后给个能直接抄的模板，改成你自己的项目信息就能用：

# 项目概述
[一句话说清楚这是什么项目]

# 技术栈
- 语言：TypeScript
- 框架：React 18
- 样式：Tailwind CSS
- 状态管理：Zustand

# 代码规范
- 命名：变量/函数驼峰，组件PascalCase
- 不用分号
- 字符串用单引号
- 优先用函数组件 + hooks

# 目录结构
src/
├── components/    # 通用组件
├── pages/         # 页面组件
├── hooks/         # 自定义 hooks
├── utils/         # 工具函数
└── types/         # 类型定义

# 工作流规则
1. 改代码前先分析需求，跟我确认
2. 优先复用 utils/ 里的现有函数
3. 有拿不准的先问我，别自己发挥

模板这东西，重要的不是抄，是改成适合自己的。你看，加上你自己的项目细节，三五分钟就能搞一个出来。

说一千道一万，AGENTS.md 就是把团队的开发习惯变成 AI 能读懂的规范文件——写一次，全项目永久生效，省下来的时间都是你自己的。

AGENTS.md 是什么？

AGENTS.md = 给AI助手的「项目说明书」。

放在项目根目录，AI自动读取，理解你的编码规范、技术架构、开发流程、项目背景。

原理很简单：

用户提问 → AI读取AGENTS.md → 理解上下文 → 生成符合规范的代码

就像新员工入职手册，AI读了就知道怎么干活。

实战模板，直接抄

以下是我在用的基础模板，说实话，根据自己项目改改就能用，不用从零开始瞎摸索：

# AGENTS.md
## 项目概述
- **项目名称**：XXX App
- **技术栈**：Kotlin + Jetpack Compose + MVVM
- **最小SDK**：Android 8.0 (API 26)
- **目标用户**：国内年轻用户
## 编码规范
### 命名规范
- 类名：PascalCase（如 UserRepository）
- 函数名：camelCase（如 getUserById）
- 常量：UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）
- 私有变量：_camelCase（如 _userData）
### 代码格式
- 缩进：4个空格（不用Tab）
- 行宽：120字符
- 括号：Egyptian风格（左括号不换行）
- 空行：函数间1空行，类间2空行
### 注释规范
- 所有public函数必须加KDoc
- 复杂逻辑加行内注释（中文）
- TODO标记必须带日期和作者：// TODO(2024-06-01 张三): 优化算法
## 架构约束
### 分层规则
- **UI层**：Composables + ViewModels
- **Domain层**：UseCases + Repository Interfaces
- **Data层**：RepositoryImpl + Retrofit + Room
- **禁止**：UI层直接调用Data层
### 依赖方向
UI → Domain ← Data
### 技术选型
- 网络：Retrofit + Kotlin Serialization
- 数据库：Room
- 依赖注入：Hilt
- 异步：Kotlin Coroutines + Flow
- 图片：Coil
## 测试要求
- 所有ViewModel必须写单元测试
- 所有Repository必须写集成测试
- 测试覆盖率目标：80%
- 测试框架：JUnit 5 + MockK + Turbine
## 提交规范
- 分支：feature/xxx, bugfix/xxx, hotfix/xxx
- Commit格式：`<type>(<scope>): <subject>`
  - 如 `feat(user): 添加用户登录功能`
- 必须关联Jira工单号
## 常见术语
- **Feed**：首页信息流
- **Card**：内容卡片组件
- **UGC**：用户生成内容
- **PUGC**：专业用户生成内容
## 性能约束
- 启动时间 < 2s
- 内存占用 < 150MB
- 网络请求超时：10s
- 图片缓存：LRU，最大100MB

不同项目，配置重点不同

Android项目

重点搞这几个：SDK版本约束、Jetpack组件规范、生命周期管理、权限处理模式。说实话，Android这块坑最多，生命周期搞不好就炸。

## Android专项
### 生命周期
- Activity别直接操作UI，走ViewModel驱动
- Fragment必须用ViewBinding，别偷懒
- 后台任务上WorkManager，别动Service了
### UI规范
- 所有页面用Compose
- 主题色从MaterialTheme拿，别硬编码颜色值
- 屏幕适配：最小宽度360dp作基准
### 权限处理
- 用ActivityResultContracts申请权限
- 用户拒绝权限？得有引导提示
- 敏感权限最好二次确认一下，稳妥

后端项目（Spring Boot）

重点配：分层架构、API设计规范、异常处理格式、数据库事务规则。后端嘛，规范严格点没毛病。

## 后端专项
### API规范
- 返回格式统一：{code, message, data}，别各写各的
- HTTP状态码：200成功，400参数错误，500内部错误
- 分页参数：page从1开始，size默认20，最大100
- 时间格式走ISO 8601，比如2024-06-01T10:00:00Z
### 异常处理
- Controller里别try-catch，让全局异常处理器干活
- 业务异常用BusinessException，HTTP 500
- 参数校验加@Valid，错误信息统一返回，别乱搞
### 数据库
- 连接池必须上，HikariCP走起
- 慢查询超过1s记个日志，方便排查
- 循环里查数据库？N+1问题，坚决不行

前端项目（React/Vue）

重点配：组件命名、状态管理、样式方案、路由约定。前端项目一多人协作，没规范就是灾难现场。

## 前端专项
### 组件规范
- 文件名PascalCase，比如UserCard.tsx
- props必须加类型定义，别用any糊弄过去
- 默认导出必须是组件，工具函数走命名导出
### 状态管理
- 全局状态用Zustand，Redux太重了没必要
- 服务端状态TanStack Query搞定
- 表单状态React Hook Form，简单好用
### 样式规范
- Tailwind CSS一把梭，别自己写CSS文件了
- 颜色从design tokens取，统一管理
- 响应式断点：sm(640), md(768), lg(1024)

从零到规范，三步搞定

步骤1：创建文件

# 项目根目录执行
touch AGENTS.md
# 写入配置
code AGENTS.md

对，就这么简单。一行命令搞定。

步骤2：AI自动读取

Claude Code会自动读取项目根目录的AGENTS.md，不需要额外操作。

来，我们验证一下：

你：请写一个用户登录功能
Claude Code：（读取AGENTS.md后）
"好的，我将按照AGENTS.md中的规范：
- 使用Kotlin + MVVM架构
- 用Hilt依赖注入
- 网络层用Retrofit
- 写对应的单元测试..."

你看，它自己就按你定的规矩来了。老实讲，这体验确实比每次手动交代强太多。

步骤3：持续迭代

不过说实话，没有一劳永逸这回事。规范这东西，得慢慢磨。

阶段 动作 效果
第1周 写个基础版本，先看AI实际输出的结果 你会发现好多规范其实漏了，之前根本没想到
第2周 把日常踩过的坑、常见错误案例都补进去 AI重复犯错的次数明显下降，省了不少沟通成本
第3周 加点你们团队的业务术语进去 AI对业务场景的理解一下子精准很多
持续 有新需求、新规范就随时更新 保持规范始终是最新的

效果对比：有 vs 没有

没有AGENTS.md：

你：写个网络请求
AI输出：
- 用Java写（项目用Kotlin）
- 用Volley（项目用Retrofit）
- 没有异常处理
- 没有日志记录
- 命名不规范
规范率：约60%

有AGENTS.md：

你：写个网络请求
AI输出：
- 自动用Kotlin + Coroutines
- 自动用Retrofit + Flow
- 自动加try-catch + 日志
- 自动命名符合规范
- 自动加KDoc注释
规范率：约95%

你看，差距就在这儿。60%直接拉到95%，就差一个文件的距离。老实讲，之前没加AGENTS.md的时候我也没太在意，感觉AI写出来的代码大差不差能用就行。但是你想想，每次都要手动改那些框架不对、命名乱七八糟的地方，是不是挺烦的？话说回来，就这一个文件搞定的事，规范率直接翻了一大截……

进阶技巧

技巧1：加负面示例

说实话，告诉AI别踩什么坑，比苦口婆心讲"你应该怎么做"管用太多了。

## ❌ 禁止事项
- 禁止在Activity中直接调用Room DAO
- 禁止在主线程执行网络请求
- 禁止用Java写新代码（项目已经全面切Kotlin了）
- 禁止提交没有单元测试的代码

技巧2：加常见错误和修复

这个我觉得特别实用。把团队踩过的坑直接写进去，AI就能提前避坑，不用你再反复review指出来。为什么这么说？因为它比你讲道理管用——直接摆事实，它记得住。

## 常见错误
### 错误1：内存泄漏
- 现象：Activity销毁后ViewModel还在引用
- 修复：用viewModelScope，自动跟着生命周期走就行
### 错误2：ANR
- 现象：主线程执行数据库操作
- 修复：所有数据库操作放在Dispatchers.IO

技巧3：版本控制

团队协作的时候，AGENTS.md也得跟代码一样有版本记录。不然改着改着，谁都不知道现在跑的是哪版规范了，对吧？

## 版本历史
- v1.0 (2024-06-01): 初始版本，基础规范
- v1.1 (2024-06-15): 加了Compose专项规范
- v1.2 (2024-07-01): 加了测试覆盖率要求

技巧4：多项目共享

公司级的通用规范用Git Submodule拉过来，项目自己需要补充的直接追加就行。这样就不用每个项目维护一份完整文件，省得两边内容打架。

# 公司级通用规范
git submodule add https://github.com/company/agents-base.git
# 项目级补充
echo "## 本项目专项" >> AGENTS.md

常见问题

AGENTS.md有长度限制吗？

没有硬性限制，但是吧……我建议基础规范控制在500到1000字左右，详细规范2000到3000字。超过5000字的话，老实讲，最好拆分一下，搞一个核心的AGENTS.md再搭配专项docs。

AI会忽略AGENTS.md吗？

一般不会。不过要注意，如果你的提问明确覆盖了AGENTS.md的内容，或者两边写得矛盾了，那肯定是以提问为准。

多人协作怎么维护？

两个思路。方案1：走代码库管理，用PR review来更新。方案2：指定一个「规范负责人」，定期同步。你看团队适合哪个？

AGENTS.md和.cursorrules有什么区别？

AGENTS.md .cursorrules
适用范围 Claude Code Cursor
格式 Markdown 纯文本
内容 项目级规范 个人偏好
位置 项目根目录 项目根目录或用户目录

可以同时用，互补不冲突。

对GPT-4/Copilot有效吗？

目前主要针对Claude Code。但是话说回来，你可以手动粘贴到GPT-4的System Prompt里。Copilot目前不支持自动读取项目级配置。未来嘛，说不定会变成行业标准，类似.editorconfig那样。

最后唠叨几句

说实话，AGENTS.md这玩意儿真不是什么魔法，但我觉得它绝对算得上是AI时代最省钱的规范手段了。改模型？不用。写插件？不用。培训团队？也不用。就一个普普通通的Markdown文件，帮你搞定八成的规范问题，你说值不值？

真的建议每个项目都搞一个，写个一百字都行。然后你就会发现，AI助手突然就「开窍」了，问啥都能答到点上。

你的项目有AGENTS.md吗？

还没有的话，现在就去建一个啊，也就花你五分钟时间，但规范率直接涨30%，这笔账怎么算都不亏对吧？

转自：https://mp.weixin.qq.com/s/F83W7FHMl_rgIEI4C2s7pg