用 AGENT.md 提升 AI 编程质量：一份拿来即用的规则模板

一、背景：AI 生成的代码为什么总差一口气

2026 年用 AI 写代码的人都体会过这种分裂：生成速度极快，质量飘忽不定。同一个需求，今天生成的是结构清晰的模块，明天就是 200 行缩进地狱的面条代码。你发现自己 30% 时间在写需求，70% 时间在当代码审查，逐行挑魔数、命名、注释、异常处理。更痛苦的是每一句纠正只在当前会话有效，新开一个会话，同一个坑再踩一遍。

Fabien Sanglard 的经历很有代表性：他第一次用 LLM 写 Rust 的 mDNS 库，代码连编译都过不了；半年后重访，复杂数据结构能写了， obscure bug 也能定位，但代码质量依然是”能跑但没法维护”。直到他把反复念叨的审查意见沉淀进 AGENT.md，情况才彻底改观：AI 从”无限耐心的实习生”变成了”懂你标准的搭档”，他只需要聚焦架构和设计，不再纠正代码风格。

AGENT.md 的本质很简单：编码智能体启动时会自动加载项目根目录下这个文件并注入 prompt。你平时/logos反复说的话，一次写进文件，永久生效。本文逐条讲解这份模板，并给出落地方法。

二、原理：为什么一个 markdown 文件这么管用

智能体启动时的 system prompt 由三部分组成：工具说明、项目上下文、用户指令。AGENT.md 属于项目上下文，位置固定且权重高，模型每次生成前都会 attending 到它。相比口头纠正，它有三个优势：稳定（每次会话都加载，不会遗忘）、前置（生成前就约束，比生成后返工便宜一个数量级）、可版本化（跟着 git 走，团队共享，review 留痕）。

但它有两个天敌，必须理解。一是上下文稀释：Lost in the Middle 论文指出，上下文越长，模型对中间指令的注意力越弱。会话写了几千行代码后，AGENT.md 的约束力会衰减，表现为代码质量后半程下滑。对策只有两个：每个功能开新会话，保持上下文短；质量下滑时 explicitly 让智能体重新加载 AGENT.md。二是规则冲突：模板里同时要求注释详尽和用词极简，模型会无所适从。写法上每条规则给清边界（什么情况下适用、反例是什么），比堆形容词管用。

三、环境准备

1. 确认你的编码工具支持 AGENT.md 约定：Antigravity、VS Code 的 Claude Code 插件、Cursor、Gemini CLI 等主流智能体 IDE 均支持，文件名一般为 AGENT.md、agents.md、CLAUDE.md 或 GEMINI.md，不支持的用符号链接对齐（ln -s AGENT.md CLAUDE.md）。
2. 把文件放在项目根目录，确保智能体启动日志里出现 loaded AGENT.md 字样。
3. 准备一份你最近吐槽最多的 AI 生成代码 diff，后面逐条规则对号入座，验证模板是否覆盖你的痛点。

四、分步实战：模板逐条讲解加落地

第 1 步：先抄下完整模板

# 项目 AGENT.md（可直接用，按需删减）

- 写给人看的文字（注释、提交信息、回复）用最少的词，每个词都要有信息量，直奔主题。
- 不许吹捧和最高级，不说你完全正确，给冷硬的事实和判断。
- 魔数魔串抽成具名常量或枚举；一眼自明的单次值保持内联；协议规范值（如 HTTP 200）一律用常量。
- 降低缩进，杜绝箭头型嵌套，用早返回和 continue 压平。
- 函数名短，30 字符以内，动宾结构。
- 函数参数不用布尔，用枚举（ dishonest 的 true 半年后没人记得含义）。
- 逻辑块之间加空行，让读者喘气；每块配一句短注释说明做什么和为什么，可配 ASCII 示意图。
- 成员默认私有，改 public 视为 breaking change，必须先征得同意。
- 按抽象分层：底层机制（裸 IO、解析、socket）封进 driver 层，上层只调领域 API。
- 只动与需求相关的代码，不顺手改无关块，不给没动的代码加注释，最小化 diff。
- 层与层只和直接下层通信，UI 层不许直调数据库和裸网络客户端，必须走 service 层。
- 单行 if 也加大括号。
- 提交信息七规则：标题正文空行隔开；标题 50 字符内；首字母大写；无句号；祈使句（Fix 而非 Fixed）；正文 72 列换行；正文写 what 和 why，不写 how。
- 修 bug 先写测试，看它失败，再写修复，看它通过。

第 2 步：风格类规则（前两条）为什么值钱

用词极简针对的是 LLM 的 verbosity 病：注释比代码长、提交信息三段排比。实测加这一条后，注释量减少一半，信息密度反而上升。禁吹捧针对的是 sycophancy：模型动不动你说得太对了，淹没真正的风险提示。关掉吹捧，review 意见的信噪比明显提高。这两条是成本最低、见效最快的，先加上。

第 3 步：结构类规则（魔数、缩进、命名、枚举）

魔数规则的关键在后半句：一眼自明的单次值保持内联。很多团队抄成一刀切，满屏 MAX_RETRY_COUNT_3，反而难读。模板的智慧在于给了例外，review 时有据可依。箭头嵌套是 AI 代码的通病：if 套 if 套 for，深达五层。早返回规则把它压到两层以内，圈复杂度直接减半。布尔参数改枚举是长期主义：sendEmail(true) 三个月后没人知道 true 是什么， sendEmail(Mode.Now) 自解释。这三条建议设为团队强制项，进 CI lint。

第 4 步：架构类规则（可见性、分层、最小 diff）

成员默认私有这条专治 AI 乱开 public：模型为省事全标 public，封装性荡然无存。改成必须审批，public 数量会掉 80%。分层规则要配项目实际层名（如 controller 只调 service，不调 repository），抄模板时把例子换成你们的目录名，否则模型不知道层在哪。最小 diff 规则专治顺手重构：AI 修一个 bug 顺带格式化三个文件，review 和 blame 全毁。加上这条，diff 行数通常减半。

第 5 步：流程类规则（提交信息、测试先行）

提交信息七规则照搬经典 Git 规范，AI 执行得比人还好，配合 git log 检查，团队日志质量一周内改观。测试先行规则把 TDD 写进生成流程：修 bug 场景下模型必须先交 failing test，杜绝假修（看起来改了，测试本来就过）。这两条是流程杠杆，一次配置，永久分红。

第 6 步：落地三板斧与自动更新

第一，新功能开新会话，保持上下文短，质量全程在线。第二，质量下滑时直说重载 AGENT.md，模型会重新 attending 到规则。第三，也是最妙的：让智能体自己更新 AGENT.md。你纠正它三次的同一句话，直接说把这条记进 AGENT.md，它会提炼成规则追加进去。从此你只说一次。每月 review 一次文件，删掉过时规则（比如换了框架），防止膨胀到模型无视。

五、常见坑

1. 规则一次写 50 条：模型全记不住，等于没写。从 10 条核心起步，踩坑再加。
2. 形容词堆砌：写高质量优雅代码等于没说，改成可检查的表述（函数 30 字符内、嵌套不超 3 层）。
3. 与 linter 重复还冲突：缩进、括号已有工具管，就别在模板里再定相反的，模板只管工具管不了的（命名、分层、注释）。
4. 多智能体文件名不统一：AGENT.md、CLAUDE.md、GEMINI.md 各认各的，用符号链接指向同一份，改一处全生效。
5. 从不 review 模板：项目换框架后旧规则成毒药，每月花 10 分钟剪枝。
6. 指望模板替代读代码：模型照样幻觉 API，模板只保风格下限，正确性还得人审。
7. 规则自相矛盾：又要注释详尽又要极简，模型随机摆烂。每条写清适用边界和反例。

六、总结

AGENT.md 是把个人审查经验编译成团队资产的最小载体：风格两条管密度，结构四条管可读，架构三条管腐化，流程两条管交付。再配上短会话、显式重载、智能体自更新三板斧，AI 生成代码的 review 成本会掉一个量级。从今晚就开始：建文件、贴模板、把目录名换成你的，让 AI 第一次就按你的标准写。

七、各家智能体配置对照与团队推广 SOP

不同工具认的文件名不一样，对照表收好：Claude Code 认 CLAUDE.md，Gemini CLI 认 GEMINI.md，Cursor 认 .cursorrules 和 AGENT.md，Antigravity 认 AGENT.md。做法是 AGENT.md 存一份正本，其他文件名全部用符号链接指过去，改一处全生效。monorepo 多包结构可以在子目录再放一份增补规则（比如前端包的组件规范），智能体会就近合并读取，正本放通用规则，子目录放特例。

团队推广别直接群发文件，五步走。第一步，找两个 AI 重度用户试点两周，收集他们追加的规则。第二步，把试点版和 lint 规则去重，冲突的以工具为准。第三步，全员宣讲 15 分钟：讲清三板斧（新会话、重载、自更新），现场演示一次。第四步，接入新人 onboarding：第一天就配好符号链接。第五步，每月例会花 10 分钟 review 模板变更 diff，多余规则当场删。度量指标就看三个：AI 生成代码的 review 返工行数、public 新增数量、提交信息规范率，三周内没改善就回炉改模板。

还有一条进阶心法：把怎么做事也写进去，而不仅是写成什么样。比如修 bug 必须先复现、本包改完跑哪条测试命令、文档更新放在哪个目录。风格规则保下限，流程规则保交付，一个管代码长什么样，一个管事情怎么办。Fabien 原文最后那句是大实话：模板再好，幻觉照样有，架构和正确性永远是人的责任，模板只是让你把精力花在刀刃上。

八、速查问答：落地前最常被问的五个问题

规则多了性能会掉吗？会，但 AGENT.md 只有几十行，相对几万行代码上下文可忽略，真正拖慢的是超长会话本身，所以短会话才是正解。规则和项目文档冲突怎么办？以 AGENT.md 为准，同时把冲突处改掉，不要留两份打架的说法。接手老项目怎么写第一版？先只放最小 diff、测试先行、提交规范三条，跑两周再按吐槽追加，冷启动不要贪多。老板问投入产出怎么答？统计两周的 review 返工行数和风格评论条数，上线模板后再统计两周，差值就是收益。多人改模板打架怎么办？走 git PR 流程，规则的新增和删除都要有理由说明，每月固定一人当模板园丁，负责剪枝。

记住模板的生命周期：初创期做加法（缺什么补什么），成熟期做减法（每月删一条最没用的），把文件行数稳定在 30 到 60 行之间。超过 100 行的模板没人维护，模型也不看，等于死亡。少即是多在这里同样成立。

九、一句话总结与检查清单

模板正本建好后，对着清单打勾：文件名符号链接全了、目录名换成真实层名了吗、lint 管的条目删掉了吗、新会话验证过效果吗、团队知道重载口令吗、日历上有每月剪枝提醒吗。六个勾全打上，这套机制才算真正落地。第一周每天看一次 AI 生成的 diff，看到违规当场记进模板，两周后你会明显感觉 review 变轻松。去做吧，今晚的半小时配置，换未来每天省下的扯皮时间。 点击阅读原文

附：最小可用 AGENT.md 正本（复制即用，记得把层名换成你的目录）。风格两条、结构四条、架构三条、流程两条，共十一行，先跑起来再按需加。任何新增规则必须带一条反例，否则不合并。 点击阅读原文

参考资料：Fabien Sanglard《My agent.md to improve LLM-assisted code quality》一文的模板与经验。 点击阅读原文