存量脚本没人敢动的死结，我让AI花了三天解开

痛点：那些“能跑就行”的遗产

接手过一个五年老项目的开发者，大概都见过这种文件：一个 deploy.sh，两百多行，中间嵌着一条六十字符的正则，用来从日志里抽取版本号。写它的人早已离职，脚本每周定时跑，没人敢动一行——因为没人确定动了会坏什么。

我们团队的实际情况更典型：

• 仓库里有 30 多个 Shell 脚本和散落各处的正则表达式，绝大多数零注释；
• 每次排查定时任务失败，平均要花 40 分钟到 1 小时通读脚本、翻 Git 历史、猜变量含义；
• 新人上手只能靠口头传授，交接成本高，且传授过程本身就在消耗老成员的时间。

粗算一下：按每月 6 次排查、每次 50 分钟计，一个月就是 5 小时纯消耗，一年 60 小时——这还没算交接和新人的摸索时间。而请人重写这些脚本风险更大，性价比更低。

写注释，是唯一低风险高回报的方案。但它一直是“重要不紧急”，永远排不上期。

AI 使用流程：三步让存量脚本变得可读

我的做法很朴素，分三步，全程用一个统一格式的提示词模板。

第一步：批量清点。 用一个简单脚本扫描仓库，把所有 .sh 文件和代码里的正则表达式（grep/sed/awk 里的模式）列成清单。这步不涉及 AI，纯文件遍历。

第二步：逐条投喂 AI 生成注释。 把每个脚本或正则连同必要的上下文（它被哪个文件调用、输入输出示例）发给大模型，要求输出固定格式：逐段注释 + 正则的分解说明 + 风险点标注。关键是要求 AI 只做解释、不改代码——注释是文档，不是重构。

第三步：人工抽查入库。 挑最关键的 5 个脚本人工核对注释准确性，其余走 Code Review 流程合入。AI 的注释偶尔会“脑补”意图，比如把一个写错了但侥幸能跑的正则解释得很合理，这必须靠人兜底。

提示词模板如下，可直接复制修改：

你是一名资深 Shell 与正则表达式专家。请为下面这段存量代码写注释，严格遵守以下规则：

1. 只添加注释，不修改任何逻辑，即使你认为有 bug，也只注释不改动；
2. Shell 脚本：按逻辑分段，每段上方写 2-3 行中文注释，说明“做什么”和“为什么”；
3. 正则表达式：逐段拆解每个部分的作用，用如下格式：
   正则：xxx
   - ^\d+ ：匹配开头的连续数字，对应日志中的进程号
   - \.(tar|gz) ：匹配压缩包后缀
   整体作用：一句话总结；
4. 对有风险或难以理解的地方，单独加“⚠️ 注意：”前缀标注；
5. 如果代码行为依赖特定环境（如 bash 版本、文件路径），明确指出；
6. 输出格式：先给完整带注释的代码，再给一段 100 字以内的整体说明。

代码如下：
---
（粘贴脚本或正则，附上输入输出示例）
---

前后对比：时间账算给你看

以我们那批存量资产为样本，对比大致如下：

最直观的变化有两个。一是原来“排不上期”的事变成了茶余饭后就能推进的活——AI 生成初稿，人只做核对，门槛从“写”降到“审”。二是新成员交接时间明显缩短，以前要口头讲一下午的部署脚本，现在照着注释自己就能读通，老成员从“讲解员”变成了“答疑员”。

成本方面，这批脚本全量注释的 API 调用费用折算下来不到团队一小时的人力成本（具体计费以官网价格页为准）。相比省下的 30 多小时，这笔账怎么算都划算。

几条经验提醒

1. 别让 AI 改代码。 注释阶段的 AI 只做解释。它偶尔会把 bug 解释成 feature，注释里应保留“⚠️ 注意”标记，留给后续修复决策。
2. 给上下文比给提示词技巧重要。 附上一条真实的输入输出示例，正则注释的准确率会高很多。
3. 注释完成后趁热加测试。 有了注释，给关键脚本补最小可用的 smoke test 就容易了，下一步才谈得上安全重构。

存量代码的债务不会自己消失，但还债的成本可以被压到一个“顺手就做”的水平。如果你也想把这个流程跑起来，可以先注册一个 API 服务试试上面的模板：https://api.thistoken.ai/register

---

想直接跑通示例？访问 https://api.thistoken.ai/register 注册 ThisToken.AI，获取 API Key 后即可开始。