删掉16.8万行注释，我的AI Agent竟毫无察觉

一次删注释引发的思考

一位开发者在 Hacker News 上分享了他的实验：删除了项目中 168,000 行注释代码，而他日常依赖的 AI 编程助手（AI Agent）在后续工作中完全没有察觉这个巨大的变化。这个看似简单的操作，直接暴露了当前 AI 编程工具在代码理解深度上的一个关键盲区。

168,000 行是什么概念？按每行 80 字符计算，这大约是 1,300 万字符的文本被移除。对于人类开发者来说，注释承载着设计意图、业务逻辑说明和踩坑记录，删除它们等于抹去了项目的大量“隐性知识”。但 AI Agent 的反应是——继续正常工作，仿佛什么都没发生。

AI 到底“看”到了什么？

这件事的核心问题不在于 AI Agent 是否足够聪明，而在于它实际处理代码的方式。当前大多数 AI 编程工具的工作机制是：在需要时检索相关代码片段，将其作为上下文注入提示词，然后生成补全或修改建议。

这里有一个关键区别：注释对 AI 的价值和人类完全不同。人类读代码时，注释是理解意图的捷径；AI 读代码时，更倾向于依赖函数签名、类型定义、调用关系和命名模式这些结构化信号。注释在向量检索中的权重往往很低，甚至可能在预处理阶段就被当作“噪声”过滤掉。

这就解释了为什么删掉 16.8 万行注释后，AI Agent 依然能正常完成任务——它本来就没有把这些注释当作核心依据。

什么是向量检索？ 当前多数 AI 编程工具依赖的检索机制，核心是把代码片段（函数、代码块、注释等）通过嵌入模型转换成高维向量，再根据语义相似度返回与当前任务最相关的片段。这一过程存在几个隐患：其一，向量化时会丢失结构信息，一段逻辑复杂的代码可能被压缩成难以区分细节的向量；其二，相似度是相对的，注释与代码正文的语义距离往往较远，因此在排序中天然处于劣势；其三，检索的“目标”由生成阶段的需求决定，若模型没有主动意识到需要设计意图类信息，它就不会去检索注释。这三点叠加，解释了为什么注释被大量删除后，AI Agent 的检索结果和生成行为依然看起来“正常”——它本就主要依赖代码正文的向量信号。

什么是上下文窗口？ 上下文窗口指模型在一次推理中能够同时读取的 token 数量上限，常被误认为是“工作记忆”的总容量。实际上，它只是单次请求的输入上限，并不代表模型能持续记住整个代码库。开发者常有一种“虚假充裕感”：以为把上下文窗口开到足够大，模型就能理解整个项目。但窗口内塞入哪些内容，取决于检索和拼接策略，而非模型主动扫描。即便代码库中保存了全部注释，只要检索环节没有把它们挑出来，模型在生成时就等于没看到。因此，上下文窗口大小与“理解项目”之间并没有直接等号，真正决定理解质量的是检索、排序和注入方式。

这暴露了什么问题

上下文窗口的虚假充裕感。 很多开发者认为给 AI 足够大的上下文窗口，它就能“理解整个项目”。但这次实验说明，即使信息真的在代码库里，AI 也未必会主动利用。它检索的是它认为相关的部分，而注释恰恰不在它的关注优先级里。

知识传递的断裂。 注释中往往藏着代码本身无法表达的决策原因，比如“这里为什么不用更优雅的方案 B，因为方案 B 在某个边界条件下会崩溃”。当这些信息被删除，AI Agent 不会报警，但下一任接手的开发者或下一次 AI 生成的代码，可能就会踩进同一个坑。

Agent 缺乏全局感知。 一个真正的“智能体”应该能感知项目结构的重大变化。16.8 万行文本消失，代码库的检索索引、文件结构、甚至统计特征都发生了剧变。AI Agent 毫无反应，说明它并没有建立起对项目的持续全局认知，只是在进行局部模式匹配。

对开发者意味着什么

这不是说注释可以随便删。恰恰相反，结论正好相反：注释比很多人想象的更重要，但它的重要性主要体现在人类协作层面，而非 AI 理解层面。

如果你正在用 AI 辅助编程，这件事提示了几个实际做法：

第一，不要把注释当作“写给 AI 看”的内容。文档、设计说明、架构决策记录这些结构化程度更高的材料，对 AI 的价值可能更大。

第二，定期检查 AI 生成的代码是否真的理解了项目上下文。它可能在你删了大量注释后依然“表现正常”，但这不代表它理解了你的意图。

第三，考虑把关键设计决策从注释中抽离出来，放到独立的文档或知识库中，让 AI 能通过更明确的检索路径找到它们。

更深层的启示

Hacker News 上的讨论虽然简短，但指向了一个更大的议题：我们距离真正能“理解”代码库的 AI Agent 还有多远。

当前的 AI 编程工具擅长局部任务——补全一个函数、修复一个 bug、生成一段测试。但它们对项目的理解是碎片化的、被动的、检索驱动的。一个人类高级工程师会在事后的代码审查中发现“这个模块的注释怎么全没了”，而 AI Agent 不会，因为它从未真正“看过”整个项目。

这次实验的价值就在于，它用一个极端的、可量化的方式，把这个问题摆到了台面上。168,000 行注释的消失，人类会震惊，AI 无感——这个对比本身就值得每一个依赖 AI 编程的人认真想一想。