AI Coding Agent 的上下文工程，是为一次任务设计完整的信息环境：Agent 首先看到什么、之后可以发现什么、哪些事实更权威，以及旧假设什么时候必须失去优先级。
目标不是给最多上下文，而是建立一条从用户结果到当前证据的最短可靠路径。
四层有效上下文
- 当前任务：本轮结果、范围、完成证据和停止条件。
- 项目上下文：稳定的产品边界、构建命令、代码约定和文档地图。
- 历史上下文：已验证决策、失败路径、最近交接和精确身份。
- 外部上下文：当前任务所需的最新合同、官方文档、市场证据或运行状态。
把当前任务放在最前面，其他层保持可发现。一份把四层内容全部混在一起的巨型 Prompt，会迫使 Agent 在理解任务前先判断哪些信息有用。
哪些内容属于仓库指令？
AGENTS.md、CLAUDE.md 或同类文件适合保存全仓长期成立的规则：
- 如何构建与测试；
- 代码和模块约定；
- 不能偏移的公共边界；
- 编辑与验证的安全默认值；
- 指向聚焦文档的索引。
GitHub 已在多种 Copilot 使用面中支持仓库级、路径级和 Agent 指令文件：custom instructions support。
指令应保持简洁。OpenAI 分享过一个重要经验：巨大的 AGENTS.md 会消耗稀缺上下文并稀释真正重要的规则，指向聚焦文档的导航地图更有效：Harness engineering。
哪些内容属于任务简报？
只对本轮成立的事实，不要写成永久规则：
- 用户当前请求；
- 第一处断链；
- 当前涉及的文件；
- 正在检查的精确版本或部署；
- 必须运行的检查；
- 临时非目标。
任务结束后，简报也随之失效。把它提升成全局指令，只会制造过期规则。
哪些内容属于项目记忆？
项目记忆应保存未来会反复使用的事实：
- 已确认的产品决策及理由；
- 已验证的接入入口；
- 重复出现的失败模式；
- 稳定的用户偏好；
- 未完成工作的最新交接。
不要把原始日志、每条命令或未经验证的诊断写成稳定记忆。保留证据入口，让新 Agent 能够回到当前系统复核。
使用渐进式检索
可靠的启动顺序是：
- 读取当前任务和硬边界。
- 检查最小相关代码与运行状态。
- 用具体问题查询文档或记忆索引。
- 只打开高相关来源。
- 新证据指向共享依赖时，再扩大范围。
VS Code 的上下文指南也区分了自动选择的工作区上下文，以及用户显式附加的文件、目录、符号、终端输出和源码改动：Add context to chat。
验证上下文，而不只是验证回答
好的上下文应该真实改变执行质量。可以检查一个全新会话能否：
- 快速找到当前权威；
- 避免已知失败路径；
- 说出正确验证方式；
- 保持产品边界；
- 产生更小、更相关的 diff。
如果仍然必须粘贴整段旧聊天，说明耐久上下文不完整。如果每个任务都会收到多页无关规则，说明上下文过宽。
常见失败
- 倾倒聊天记录：保留了对话顺序，却没有保留当前事实。
- 所有内容都永久化：把一次事故提升为通用规则。
- 使用泛词检索：用“项目”“任务”匹配，而不是具体问题。
- 记忆覆盖代码：让旧笔记高于当前行为。
- 没有证据入口：要求未来 Agent 相信无法复核的描述。
可复用上下文简报
用户结果
完成后用户能做什么。
当前证据
文件、测试、日志、页面与精确身份。
不变量
产品行为、数据权威、隐私与公共合同。
检索索引
哪些聚焦文档或记忆查询可能有用。
验证方式
最终消费者必须显示什么。
会话交接
已验证状态、剩余缺口与下一步安全动作。
核心原则
上下文工程是服务行动的信息架构。给 Agent 一个清楚的任务、一张可信地图，以及在证据需要时继续检索细节的能力。