Codex Token 纪律
目标
在不削弱任务成功率、所需证据或要求交付成果的前提下，降低根会话和子会话的总成本。
保持读取、工具输出、重试和委托的可控性。保留可复用的证据，仅上报未解决的部分。
操作框架
仅使用能改变行为的部分：
- 指明当前阶段：探索（explore）、计划（plan）、实现（implement）、验证（verify）、发布（publish）或交接（handoff）。
- 在广泛读取之前，定义下一步所需的证据。
- 在调用可能产生大量噪音的工具前，定义最小的有用返回形状和输出预算。
- 仅当噪音副任务能返回经过提炼的、带有证据的结果时，才进行委托。
- 在阶段边界上，保存紧凑的恢复状态，并在存在所属指挥器（director）的情况下，将会话延续决策交给它处理。
对于小型编辑、直接答案和简单命令，跳过此仪式。
预检输出契约
在多余输出进入主体上下文之前就加以阻止；不要依赖事后总结。
- 对于任何不可预测或批量命令，首先命名所需的返回形状：状态、计数、路径、选定字段或首个可操作失败信息。
- 在工具调用上设置有限的返回预算。对于 exec 系列调用，默认设置显式预算，不超过 2,000 token，除非命名的证据需要更多；不要等待单个大输出阈值。
- 在源头进行过滤、聚合或选择。对于测试和构建，首先返回退出状态、首个可操作失败信息和命令，再请求更多细节。
- 当完整输出对后续检查有用时，将其写入任务本地或临时工件（artifact），仅返回其路径、大小、紧凑摘要和首个可操作失败信息。根据需要从工件中检查有限的分片。
- 对于可在源头缩减的一次性输出，不要创建工件。
摘要优先读取
从窄范围开始；仅当它能改变下一步决策时才扩大范围。
- 使用
rg或文件列表进行搜索，然后再打开文件。 - 优先使用
git diff --stat、git diff --name-only、聚焦的git diff -- <path>和有针对性的sed -n范围，而非完整差异。 - 对于日志和命令输出，在获取完整 transcripts 之前，优先使用
tail、head、jq、计数、过滤器或错误搜索。 - 将每个返回的工具结果视为未来的输入成本。优先使用计数、路径、摘要或选定的证据，而非完整输出。
- 失败后，从保存的工件开始扩大范围，或仅重新运行最小的失败范围；避免在主线程中重复完整的 transcripts。
如果必须进行广泛读取，请说明原因，并将其限制在最小的有用范围内。
长时间运行的工作
将阶段变化视为上下文检查点。
- 在实现或仓库/任务切换之前，保存结论、下一步决策、最近的下一步和最小的有用边界。
- 在使用
project-context的仓库中，优先使用BRIEF.md作为紧凑的当前状态，并使用日志作为证据。 - 当协调器协调长时间运行的工作时，上报检查点，并由协调器决定是否继续、交接或轮换会话。不要无条件地规定或启动一个新会话。
- 如果没有协调器，仅当保存的表面足以继续，并且用户或所属工作流要求时才重新开始。
不要为了补偿大型对话而存储 transcripts、验证矩阵或文件清单。
子代理
委托并不天然更低成本。使用最窄的命名代理来处理有限的工作，这些工作能返回紧凑、独立有用的证据或输出。
从一个代理开始。仅并行处理独立的、不重叠的范围。不要重复相同的调查，在集成后保持子代理存活，或重复仍然有效的验证。
用范围、写入边界、完成条件、验证和预期的紧凑输出进行提示。子代理不得再委托。
浏览器和 UI 循环
在重复进行视觉或浏览器验证之前，写下要检查的状态。
- 每个命名状态优先使用一个截图或浏览器 pass。
- 如果检查失败，检查最小的归属者：控制台错误、DOM 状态、路由数据或聚焦的组件。
- 除非该工件本身影响下一步决策，否则不要将图片、base64 截图、完整 body 文本和 DOM 转储保留在主线程中。
- 一旦命名的状态被验证，或具体的阻塞点被隔离，就停止。
始终读取的表面
全局或仓库指令中的每一行都有重复的成本。
- 将持久的行为规则和安全边界放在 AGENTS 风格的文件中。
- 将可重复的工作流程放在技能中。
- 将当前任务状态放在仓库任务文档中。
- 将当前可复用的领域事实放在参考文档中。
- 移除陈旧的配置文件、重复的指令和历史解释，而不是在它们周围编写文档。
在编辑始终读取的文件时，优先使用简短的路由规则，而非过程文本。
使用审计
当被问及 token 去向时，解析相对于此已安装技能目录的 scripts/summarize_codex_usage.py，使用 --help 运行它，然后用显式的 --cwd-prefix 进行审计。
该脚本按根线程分组 Codex rollout 日志，并报告 token 总数、缓存输入率、子会话 token 份额、工具输出量、大输出事件和顶级输出工具信号，而不包含原始负载。
将 token 总数视为信号，而非质量指标。避免全仓库文本搜索；将脚本指向 $CODEX_HOME/sessions 或其他显式的会话根目录。
最终检查
- 主线程是否只收到了当前决策所需的证据？
- 有噪音的工具工作是否在执行前定义了返回形状和预算，且仅在有用时将完整细节保留在工件中？
- 大型读取、浏览器循环和子代理是否被明确的问题所约束？
- 可恢复的状态是否在正确的表面上，并且所属协调器保留了继续/交接/轮换的决策？
- 始终读取的指导是否保持简短，并将细节路由到别处？