context-engineering

name	context-engineering
description	Feeds agents the right information at the right time. Use when starting a session, switching tasks, or output quality drops.

上下文工程

Overview

AI Agent 的能力上限 = 它的上下文质量。上下文太少 → 幻觉；上下文太多 → 注意力稀释。上下文工程是管理这一平衡的学科：在正确的时间投喂正确的信息，并用渐进式披露避免上下文窗口溢出。

When to Use

• 开始一个新的开发会话时
• 在多个任务间切换时
• 发现 Agent 输出质量下降（幻觉、遗漏、重复）
• Agent 上下文窗口接近极限
• 设置新项目或代码库的规则文件
• NOT for 单文件、独立、不需要额外上下文的简单问题
• NOT for 用户明确说"不要读其他文件，只看这个"

Core Process

1. 分层上下文 — 分三个层级组织信息：

   • L1 核心（始终在上下文中）：项目 README、AGENTS.md、当前任务描述
   • L2 按需（任务开始前加载）：相关模块文档、接口定义、架构图
   • L3 按需（任务进行中按需获取）：源码文件、测试文件、日志

2. 规则文件 — 为每个项目维护 AGENTS.md，包含：

   • 启动命令、lint/test 命令
   • 架构约定和设计决策
   • 已知陷阱和常见错误
   • 语言要求（中文/英文）

3. 上下文打包 — 把零散信息整合为紧凑的摘要：

   • 不要丢 10 个文件让 Agent 自己看 → 提取关键片段
   • 用 grep 搜索相关代码而不是全量读取
   • 复杂的 API 或协议用示例替代完整文档

4. MCP 集成 — 用 MCP 服务器提供不应常驻上下文但需要时可即时获取的信息：

   • 数据库 schema、API 文档、设计文件
   • 工具服务器的结构化数据

5. 渐进式披露 — 不要一次性把所有信息放入上下文：

   • 先放任务描述和 L1 核心
   • 确定需要时再加载 L2
   • Agent 主动搜索时再引入 L3

Common Rationalizations

Rationalization	Reality
"把整个代码库丢进上下文最安全"	上下文窗口溢出 → 注意力稀释 → 输出质量崩溃
"每个文件都让 Agent 自己读一遍"	浪费上下文窗口，且 Agent 不知道哪些文件关键
"规则文件写一次就够了"	代码库演化，规则需要同步更新
"我设好了规则，Agent 会自己遵守"	规则在上下文后半段会被遗忘，需要定期重申
"信息多总比信息少好"	噪声信号比 = 输出质量的反比

Red Flags

• 一个会话中读了超过 20 个文件
• Agent 频繁忘记前几步的结论
• 任务描述中重复了已经在 AGENTS.md 中的信息
• Agent 输出了与项目约定不符的代码
• 感觉"跟它说了很多遍了，它就是记不住"
• AGENTS.md 内容超过 200 行（太长，Agent 不会全读）

Verification

• L1 核心上下文（任务描述 + 规则文件）始终在上下文中
• 没有因为上下文过多导致 Agent 输出质量下降
• AGENTS.md 包含了启动命令、lint/test 命令、已知陷阱
• 需要时通过 MCP 或搜索获取 L3 信息，而非预加载
• 任务切换后清理了上一个任务的 L2/L3 上下文