Context Rot in AI-Assisted Software Development: Repurposing Documentation Consistency for AI Configuration Artifacts
Christoph Treude, Sebastian Baltes
cs.SE, cs.AI
2026-06-08
把现成的README一致性检查器DOCER原样套到CLAUDE.md一类配置上，抽样356个仓库里23.0%已有过期代码引用，50条抽检中64%是真漂移。
写给编码助手的仓库级配置，CLAUDE.md、AGENTS.md、.cursorrules 一类，已经变成跨会话的持久上下文。文件里会写认证逻辑在哪个路径、主 API 客户端叫什么、某个脚本还在不在。代码继续改，这些描述经常不改。模型于是去 import 已删模块、遵守团队早丢弃的约定，而且不一定报错。
作者把这种配置与代码库、工具、架构、约定之间的逐渐偏离叫做 context rot。术语原先多用来形容上下文窗口变长后模型有效回忆下降；这里把它伸到仓库里版本化、会自动喂给模型的配置工件。问题本身并不新。软件工程社区查 README、注释、API 文档、架构描述、安装说明和代码是否一致，已经做了二十年。这篇的主张很具体：那套工具箱可以直接拿来侦测 AI 配置腐烂。
经验部分只覆盖一种腐烂：referential rot，配置文件指向仓库里已经不存在的函数、类、常量、脚本或路径。数据来自 Galster 等人收集的 GitHub AI 配置语料。去掉空文件和纯指针文件、并要求记录首次提交 SHA 之后，候选是 4,420 个仓库。随机抽 356 个（seed 42），覆盖其中全部配置文件，共 612 个文件，按 95% 置信水平、5% 误差设计成对合格总体的代表样本。
检测器是 DOCER，原本给 README 和 wiki 用的正则抽取加双快照核对。流程刻意不调参：在 HEAD 抽取候选标识符，到配置文件首次提交时的源码里确认当时存在，再到当前 HEAD 再搜一遍。当时有、现在没有，记为过期；两边都没有当噪声丢掉。搜索范围排除 README 和各类 AI 配置文件，避免文档引用文档。作者明确说目标不是改进 DOCER，而是看传统文档一致性工具不改规则能不能在新工件上开火。
DOCER 抽出 29,454 个候选，首次提交时能对上源码的有 18,048 个。其中 17,818 个在 HEAD 仍在，230 个过期，分布在 82 个仓库，占样本 23.0%（95% CI 18.8–27.2%）。受影响仓库的过期引用中位数是 1，最多 20。按文件类型看，每条已验证引用的过期率大约 1.0% 到 1.4%，作者未做显著性检验。
一人抽检 50 条被标过期的元素：32 条（64%）是真的引用腐烂，12 条假阳性，6 条含糊。假阳性多半是正则把普通英文词或泛化 token 当成标识符。作者同时指出两个方向相反的偏差：双快照设计漏掉配置文件后续编辑才引入的引用，会压低估计；宽正则带来的假阳性会抬高估计。所以 23.0% 被当成可行性信号，不是精确流行率。
| 指标 | 数字 |
| 抽样仓库 / 含过期引用 | 356 / 82（23.0%） |
| 已验证引用 / 过期 | 18,048 / 230 |
| 50 条人工抽检真腐烂 | 32/50（64%） |
对已经在仓库里维护 CLAUDE.md 的团队，这不是一篇新算法论文，是一张立刻能跑的检查单。两快照 git grep 可以进 CI，抓住重命名函数、删掉的脚本、失踪的依赖。把配置文件当代码审，重构时一起改，能挡住很大一块引用腐烂。路线图还把注释一致性、API 文档检查、架构追踪、安装/依赖检查分别映射到行为指令、MCP 工具描述、架构声明和运行时版本，并列出四个研究问题：腐烂有哪些类、哪些老工具能原样迁移、哪些腐烂真的改模型行为、怎么修。
这是短文加路线图，经验证据只覆盖引用腐烂一种。DOCER 的过期定义要求元素在配置首次提交时存在，后续写入的引用全部在视野外。人工抽检只有一名标注者，没有一致性。样本限于公开 GitHub 且已有 AI 配置的仓库。更关键的缺口是行为：配置过期之后，助手输出到底差多少，这篇没有做。Lulla 等人证明过 AGENTS.md 存在与否影响耗时和 token，过期引用的因果实验仍写在 RQ3 里。