项目上下文文件能否解决 AI 编程助手的新会话失忆问题？

项目上下文文件可以缓解新会话缺少仓库规则的问题，但不能保证 AI 编程助手更正确。2026 年一项针对 Claude Code 与 Codex 的消融研究，在 3 个真实 Python 仓库、17 个任务和 288 次有效评估中，没有测得 AGENTS.md 或按需 Wiki 对任务通过率的显著提升。不过研究也观察到，明确的测试耗时提示能减少 Claude Code 盲目运行完整测试套件。结论应理解为“静态上下文文件不是正确率万能药”，而不是“上下文文件没有价值”。

这项研究想回答什么

AGENTS.md、CLAUDE.md 等项目文件已成为编码 Agent 的常见基础设施。团队把构建命令、架构约束、代码风格和工作流写进去，希望新会话自动获得项目知识。

此前研究结论并不一致：有研究发现上下文文件降低运行时间和输出 Token，也有研究没有发现任务完成率提升。新研究试图在相同任务与评估流程下，同时比较两类主流 Agent，并控制上下文注入方式。

三种上下文策略

第一种是 none：移除工作区中的 AGENTS.md，不在提示中提供额外仓库说明，Agent 只从代码库探索。

第二种是 always_on：每一轮都把完整 AGENTS.md 注入提示，让规则始终出现在上下文中，同时移除工作区文件以避免重复读取。

第三种是 selective：只提示 Agent 可以按需读取按主题拆分的 Wiki 文件。需要架构、错误处理或测试信息时，再通过工具检索相关文档。

研究者特别承认，selective 并非完全纯粹的注入方式对照。在两个仓库中，Wiki 内容比原 AGENTS.md 更广，文字量约为后者的 10 倍和 18 倍，因此它同时改变了传递方式与内容范围。

任务和仓库如何选择

实验从约 40 个候选仓库中筛选，要求只有一份根 AGENTS.md、文件质量较好、环境可运行且使用 Python。最终选择 PDM、Firebase Admin Python 和 Opshin 三个不同领域的仓库。

任务来自已合并的 Pull Request。PR 描述作为 Agent 的任务提示，合并前提交作为起始代码，PR 中新增或修改的测试则作为隐藏金标准。Agent 看不到这些测试，完成修改后才由评估器应用测试并判断是否全部通过。

Codex 运行 17 个任务，Claude Code 运行其中 15 个。每个任务在三种策略下分别重复三次，总计 291 次完成运行，其中 3 次 Claude 运行因崩溃或超时无法形成有效测试结果，最终正确率分析使用 288 个单元。

如何防止答案泄露

所有运行在禁止外部网络的隔离环境中执行，GitHub 域名被阻断，远程地址与凭据被清理，提交和推送命令受限。未来提交历史也被剪除，避免 Agent 通过 Git 日志看到目标 PR 的正确实现。

这些控制提高了实验可信度，因为上下文策略之外的外部搜索和答案泄露被尽量排除。但它也让实验环境与真实开发有所不同，现实中的 Agent 可能使用网络文档、Issue、代码审查和更多工具。

正确率结果

策略	Claude Code	Codex
无上下文文件	53.3%	58.8%
始终注入	55.6%	56.9%
按需检索	55.6%	52.9%

Claude 三种策略之间最大差异约 2.3 个百分点；Codex 最大差异约 5.9 个百分点。置换检验没有发现策略对正确率的显著影响。研究者的等效性分析把观察到的策略差异约束在 Claude 10 个百分点以内、Codex 15 个百分点以内。

这不等于证明真实效果精确为零。任务数只有 15 到 17 个，统计功效有限。论文的模拟显示，要以 80% 功效检测 10 个百分点差异，可能需要约 120 到 200 个任务。

为什么上下文没有提高通过率

研究者检查了只差少数隐藏测试的近失任务，发现主要问题不是缺少仓库事实，而是实现能力。失败包括细微优化逻辑错误、选错架构模式、校验条件接线错误和类型系统推理不足。

这些问题即使 Agent 知道构建命令、目录结构和编码规范，也不一定能修好。上下文文件能告诉它“项目怎么工作”，却不能自动补足特性设计、模式选择和精确实现能力。

上下文文件仍可能改善工作过程

Opshin 的 AGENTS.md 明确提醒完整测试套件耗时超过 20 分钟。没有提示时，Claude 平均每个实验单元盲目运行完整测试 3.67 次；始终注入时下降到 2.44 次，按需检索时下降到 1.67 次。

对应平均运行时从约 2689 秒降至 2066 秒和 2032 秒，约有 24% 的差异。研究将其作为探索性流程效应，而不是已确认的普遍结论：它只出现在 Claude 与 Opshin 组合中，样本很小，Codex 的耗时则基本持平。

这说明可操作的环境知识可能减少明显浪费，即使最终正确率没有变化。告诉 Agent 哪些测试昂贵、应该先运行哪些目标测试，往往比泛泛描述技术栈更有价值。

始终注入与按需读取的成本差异

在 Claude 运行中，按需策略的缓存创建 Token 显著低于无上下文策略，缓存读取也呈下降趋势。论文认为这主要来自传递机制：按需策略只在提示中放短说明，需要时才读取文档，不必每轮重复完整文件。

这个结果更像上下文打包方式的机械差异，不能直接解释为 Agent 更聪明。对于大型规则库，分层、按主题检索仍可能是更节省上下文的工程选择，但需要用真实任务衡量。

任务难度会因 Agent 而不同

同一个任务可能对 Claude 属于边缘难题，对 Codex 却始终失败，反之亦然。15 个共同任务的通过率相关性较高但不完全一致，论文报告 Spearman 相关系数为 0.75。

约 40% 的共同任务在两个 Agent 上处于不同的地板或天花板状态。一个 Agent 总能通过或总会失败时，上下文策略很难展示效果；只有接近能力边界的任务才有机会被额外信息推动。

这也解释了为什么只测试单一 Agent 的研究可能得到矛盾结果。评估上下文文件时，任务需要针对每个 Agent 单独筛选，不能把一个模型的边界任务直接套给另一个模型。

这项研究有哪些限制

首先，它是尚未经过正式同行评审的单作者预印本。其次，只覆盖 3 个 Python 仓库和少量任务，不能直接外推到大型多语言单体仓库、前端项目或企业私有系统。

第三，selective 策略在两个仓库使用了更大的自动生成 Wiki，不是对原 AGENTS.md 的等量拆分。第四，两种 Agent 的注入渠道不同：Claude 使用追加系统提示，Codex 通过用户提示前置内容，可能影响注意力。

第五，实验只评估隐藏测试是否全部通过，未直接衡量代码可维护性、安全性、规范遵守、审查成本和长期架构一致性。上下文文件在这些维度上的价值仍未被该研究否定或证明。

项目文件应该继续保留吗

应该保留，但要调整期望。上下文文件最适合保存难以从代码立即发现、且会改变工作方式的信息：精确构建测试命令、昂贵操作提醒、生成目录禁令、数据库安全边界、模块所有权和发布约束。

不要把它当作提高所有编码任务正确率的通用补丁。代码库已有清晰模式时，Agent 往往能自行探索；任务失败若来自复杂设计与精确实现，继续增加背景文字可能没有帮助。

如何提高文件的信息密度

删除文件树中显而易见的描述和长篇教程，优先写会阻止真实错误的规则。每条规则尽量包含触发条件与具体动作，例如“完整测试超过 20 分钟，先运行当前模块的目标测试”，而不是“注意测试效率”。

将不同目录的局部规则放在对应位置，或按主题拆分并按需读取。文件更新应与代码审查绑定，过期规则要及时删除。过多无关内容会占据上下文，却不一定改变执行。

团队如何做自己的小型评估

选择一组真实、可重复、有自动测试的任务，在无文件、精简文件和按需文档三种配置下重复运行。记录通过率、工具调用、运行时间、Token、盲目全量测试次数和人工返工。

不要只比较一两次演示。模型输出有随机性，同一任务至少重复数次；任务也要覆盖简单、边缘和困难区间。不同 Agent 分开分析，避免把不可比较的“轮次”或 Token 口径直接合并。

如果文件没有提高正确率，却明显减少危险命令、无效构建或全量测试，它仍有工程价值。相反，若文件很长且不改变任何行为，就应精简或删除。

新会话失忆的完整解决方案

上下文文件只解决稳定项目规则。当前任务进度需要 Issue、计划或交接记录；代码事实需要重新读取当前工作树；行为正确性需要测试；跨仓库知识可由语义索引或搜索提供。

稳定规则：AGENTS.md / CLAUDE.md
任务进度：Issue / handoff
当前事实：Git diff / source code
行为证明：tests / build / runtime checks
大库检索：semantic index / code search

把这些层次组合起来，新会话才能既快速进入状态，又不盲信过期摘要。

结论

这项 288 次有效运行的研究没有发现上下文注入策略能显著提高 Claude Code 或 Codex 的隐藏测试通过率。失败更多来自设计、模式选择和精确实现，而不是缺少一条仓库规则。

但上下文文件仍能承载新会话无法从代码轻易获得的操作知识，并可能减少昂贵或危险的无效步骤。最佳做法不是无限扩充项目说明，而是保留短小、具体、可执行的规则，按需提供详细知识，并用真实任务和测试验证它是否改变了结果或工作过程。