## Three Mistakes I Made First

Three Mistakes I Made First

When I took over a risk control system that had been running for five years, the repository contained more than two hundred regular expressions and dozens of Shell scripts. No comments, no documentation, and the people who wrote the code had long since left. Looking back now, every step of my initial approach was wrong.

Mistake one: Asking AI to "rewrite everything" in one shot. I threw the entire script directory at the model and said "refactor this and add comments." The returned code was indeed beautiful, with comprehensive comments—but it also "optimized" several pieces of logic along the way, changing a check that depended on the system timezone to a standard implementation. That "non-standard" code existed precisely to accommodate an old server with a modified timezone. The night we went live, alarms went off, and I rolled back at three in the morning.

Mistake two: Only asking AI to add comments, not to explain "why." The second time, I learned my lesson—comments only, no code changes. The comments AI returned looked like this: # Matches strings starting with a digit. Technically completely correct, and completely useless. Because I already knew what it matched; what I didn't know was: which class of attacks this regex was meant to block, why it used ^ instead of \A, why the capture group only took the second segment. This kind of "syntax-translation comment" might as well not exist.

Mistake three: Trusting AI to understand a regex with no context. For a 300+ character email header validation regex, AI confidently provided comments. I verified it with three boundary test cases and found that its understanding of a (?!...) negative lookahead was backwards. AI wasn't lying—it simply tends to produce a "plausible-looking" answer when information is insufficient.

After falling into these three pits, I understood one thing: when writing comments for legacy code, the hard part is never "writing"—it's "verification." AI writes fast, but if no one checks its work, comments become another form of lie—more dangerous than having no comments at all, because people who come after will believe them.

The Process That Finally Worked

I broke the entire process into four steps, with the core principle: AI is responsible for "explaining," I'm responsible for "adjudicating," and running results are the ultimate source of truth.

Step one: Inventory assets, categorize before acting. Write a simple script that sorts all regexes and Shell scripts into three tiers based on "still referenced, last modified time, length/complexity": active and complex (handle first), active but simple (batch process), suspected dead (flag only, don't touch). This step prevents wasting effort on dead code—I once spent half an hour carefully writing comments for logic that had been decommissioned long ago.

Step two: Item-by-item explanation + reverse verification. This is the key to the whole process. Instead of having AI write comments directly, have it do two things first:

1. Explain in natural language the intent of this regex/script;
2. Automatically generate 5-10 test cases, which must include boundary cases (empty input, extra-long input, special characters, multi-byte characters).

Then I run these cases in the actual environment, or cross-check against historical logs. Only when AI's explanation matches the real behavior do we proceed to the next step; if they don't match, I feed the discrepancy back to AI for reanalysis. That email header regex was exposed at this step—among the generated cases was a legitimate email that AI predicted would not match, consistent with production behavior, proving its earlier explanation was indeed wrong. Only after correcting it did I get reliable comments.

Step three: Write comments in two layers. I require AI to distinguish between "what" and "why":

• Inline comments: explain syntax and behavior, for future maintainers;
• Header comments: record business context, known boundaries, and verified test cases.

The fourth step is the most valuable: have AI turn the verified cases into executable test files. This way, comments aren't just text—they come with "living evidence." Six months later, if anyone doubts whether a comment is outdated, running the tests settles it.

Step four: Human final review, risk-tiered. For code involving security, money, or permissions, I personally review every comment; for utility scripts, spot checks suffice. AI compressed the initial review time from days to hours, and I spend the saved time where human judgment is genuinely needed.

Before and After

More important is the change in mindset: these legacy code used to be a "minefield no one dared to touch"; now every mine has a sign next to it, explaining why it's a mine, under what circumstances it will blow up, and how to verify it.

A Reusable Prompt Template

你是一位资深代码考古专家。我会给你一段存量正则表达式或 Shell 脚本,
请严格按以下步骤处理,不要跳步:

1. 【解释】用自然语言说明这段代码的行为和可能的业务意图。
   对不确定的部分,明确标注"推测",不要编造确定的解释。
2. 【用例】生成 5-10 个测试输入,必须覆盖:空输入、超长输入、
   特殊字符、多字节字符、以及你认为最容易被误判的边界情况。
   对每个用例,给出你预测的执行结果。
3. 【风险】指出这段代码中语法上可能产生歧义或历史遗留的写法。
4. 【注释】待我确认第1-3步与实际行为一致后,再输出两层注释:
   - 头部注释:业务背景、边界说明、验证过的用例
   - 行内注释:解释语法和行为,不重复代码本身
规则:禁止修改任何代码逻辑;禁止在未验证前输出最终注释。

待处理代码:
{粘贴你的正则或脚本}
{可选:补充这段代码的调用场景或历史背景}

The core of the template is the line "output comments only after I confirm"—it forces the process into three stages: "AI explains → human verifies → AI writes," closing the door on AI confidently fabricating answers.

A Few Reminders

• For model selection, use models with strong reasoning capabilities for complex regexes; lightweight models are sufficient for commenting simple scripts—the cost difference is significant (refer to the official pricing page);
• Be especially careful with Shell scripts—logic involving rm, pipes, and environment variables must be verified in a sandbox environment; never trust any output that "looks right";
• Finishing the comments isn't the end. Only by incorporating them along with the test cases into CI can they stay fresh long-term.

When it comes to commenting legacy code, every year you delay adds another year of debt. AI can't repay the debt for you, but it can reduce the cost of "archaeology" to one-tenth of doing it yourself—provided you always hold the final verdict.

If you're looking for a stable AI API that supports switching between multiple models for this kind of code maintenance work, you can try this gateway: https://api.thistoken.ai/register

---

Tired of juggling provider integrations? Register at https://api.thistoken.ai/register and call every model through one base_url.