🔶 我删除了 16.8 万行注释，我的 AI Agent 毫无察觉
英文标题：🔶 I Deleted 168,000 Lines of Comments. My AI Agent Didn't Notice
作者从代码库中删除了约 16.8 万行注释，并让 Claude Code 在保留注释和移除注释的两个版本上分别完成相同任务、各运行三次。所有运行均通过 lint、类型检查、现有测试以及大任务中的隐藏测试，AI 评审给出的代码质量评分也处于误差范围内。小任务中，移除注释后 Agent 的 token 消耗减少约 22%；大任务的成本与 token 差异则没有明显统计意义。作者认为，注释是否保留应服务于阅读代码的人，而非为了帮助 AI Agent；但项目文档和 AGENTS.md 对 Agent 的影响可能更大。
3.2 KB
7.9 KB
51.3 KB
8.3 KB
中文
我们的源代码中，近三分之一是注释。我删除了全部注释，并要求一个 AI Agent 在两个版本的代码库中分别构建相同功能，每个版本各执行三次。无论是否保留注释，它写出的代码质量都同样好。
如果你在真实代码库中使用 Agent，并想知道注释究竟能帮助它们、拖慢它们，还是根本无关紧要，以下是我的发现。
我为什么进行这项测试
在这段视频中（约 23:07），Lauren提到，他们不允许 Agent 在代码中编写注释。我们的代码库则恰恰相反：其中充满了注释，而且大部分是由 Agent 编写的。
因此我开始思考：这些注释究竟是在帮助 Agent，还是只是增加了它需要阅读的额外文本？
用一段话说明实验
我复制了一份代码库，并删除其中的所有注释，合计约 16.8 万行。随后，我在两个版本中将相同任务交给同一个 Agent，每个版本各运行三次，并以相同方式检查结果。我针对两个任务进行了这一测试：一个小任务和一个较大的任务。
结果
每次运行都通过了所有检查：lint、类型检查和现有测试；对于较大的任务，还通过了一个 Agent 从未见过的隐藏测试。另有一个独立的 AI 评审器在不知道结果来自哪个代码库副本的情况下，对每个结果进行了评分（下文会进一步说明）。
小任务：平铺所有打开的窗口（满分 19 分）
| 分支 | 得分 | Tokens | 成本 |
|---|---|---|---|
| 保留注释 | 18.3 | 2.18M | $1.42 |
| 移除注释 | 19.0 | 1.71M | $1.04 |
较大任务：让窗口保持置顶（满分 23 分）
| 分支 | 得分 | Tokens | 成本 |
|---|---|---|---|
| 保留注释 | 21.7 | 9.06M | $3.84 |
| 移除注释 | 22.0 | 9.12M | $3.95 |
这些数字均为三次运行的平均值。得分差异处于噪声范围内，较大任务的成本差异也是如此。对于小任务，在没有注释时，Agent 使用的 token 少了约 22%，这很合理：因为它要读取的内容确实更少。
较大任务中设置了一个陷阱。置顶状态必须在页面重新加载后继续保留，而保存窗口会话的 PHP 函数会丢弃所有它不认识的键。如果漏掉这一点，功能在重新加载前看似正常，但一旦刷新页面就会失效。这正是你会预期注释能够提供帮助的那类问题。六次运行全部发现了这个问题，无论是否有注释。
为什么一次运行并不够
我最初计划让每个分支只运行一次。很庆幸我没有这么做。
在较大任务中，保留注释的三次运行分别使用了 8.21M、8.79M 和 10.17M tokens。移除注释的三次运行则分别使用了 7.01M、9.70M 和 10.64M tokens。
如果我从每个分支中各挑选一次运行结果，就能写出两篇结论完全相反的博客文章。比较 10.64M 与 8.21M，删除注释会让 Agent 成本增加 30%。比较 7.01M 与 10.17M，删除注释又会让 Agent 成本降低 31%。同一个任务、同一份代码、同一天。
Agent 并非确定性的。如果你要衡量一个 Agent，请不要只运行一次。
我是如何执行测试的
- **Agent：**使用高努力程度设置的 Claude Code 与 Opus 5.5。每次运行使用相同的模型和设置。
- **两个代码库：**我们的主分支，以及一个删除注释后的副本。我编译了两者，并确认生成的代码完全一致。仅保留了工具正常运行所需的注释，例如 lint 指令和插件头信息，约 800 行。
- **任务：**两个真实功能，在两个分支上使用完全相同的提示词。
- **检查：**项目自身的 lint、类型检查和测试。对于较大任务，我还在 Agent 完成后增加了一个隐藏测试，因此它无法通过专门编写代码来通过该测试。
- **评审器：**一个独立的 Claude 会话会阅读每项改动，并按照运行前编写的检查清单进行评分：功能是否正常、是否遵循项目约定、是否包含测试，等等。这些改动被赋予随机名称，因此评审器不知道每项改动来自哪个分支。
- **运行：**每个任务中，每个分支各运行三次，并交替运行两个分支，以便一天中不同时间的影响能同等作用于两者。
我的结论
对于 Agent 而言，代码注释不会影响它写出代码的质量。它们既没有帮助，也没有伤害。
因此，是否保留或删除注释，应当取决于它对阅读代码的人有什么作用，而不是为了 Agent。
这并不能证明注释的影响绝对为零。我只测试了一个模型、两个任务，以及每个分支三次运行；这足以排除显著影响，但不足以排除微小影响。
**接下来：**注释没有带来差异，但移除我们的 docs/ 文件夹和 AGENTS.md 则产生了影响。这将是下一篇文章的主题。
附录：数据与链接
| 保留注释 | 移除注释 |
|---|---|
| 整个仓库 | 765,491 |
| 插件源代码 | 408,527 |
插件源代码是指随插件一同发布的代码（src/、includes/、apps/ 以及 CSS），不包括测试、文档或工具代码。
English / 原文
Almost a third of our source code was comments. I deleted all of them and asked an AI agent to build the same features on both versions of the codebase, three times each. The code it wrote was just as good with or without comments.
If you use agents on a real codebase and wonder whether comments help them, slow them down, or don’t matter, here’s what I found.
Why I tried this
In this video (around 23:07), Lauren mentions that they don’t let their agents write comments in the code. Our codebase, is the opposite: it’s full of comments, and most of them were written by agents.
So I wondered: are all those comments helping the agent, or are they just extra text it has to read?
The experiment in one paragraph
I made a copy of the codebase with every comment removed, about 168,000 lines in total. Then I gave the same task to the same agent on both copies, three times on each, and checked the results the same way. I did this for two tasks, a small one and a bigger one.
The results
Every run passed every check: lint, type checks and the existing tests, plus, on the bigger task, a hidden test the agent never saw. A separate AI judge scored each result without knowing which copy it came from (more on that below).
Small task: tile all open windows (score out of 19)
| Branch | Score | Tokens | Cost |
|---|---|---|---|
| With comments | 18.3 | 2.18M | $1.42 |
| Without | 19.0 | 1.71M | $1.04 |
Bigger task: keep a window on top (score out of 23)
| Branch | Score | Tokens | Cost |
|---|---|---|---|
| With comments | 21.7 | 9.06M | $3.84 |
| Without | 22.0 | 9.12M | $3.95 |
The numbers are averages of three runs. The score differences are within noise, and so is the cost on the bigger task. On the small task, the agent used about 22% fewer tokens without comments, which makes sense: there was simply less to read.
The bigger task had a trap. The pinned state has to survive a page reload, and the PHP function that saves the window session drops any key it doesn’t know. Miss it and the feature looks fine until you reload. That’s exactly the kind of thing you’d expect a comment to help with. All six runs found it, with and without comments.
Why one run is not enough
My first plan was to run each branch once. I’m glad I didn’t.
On the bigger task, the three runs with comments used 8.21M, 8.79M and 10.17M tokens. The three runs without comments used 7.01M, 9.70M and 10.64M.
If I had picked one run from each branch, I could have written two opposite blog posts. Comparing 10.64M with 8.21M, removing comments makes the agent 30% more expensive. Comparing 7.01M with 10.17M, it makes the agent 31% cheaper. Same task, same code, same day.
Agents are not deterministic. If you’re measuring one, run it more than once.
How I ran it
- The agent: Claude Code with Opus 5.5 at high effort. Same model and settings for every run.
- The two codebases: our main branch, and a copy with the comments removed. I compiled both and checked that the resulting code is identical. The only comments left are the ones the tools need to work, such as lint directives and plugin headers, about 800 lines.
- The tasks: two real features, with the same prompt on both branches.
- The checks: the project’s own lint, type checks and tests. On the bigger task, also a hidden test I added after the agent finished, so it couldn’t write code just to pass it.
- The judge: a separate Claude session read each change and scored it against a checklist written before the runs: does it work, does it follow the project’s conventions, does it have tests, and so on. The changes were labelled with random names, so the judge didn’t know which branch each one came from.
- The runs: three per branch per task, alternating branches so that time of day affected both equally.
My conclusion
For the agent, code comments don’t make a difference to the quality of the code it writes. They don’t help, and they don’t hurt.
So keep a comment or delete it based on what it does for the people reading the code, not for the agent.
This doesn’t prove comments have zero effect. I tested one model, two tasks and three runs per branch, which is enough to rule out a big effect, not a small one.
Next: comments made no difference, but removing our docs/ folder and AGENTS.md did. That’s the next post.
Appendix: data and links
| With| Without
---|---|---
Whole repository| 765,491| 597,332
Plugin source code| 408,527| 280,421
Plugin source code means the code that ships in the plugin (src/, includes/, apps/ and the CSS), without tests, docs, or tooling.