上下文不是越多越好：为 Codex 设计分层入口

上一篇文章给仓库补上了稳定规则。接着往下做，很多人会产生一个很自然的想法：既然缺上下文会让 Codex 猜，那就把架构文档、历史 Issue、测试日志和相关代码一次性都交给它。

短任务里，这种做法偶尔有效。项目一大，问题很快换了方向：旧文档与当前代码冲突，失败日志挤在真正的错误前面，一份临时评审意见又被当成长期要求。Codex 没有“少读”，却依然可能做错判断。

小编现阶段更倾向于把上下文看成一次工程输入。输入的价值不由体积决定，而要看它是否与当前决策有关、能否保持真实，以及读完以后会不会挤掉更关键的证据。

一、上下文不足和过载，最后都会变成猜测

上下文不足很好识别。Codex 不知道项目用什么包管理器、不知道生成文件不能手改，也没读到目标模块的接口约束，只能靠常见项目结构补全空白。上一篇建立仓库规则，就是先解决这部分问题。

过载更隐蔽。假设一次重构任务同时附上这些材料：

• 三年前的架构设计稿；
• 当前模块的源码与测试；
• 两次失败构建的完整日志；
• 与目标模块无关的产品需求；
• 一段已经被后续讨论推翻的聊天结论。

这些材料都“与项目有关”，却不等于都应该进入当前判断。旧架构可能与代码冲突，完整日志里大量成功输出没有诊断价值，无关需求则会引入新的目标。信息越多，Codex 越需要判断哪些可以信；来源、时效和用途没有标出来时，这个判断仍然只能靠猜。

OpenAI 当前的模型指导也在提醒同一件事：重复指令和过长工具说明会增加上下文负担，长会话还会放大重复内容。官方建议保留真正承载产品要求或修复已测问题的说明，同时让指令保持精简。OpenAI：Favor leaner prompts

这并不意味着项目资料要删掉。更合适的处理是保留事实来源，只调整它进入任务的时机。

二、先问四个问题，再决定资料放在哪里

“常驻 / 按需 / 不加载”是本文为了管理项目资料采用的工程分类，不是 Codex 产品里的三个按钮。判断一份材料的去向时，可以先看四件事。

2.1 它能稳定多久

跨任务长期成立的事实适合靠近常驻入口，例如仓库使用的包管理器、生成文件的处理方式和最低验证要求。

版本号、分支冻结状态、某次迁移进度都可能快速变化。它们应从当前清单、代码或状态文件读取，不要复制成永久说明。一份内容越容易过期，越需要在使用时重新核验。

2.2 它是否改变当前决策

相关性不能只看“是不是这个项目的资料”，还要看它是否影响眼前动作。

写 01-02 时，系列定位、01-02 文章规划、前置文章和写作规范会改变正文内容，应该读取。01-01 的质检报告已经完成了它的用途，除非当前任务要回看前文问题，否则没有必要再次带入。

2.3 它是否适合进入模型上下文

密钥、令牌、真实客户数据和未脱敏日志，即使与任务高度相关，也不该直接加载。此类材料应先脱敏、提取必要字段，或者通过只返回最小结果的受控工具处理。

本文只讨论信息去向，不展开谁来批准读取、工具应该获得什么权限。确认门禁与权限半径属于第二章。

2.4 读取成本是否值得

成本不只是 token 数量。大文件需要更久的读取和筛选，二进制产物可能根本不适合直接理解，完整构建日志还会让关键报错变得难找。

先缩小对象通常更有效：从日志里定位失败段，从大型配置里读取相关节，从仓库历史里查目标提交。只有缩小后的材料仍不足以支持判断，才继续扩展范围。

三、把入口分成常驻、按需和不加载

前面的四个问题无需评分。它们只帮助我们解释一个选择：这份材料为什么现在要读，或者为什么不读。

3.1 常驻：每次任务都容易踩错的稳定约束

常驻层只放跨任务稳定、缺失后容易造成返工或越界的信息。项目根目录的 AGENTS.md 是典型入口。在当前 JVS 项目里，它定义主题大师、文章大师和文章质检员的职责，规定三者的串行顺序，并列出交接必须携带的字段。

这些规则不因文章编号改变。写 01-01 和写 01-02 都要遵守，所以让它们持续可见是划算的。至于每篇文章的标题、状态和素材，不属于根规则。

常驻层要克制。上一篇已经说明 AGENTS.md 的发现和覆盖方式，本篇不再增加另一套项目规则，只确认它在上下文路由中的职责：提供稳定入口，不负责搬运全部项目知识。

3.2 按需：先暴露入口，命中任务后再读正文

按需层保存“某类任务会用到，但并非每次都需要”的材料，例如 Skill、写作风格规范、模块设计说明、故障手册和某篇文章的前置资料。

Skills 本身就采用了类似机制。根据 OpenAI 当前文档，ChatGPT 和 Codex 初始获得每个 Skill 的名称与描述；Codex 还会看到文件路径。决定使用某个 Skill 后，才加载完整的 SKILL.md。官方把这种方式称为渐进披露。OpenAI：Build skills

当前 JVS 项目可以直接验证这种分工：

• jvs-write/SKILL.md 负责单篇写作流程；
• jvs-write/references/writing-style.md 负责语言和真实性；
• jvs-write/references/article-structure.md 负责正文结构；
• codex-advanced-usage/topic.md 提供当前系列边界和文章地图；
• 目标正文与显式前置文章提供本次衔接事实。

入口告诉 Codex “什么时候应该读什么”，被引用的文件继续做事实来源。这样修改写作风格时只改权威文件，不必把同一段规范复制进每次任务。

3.3 不加载：敏感、派生或与任务无关的材料

“不加载”不等于删除。它只是说这些材料不该直接进入当前任务上下文。

当前仓库里的 .DS_Store、node_modules/、图片二进制和已经压缩好的发布产物，对写作判断没有帮助；令牌配置和环境变量文件则涉及敏感信息；其他系列的正文虽然可以公开，却与 01-02 无关。这几类材料留在原处即可。

有些材料经过处理后可以改变去向。完整日志不加载，但提取出的错误段可以按需读取；真实数据不加载，脱敏后的最小样本可能足以复现问题。同一文件在任务变化或完成脱敏后，可以重新判断去向。

四、给真实仓库做一张上下文路由表

下面这张表来自当前 JVS 项目的实际文件，用来示范如何留下可检查的盘点结果。每个仓库的条目都会不同，判断字段可以复用。

信息或入口	稳定性与用途	当前路由	使用方式
根目录 AGENTS.md	跨文章稳定的角色、顺序和交接规则	常驻	新任务先确认它已生效
jvs-write/SKILL.md 及必读 references	单篇写作时稳定，其他任务未必相关	按需	写作任务命中后完整读取
codex-advanced-usage/topic.md	系列权威状态，会随规划和写作更新	按需	每篇开写前重新读取最新文件
目标正文、显式前置文章、对应审阅报告	只服务当前文章或修订阶段	按需	按文章编号和状态定位，避免读取无关文章
node_modules/、图片产物、.DS_Store	派生、二进制或无关材料	不加载	保留在磁盘，不加入写作上下文
令牌、环境变量、未脱敏私人数据	可能相关但包含敏感信息	不加载	不直接读取；先脱敏或改用受控结果

盘点时最容易漏掉的是“权威来源”。同一事实出现在 topic.md、聊天记录和旧正文里，应先说明以哪一份为准。否则即使三份材料都加载了，Codex 仍然要猜冲突时听谁的。

还要记录重新读取的时机。topic.md 会随着文章状态更新，适合在每篇任务开始时读取最新版本；稳定写作规范可以在相关 Skill 启动时读取；目标正文则在修订和质检阶段重新读取。路径不变，并不代表内容没有变化。

五、怎么知道 Codex 当前真的掌握了什么

我们经常问 Codex：“你理解了吗？”这个问题几乎没有验证价值。更有效的检查是让它把当前判断拆成事实来源和缺口。

可以先要求一次不写文件的上下文回放：

这段检查刻意区分“读过内容”和“知道入口存在”。以 Skill 为例，初始列表里出现名称、描述和路径，不代表完整 SKILL.md 以及 references 已经加载。只有实际读取后，它们才能作为当前判断的证据。

随后做只读核对：确认文件路径真实存在，读取状态文件的最新内容，检查规划引用的前置文章是否匹配，并用搜索定位与当前目标有关的代码或文档。发现冲突时先标出各自来源和更新时间，不急着把其中一份润色成结论。

Codex 能准确说出任务边界，却给不出依据路径，可能只是在复述提示词。列出大量文件，却无法说明它们改变了哪个判断，说明按需层仍然太宽。敏感文件被当成普通材料建议读取，则说明“不加载”边界还没有写清楚。

经过这一步，读者应该留下两份很朴素的产物：仓库信息盘点表，以及每类信息进入“常驻 / 按需 / 不加载”的路由表。它们不负责安排后续任务，也不决定哪些动作需要授权。

它们只做一件事：让下一次 Codex 开工时，关键事实有入口，任务材料能按需找到，无关和敏感内容不会因为“可能有用”就一股脑塞进上下文。