编码代理上下文工程：范围、检索与持久状态

仓库指令表达长期约定，任务证据描述当前代码与故障，外部资料描述上游契约，工具输出是一次观察，代理笔记则是暂时解释。把这些内容混成一段对话后，就很难判断哪些信息仍然有效、哪些具有权威性、哪些可以安全复用。

为每类内容指定所有者、来源、刷新条件与保留规则。构建命令可能几个月不变，而修复后的错误堆栈必须立即刷新。Issue 评论或网页中的文字只能作为证据，除非维护者明确把它提升为指令。

先加载任务、允许修改的路径、验收命令以及最近的仓库指令，再让代理查看相关入口，而不是一开始读取整棵目录与全部文档。只有当决策确实依赖某份资料时才引入它，并把 URL 或文件路径与结论一起保存。

“最小”不能以遗漏为代价。包级测试命令或生成代码规则若未进入工作集，造成的损失会超过少量冗余文本，因此需要结合仓库结构和变更边界检查上下文是否充分。

跨会话任务应留下简洁交接：当前 commit、已作决策、证据、改动文件、执行命令、未决问题和下一步。交接内容必须可审查且不含凭据。新会话应能依靠这份产物与仓库权威文件恢复工作，而不需要重放全部探索过程。

只有经过人类审查的稳定约定才进入长期文档。临时假设保留在任务范围内，证据变化后应删除或明确标记为已失效。

从诊断进入实现、从实现进入验证，或切换子系统时，都应重建工作集。重新读取已经变化的文件并再次运行权威命令，不要信任缓存输出。这样才能让结论与代理真正修改的仓库状态一致。

审查关键决策是否引用来源、适用指令是否加载、最终验证是否基于当前 diff，以及敏感或不可信文字是否被错误写入长期指令。这些控制检查上下文流程，不假装测量模型不可见的内部推理。