假设开发者只要求修复缓存淘汰竞态。Coding Agent 读到同一文件里的旧 TODO,发现它指向替换序列化器的工单,于是搜索更多模块,改了序列化接口,还补了一组测试。代码可能有价值,任务仍然越界了。
这类问题很难靠一句不要扩大范围解决。TODO 离代码近,写法像动作,工单号又能继续检索。对 Agent 而言,它比一份遥远的历史记录更像当前指令。
Google 在 2026 年 11 月发布的 Agent Distraction 报告说明,这已经可以被观测和分类。真正需要治理的是两种漂移:注释与真实工单状态之间的状态漂移,以及注释内容与用户请求之间的任务漂移。
一组内部数据,两个不同问题
Google 报告称,在数百万个内部文件读取会话中,13% 遇到带工单引用的 TODO 或 FIXME。每 100 次这类遭遇中,约有 6 次出现针对同一工单号的后续行动;这些行动里,83% 没有来自开发者的要求。
未经要求的偏航又分成三类:
- 41% 指向已经关闭的死路。其中 32% 已修复或验证,9% 已废弃或明确不处理。
- 57% 指向仍开放的工单。问题可能真实存在,但不属于当前请求。
- 2% 指向重复或受限工单,不能按普通当前工作处理。
第一类是状态过期,第二类是授权缺失。把仓库里的过期 TODO 全部清完,只能缓解第一类。只检查工单是否开放,也挡不住第二类。
Google 还报告,在控制开发者、代码库复杂度、任务类型、模型等级、读取文件数、初始 Prompt 长度和首次遇到工单的步骤后,未经要求的偏航与步骤增加 70%、Token 增加 77%、等待时间增加 105% 相关,p 值低于 0.0001。
这是内部观测,不是外部团队的收益预测。公开页面没有提供原始数据、完整系数表、置信区间或独立复现。稳妥用法是把它当成风险信号和测量模板,不能把删除 TODO 写成节省 77% Token 的因果承诺。
先建一张状态矩阵
Google 当前的 C++ 风格指南要求 TODO 附上工单、负责人或其他可检索标识,同时明确 TODO 不代表被提到的人承诺修复。
这说明注释更像一份靠近代码的缓存指针。当前事实仍在工单系统里。维护者可以把每条结构化标记放进下面的矩阵:
| 工单当前状态 | 与本次请求的关系 | 默认动作 |
|---|---|---|
| 已关闭,注释意图也失效 | 无关 | 提出最小删除,检查历史后送审 |
| 已关闭,注释仍解释兼容性或约束 | 相关或长期有效 | 改写成持久说明,去掉错误的待办语气 |
| 仍开放 | 完成当前请求必需 | 纳入任务并记录依据 |
| 仍开放 | 相邻但非必需 | 暂存或报告,不修改 |
| 重复或已被取代 | 任意 | 跟随新的权威工单重新判断 |
| 受限、ID 错误或系统不可用 | 未知 | 保留未知,进入复核队列 |
矩阵最重要的一格是开放但无关。它提醒 Agent:真实工作不等于已授权工作。
阶段一:建立可对账库存
扫描范围包括代码、测试、配置和仍在使用的设计文档。除了 TODO 和 FIXME,还应覆盖 HACK、XXX、弃用说明和工单 URL。
每条记录至少保存:
- 仓库、路径、行号和当前文件哈希;
- 标记类型、原文和规范化工单 ID;
- 注释年龄、最后修改提交和代码所有者;
- 工单当前状态、可见性和最后更新时间;
- 与当前代码是否仍有关系的证据。
自然语言 TODO 没有稳定 ID,自动判断能力更弱。它可以被扫描出来,但应单列为未解析,而非推断成已完成或无效。
Google 说,它的清理 Agent 不会看到关闭状态就直接删。系统还会检查工单历史、文件历史和代码变化,只有确认 TODO 及其原始意图都已过期,才提交删除变更。六个月内,Google 自报删除了数千个确认过期引用,人工审核接受率超过 95%。这个结果支持该流程在 Google 内部获得了较高的人工审核采纳率,不能替代其他仓库自己的验证。
阶段二:让 Agent 显式判定支线
库存治理解决历史债,运行时还要处理今天才遇到的注释。Agent 一旦准备围绕非请求工单继续检索或修改,Harness 应要求它先回答四个问题:
- 用户要完成的结果是什么?
- 这个 TODO 是完成结果的必需依赖,还是相邻问题?
- 当前准备做的是读取、报告、改代码,还是更新外部状态?
- 继续行动需要哪一级授权?
输出可以压缩成一份判定记录:来源位置、工单当前状态、与请求的关系、拟执行动作和结论。结论只有继续、暂存、只报告、补证据四类。
读取公开工单通常风险较低,可以给一个有界的调查额度。修改代码、更新工单或改变外部状态会形成副作用,应要求与当前任务存在更强关系。受限工单无法读取时,证据状态保持未知,不允许 Agent 根据注释语气猜测内容。
阶段三:用最终 diff 追责
推理过程再清楚,也可能在实际补丁里扩大范围。提交前需要把每个变更文件映射回三类依据之一:用户验收标准、完成任务所需依赖、已批准的范围扩张。
无法映射的文件进入阻断。审查者继续检查:
- 新增测试是在验证原问题,还是为偶遇 TODO 服务;
- 公共 API、配置和文档是否出现请求外变化;
- Agent 是否借重构之名改动了相邻模块;
- 最终报告是否掩盖了未获授权的顺手修复。
这一步与站内的提交门控使用同一原则:进入上下文的规则只能影响推理,真正产生副作用的动作还要经过独立验证。
维护团队怎样测,才不会被一个总分误导
至少保留两套独立记录。
运行记录回答 Agent 怎样偏航:符合条件的文件读取会话有多少,多少会话遇到结构化标记,多少次继续检索,多少次生成未经要求的支线,多少次尝试修改,多少次最终进入提交。
维护记录回答仓库怎样变干净:扫描到多少标记,多少成功联结工单,多少被判为过期,多少形成清理提案,多少被人工接受,多少后来回滚。
两套记录的对象、窗口和分母不同。接受的清理提案不能除以 Agent 暴露会话;全仓 TODO 数量也不能直接与某个模型的偏航率比较。
评测集应该覆盖几种相反案例:
- 已关闭且可以删除的注释;
- 已关闭但仍解释兼容性限制的注释;
- 开放且完成当前任务必需的工单;
- 开放但与当前任务无关的工单;
- Agent 无权读取的受限工单;
- 与更新后仓库规则冲突的旧 TODO;
- 邻近位置存在真实缺陷,只允许报告而不允许修复。
通过标准不是一律忽略 TODO。可靠行为是正确识别权限、保留未知,并让最终补丁停在授权边界内。
一份可直接采用的维护清单
每周或每个发布周期执行一次:
- 冻结本轮扫描范围和仓库版本。
- 解析结构化标记,单列无法解析和无法访问项。
- 联结工单当前状态,再检查文件和提交历史。
- 对确认过期项生成最小 diff,不夹带重构。
- 运行相关测试和代码所有者审查。
- 保存接受、拒绝与回滚原因,补进回归案例。
- 检查 Agent 轨迹中是否仍出现开放但越界的支线。
这份清单与用 Eval 安全删指令互补。Prompt 清理处理系统提示里的过期控制文本,仓库维护处理环境里的过期控制文本。两者都要保留历史、形成最小变更,并用回归检查证明真实约束没有随文本一起被删掉。
最终判断
TODO 既不是无害文本,也不是自动任务。它是一份权限较低、状态可能漂移的上下文指针。
维护者负责让指针可解析、可对账、可回收;Harness 负责判断它与本次请求的关系;提交门负责核对最终改动。三层同时工作,昨天留下的记录才不会在今天变成未经授权的支线。