Anthropic Agent 工程实战笔记（三）上下文与记

本模块主要参考（官方）

$1\] [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)（Anthropic Engineering，Sep 2025）$

本模块在整体中的位置

模块二解决了「工具选什么、返回什么」；但工具的输出会不断塞进 context，长对话、长任务下必然遇到装不下、记不住 。上下文与记忆要解决的是：在 context 有限、且存在注意力预算 （模型对长 context 的有效关注有限）与 context rot （越长召回越差）的前提下，如何用最少的高信号 token 达成目标，以及如何跨轮、跨窗保持连贯。本模块先讲「为什么 context 是有限资源」（§1）→ 再讲检索与按需加载（§2）→ 再讲长时程的三种手段：compaction （摘要压缩后开新窗继续）、笔记、子 Agent（§3）→ 最后点到 RAG （检索增强生成）的进化 Contextual Retrieval （§4）。学完这里，模块四的「长任务 Harness」（运行框架，见 04）才有上下文层面的支撑。

逻辑线索（本模块阅读顺序）

约束：context 有注意力预算与 context rot；system prompt、tools、examples 都要「最小必要、高信号」。
检索：优先 just-in-time（按需、用时再加载）按需加载，用元数据引导；可混合预取与按需。
长时程：单轮装不下时选 compaction / 笔记 / 子 Agent，按场景选。
RAG：Contextual Retrieval 用「先解释再切片」缓解指代丢失。

本模块总流程图：上下文策略选择 [1]

能
不能
是
否
是
否
对话/任务
单轮能装下?
最小必要 system + tools + examples
有明确里程碑/需跨 session?
结构化笔记 / Memory 工具
多源深度探索?
子 Agent 只回传压缩结果
Compaction: 摘要 + 新窗继续
Just-in-time 按需加载

1. 上下文是有限资源 [1]

据 [1]，上下文窗口再大，也存在注意力预算 与 context rot ：token 越多，模型对其中信息的召回与利用会下降；和人类工作记忆类似，需要用最少的高信号 token 达成目标。
System prompt [1]：在「写死复杂 if-else 逻辑」和「过于笼统、假设共享上下文」之间取平衡；用分节（如 XML 或 Markdown 标题）组织，保持最小必要信息，再根据失败用例补充。
Tools [1]：工具应 token 高效、边界清晰、少重叠；若人说不清「该用哪个工具」，模型更不行。详见（二）工具设计。
Examples [1]：用少量多样、有代表性的示例表达预期行为，避免把各种边界情况全塞进 prompt。原因：示例相当于「用图说话」------模型从示例中泛化行为，比从长段规则中更稳；塞太多边界反而稀释重点。

上下文组成示意 [1]：

复制代码

┌─────────────────────────────────────────────────────────┐
│  System prompt（最小必要、分节清晰）                      │
│  Tools（少重叠、token 高效、边界清晰）                    │
│  Examples（少量多样、有代表性）                           │
│  Message history / 检索结果 / 本次 tool 输出 ...           │
└─────────────────────────────────────────────────────────┘
         ↑ 每次推理前都要决定：放什么、不放什么

2. 检索与「Just-in-time」加载 [1]

据 [1]，不必把所有相关数据预先塞进 context；可维护轻量引用 （路径、查询、链接），在运行时用工具按需加载。类似人类用文件系统、书签，而非背诵全文。
目录结构、命名、时间戳等元数据本身就能引导 Agent 何时用哪份信息；让 Agent 自主探索（progressive disclosure，渐进式披露、按需展开信息）可减少无关信息占用，但需要好工具与启发式，否则会浪费 context [1]。
混合策略 [1] 常见：一部分预取（如 CLAUDE.md），一部分由 Agent 用 glob/grep 等按需拉取。Claude Code 即采用此类混合。

示例：Just-in-time 按需加载 [1]

不预先塞入全文，只提供「引用」；Agent 请求某 path 时再拉取并追加到 messages：

python 复制代码

def load_on_demand(path: str) -> str:
    """按 path 返回内容；在 agent 循环中，仅当模型请求该 path 时再调用。"""
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

# 在 agent 循环中的用法：若 assistant 发出 tool_use(read_file, path="src/config.py")，
# 则 content = load_on_demand(path)，并 append {"role": "user", "content": [tool_result(content)]}

3. 长时程任务：三种手段 [1]

3.1 Compaction [1]

据 [1]，接近上下文上限时，用模型对对话做摘要与压缩，再开新窗口用摘要 + 最近关键内容继续。
关键是「保留什么、丢弃什么」：可先偏 recall 再迭代提高 precision [1]。
轻量做法 [1]：只清掉已用过的 tool 结果，保留决策与未解决问题；Claude Developer Platform 已提供 context management 类能力。

流程示意：
即将满的 context
模型做摘要
保留：架构决策、未解决 bug、实现要点
丢弃：冗余 tool 输出、重复消息
新 context = 摘要 + 最近若干文件/消息
Agent 继续执行

3.2 结构化笔记（Agent 记忆）[1]

据 [1]，Agent 把进度、决策、待办写入持久存储（如 NOTES.md、memory 工具），后续 session 再读入。
例 [1]：Claude 玩 Pokémon 时维护步数、等级、地图、战斗策略等，在 context 重置后读自己的笔记继续长时任务。
Memory 工具（Claude Developer Platform 公测）：基于文件的存储，便于跨 session 维护状态与知识库。

示例：追加写入笔记 [1]

Agent 在关键节点把「当前进度、未完成项」写入文件，下次 session 先读该文件再接上：

python 复制代码

NOTES_FILE = "NOTES.md"

def append_note(section: str, content: str) -> None:
    with open(NOTES_FILE, "a", encoding="utf-8") as f:
        f.write(f"\n## {section}\n{content}\n")

def read_notes() -> str:
    try:
        with open(NOTES_FILE, "r", encoding="utf-8") as f:
            return f.read()
    except FileNotFoundError:
        return ""

3.3 子 Agent 架构 [1][2]

据 [1]，主 Agent 做规划与汇总，子 Agent 做深度检索或技术子任务，只把精简结果（如 1k--2k tokens）回传，避免主 context 被塞满。
多 Agent 研究系统 [2] 有完整架构；适合复杂研究与多源分析。详见（四）长任务与多 Agent。

3.4 如何选

场景	更合适的手段
需要大量来回对话、单 Agent 即可	Compaction
有明确里程碑、迭代开发	结构化笔记
复杂研究、需并行探索与综合	子 Agent / 多 Agent

4. Contextual Retrieval（RAG 进化）[2]

问题：传统 RAG（Retrieval Augmented Generation，检索增强生成）切片会丢失上下文（如切片里只有「他同意了」，却不知道「他」指谁）。
做法：在切片前让模型先生成一段解释性上下文，再基于「原文 + 解释」做检索，提升检索准确率，被视为当前 RAG 的先进实践之一。

4.1 可运行代码示例：轻量 Compaction [1]

当 context 接近上限时，用模型对「最近 N 条消息 + 关键决策」做摘要，再以摘要 + 最近几条新消息作为新 context 继续。下面为最小可运行 示例：将一段模拟对话压缩为摘要。需 pip install anthropic 并设置 ANTHROPIC_API_KEY。

python 复制代码

from anthropic import Anthropic

client = Anthropic()

# 模拟即将「满」的对话片段（实际可从 messages 截取）
recent_conversation = """
[User] 请实现登录 API，要校验邮箱格式。
[Assistant] 已添加 validate_email 和 /login 路由；当前只支持密码登录。
[User] 再加一个「忘记密码」流程，发重置链接到邮箱。
[Assistant] 已添加 /forgot-password 与 send_reset_email；重置链接 24h 有效。
[User] 登录时还要记录 last_login_at。
"""

compaction_prompt = f"""请将以下开发对话压缩为一段简短摘要，用于在新对话中「接上进度」。
要求：保留架构/接口决策、未完成项、关键实现要点；去掉冗余细节与重复说明。
输出仅一段摘要，不要列表。

对话：
{recent_conversation}
"""

resp = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=512,
    messages=[{"role": "user", "content": compaction_prompt}],
)
summary = resp.content[0].text
# 新 context = 摘要 + 后续新消息（此处略）
print("Compaction 摘要:", summary[:400])

Just-in-time 按需加载可用「工具返回文件/检索结果」实现，Agent 在需要时再调用工具拉取内容，见（一）（二）的工具与 agent 循环。LangGraph 1.0 下 load_on_demand、笔记与 compaction 的等价写法见延伸阅读的「五、LangGraph 1.0 对照代码」§5.3。

5. 实战自检清单

System prompt 是否最小必要、分节清晰？是否避免硬编码复杂逻辑或过于笼统？
是否优先「按需加载」而非一次性塞满？是否用目录/命名/时间戳等元数据引导使用？
长对话是否规划了 compaction 或 tool 结果清理？长任务是否用笔记或子 Agent 分担 context？
若做 RAG，是否考虑 Contextual Retrieval 式「先解释再切片」？

6. 本模块要点回顾（便于自检与分享）

约束：context 是有限资源；存在注意力预算与 context rot；目标是用最少高信号 token 达成结果。
组成：system prompt 最小必要、分节清晰；tools 少重叠、token 高效；examples 少量多样。
检索：优先 just-in-time 按需加载；用路径/命名/时间戳等元数据引导；可混合预取与按需。
长时程：compaction（摘要+新窗）、结构化笔记（持久状态）、子 Agent（主 Agent 只拿压缩结果）；按场景选。
RAG：Contextual Retrieval 在切片前生成解释性上下文，减轻指代丢失。

参考文献（本模块）

编号	来源	链接
[1]	Anthropic, Effective context engineering for AI agents	https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
[2]	Anthropic, Introducing Contextual Retrieval	https://www.anthropic.com/engineering/contextual-retrieval

7. 延伸

Memory and context management cookbook ： tool-use-memory-cookbook。
GitHub ： claude-quickstarts 中 autonomous-coding 等项目的 context/进度管理可与本模块对照；索引有「GitHub 与官方源码」汇总。
上一模块：（二）工具设计 · 下一模块：（四）长任务与多 Agent。