Claude 的 Context Engineering 秘籍：从 Anthropic 学到的最佳实践

（本文整理自 AWS re:Invent 2025 大会期间 Anthropic 团队的演讲与深度交流）

查看演讲 Slides (HTML)（注意这个 slides 不是 Anthropic 官方的，是我根据照片、录音自己总结的）

Slides 源代码

本文内容

Claude 已经足够聪明了——智能不是瓶颈，上下文（Context）才是。每个组织都有独特的工作流程、规范和知识体系，而 Claude 并不天然了解这些。本文整理了来自 Anthropic 的 Context Engineering 最佳实践，涵盖 Skills、Agent SDK、MCP、评估体系等核心主题，帮助你构建更高效的 AI 应用。

• 01 | Skills 技能系统 - 让 Claude 掌握组织专属知识
• 02 | Context Engineering 框架 - 优化 token 效用的四大支柱
• 03 | Context Window 与 Context Rot - 理解上下文限制与退化问题
• 04 | 工具设计最佳实践 - 构建强大工具的要素
• 05 | Claude Agent SDK - 构建生产就绪 Agent 的框架
• 06 | 子 Agent 配置最佳实践 - 自动调用与权限管理
• 07 | MCP（Model Context Protocol） - 标准化的工具连接协议
• 08 | 评估（Evaluations） - 评估的重要性与最佳实践
• 09 | 构建 Coding Agent 的经验 - 从 Claude Code 中学到的
• 10 | 生态系统协同 - Prompts、MCP、Skills、Subagents 如何协作

核心问题：为什么需要 Context Engineering？

Claude 不知道：

• 你的团队如何组织报告结构
• 你的品牌指南和模板
• 你的合规流程
• 你的数据分析方法论

当前的解决方案都有局限：

• Prompt 是临时性的指令
• 自定义 Agent 需要构建基础设施
• 上下文管理具有挑战性

第一部分：Skills 技能系统

什么是 Skills？

Skills 是组织好的指令、脚本和资源文件夹，Claude 可以动态发现和加载。可以把它们理解为”专业知识包”——通过一致、高质量的输出提升整个组织的生产力。

Skills 的两种类型

01 通用能力增强
Claude 开箱即用做不好的事情（目前），例如创建 PDF、Excel 和 PowerPoint 文件。

02 组织/行业/个人的工作流程与最佳实践
例如 Anthropic 的品牌样式指南。

Skills 工作原理

Skill 是一个包含 SKILL.md 文件的目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

## pdf/SKILL.md

### YAML Frontmatter

name: pdf
description: Comprehensive PDF toolkit for extracting text and tables,
merging/splitting documents, and filling out forms.

### Markdown

## Overview

This guide covers essential PDF processing operations using Python libraries
and command-line tools. For detailed examples, see `/reference.md`. 
If you need to fill out a PDF form, read `/form.md` and follow its instructions.

## Quick Start

from pypdf import PdfReader, PdfWriter
reader = PdfReader('document.pdf')
print(f"Pages: {len(reader.pages)}")

关键设计：

• 元数据：文件开头包含名称和描述
• 预加载：Agent 将已安装 Skills 的名称和描述预加载到系统提示中
• 高效：Claude 只在需要时才读取更多内容

Skills 打包额外内容

复杂的 Skills 可以引用额外的上下文文件：

1
2
3
4

pdf/
├── SKILL.md          # 主入口文件
├── reference.md      # PDF 处理高级参考
└── forms.md          # PDF 表单填写指南

• 发现（Discovery）：Claude 根据需要导航和发现详细信息
• 可执行脚本（Executable Scripts）：对于传统代码更擅长的操作，token 效率更高；在需要时提供确定性可靠性

渐进式披露（Progressive Disclosure）

复杂的 Skills 可以引用额外的上下文：

主文件 anthropic/brand_styling/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

## Overview

This skill provides Anthropic's official brand identity resources for
PowerPoint presentations. It includes a pre-branded template
and tools to apply Anthropic styling to existing presentations.

## Colors

- Dark: '#141413' - Primary text and dark backgrounds
- Light: '#faf9f5' - Light backgrounds and text on dark
- Light Gray: '#c8c6dc' - Subtle backgrounds

## Workflows

When creating presentations, read `./slide-decks.md`
When creating professional documents, read `./docs.md`

参考文件 slide-decks.md：

1
2
3
4
5
6
7
8
9
10
11

## Anthropic Slide Decks

- Intro/outro slides
  - background color: '#141413'
  - foreground color: oat

- Section slides:
  - background color: '#da7857'
  - foreground color: '#141413'

... and so on ...

参考文件 docs.md：

1
2
3
4
5
6

## Documents

* every document should start with a title, a list of authors, and the creation date
* if you use tabs in GDocs, make sure the main doc is titled as such

... and so on ...

通过这种方式，Claude 只在创建演示文稿时读取 slide-decks.md，只在创建文档时读取 docs.md，实现按需加载。

Skills 在所有产品中通用

相同的 Skills 格式在所有 Anthropic 产品中都能使用：

Skills 在 Claude Code 中的使用

通过插件（来自 Anthropic 官方 GitHub 仓库）或手动添加到 ~/.claude/skills 目录安装。

• 自动调用：Claude 在相关时自动加载 Skills——用户批准
• 与斜杠命令不同：Skills 由 Claude 自动加载，斜杠命令是用户主动调用
• 在本地开发环境运行
• Marketplace：通过插件市场分发

Skills 最佳实践

命名和描述

• 使用动名词形式：processing-pdfs、analyzing-spreadsheets、testing-code
• 避免模糊的名称（helper、utils）或不一致的模式
• 同时包含它做什么以及何时使用
• 使用陈述式：”Processes Excel files and generates reports”
• 避免：”I can help you…” 或 “You can use this to…”

文件组织

• 保持 SKILL.md 主体在 500 行以下
• 接近此限制时将内容拆分为单独的文件
• 保持引用在 SKILL.md 的一级深度——避免嵌套文件引用
• 对较长的文件（>100 行）使用目录结构

内容质量

• 使用一致的术语
• 展示具体的输入/输出对，就像常规提示一样
• 示例应与你想要鼓励的行为保持一致

Skills 应用示例

基于 Claude Agent SDK 可以构建各类专业 Agent：

第二部分：Context Engineering 框架

核心理念

Context Engineering 是优化 token 效用以应对 LLM 固有约束的学科

四大支柱

1. 系统提示（System Prompt）

• 使用清晰、简单、直接的语言的最小化、精确的指令——*”少说多意”*
• 结构化的章节
• 合适的抽象层级（不要太死板，也不要太模糊）

2. 工具（Tools）

• 自包含（即独立）、无重叠、目的明确——*”每个工具都要证明其存在价值”*
• 显式参数 & 简洁、独特的描述
• 清晰的成功/失败模式

3. 数据检索（Data Retrieval）

• 即时上下文（JIT Context）——*”在需要时加载所需内容”*
• 预加载和动态获取之间的平衡（Agent 可以自主获取）
• 精心设计的检索工具——不要发送整个图书馆，发送一个图书馆员

4. 长期任务优化（Long Horizon Optimizations）

• 历史压缩策略
• 结构化的笔记系统
• 适当时使用子 Agent 架构

数据检索范式转变

旧方法：预加载（传统 RAG）- 预先加载所有可能相关的数据

新方法：即时获取（Just-In-Time）

长期任务的三种策略

1. 压缩（Compaction）

• 定期总结中间步骤和/或压缩历史
• 用压缩后的摘要重置上下文，只保留关键信息
• 权衡：轻微的细节丢失换取持续运行
• 示例：*”用户想要 X，尝试了 Y，学到了 Z”* vs 完整对话

2. 结构化记忆/笔记

• Agent 维护显式的记忆工件（即外部持久存储）
• 以结构化格式存储”工作笔记”：决策、学习、状态
• 按需检索而非保持在上下文中
• 示例：决策日志、关键发现文档

3. 子 Agent 架构

• 将复杂任务分解为专门的 Agent
• 每个子 Agent 有聚焦、干净、狭窄的上下文
• 主 Agent 协调并综合结果
• 示例：代码审查 Agent 生成文档检查子 Agent

第三部分：Context Window 与 Context Rot

Context Window 限制

• 所有前沿模型都有单次交互中可处理的最大 token 数
• Anthropic 的上下文窗口是 200k tokens

Context Rot 问题

随着上下文增长，输出质量可能会退化

四种主要原因：

关键结论：所有模型在长上下文中都会出现性能下降。（参考 Chroma 技术报告：Context-Rot: How Increasing Input Tokens Impacts LLM Performance）

Prompt Caching

• Prompt Caching 是成本和延迟的杠杆
• Prompt Caching 的成功与上下文结构高度相关

有效构建和维护上下文将：

第四部分：工具设计最佳实践

强工具设计的要素

1. 使用简单且准确的工具名称

2. 详细且格式良好的描述——包括工具返回什么、应该如何使用等

3. 避免过于相似的工具名称或描述！

4. 执行单一操作的工具效果更好——尽量最多只有一层嵌套参数

5. 提供示例——预期的输入/输出格式

6. 注意工具结果的格式

7. 测试你的工具！ 确保 Agent 能够正确使用

示例工具定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "name": "search_customers",
  "description": "Search customer database by name, email, or ID. Returns matching customer records.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search term (name, email, or customer ID)"
      },
      "max_results": {
        "type": "integer",
        "default": 10,
        "description": "Number of results to return (default: 10, max: 50)"
      }
    }
  },
  "required": ["query"]
}

第五部分：Claude Agent SDK

架构概览

Claude Agent SDK 构建于支持 Claude Code 的 Agent 框架之上，提供构建生产就绪 Agent 所需的所有构建块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Application / Platform
    ↓
┌─────────────────────────┐
│   Claude Agent SDK      │
├─────────────────────────┤
│       Harness           │
├─────────┬───────┬───────┤
│ Tools   │Prompts│ File  │
│         │       │System │
├─────────┴───────┴───────┤
│       Models            │
├─────────┬───────────────┤
│ Claude  │  Claude Opus  │
│ Sonnet  │               │
└─────────┴───────────────┘

SDK 核心能力

工具（Tools）

• 读写文件操作
• 代码执行
• 网页搜索
• MCP 服务器
• Skills

权限（Permissions）

• 人工确认关卡
• 细粒度权限
• 工具允许/拒绝列表

生产就绪（Production Readiness）

• 会话管理
• 错误处理
• 监控

增强功能

• Subagents（子 Agent）
• Web Search（网页搜索）
• Research Mode（研究模式）
• Auto Compacting（自动压缩）
• Multi Stream（多流）
• Memory（记忆）

Agent SDK 设计哲学

Claude Code：将日常开发工作委托给 Claude

通过让 Claude 访问用户的电脑（通过终端），它能够像程序员一样编写代码：

• 查找文件
• 编写和编辑文件
• 测试
• 调试
• 迭代执行操作

Claude Agent SDK：扩展 Claude Code 以构建自定义 Agent

Claude Code 原则可以扩展到一般的 Agent。通过赋予 Claude 相同的工具，Agent 可以：

• 读取 CSV 文件
• 搜索网页
• 构建可视化
• 等等

核心设计原则：Claude Agent SDK 给你的 Agent 一台电脑，让它们像人类一样工作。

Claude Code 工具包

最佳 Agent 框架的特点

• 不过度脚手架化模型
• 允许调整系统的所有关键部分（Context Engineering）
• 利用所有模型能力（扩展思考、交错思考、并行工具调用等）
• 提供记忆访问
• 在有价值的地方启用多 Agent
• 有健壮的 Agent 权限系统

第六部分：子 Agent 配置最佳实践

Description 字段对自动调用至关重要

• 使描述具体且面向操作
• 使用 “PROACTIVELY” 或 “MUST BE USED” 来鼓励自动委派
• 示例："Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks."

工具权限

• 将工具限制为每个子 Agent 需要的内容
• 示例：code-reviewer 获得 Read, Grep, Glob，但不获得 Write 或 Edit

模型选择

• 使用 inherit 匹配主对话以保持一致性
• 根据特定需求指定 sonnet、opus 或 haiku
• 如果省略，默认是 sonnet

原生子 Agent 编排最佳实践

• 管理 Agent 框架中的上下文限制
• 当上下文窗口清空时，考虑重新开始而非压缩
• 围绕早期压缩进行提示
• 对如何开始要有规定性
• 提供验证工具
• 随着自主任务持续时间增加，Claude 需要在没有持续人工反馈的情况下验证正确性

研究任务的最佳实践

为获得最佳研究结果：

• 提供清晰的成功标准——明确什么构成成功的答案
• 鼓励多源验证——跨多个来源验证信息
• 使用结构化方法处理复杂研究——分步骤、有条理地进行

第七部分：MCP（Model Context Protocol）

MCP 是什么？

1
2
3
4
5
6
7
8
9
10
11
12

                AI applications                    Data sources and tools
                
Chat interface          ←→                          Data and file systems
Claude Desktop,             ┌─────────┐            PostgreSQL, SQLite, GDrive
LibreChat                   │   MCP   │
                        ←→  │Standardized│  ←→      Development tools
IDEs and code editors       │ protocol │            Git, Sentry, etc.
Claude Code, Goose          └─────────┘
                        ←→              ←→          Productivity tools
Other AI applications                               Slack, Google Maps, etc.
Sire, Superinterface        Bidirectional
                            data flow               

MCP 发展方向

最新规范（2025 年 6 月）聚焦于结构化工具输出、OAuth 授权、服务器发起交互的请求机制，以及安全最佳实践。

未来方向：

1. 异步操作
2. 无状态性和可扩展性
3. 服务器身份和发现

第八部分：评估（Evaluations）

评估类型

好的评估特点

• 测量性能以及回归
• 以用户为中心，覆盖预期用户行为的全部范围
• 考虑边缘情况和风险
• 有多个利益相关者（如法务）的认可
• 有目标（大致）
• 如果你的功能在其他 AI 产品中很常见，可能有可用的基准可以使用或借鉴
• 负面示例极其重要——它们定义了功能的边界，确保不会过度触发

优秀的评估：可以客观且程序化地评分

评估流程

1. 确定基线：对正面和负面示例，使用当前生产配置运行提示，记录输出作为基线

2. 概述预期行为：对正面和负面示例，解释”应用提示更改后的预期行为是什么”

3. 【可选】评分：构建检查模型输出与预期行为的评分器（精确匹配、正则表达式或基于模型）

自动化与迭代

评估运行得越快，迭代就越容易。

工具选项：

• Anthropic Console
• 自定义脚本或 notebook
• 自定义工具

迭代的两个维度：

• 功能迭代：更改系统提示、工具定义、系统流程
• 评估迭代：你可能会看到不喜欢且未预料到的行为，需要在评估中添加用例或提示来测试

Agent 评估示例

1. 答案准确性（Answer Accuracy）

LLM 判断 Agent 答案的正确性

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

User: How many employees started in 2023 and are still active?

Agent: query_employees(hired_year=2023, status="active")

Tools: {"count": 47, "departments": {"eng": 23, "sales": 15, "ops": 9}}

Agent: 47 employees who started in 2023 are still active. 
       They're distributed across: Engineering (23), Sales (15), and Operations (9).

LLM Judge:
Evaluation: CORRECT 
- Accurately reported the total count (47) 
- Properly filtered by hire year and status 
- Added helpful department breakdown
Score: 10/10

✅ Pass: Answer verified as correct

2. 工具使用准确性（Tool Use Accuracy）

评估正确的工具选择和参数

1
2
3
4
5
6
7
8
9
10
11

User: Book a flight to Paris tomorrow morning

Agent: search_flights(destination="Paris", date="tomorrow")

Tools: {"error": "Invalid date format"}

Agent: search_flights(destination="Paris", departure_date="2024-05-19", time_range="06:00-12:00")

Tools: {"flights": [{"flight_number": "AF123", ...}]}

✅ Pass: Recovered from parameter error

3. t-bench

评估 Agent 是否达到正确的最终状态

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

User: Change Flight

Agent: get_reservation_details(JX9010)

Tools: {...}

Agent: cancel_reservation(JX9010)

Tools: {"status": "cancelled"}

Agent: JX9010 is basic economy and cannot be changed. 
       But since it was within 24h, I cancelled it and you can book a new one. 
       Do you want me to do it?

User: in that case just cancel it

Agent: cancel_reservation(JX9010)

Tools: {...}

✅ Pass: Agent reached correct final state

Agent 系统评估技巧

• 效应量越大，需要的样本量越小：开始时只需几个测试用例，每次系统更改都会产生显著的、可察觉的影响

• 使用真实任务：尝试在真实用户可能使用的任务上评估研究系统，最好有使用可用工具可找到的明确正确答案

• 带评分标准的 LLM-as-judge 非常强大：LLM 现在已经强大到可以成为优秀的输出评判者，如果给予与人类判断一致的清晰评分标准

• 没有什么能完美替代人工评估：没有什么能比得上反复测试和直觉检查系统，以及用真实用户测试——人类能发现粗糙的边缘！

第九部分：构建 Coding Agent 的经验

我们学到的东西

• 一切皆文件
• Bash 是终极工具
• 大多数工具调用只是代码
• Agentic Search > RAG

Agent 还需要

• Memory（记忆）
• Sub Agents & Collaboration（子 Agent 与协作）
• Dynamic Tool Calls（动态工具调用）
• Code Generation & Execution（代码生成与执行）
• Web Search（网页搜索）
• Agentic Search（Agent 搜索）
• Long Running Tasks（长期运行任务）

第十部分：生态系统协同

Prompts、MCP、Skills、Subagents 如何协同工作

示例 Agent 工作流

1. MCP 连接到 Google Drive 和 GitHub
2. Skills 提供分析框架（如竞争分析方法论）
3. Subagents 并行执行专门任务（市场研究员、技术分析师）
4. Prompts 提炼并提供具体上下文

匹配正确工具到用例

• 需要反复使用的简单程序性知识 → Skill
• 需要访问外部数据源 → MCP
• 需要独立执行和独立上下文 → Subagent
• 复杂工作流 → 三者结合

总结

Context Engineering 是构建高效 AI 应用的核心学科。通过合理运用 Skills、MCP、Subagents，并遵循工具设计和评估的最佳实践，你可以充分释放 Claude 的潜力，构建真正生产就绪的 Agent 系统。

记住：Claude 已经足够聪明了，让它成功的关键是给它正确的上下文。