教程2026-11-15 · 智涌AI

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

把对 Agent 的纠正写成 lint 规则的教程头图:左侧大字「纠正一次 写一条 lint」与月合并 1.1 万 PR、回滚 0.5%、禁掉 99% 注释数据卡;右侧对比表展示 useEffect、定时器补丁、行内豁免从文档提醒改为 ESLint 规则

你纠正了 Agent 一次「别在组件里乱用 useEffect」,它记住了这一轮;换个会话、换个 Agent,同样的写法又出现在 PR 里。AI Engineer 频道 11 月发布的演讲《All Code Is Slop (Except Mine)》给了一个很实在的办法:每纠正一次,就把它变成一条会报错的检查,而不是往 AGENTS.md 里再加一行字。讲者所在的 SpaceXSI Grok Bot 团队,上个月合并了约 1.1 万个 PR,回滚比例稳定在 0.5% 左右。这篇把演讲里的方法落到 ESLint 配置上,给出能直接改的规则写法。

前置条件

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 能先禁掉行尾注释这一类。

常见坑

验证是另一半

静态规则挡住已知的坑,剩下的靠验证。演讲里团队的代码审查已经缩成看验证材料:录屏、截图、图表、形式化验证结果。他们给 Agent 准备了一份「功能地图」,从用户视角列出应用里所有功能,相当于共享词汇;还在 Skill 里放了自定义 CLI,让 Agent 每次复用同一个驱动,省 token 也能测试。主要用户流程用 TLA+ 做模型检查,自研虚拟列表库用 Lean 证明不会闪烁抖动。讲者说自己大部分 token 都花在验证上。

站内有两篇可以接着看:Agent 完成证据怎么留 讲录屏和截图怎么写进 PR,形式化验证与状态图 Skill 讲怎么让 Agent 画出状态机来审。

完成标准

最后

翻一下你的 AGENTS.md 或 CLAUDE.md,找出所有以「不要」「禁止」开头的句子,挑一条最常被违反的,今天就把它改写成一条 ESLint 规则。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。