那些年我让AI补注释翻的车——存量正则和Shell脚本的正确打开方式
一、先说说常见的失败做法
接手过一个老项目的开发者，大概率都有这种体验：仓库里躺着几百行 Shell 脚本和一堆没人敢动的正则表达式。没有注释，没有文档，写代码的人早已离职，甚至 git blame 出来是「initial commit」。
于是很多人第一反应是：让 AI 一把梭。
失败姿势一：整文件直接丢给 AI，说「帮我加注释」。
结果往往是一份看起来很漂亮、实则毫无用处的注释。比如某个正则 ^(?:\d{1,3}\.){3}\d{1,3}(:\d+)?$,AI 注释成「匹配 IP 地址和可选端口」——正确，但没有说明这个正则在实际业务里是校验上游网关白名单的，失败时日志会落到哪个分支。通用解释谁都会写，业务语境才是存量代码注释的灵魂。
失败姿势二：接受 AI 的第一版输出，直接提交。
AI 有时会「顺手帮忙」：把 ${var} 改成 $var,把 grep -E 换成它认为更好的写法，甚至在注释里描述的是它脑补的理想行为而非脚本真实行为。你以为是加注释的 PR,实际上是隐性的重构 PR——出了问题都不知道该回滚哪一行。
失败姿势三：一次处理太多，没有验收环节。
一次性把几十个脚本全部注释完， reviewer 看不过来，草草合入。三个月后发现某条注释和代码行为完全对不上，反而制造了新的「信任债」：大家开始默认注释不可信，那这个注释就比没有更糟。
失败姿势四：只注释正则本身，不注释它为什么存在。
sed 's/\r$//' 这种，AI 会写「删除回车符」。但真正该记录的是「2019 年 Windows 同事提交的文件带 CRLF,导致 cron 任务静默失败过一次」。这种决策上下文，AI 不给材料是猜不出来的。
二、正确的路径：小批量、给语境、要求只读、留验收
核心原则一句话：AI 负责理解和初稿，你负责提供语境和验收，且明确禁止它改动代码。
我摸索出的流程分五步：
- 盘点存量。 先用一个简单脚本列出所有待注释文件，按「风险高(被 cron 调用、在生产链路上)」和「风险低(一次性工具)」排序。优先处理高风险的小文件，建立信心。
- 小批量投喂。 每次一个文件，或一组相关正则。附带上下文：这个脚本被谁调用、输入输出长什么样、已知的历史坑。
- 使用「只读模式」提示词。 明确要求 AI 不得修改任何代码字符，注释只能解释现状。
- diff 验收。 用
git diff -w检查除注释外是否有任何代码变动，有任何非注释改动一律打回。 - 业务知识回填。 AI 注释中标记为「不确定」的地方，找团队里最熟这段代码的人确认，或者用一段真实输入跑一遍验证 AI 的解释，再补上业务语境。
这样做下来，一个 200 行的部署脚本，从投喂到验收大概十分钟；人工从头啃，一小时起步还未必敢说自己全懂了。
三、用 AI 前后的对比
用 AI 之前：
- 新人接手脚本库，平均要花几天问人、试错；
- 正则改错一个字符，日志采集静默丢失，一周后才发现；
- 「这段为什么这么写」的答案只存在于某个离职同事的脑子里；
- 没人敢删没人敢动，脚本越攒越多。
用 AI 之后(流程跑顺之后)：
- 每个文件头部有职责说明、依赖清单、已知副作用；
- 复杂正则逐段拆解注释，并附带 2-3 个匹配/不匹配的示例；
- 注释中标注「此处行为依赖 GNU sed 特性，macOS 下不可用」这类可移植性陷阱；
- review 成本从「通读代码」降到「核对 AI 解释是否与行为一致」，对独立开发者来说就是自我验收时间大幅缩短。
关键变化不是「写得快了」，而是存量代码第一次变得可讨论、可交接。一个人维护的项目，也等于多了一个随叫随到、能读懂烂代码的搭档。
四、可复制的提示词模板
你是一位资深 Shell 与正则维护工程师。请为下面的存量代码补充注释。
严格遵守:
1. 只添加注释,禁止修改、格式化或"优化"任何一行原有代码,包括空格;
2. 注释解释的是代码的真实行为,不是理想行为;不确定的地方标注 [待确认];
3. 文件头部增加块注释,包含:脚本职责、输入输出、依赖的外部命令、已知风险;
4. 对每个正则表达式,逐段拆解含义,并给出 1-2 个能匹配和 1 个不能匹配的示例;
5. 指出可移植性问题(如 GNU/BSD 差异)、边界情况和潜在的静默失败点;
6. 输出完整代码,并在最后单独列出"我无法确定、需要人工确认的点"。
背景信息(供理解,不要写进注释):
- 该脚本的调用方:{cron/CI/手动}
- 运行环境:{系统/SHELL 版本}
- 已知历史问题:{没有可写"无"}
代码:
{粘贴代码}最后一条「单独列出待确认点」特别有用——它把 AI 的不确定性显式化了，你可以只花精力核对这几处，而不是逐行怀疑。
五、几句提醒
- 模型选择上，处理这类任务建议用能力较强的模型，具体价格以官网价格页为准，注释这类一次性投入，质量优先于成本。
- 涉及敏感信息的脚本，投喂前先做脱敏。
- 注释合入后，让下一个读的人顺手校对——注释的可信度是靠持续维护建立起来的。
存量代码不会自己开口说话，但有了流程和工具，AI 能替你把它「翻译」出来。如果你打算动手试试，可以先在 https://api.thistoken.ai/register 注册一个账号，拿仓库里最头疼的那个脚本练手——从失败姿势里爬出来的最好方式，就是用正确姿势再跑一遍。
---
不想折腾多家供应商的接入差异？在 https://api.thistoken.ai/register 注册，用一个 base_url 调用所有模型。