把每次纠正写成 lint 规则:别让 Agent 抄烂代码

你纠正了 Agent 一次「别在组件里乱用 useEffect」,它记住了这一轮;换个会话、换个 Agent,同样的写法又出现在 PR 里。AI Engineer 频道 11 月发布的演讲《All Code Is Slop (Except Mine)》给了一个很实在的办法:每纠正一次,就把它变成一条会报错的检查,而不是往 AGENTS.md 里再加一行字。讲者所在的 SpaceXSI Grok Bot 团队,上个月合并了约 1.1 万个 PR,回滚比例稳定在 0.5% 左右。这篇把演讲里的方法落到 ESLint 配置上,给出能直接改的规则写法。
前置条件
- 一个 JavaScript / TypeScript 仓库,ESLint 用的是 flat config(
eslint.config.js)。 - CI 或提交钩子里已经跑 ESLint,并且 error 会让检查失败。规则只在编辑器里标红,Agent 照样能提交。
- Claude Code、Codex、Cursor 等任意编程 Agent,能在本地跑 lint 命令。
Agent 照着代码库学,文档只是补充
演讲的出发点很朴素:Agent 的输出取决于输入,而代码库是它最大的输入。临时补丁、反模式、过时写法留在仓库里,下一个 Agent 读到会以为这就是项目惯例,接着复制。讲者用了一个园艺的比喻:以前一天审三个同事的 PR,现在一个人背后是几百个 Agent,代码像一条持续的流涌进来,杂草一旦长出来,很快就铺满整个园子。
她给的投入顺序是一个倒金字塔,从上往下越来越不确定:
| 层 | 手段 | 特点 |
|---|---|---|
| 代码本身 | API 设计、架构、重构 | 让正确写法成为默认写法 |
| 静态检查 | lint 规则、类型系统、编译器、测试 | 确定性,违反就报错 |
| 验证 | 运行时验证(录屏、截图)、形式化验证 | 检查行为和意图是否对得上 |
| 文字 | 规则文件、Skills、AGENTS.md | 只放需要判断力的东西 |
所以每次想往 AGENTS.md 里加一句「不要……」之前,先问能不能写成一条确定性检查。写进代码的约束每次都生效,写进文档的话 Agent 不一定照做。
每纠正 Agent 一次,就把它变成一条确定性检查,或者从 API 设计上让这个问题不再可能出现。
第一步:把纠正写成带修复指引的报错
演讲里的第一个例子是 React 的 useEffect:用得好要很多经验,Agent 经常用错。团队的做法是在产品代码里直接禁用,只允许在自研框架的少数 API 内部使用,这一类问题就再也不用在代码审查里抓了。
ESLint 自带的两条规则就能做到,而且都支持自定义报错信息。要紧的是 message:别只写「禁止」,要写清楚该改成什么,Agent 看到报错会按提示去改。
// eslint.config.js
export default [
{
files: ["src/features/**/*.{ts,tsx}"],
rules: {
"no-restricted-imports": ["error", {
paths: [{
name: "react",
importNames: ["useEffect"],
message: "产品代码不用 useEffect:派生数据在渲染时直接算;订阅外部数据用 src/lib/hooks/useSubscription。"
}]
}],
"no-restricted-syntax": ["error",
{
selector: "MemberExpression[object.name='React'][property.name='useEffect']",
message: "同上,React.useEffect 也不允许。"
},
{
selector: "CallExpression[callee.name=/^(setTimeout|requestAnimationFrame|requestIdleCallback)$/]",
message: "不要用定时器绕开时序问题。先找到状态从哪来,改成声明式更新;确实需要调度用 src/lib/scheduler。"
}
]
}
}
];
第二条选择器对应演讲里另一个例子:在上一家公司,Agent 很爱用 setTimeout、requestAnimationFrame、requestIdleCallback 这类命令式定时器当快速补丁,背后其实是 VS Code 的命令式风格和 React 声明式风格的架构冲突。定时器大量创建销毁引发频繁的垃圾回收,应用越来越卡,而且这种写法扩散到了到处都是。
写选择器时可以打开 ESLint 官方的 Code Explorer(TypeScript 项目用 typescript-eslint Playground),粘一段要拦的代码,看它对应的 AST 节点。
第二步:用目录结构加导入限制挡住跨层引用
演讲的第二个模式叫「用目录结构传递上下文」。Electron 应用里,Agent 常把主进程代码引进渲染进程,造成长任务和卡顿。团队的做法是建两个顶层目录,直接叫 electron-renderer 和 electron-main,两者之间的导入由依赖图分析器和 lint 规则禁止。
用 no-restricted-imports 的 patterns 就能实现最简版:
{
files: ["src/electron-renderer/**"],
rules: {
"no-restricted-imports": ["error", {
patterns: [{
group: ["**/electron-main/**"],
message: "渲染进程不能直接引用主进程代码,通过 src/shared/ipc 定义的通道通信。"
}]
}]
}
}
同样的思路适用于 Web 项目:服务端模块和客户端组件分目录,数据库客户端只许在 server 目录里出现。目录名本身就是说明,Agent 一看路径就知道自己在哪一层。
第三步:关掉行内豁免,管住注释
演讲里有个反直觉的观察:Agent 会把 Markdown、代码注释、规则文件当成「解释为什么不按正确方式做」的地方。上面那批定时器补丁旁边,就有大量注释在论证这次走捷径是合理的,后来的 Agent 读到也照着学。团队后来禁掉了 99% 的注释,理由有三:注释容易过时;人其实很少读;它给了 Agent 一个回避正确做法的出口,而且注释没法强制执行。
落到 ESLint 上,最直接的一步是让 Agent 没法用 // eslint-disable-next-line 把规则关掉:
{
linterOptions: {
noInlineConfig: true
}
}
noInlineConfig 打开后,文件里的行内配置和豁免注释都不再生效。确实需要例外的地方(比如框架内部允许用 useEffect),在配置里用 files / ignores 单独开一段,例外写在配置里,就能在 PR 里被看到、被审查。注释本身要不要全禁,可以按团队习惯来,ESLint 的 no-inline-comments 能先禁掉行尾注释这一类。
常见坑
- 只禁不给路。报错信息只写「禁止使用 X」,Agent 会换一种同样糟糕的写法绕过去。每条 message 都要指向推荐写法或项目里现成的封装。
- 以为 no-restricted-imports 能拦住所有导入。官方文档写明它只管静态 import,动态
import()不在范围内;importNames也拦不住React.useEffect这种从默认导入上取成员的写法,所以上面多加了一条 syntax 选择器。 - 加了规则不清旧账。演讲的建议是先加 lint 规则阻止新增,再把旧写法清掉。旧代码留着,Agent 读到的「惯例」还是坏的那套,还会逼你给规则加一堆例外。
- 规则跑在编辑器里,没跑在门禁上。只在本地标红没有约束力,要放进 pre-commit 或 CI,error 必须让流水线失败。
验证是另一半
静态规则挡住已知的坑,剩下的靠验证。演讲里团队的代码审查已经缩成看验证材料:录屏、截图、图表、形式化验证结果。他们给 Agent 准备了一份「功能地图」,从用户视角列出应用里所有功能,相当于共享词汇;还在 Skill 里放了自定义 CLI,让 Agent 每次复用同一个驱动,省 token 也能测试。主要用户流程用 TLA+ 做模型检查,自研虚拟列表库用 Lean 证明不会闪烁抖动。讲者说自己大部分 token 都花在验证上。
站内有两篇可以接着看:Agent 完成证据怎么留 讲录屏和截图怎么写进 PR,形式化验证与状态图 Skill 讲怎么让 Agent 画出状态机来审。
完成标准
- 最近一个月你在对话里纠正过 Agent 的问题,至少有 3 条变成了 ESLint error,每条都带修复指引;
- 跨层导入有目录约定和
no-restricted-imports双重约束; noInlineConfig已打开,所有例外都写在eslint.config.js里;- CI 里 lint 失败会挡住合并,AGENTS.md 里删掉了已经被规则覆盖的那几句。
最后
翻一下你的 AGENTS.md 或 CLAUDE.md,找出所有以「不要」「禁止」开头的句子,挑一条最常被违反的,今天就把它改写成一条 ESLint 规则。