知识卡片：面向编码智能体的紧凑文档——基准、优化器与未能迁移

英文标题： Compact Documentation for Coding Agents: A Benchmark, an Optimizer, and Why It Does Not Transfer

一句话结论

论文构建了评估代码描述保真度的 roundtrip benchmark，并优化出能达到完整保真的描述写作 prompt；但在两个模型家族、十个仓库的真实仓库问题解决测试中，更好的紧凑文档并未迁移为编码智能体的任务收益。

事件概述或研究问题

论文研究自然语言文档是否帮助编码智能体解决软件问题，并构建用于构造和评估这类文档的工具。核心假设是：更好的文档应当帮助智能体解决真实仓库 issue。论文同时报告了支持文档构造与评估的基准、优化器，以及一个与该假设相反的负结果。

方法/产品要点

• 提出 roundtrip benchmark：给代码描述打分，判断依据是“由该描述重新生成的代码是否通过原始测试”。
• 发现驱动描述保真度的是 完整性（completeness），而不是长度。
• 将 benchmark 作为优化信号，发现一个描述写作 prompt，达到 full fidelity，并能泛化到未见文件。
• 随后测试动机假设：更好的文档是否帮助智能体解决真实仓库问题。
• 评估覆盖 两个模型家族 和 十个仓库，并设置了 positive control，用于确认评估本身能检测到真实改进。

主要结果或产业意义

• 在真实仓库 issue 解决任务上，更好的文档 没有 带来预期改进。
• 当源代码存在时，无论是静态紧凑文档，还是检索到的上下文，都没有超过“仅提供 issue”这一基线。
• positive control 表明评估具备检测真实改进的能力，因此该负结果不是因为评测完全无灵敏度。
• 产业意义：不能默认给编码智能体加入文档或检索上下文就一定提升问题解决效果；文档的“保真度”与下游任务收益之间可能存在断裂，需要按任务阶段和边界条件验证。

为什么重要

这篇论文直接挑战“更好的文档会改善编码智能体表现”的常见假设，并把问题拆成两个可分别测量的层面：描述能否忠实保留代码信息，以及这种保真度能否迁移到真实 issue 解决。其负结果与 positive control 一起，提示后续工作需要更精确地刻画文档在何种条件下才有帮助。

与既有脉络的关系： 已有相关卡片从行为数据观察编码智能体如何发现、阅读和编写技术文档，指出其文档交互以面向智能体的指令文件和工作笔记为主，且“可操作、可验证”等智能体友好文档假设在行为数据中缺乏一致支持。本卡片增量在于：不只观察文档使用行为，而是构建 roundtrip benchmark 和描述优化 prompt，并用两个模型家族、十个仓库的实验测试“更好文档→解决真实 issue”的迁移，报告源代码存在时未发现增益。

局限与不确定性

• 摘要未列出具体模型家族、十个仓库名称、评测指标、prompt 文本、positive control 设计与边界条件；这些细节 待核实。
• “compact documentation”和“retrieved context”的具体形式与构造方式，摘要未展开；待核实。
• 负结果的适用范围限于论文实验设置，不能直接推断所有文档类型、所有编码任务或所有智能体配置；更广适用性 待核实。
• 论文是否公开 benchmark、优化器或代码，摘要未说明；待核实。
• 论文称刻画了文档有帮助的边界，但摘要未给出边界内容；待核实。

可用于图书/PPT/简报的角度

• “更好的文档不等于更好的任务表现”：一个适合讲负结果与迁移失败的案例。
• “完整性而非长度”：文档评估可以用 roundtrip 与原始测试来衡量保真度。
• “从保真到迁移”：中间产物质量高，不代表下游收益高。
• “positive control 的价值”：如何证明评测能检测真实改进，从而让负结果更可信。
• “检索增强/RAG 的边界”：当源代码存在时，检索上下文未必优于仅给 issue。
• “行为观察 vs 实验测量”：与已有编码智能体文档行为研究形成对照，讨论文档使用与文档收益之间的差异。

原始材料

• 英文标题： Compact Documentation for Coding Agents: A Benchmark, an Optimizer, and Why It Does Not Transfer
• 作者： Md Shohel Arman, Igor Molybog
• arXiv ID： 2609.31587v1
• 发布/更新时间： 2026-09-25T17:42:22Z
• 主分类/分类： cs.SE；cs.SE, cs.AI, cs.CL
• Abstract URL： https://arxiv.org/abs/2609.31587v1
• PDF URL： https://arxiv.org/pdf/2609.31587v1
• 英文关键词： 原始材料未列出，待核实。