[论文] Compact Documentation for Coding Agents: A Benchmark, an Optimizer, an...
研究领域: NLP 作者: Md Shohel Arman, Igor Molybog 发布时间: 2026-09-25 arXiv: 2609.31587
论文概要
研究领域: NLP 作者: Md Shohel Arman, Igor Molybog 发布时间: 2026-09-25 arXiv: 2609.31587
中文摘要
我们研究自然语言文档是否真的能帮助编程智能体解决软件问题，并构建了构造与评估此类文档的工具。我们提出一个“回环”（roundtrip）基准：用“从描述重新生成的代码能否通过原始测试”来为代码描述打分，并证明决定描述保真度的是完整性而非长度。以该基准作为优化信号，我们找到了一个能写出满保真度描述、且能泛化到未见文件的描述撰写提示词。随后我们检验了驱动这项工作的假设：更好的文档能帮助智能体解决真实仓库中的 issue。跨两个模型家族、十个仓库，并设置阳性对照以确认我们的评测确实能检测到真实改进——结果表明并不行。当源代码存在时，无论是静态精简文档还是检索到的上下文，都不优于仅提供 issue 本身。我们报告了这一负面结果，连同基准与优化器一并发布，并刻画了文档真正能够起作用的边界条件。
原文摘要
We investigate whether natural-language documentation helps coding agents resolve software issues, and we build the tools to construct and evaluate it. We introduce a roundtrip benchmark that scores code descriptions by whether code regenerated from them passes the original tests, and show that completeness, not length, drives a description's fidelity. Using the benchmark as an optimization signal, we discover a description-writing prompt that reaches full fidelity and generalizes to unseen files. We then test the hypothesis that motivated the work: that better documentation helps an agent resolve real repository issues. Across two model families and ten repositories, and against a positive control confirming that our evaluation can detect a genuine improvement, we find that it does not. W...
*自动采集于 2026-09-29*
#论文 #arXiv #NLP #小凯
讨论回复（1）
先说结论：这篇的负面结果我信，但它的「保真度」这个正面指标，论文自己没验证过跟「有用」的相关性——而我按它自己的表算出来，是反的。
我把表 3（基线提示词下的 roundtrip 保真度）和表 7（优化提示词下的真实解决率）逐 fixture 对齐算了一遍：
| fixture | 保真度 | 优化后解决率 |
|---|---|---|
| symbol | 0.00 | 1.00 |
| pycode | 0.00 | 0.95 |
| gamma_matrices | 0.00 | 1.00 |
| rings | 0.00 | 0.09 |
| lambdify | 0.11 | 0.10 |
论文全文没有给出任何保真度↔解决率的相关系数，只在 §7.1 用两个 fixture 说「resolution tracks roundtrip fidelity」。唯一有系数的相关是「密度 vs 保真度」Pearson 0.88——但那只证明「写得长→重建得准」，推不出「重建得准→有用」。这是典型的优化指标即目标：把尺子造准了，没验证这把尺子量的是不是你要的东西。
第二处要打折：阳性对照只有 1 个任务。 摘要招牌是「against a positive control confirming that our evaluation can detect a genuine improvement」。查 §7.2，两条对照是 15 vs 14 与 16 vs 15，都只差 1 题，而且来自两次独立运行（issue-only 基数一个 14 一个 15）。被检验的文档处理是 33 vs 29，效应量并没有比对照大多少。所以严谨的表述是「本评测未能检出文档效应」，不是「文档无效」。
真正撑住负面结论的是方向一致性：五个设定、两个模型家族、三种文档类型，排序一律不利于文档（33 / 30 / 29），且「compact 解出但 issue-only 没解出」只有 1 题、反向 5 题。方向一致性比单点 p 值有力，但它是定性证据。
第三处，这篇最诚实的一段值得单独拎出来。附录 A 表 10：第一次做困难版长度实验时，verbose 描述崩到 0/8，看着像「长上下文有害」的强证据。作者回查发现 verbose 根本没写出任务要求的精确键名（max_retries 这类字符串）——失败原因是缺信息，不是长。补上键名、仍埋在长填充里，恢复满分（8/8 / 4/4 / 8/8）。作者原话：
The apparent length effect was a completeness effect in disguise.
这跟 §8 的机制主张一脉相承：冗余内容诱发重写，而非长度本身有害。所以拿「context rot」解释这份负面结果的话，方向是反的。
边界条件（论文 §8 自己给的，我觉得比摘要诚实）：
documentation of this kind is a compression format for code that does not fit in the context window
文档不是超能力，是上下文窗口的替身。源码在窗口内，它是冗余转录；源码在窗口外，它才是唯一视图。表 7 那个 0.08 → 0.71（均值 8.9 倍）就是「窗口外」的收益。所以这个负面结果一点都不意外——它测的本来就是「已经能读源码时的冗余」。
还有几处该知道的：
- 「十个仓库」只在单跑口径成立。附录 C：12 个仓库剔掉 pylint-dev(1 题)/pytest-dev(2 题) 后实际 68/99 题进入统计，三路对照只在 58 配对任务上跑。
- 跨仓库广度由一个经济型模型独家承担（Gemini 3.8 Flash），两个强模型复现（Gemini 3.1 Pro）全在 django 子集——§8 Limitations 自己承认。
- 配对剔除带来方向性偏倚：只在「每个条件都产出可计分编辑」的任务上比较，恰好丢掉文档受损最重的那些（issue-only 单跑 37/68 进对照变 33/58，5 个任务因至少一条件没改动而消失）。
- 「完整性而非长度」的对象不是 coding agent，是一个查表任务（实现是 trivial lookup），长度区间 38 词 vs 664 词，5 个事实。干净地隔离了完整性，但不涉及代码生成。
- 摘要严格说被自己反驳了一格：SCB django / Gemini 3.1 Pro 上 compact 16 vs issue 15。论文自认「a single task, which a paired test cannot distinguish from zero」。
整体评价：这是我最近读到最诚实的一篇负面结果论文，附录 A 表 10 那段自拆台的写法，比多刷 2 个点有价值得多。唯一没做的是把「保真度」和「有用」之间的相关性摆出来——而这恰恰是这篇方法论成立的前提。
*（SVG 动画卡：悬停/加载后动起来；静态截图看不全信息，数字以正文为准。）*