上下文工程实战：决定 AI 输出质量的第一变量

上下文是 AI 输出质量的第一变量

大多数人把精力放在”怎么写 prompt”上，但实际上决定 AI 输出质量的第一变量是你给了它什么上下文。

一个普通的 prompt + 精心组织的上下文 > 一个精心设计的 prompt + 混乱的上下文。

---

上下文工程的四个层次

第一层：环境上下文（始终存在）

这是 AI 在每次交互中都能”看到”的背景信息：

• Claude Code：CLAUDE.md + 项目目录结构 + 最近的 git 状态
• Cursor：Rules 文件 + 当前打开的文件 + 项目索引
• Codex：AGENTS.md + 仓库完整快照

优化策略：投入时间写好这些文件。你花 30 分钟写一份好的 CLAUDE.md，之后每次对话都能受益。

CLAUDE.md 的关键内容：

# 项目名称

## 技术栈
- 前端: React 19 + TypeScript + TailwindCSS
- 后端: Node.js + Hono
- 数据库: PostgreSQL + Drizzle ORM
- 部署: Vercel

## 目录结构
src/
  app/       # 路由和页面
  lib/       # 共享逻辑
  components/ # UI 组件

## 代码规范
- 使用 TypeScript strict mode
- 组件文件使用 PascalCase
- 工具函数使用 camelCase
- 禁止使用 any 类型

## 常用命令
- dev: npm run dev
- build: npm run build
- test: npm test

第二层：任务上下文（每次对话指定）

针对当前任务需要 AI 知道的具体信息：

给什么：

• 相关的源代码文件（只给相关的，不是全部）
• 错误信息/日志（完整的，不要截断）
• 相关的设计文档或需求描述
• 类似功能的参考实现

不给什么：

• 不相关的文件（噪声）
• 过长的历史对话（信息污染）
• 模糊的口头描述（“你懂的那个功能”）

第三层：反馈上下文（迭代中积累）

在多轮对话中，你的反馈本身就是重要上下文：

轮次1: "实现一个用户登录功能"
AI: (生成基础版本)

轮次2: "这里需要加上 rate limiting，用 token bucket 算法"
AI: (加入限流逻辑)

轮次3: "限流阈值从环境变量读取，不要硬编码"
AI: (改为配置化)

每一轮反馈都在精确化需求。这比一次性写一个超长 prompt 更高效，因为你可以基于 AI 的输出做精准纠正。

第四层：外部上下文（按需获取）

通过 MCP 或工具调用从外部系统获取的信息：

• 数据库 schema（通过 DB MCP server）
• API 文档（通过 context7 或 web fetch）
• 第三方库的最新用法（通过文档查询）
• 生产环境的错误日志（通过监控系统 MCP）

---

常见的上下文错误

错误1：信息过载

把整个项目的 20 个文件都扔给 AI，“你自己看着办”。

问题：AI 会”注意力分散”，可能忽略真正重要的文件中的关键细节。

正确做法：只给 3-5 个最相关的文件，并明确告诉 AI “重点看 X 文件的 Y 函数”。

错误2：信息不足

只说”这个 bug 怎么修”，不给报错信息、不给相关代码。

问题：AI 只能猜测，输出的方案大概率偏离实际情况。

正确做法：提供完整的错误堆栈 + 相关代码 + 你已经尝试过什么。

错误3：历史污染

在一个对话里先做了任务 A，再做完全不相关的任务 B。

问题：任务 A 的上下文会干扰任务 B 的输出，AI 可能用 A 的约定去处理 B。

正确做法：不同任务开新对话。一个对话只解决一个问题。

错误4：隐含假设

你心里知道”这个项目用 Tailwind v4”，但没有明确告诉 AI。

问题：AI 可能默认 Tailwind v3 的语法，生成的代码需要你手动修改。

正确做法：在 Rules/CLAUDE.md 中明确写清楚版本号和关键约定。

---

实战模板

模板1：Bug 修复的上下文

## 问题描述
[一句话描述 bug 表现]

## 复现步骤
1. ...
2. ...

## 错误信息
[完整的错误堆栈]

## 相关文件
- [关键文件1的路径和相关函数]
- [关键文件2的路径和相关函数]

## 已尝试的方案
- 尝试过 X，结果是...
- 排除了 Y 的可能性，因为...

模板2：新功能开发的上下文

## 功能需求
[2-3 句话描述要做什么]

## 影响范围
- 需要修改的文件: [列出]
- 需要新建的文件: [列出]
- 依赖的现有模块: [列出]

## 参考实现
[类似功能在项目中的现有实现路径]

## 约束
- 性能要求: ...
- 兼容性要求: ...
- 安全要求: ...

模板3：代码审查的上下文

## 变更目的
[这次修改要解决什么问题]

## 关注点
- 请重点检查: [具体方面]
- 已知的 trade-off: [你选择这么做的原因]

## 变更范围
[git diff 或文件列表]

---

度量你的上下文质量

如何判断你给的上下文够不够好？看 AI 的响应：

AI 响应信号	意味着	应该做
”我假设你使用的是…”	信息不足	明确告诉它技术栈版本
输出完全偏离预期	关键上下文缺失	补充相关文件和需求描述
输出过于泛化/教科书式	缺少项目特定信息	给出项目中的具体代码示例
精准命中需求	上下文恰到好处	继续保持这个模式
输出矛盾或自相冲突	上下文有冲突信息	清理对话或重新组织信息

---

小结

上下文工程的操作原则：给对的信息，给够的量，在对的时机。

• 对的信息：只给相关的，排除噪声
• 够的量：不多不少，AI 不用猜
• 对的时机：持久信息放 Rules，临时信息放对话

上下文质量直接影响返工次数。如果你发现经常需要多轮纠正 AI 输出，优先检查给出的上下文是否充分、准确、无冲突，而不是反复调整 prompt 措辞。

最后验证日期：2026-06-13。工具的上下文机制、默认行为和配置文件格式可能随版本更新变化，使用前请核对官方文档。