03a - 上下文工程方法论

本文是《AI Agent 实战手册》第 3 章第 1 节。 上一节：Prompt 模板库 | 下一节：规则文件编写指南

概述

2025 年中，Shopify CEO Tobi Lütke 的一条推文让”上下文工程”（Context Engineering）这个概念迅速出圈——他说”比起 prompt engineering，我更喜欢 context engineering 这个词，它更准确地描述了核心技能：为任务提供所有上下文，使 LLM 有可能解决它。“Andrej Karpathy 也表达了类似观点：在工业级 LLM 应用中，真正的技术是精心填充上下文窗口。本节系统讲解上下文工程的方法论，解释它为什么比单纯的 prompt engineering 更重要，并拆解四大支柱及其协作关系。

1. 什么是上下文工程？

定义

上下文工程是一门系统化设计、组织和管理 AI 模型输入信息的学科。它关注的不是”怎么问”（prompt engineering），而是”给什么”——在每次 LLM 调用之前，确保模型看到的是恰到好处的信息组合。

与 Prompt Engineering 的关系

为什么上下文工程比 Prompt Engineering 更重要？

1. 模型能力已经足够好，瓶颈在输入质量

2025-2026 年的前沿模型（Claude 4、GPT-4.5、Gemini 2.5 Pro）在推理能力上已经非常强大。大多数失败不是因为模型”不够聪明”，而是因为它没有看到正确的信息。一个精心设计的 prompt 如果缺少关键上下文，输出质量依然很差。

2. Agent 时代需要系统级思维

当 AI 从单次问答进化到多步骤自主执行（Agentic Loop），每一步的上下文都在变化。Prompt engineering 只能优化单个节点，而 context engineering 设计的是整条信息管线——从工具输出到记忆检索，从规则注入到历史压缩。

3. 上下文失败的代价远高于 prompt 失败

Firecrawl 团队总结了上下文的四种失败模式：

• 中毒（Poisoning）：错误信息混入上下文，导致模型基于错误前提推理
• 干扰（Distraction）：无关信息过多，模型注意力被分散
• 混淆（Confusion）：格式不一致或结构混乱，模型无法正确解析
• 冲突（Clash）：不同来源的信息相互矛盾，模型无所适从

这些问题无法通过”写更好的 prompt”来解决，必须从系统层面管理上下文。

4. 更大的上下文窗口不等于更好的结果

Databricks 的研究发现，LLM 的准确率在约 32K token 处开始下降，远早于百万 token 的窗口上限。更多信息不等于更好的结果——关键是信息的相关性和组织方式。

2. 上下文工程的四大支柱

上下文工程的核心是管理四类信息源，它们共同构成 AI agent 的”认知环境”。

支柱关系图

┌─────────────────────────────────────────────────┐
│              AI Agent 上下文窗口                  │
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ 项目文件  │  │ 规则文件  │  │ 工具连接  │       │
│  │          │  │          │  │          │       │
│  │ 代码库   │  │ CLAUDE.md│  │ MCP      │       │
│  │ 文档     │  │ Steering │  │ API      │       │
│  │ 配置     │  │ .cursor  │  │ 数据库   │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       │             │             │              │
│       └──────┬──────┘             │              │
│              │                    │              │
│              ▼                    ▼              │
│  ┌─────────────────────────────────────┐        │
│  │           记忆管理                    │        │
│  │                                      │        │
│  │  会话历史 │ 工作记忆 │ 长期记忆       │        │
│  │  (对话)   │ (草稿本) │ (向量存储)     │        │
│  └─────────────────────────────────────┘        │
└─────────────────────────────────────────────────┘

支柱一：项目文件（Project Files）

项目文件是 AI agent 理解你的代码库和业务领域的基础。

包含内容：

• 源代码文件（agent 需要读取和修改的代码）
• 项目文档（README、API 文档、架构决策记录）
• 配置文件（package.json、Cargo.toml、tsconfig.json 等）
• 测试文件（帮助 agent 理解预期行为）
• 数据模型定义（数据库 schema、GraphQL schema、OpenAPI spec）

关键策略：

• 不要把整个代码库塞进上下文——选择与当前任务相关的文件
• 使用 .gitignore 风格的排除规则过滤无关文件（node_modules、build 产物等）
• 为大型项目提供”代码地图”（codebase map），帮助 agent 快速定位

支柱二：规则文件（Rule Files）

规则文件是你与 AI agent 之间的”契约”，定义了编码规范、项目约定和行为边界。

主要形式：

关键策略：

• 规则文件应该包含：项目结构说明、编码规范、技术栈约定、常用命令、禁止事项
• 保持规则简洁明确——过长的规则文件反而会稀释重要信息
• 定期更新规则文件，使其与项目演进保持同步

详见 规则文件编写指南

支柱三：工具连接（Tool Connections）

工具连接让 AI agent 能够与外部世界交互——读取数据库、调用 API、操作文件系统、执行命令。

主要形式：

• MCP（Model Context Protocol）：标准化的工具连接协议，支持文件系统、数据库、API 等
• 内置工具：编辑器/IDE 提供的文件读写、终端执行、搜索等能力
• 自定义工具：通过 MCP Server 或 function calling 暴露的业务特定能力

关键策略：

• 只连接当前任务需要的工具——过多的工具选项会增加 agent 的决策负担
• 为工具提供清晰的描述和使用示例，帮助 agent 正确选择
• 实施权限控制，限制 agent 对敏感操作的访问

支柱四：记忆管理（Memory Management）

记忆管理解决 LLM 的”无状态”问题——模型本身不记得之前的对话，需要外部机制来维持连续性。

记忆层次：

关键策略：

• 对长对话进行摘要压缩，保留关键信息，丢弃冗余细节
• 使用 RAG（检索增强生成）从长期记忆中按需检索相关信息
• 为重要决策创建显式记录（如 ADR），而不是依赖对话历史

3. 上下文工程的工作流

三层上下文模型

Kubiya 团队提出了一个实用的三层上下文模型：

┌─────────────────────────────────┐
│     指令层（Instructional）       │  ← 系统 prompt、规则文件、角色定义
├─────────────────────────────────┤
│     知识层（Knowledge）           │  ← 项目文件、文档、RAG 检索结果
├─────────────────────────────────┤
│     工具层（Tool）               │  ← MCP 工具、API 调用、数据库查询
└─────────────────────────────────┘

四步操作法

在每次 LLM 调用之前，上下文工程师需要执行四个操作：

1. 写入（Write）— 外部记忆

• 将重要信息持久化到外部存储（文件、数据库、向量存储）
• 不要依赖上下文窗口来”记住”一切

2. 选择（Select）— 相关检索

• 从所有可用信息中，选择与当前任务最相关的子集
• 使用语义搜索、关键词匹配、文件路径过滤等方法

3. 压缩（Compress）— 摘要精简

• 对选中的信息进行压缩，去除冗余，保留核心
• 长对话历史可以用摘要替代完整记录

4. 隔离（Isolate）— 分区执行

• 将复杂任务分解为独立的子任务，每个子任务有自己的上下文
• 避免不相关的信息在子任务间交叉污染

4. 上下文工程在 AI 编码中的应用

工具推荐

实际工作流示例

以一个 Next.js 全栈项目为例，展示上下文工程的实际应用：

项目根目录/
├── CLAUDE.md              ← 规则文件：项目结构、编码规范、常用命令
├── .kiro/
│   └── steering/
│       ├── coding-standards.md   ← 编码标准（始终包含）
│       └── api-patterns.md       ← API 模式（条件包含：匹配 src/api/**）
├── .cursorrules           ← Cursor 规则文件
├── docs/
│   ├── architecture.md    ← 架构文档（项目文件）
│   └── api-spec.yaml      ← API 规范（项目文件）
├── src/                   ← 源代码（项目文件）
└── .kiro/
    └── settings/
        └── mcp.json       ← MCP 工具连接配置

当开发者要求 agent “实现用户注册 API”时，上下文组装过程：

1. 指令层：加载 CLAUDE.md / Steering 规则 → agent 知道项目用 TypeScript + Prisma + Next.js API Routes
2. 知识层：读取 api-spec.yaml 中的注册端点定义 + 现有 auth 模块代码 → agent 理解接口规范和现有模式
3. 工具层：通过 MCP 连接数据库查看 User 表结构 → agent 知道数据模型
4. 记忆层：检索之前关于认证方案的讨论记录 → agent 知道团队选择了 JWT + bcrypt

实战案例：从”裸 prompt”到”工程化上下文”

场景：让 AI 为 Rust 项目添加错误处理

❌ 裸 prompt（无上下文工程）

给这个函数添加错误处理

结果： agent 不知道项目用的是 anyhow 还是 thiserror，不知道团队的错误处理规范，生成的代码风格与项目不一致。

✅ 工程化上下文

# CLAUDE.md 中已定义：
- 错误处理使用 thiserror 定义领域错误，anyhow 用于应用层
- 所有公共 API 返回 Result<T, AppError>
- 错误日志使用 tracing crate

# Agent 自动读取：
- src/error.rs（现有错误类型定义）
- Cargo.toml（依赖版本）
- 相关模块的现有错误处理模式

# 用户 prompt：
给 src/sync_engine.rs 中的 sync_files 函数添加错误处理

结果： agent 生成的代码完全符合项目规范，使用正确的错误类型，日志格式一致，无需人工修正。

避坑指南

❌ 常见错误

1. 把整个代码库塞进上下文

   • 问题：信息过载导致模型注意力分散，关键信息被淹没，且浪费 token 预算
   • 正确做法：只选择与当前任务相关的文件，使用 .gitignore 风格的排除规则

2. 规则文件写成小说

   • 问题：过长的规则文件（>2000 行）会稀释重要规则的权重，模型可能忽略关键约定
   • 正确做法：保持规则简洁（500-1000 行以内），按优先级排列，最重要的规则放在最前面

3. 忽略上下文的动态性

   • 问题：使用固定的上下文模板，不根据任务类型调整
   • 正确做法：根据任务类型动态组装上下文——写测试时加载测试规范，做架构设计时加载架构文档

4. 不管理对话历史

   • 问题：长对话中早期信息被截断或遗忘，导致 agent 行为不一致
   • 正确做法：定期压缩对话历史，将关键决策写入外部记忆

5. 工具连接过多

   • 问题：给 agent 连接了 20 个 MCP server，每次调用都要在众多工具中选择
   • 正确做法：只启用当前任务需要的工具，减少 agent 的决策负担

相关资源与延伸阅读

核心概念

• Context Engineering for AI Coding 101 — Packmind  — 上下文工程入门教程，清晰解释核心概念和实践方法
• AI-Ready Codebase Guide — LLMX  — 如何让代码库对 AI Agent 友好的完整指南

工具与框架

• LangChain  — 最流行的 LLM 应用框架，内置上下文管理和 RAG 能力
• LlamaIndex  — 专注数据索引和检索的框架，擅长将外部知识注入 AI 上下文
• Langfuse  — 开源 LLM 可观测性平台，追踪上下文使用效率

规则文件示例

• Awesome CLAUDE.md  — 社区收集的 CLAUDE.md 示例和最佳实践
• Awesome CursorRules  — 社区收集的 .cursorrules 文件模板
• Kiro Steering 官方文档  — Kiro Steering 文件的编写指南和示例

社区与讨论

• r/ChatGPTCoding  — 讨论 AI 编码工具的上下文管理策略
• Context Engineering — Martin Fowler  — Martin Fowler 对上下文工程的深度分析

参考来源

• Context Engineering for AI Coding Agents — Pixelmojo （2026-02）
• Context Engineering Best Practices — Kubiya （2025-10）
• Context Engineering vs Prompt Engineering — Firecrawl （2025-12）
• Context Engineering: The Next Frontier — Deepset （2025-12）
• Beyond Prompt Engineering — Forbes （2025-09）
• Context Engineering with OpenAI — Fractal AI （2026-02）

📖 返回 总览与导航 | 上一节：Prompt 模板库 | 下一节：规则文件编写指南