这篇写给拿 AI 结对写代码、被「同一个错误犯第二次」折磨过的独立开发者与小团队——教训不是没记下来,是记下来的地方没人看。下面这张表按角色列出你能带走什么、从哪节开始读:
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 老被同一个坑绊住的人 | 教训四字段模板 | 把最近一次重复犯的错写成条目 | 3 |
| 想给仓库加自动检查的人 | 四类判断标准的取舍 | 按教训的形态选文本匹配、跑命令或人工复核 | 4 |
| 负责提交纪律的人 | 30 行提交范围脚本 | 插进 git add 与 commit 之间 | 5 |
只想找 AI 提示词模板的人不必读。
这篇只讲一件事:把踩过的坑从「写在文档里」搬成「机器执行」。改造的方向很具体——原来靠人记,现在靠脚本拦。下面这张概览表说明每节讲什么、读它能得到什么:
| 小节 | 讲什么 | 读它能得到什么 |
|---|---|---|
| 1 | 安装与准备 | 一个零依赖的 Node 环境 |
| 2 | 三个真实事故 | 分清「知道了」和「被拦住了」 |
| 3 | 教训条目四字段 | 让一条教训可被执行 |
| 4 | 四类判断标准 | 选对检查形式 |
| 5 | 已知答案自验与提交范围脚本 | 两段可直接用的代码 |
| 6 | 坑表 | 对号入座 |
后面所有示例只用 Node 18 以上的内置模块和 git,npm install 一行都不用跑。先确认两条命令能打印版本号:
node --version # 需要 v18 以上,代码里用到 node: 前缀
git --version # 判断提交范围要读 git 的暂存区
git rev-parse --show-toplevel # 确认当前目录在仓库里
检查脚本最后要挂进 git 钩子(在特定 git 动作前后自动执行的脚本),所以 git 是必需的;node --version 出来的版本号低于 18 时,node: 前缀的内置模块导入会直接报错。
原来怎么做:教训写在文档和笔记里,执行方式是「下次记得看一眼」——也就是没有执行方式。现在怎么做:把教训挂到必经动作上(提交前、构建入口、测试入口),失败时用退出码(进程结束时返回给调用方的数字,0 表示成功、非 0 表示失败)表达。转化的链路固定四步:教训 → 判断标准 → 脚本 → 退出码。
为什么这样有效:跳过检查的成本高于跑检查,人就没有「省掉这一眼」的余地。
三个事故只列关键:
git add -A 与 git commit 之间只有一条打印命令,同一天吞进了另一个任务的 6 篇文章。下面这张表对比两种执行方式在三个维度上的差别:
改造前后差在哪(下表):
| 改动点 | 改造前 | 改造后 |
|---|---|---|
| 执行者 | 人,靠自觉 | 机器,挂在命令里 |
| 失败反馈 | 无,容易漏 | 退出码非 0,命令链中断 |
| 有效性证明 | 只能证明「我写过」 | 用构造输入证明「这次被拦了」 |
原来怎么写:一句话记「踩过什么坑」,比如「检查要按文件名过滤」。三个月后连自己都想不起当时指哪份脚本、为什么不能用目录前缀。 现在怎么写:四个字段,写不进四字段的教训先不收录——写不进去通常意味着这条教训还没被想清楚。下表是四字段各自的作用和一个真实例子:
| 字段 | 作用 | 例子 |
|---|---|---|
| 触发场景 | 什么操作、什么代码形态下会遇到 | 改动落在插件目录,又跑了按目录过滤的检查 |
| 判断标准 | 机器怎么判「又出现了」 | 输出 PASS 而目标文件计数为 0 |
| 复发病史 | 上次违反的提交(前 7 位) | 便于回放当时的输入 |
| 修法 | 改哪里、为什么能解决 | 过滤条件从目录前缀改成文件名匹配 |
差别在哪:一句话教训只有人能读,四字段能直接翻译成脚本题材;「判断标准」这一栏写不出机器可跑的判定,说明这条教训还停在感觉层面。
改造前后差在哪(下表):
| 改动点 | 改造前 | 改造后 |
|---|---|---|
| 记录形态 | 一句自然语言 | 四字段结构化 |
| 可执行性 | 靠人回忆上下文 | 判断标准可直译为脚本 |
| 收录门槛 | 想到就记 | 写不出判断标准就不收录 |
原来怎么做:所有教训都写成文字,靠人比对。现在怎么做:按「怎么判最省事」分四类,能跑命令就不做文本匹配。下表是四类各自判什么、适合什么教训:
| 类型 | 判什么 | 适合 |
|---|---|---|
| 必须 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 即判失败 |
| 覆盖范围 | 目录匹配大面积空转 | 文件名匹配跨目录唯一 |
原来怎么做:检查脚本写完就信,从没测过它自己。现在怎么做:给每条检查加 --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 让命令链自己断 |
| 检查清单 | 散在目录里,谁写谁记得 | 登记表:名称 / 拦什么 / 命令 / 何时必跑 |
下表把四类坑按「什么场景遇到 → 为什么是坑 → 怎么解决 → 为什么能解决」列全,方便对号入座:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 按目录前缀过滤(场景:检查脚本加了目标目录参数) | 目录之外的文件没进检查,0 个目标文件和真的 0 个错误分不清 | 改按文件名匹配,逐文件打印 | 文件名跨目录唯一,0 目标文件会立刻暴露 |
| 同一距离写两处(场景:新增一种目标体型) | 两处各自合理,合起来停在阈值外 | 停靠距离从开火阈值反推,只留一处 | 改一处,天然同步 |
| 只打印不判定(场景:把检查串进发布或提交脚本) | 打印不等于判定,管道还会覆盖退出码 | 范围脚本 + 三条独立命令 | 退出码是命令链唯一识别的信号 |
| 检查自身的承诺没实现(场景:脚本注释写了分支,代码没写) | 一直宽松放行,看起来一直很顺 | 已知答案自验 | 自验不依赖工作区,能判对错 |
翻出最近一次重复犯的错,写一条「必须 0 命中」的检查,挂到 pre-commit 里。一条就够。
这些内容来自一个真实项目里持续数月的教训沉淀:把反复犯的错逐条写成带判定标准的条目,再挑出其中能机械判定的部分做成检查,前后覆盖了几十条历史事故。文中的条数与命中数都是当时实测的结果。