同一个坑不再犯第二次:把 AI 编码教训变成自动检查 | 杨元超的世界

读者是谁

这篇写给拿 AI 结对写代码、被「同一个错误犯第二次」折磨过的独立开发者与小团队——教训不是没记下来,是记下来的地方没人看。下面这张表按角色列出你能带走什么、从哪节开始读:

读者 带走什么 拿它做什么 从哪节开始读
老被同一个坑绊住的人 教训四字段模板 把最近一次重复犯的错写成条目 3
想给仓库加自动检查的人 四类判断标准的取舍 按教训的形态选文本匹配、跑命令或人工复核 4
负责提交纪律的人 30 行提交范围脚本 插进 git add 与 commit 之间 5

只想找 AI 提示词模板的人不必读。

0 本文讲什么

这篇只讲一件事:把踩过的坑从「写在文档里」搬成「机器执行」。改造的方向很具体——原来靠人记,现在靠脚本拦。下面这张概览表说明每节讲什么、读它能得到什么:

小节 讲什么 读它能得到什么
1 安装与准备 一个零依赖的 Node 环境
2 三个真实事故 分清「知道了」和「被拦住了」
3 教训条目四字段 让一条教训可被执行
4 四类判断标准 选对检查形式
5 已知答案自验与提交范围脚本 两段可直接用的代码
6 坑表 对号入座

1 安装与准备

后面所有示例只用 Node 18 以上的内置模块和 git,npm install 一行都不用跑。先确认两条命令能打印版本号:

node --version                    # 需要 v18 以上,代码里用到 node: 前缀
git --version                     # 判断提交范围要读 git 的暂存区
git rev-parse --show-toplevel     # 确认当前目录在仓库里

检查脚本最后要挂进 git 钩子(在特定 git 动作前后自动执行的脚本),所以 git 是必需的;node --version 出来的版本号低于 18 时,node: 前缀的内置模块导入会直接报错。

2 三个事故:教训写下来了,还是照犯

原来怎么做:教训写在文档和笔记里,执行方式是「下次记得看一眼」——也就是没有执行方式。现在怎么做:把教训挂到必经动作上(提交前、构建入口、测试入口),失败时用退出码(进程结束时返回给调用方的数字,0 表示成功、非 0 表示失败)表达。转化的链路固定四步:教训 → 判断标准 → 脚本 → 退出码。

为什么这样有效:跳过检查的成本高于跑检查,人就没有「省掉这一眼」的余地。

三个事故只列关键:

下面这张表对比两种执行方式在三个维度上的差别:

改造前后差在哪(下表):

改动点 改造前 改造后
执行者 人,靠自觉 机器,挂在命令里
失败反馈 无,容易漏 退出码非 0,命令链中断
有效性证明 只能证明「我写过」 用构造输入证明「这次被拦了」

3 一条教训要写清什么

原来怎么写:一句话记「踩过什么坑」,比如「检查要按文件名过滤」。三个月后连自己都想不起当时指哪份脚本、为什么不能用目录前缀。 现在怎么写:四个字段,写不进四字段的教训先不收录——写不进去通常意味着这条教训还没被想清楚。下表是四字段各自的作用和一个真实例子:

字段 作用 例子
触发场景 什么操作、什么代码形态下会遇到 改动落在插件目录,又跑了按目录过滤的检查
判断标准 机器怎么判「又出现了」 输出 PASS 而目标文件计数为 0
复发病史 上次违反的提交(前 7 位) 便于回放当时的输入
修法 改哪里、为什么能解决 过滤条件从目录前缀改成文件名匹配

差别在哪:一句话教训只有人能读,四字段能直接翻译成脚本题材;「判断标准」这一栏写不出机器可跑的判定,说明这条教训还停在感觉层面。

改造前后差在哪(下表):

改动点 改造前 改造后
记录形态 一句自然语言 四字段结构化
可执行性 靠人回忆上下文 判断标准可直译为脚本
收录门槛 想到就记 写不出判断标准就不收录

4 四类判断标准

原来怎么做:所有教训都写成文字,靠人比对。现在怎么做:按「怎么判最省事」分四类,能跑命令就不做文本匹配。下表是四类各自判什么、适合什么教训:

类型 判什么 适合
必须 0 命中 禁止性规则 不许留调试日志、不许写死某个数
必须存在 结构性规则 移动完成的回调里必须有再入判断(同一链未结束不许再进)
跑命令看退出码 逻辑正确性 自验、构建、类型检查
人工 语义判断 这个修法是否覆盖同类变体

文本匹配有两个实测陷阱。一是目录 glob(路径通配)被转成首尾全匹配后永远匹配不到文件——一次全仓扫查出 11 处这类目录匹配,全是空转。二是按目录前缀过滤会假绿(检查打印通过,实际一个文件都没测到)。下面这段代码先给反例、再给正例,跑完能看出「总数」和「逐文件计数」的差别:

# 反例:只打印总数,分不清「没有目标文件」和「真的没错误」
tsc --noEmit | grep -c "error TS"

# 正例:逐个文件打印
for f in ArmyUtils Move; do
  n=$(tsc --noEmit 2>&1 | grep -c "$f\.ts")
  echo "$f.ts 错行数: $n"
done

选择形式上的差别可以归成三点:

改造前后差在哪(下表):

改动点 改造前 改造后
判断形式 一律文本匹配 先看能否跑命令
空转风险 匹配不到也算通过 目标计数为 0 即判失败
覆盖范围 目录匹配大面积空转 文件名匹配跨目录唯一

5 已知答案自验 + 提交范围脚本

原来怎么做:检查脚本写完就信,从没测过它自己。现在怎么做:给每条检查加 --self-test(已知答案自验:喂构造好的输入,不读当前工作区);再给提交加一道范围检查。

为什么:检查会坏,而且坏了通常还是打印「通过」——路径判断少一个分隔符,就会把 dd/ 当成 d/ 放行。下面这段 20 行左右的自验把三种输入喂进同一个范围判断函数,跑完打印 PASS 或 FAIL:

// 已知答案自验:前缀判断必须带分隔符
const norm = p => p.replace(/\\/g, '/').replace(/\/+$/, '')
const inScope = (f, e) => {
  const a = norm(f), b = norm(e)
  return a === b || a.startsWith(b + '/')
}
const cases = [
  { staged: ['a.ts'],         expect: ['a.ts'], want: [] },
  { staged: ['a.ts', 'o.md'], expect: ['a.ts'], want: ['o.md'] },
  { staged: ['dd/x.md'],      expect: ['d'],    want: ['dd/x.md'] },
]
let bad = 0
for (const c of cases) {
  const got = c.staged.filter(f => !c.expect.some(e => inScope(f, e)))
  if (JSON.stringify(got) !== JSON.stringify(c.want)) bad += 1
}
console.log(bad ? 'self-test FAIL' : 'self-test PASS')
process.exit(bad ? 1 : 0)

跑完会看到 self-test PASS;把第 3 个用例的 want 改成空数组,它会变成 FAIL 并退出 1——这一步证明「自验自己会红」,不能省。

提交范围脚本的判断逻辑与上面同一个函数:读 git diff --cached --name-only,逐条比对本次声明的范围,越界退出 1。接线时把 git add、范围检查、git commit 写成三条独立命令——写成一条 && 链再配管道,管道会把失败退出码换成自己的。

改造前后差在哪(下表):

改动点 改造前 改造后
检查有效性 靠「跑过没问题」 自验用例 + 注入错误必须变红
越界提交 打印清单,人看着办 退出码 1 让命令链自己断
检查清单 散在目录里,谁写谁记得 登记表:名称 / 拦什么 / 命令 / 何时必跑

6 坑表

下表把四类坑按「什么场景遇到 → 为什么是坑 → 怎么解决 → 为什么能解决」列全,方便对号入座:

坑是什么 为什么是坑 如何解决 为什么能解决
按目录前缀过滤(场景:检查脚本加了目标目录参数) 目录之外的文件没进检查,0 个目标文件和真的 0 个错误分不清 改按文件名匹配,逐文件打印 文件名跨目录唯一,0 目标文件会立刻暴露
同一距离写两处(场景:新增一种目标体型) 两处各自合理,合起来停在阈值外 停靠距离从开火阈值反推,只留一处 改一处,天然同步
只打印不判定(场景:把检查串进发布或提交脚本) 打印不等于判定,管道还会覆盖退出码 范围脚本 + 三条独立命令 退出码是命令链唯一识别的信号
检查自身的承诺没实现(场景:脚本注释写了分支,代码没写) 一直宽松放行,看起来一直很顺 已知答案自验 自验不依赖工作区,能判对错

7 你下一步能做什么

翻出最近一次重复犯的错,写一条「必须 0 命中」的检查,挂到 pre-commit 里。一条就够。

这些内容来自哪里

这些内容来自一个真实项目里持续数月的教训沉淀:把反复犯的错逐条写成带判定标准的条目,再挑出其中能机械判定的部分做成检查,前后覆盖了几十条历史事故。文中的条数与命中数都是当时实测的结果。

相关文章