Damn Agent上下文工程
上下文工程关注如何组织任务信息，让模型在有限窗口内稳定完成工作。
上下文工程不是把提示词写得更长，而是把任务所需的信息以稳定、可审计、可压缩的方式交给模型。
上下文分层
推荐把上下文分成四层：
- 系统约束：角色、权限、输出格式、禁止事项。
- 用户意图：目标、成功标准、边界。
- 工作状态：已完成步骤、工具结果、失败记录。
- 参考材料：文档片段、代码、日志、外部资料。
好的上下文长什么样
目标：
- 修复文档站 build 失败
已知事实：
- Next.js 版本是 16.x
- 文档内容来自 content/docs
当前阻塞：
- MDX 编译报 frontmatter 错误
下一步：
- 先定位具体文件
- 再修复 frontmatter 或 MDX 语法常见策略
- 对长资料先做结构化摘要，再注入原文片段。
- 对工具结果保留来源和时间。
- 对用户偏好只注入与当前任务相关的部分。
- 对失败轨迹保留关键节点，而不是完整 token 流。
装配流程
上下文装配可以按固定流程执行：
- 明确目标：写出本轮要完成的可验证结果。
- 列出约束：权限、输出格式、禁止事项、用户偏好。
- 选择证据：只注入和当前目标直接相关的文件、日志、检索结果。
- 压缩历史：把已完成步骤、失败原因和待办项压成结构化状态。
- 预留输出预算：为模型回答、tool call 参数和错误重试留下 token。
- 记录来源：为每个证据片段保留路径、行号、URL、时间或查询条件。
如果每轮上下文都是临时拼接的字符串，后续很难解释一次失败到底是模型问题、证据问题还是装配问题。
证据引用
推荐把证据写成可追踪对象，而不是只写自然语言摘要：
{
"source": "content/docs/practices/evaluation.mdx",
"kind": "file",
"locator": "lines 1-41",
"summary": "页面已有评测维度、评测样例和回归流程。",
"usedFor": "判断是否需要补充发布闸门和指标章节"
}这样做有两个好处：模型能看到摘要，人类能回到原文复核。对于代码、论文、网页、日志和工具输出，都应保留类似定位信息。
压缩策略
| 策略 | 适合场景 | 注意事项 |
|---|---|---|
| 任务摘要 | 长对话、长任务恢复 | 保留目标、约束、已完成、下一步 |
| 证据索引 | 多文件、多网页、多检索结果 | 摘要加定位，不要复制全部原文 |
| 失败摘要 | 多轮重试、复杂排障 | 记录失败签名和已排除路径 |
| 角色视图 | 多 Agent 或多人协作 | 不同角色只看到必要上下文 |
| 冷存储引用 | 大日志、大文件、历史 trace | 用路径或 ID 引用，按需读取 |
压缩后的上下文要能支持下一步行动，而不是只给出“我们讨论过很多内容”的概括。
反模式
- 把全部聊天历史、全部文件和全部工具结果塞给模型。
- 为了“保险”重复注入多份相同约束，导致窗口浪费。
- 摘要只写结论，不保留来源，后续无法复核。
- 长期记忆没有时间戳和适用范围，旧信息污染新任务。
- 工具输出没有截断策略，异常日志挤掉真正重要的任务状态。
质量检查
一次上下文构造完成后，检查它是否满足：
- 模型能知道目标是什么。
- 模型能知道不能做什么。
- 模型能引用证据。
- 模型能判断何时停止。
- 模型能知道哪些信息是事实、哪些只是计划或假设。
- 人类能从上下文回到原始证据。
延伸阅读
- Token 与上下文窗口：上下文预算和压缩策略。
- 工具调用与记忆：记忆如何作为上下文原材料。
- 可观测性与轨迹回放：如何记录上下文装配过程。
参考来源
- Claude Code Harness Engineering：pp. 88-106，上下文压缩、缓存和记忆提取。
- Demystifying Claude Code v1.8：pp. 154-180，上下文优化和性能设计。
- Anthropic: Building Effective Agents：从 workflow 到 agentic system 的上下文和复杂度取舍。