上下文工程入门实战：从"提示词技巧"到"信息架构"

一、为什么"上下文工程"比"提示词工程"更准确

2025 年中，Anthropic 正式提出了"上下文工程"（Context Engineering）这个概念。到 2026 年，它已经成为 AI 工程领域的主流范式。原因很简单：

提示词工程只管"说什么"，上下文工程管整个信息系统。

具体来说：

• 提示词工程关注的是：怎么措辞、用什么句式、怎么组织指令
• 上下文工程关注的是：说什么、怎么说、什么时候说、用什么格式说、在什么位置说、信息从哪来、怎么更新、怎么防止过期

2026 年初，虎嗅上有一篇文章把这个演进总结为三个阶段：提示词工程到上下文工程，再到 Harness 工程（运行环境优化）。每一步都是在更大范围内做系统化的信息管理。

我个人觉得最形象的类比是：提示词工程是给 AI 写一份工作邮件，上下文工程是给 AI 搭一个完整的工作台——邮件只是工作台上的一张纸。

---

二、核心概念速览

下面这些概念是我日常开发中高频接触的，用大白话解释一下。

2.1 System Prompt：AI 的"岗位说明书"

System Prompt 是每次对话开始前就注入的指令，告诉 AI “你是谁、你的职责是什么、你应该遵守什么规则”。

它就像是新员工入职时收到的那份岗位说明书：不需要每次重复交代，但一直在起作用。

# 一个简单的 System Prompt 示例
system_prompt = """
你是一个资深 Python 后端工程师。
- 只使用 Python 3.11+ 语法
- 代码风格遵循 PEP 8
- 优先使用 Pydantic 做数据校验
- 所有 API 入参必须做类型检查
- 错误信息必须包含 code 字段和上下文描述
"""

2.2 CLAUDE.md / .cursorrules：项目级的持久化上下文

这两个文件是我日常用得最多的东西。它们本质上是一样的——让 AI 编码工具在进入项目时自动加载项目级别的规则和背景。

CLAUDE.md 是 Claude Code 的项目配置文件，.cursorrules 是 Cursor 的。2026 年越来越多的工具开始支持这类文件，比如 Windsurf、Gemini CLI 等。

关键思路：把项目规范、技术栈约束、常用命令、已知坑点都写进去，AI 每次进来就能"看到"这些信息，不需要你每次重复交代。

# CLAUDE.md 的典型结构（建议控制在 80 行以内）

## 项目简介
一句话说明这是什么项目。

## 技术栈
后端：FastAPI + SQLAlchemy + PostgreSQL
前端：React + TypeScript + Vite

## 硬性规则
- 单文件不超过 500 行
- 新增代码必须有对应测试
- 禁止使用 any 类型

## 常用命令
- 测试：poetry run pytest -v
- 启动：poetry run uvicorn app.main:app --reload
- Lint：ruff check . && ruff format .

实践建议：CLAUDE.md 不要一次塞太多内容。Anthropic 官方建议控制在 200 行以内，我自己体感是 80 行左右效果最好。太长的话 AI 反而会被干扰，关键信息被淹没在噪声里。

2.3 Few-shot Examples：给 AI 看几个"优秀案例"

Few-shot 就是在提示词里给 AI 展示几个"输入-输出"的范例，让它知道你期望什么样的结果。

这个技巧不新鲜，但很多人用得不对。我总结了几条经验：

1. 示例要覆盖典型场景，不要只给最简单的 happy path
2. 示例之间要有差异，展示边界条件和异常处理
3. 3-5 个示例就够了，太多反而会让 AI 被特定的模式"锁死"

# Few-shot 示例：代码审查

## 示例 1：发现安全问题
输入：def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    return db.execute(query)

输出：存在 SQL 注入风险。建议使用参数化查询：
def get_user(user_id: int):
    stmt = select(User).where(User.id == user_id)
    return session.execute(stmt).scalar_one_or_none()

## 示例 2：发现性能问题
输入：def get_all_orders():
    return [order for order in Order.query.all()]

输出：缺少分页和过滤，数据量大时会 OOM。建议：
def get_orders(page: int = 1, size: int = 20, status: str | None = None):
    query = select(Order)
    if status:
        query = query.where(Order.status == status)
    return paginate(query, page=page, size=size)

2.4 上下文窗口管理：AI 的"短期记忆"有限

上下文窗口可以理解为 AI 的"工作台面积"。Claude 的窗口大概是 200K token，GPT-4 系列在 128K 左右。听起来很大，但实际用起来很容易装满。

几个关键认知：

1. 上下文不是越大越好。研究表明，模型在上下文过载时会出现"中间丢失"现象——中间部分的信息被忽略。学术界管这个叫"Lost in the Middle"。
2. 信息的排列位置很重要。开头和结尾的信息被关注的程度最高，中间最低。
3. 有效利用窗口的关键是"按需加载"，而不是"一股脑全塞进去"。

我自己的做法是：长对话中定期用 /clear 清理上下文，复杂任务拆成多个会话，每个会话聚焦一个子任务。

2.5 RAG（检索增强生成）：需要时才去"翻资料"

RAG 的思路很简单：不要把所有参考资料都塞进提示词里，而是让 AI 在需要的时候去检索。

打个比方，你不需要把整本手册背下来再去干活，只需要知道手册在哪、怎么查就行。

# RAG 的基本流程

1. 用户提问
2. 系统从知识库中检索相关文档片段
3. 把检索到的片段作为上下文，和用户问题一起喂给 AI
4. AI 基于这些上下文生成回答

2026 年 RAG 已经进化出好几个变种：Agentic RAG（AI 自主决定何时检索、检索什么）、Graph RAG（基于知识图谱的检索）等。但核心思想没变——按需取用，而不是全量加载。

2.6 MCP（Model Context Protocol）：让 AI 能连外部工具

MCP 是 Anthropic 在 2024 年底提出的一个开放协议，到 2026 年已经成为行业标准。它解决的问题是：怎么让 AI 模型标准化地连接外部工具和数据源。

在 MCP 出现之前，每个 AI 工具都要单独做集成。MCP 相当于定义了一个"USB 接口"——只要工具支持 MCP，任何 AI 模型都能即插即用。

# MCP 的典型使用场景

- 文件系统 MCP：让 AI 读写本地文件
- GitHub MCP：让 AI 操作仓库、创建 PR
- 数据库 MCP：让 AI 查询数据库
- 飞书/企业微信 MCP：让 AI 读取公司内部文档

一个重要的工程经验：MCP 工具不是越多越好。Anthropic 的数据显示，5 个 MCP Server 的 58 个工具就要消耗约 55K token。工具太多会导致 AI 选错工具、传错参数。2026 年的最佳实践是"按需发现，动态加载"——先给 AI 一个工具搜索入口，用到哪个加载哪个。

---

三、实战经验——我在开发中怎么用上下文工程

3.1 项目配置文件怎么写

我现在的做法是分层管理：

项目根目录/
  CLAUDE.md           # 全局规则（80 行以内）
  .claude/
    rules/
      python-style.md  # Python 编码规范
      security.md      # 安全规范
      docs-sync.md     # 文档同步规则
  docs/
    architecture/      # 架构文档
    design/            # 设计文档
    plans/             # 迭代计划

核心原则：CLAUDE.md 只放"导航地图"，详细规则分散到 rules/ 目录下按需加载。

这样做的好处：

• AI 进入项目时只读 CLAUDE.md，不会被海量信息淹没
• 需要编码规范时，AI 会自动读取 rules/ 下的对应文件
• 规则更新只改局部文件，不会影响全局

3.2 给 AI 写需求时的技巧

规格先行，小步迭代。

我现在的做法是：先写清楚我要什么，再让 AI 写代码。具体来说：

1. 描述清楚目标和约束，不要上来就说"帮我写一个 XX"
2. 指定要修改的文件和范围，不要让 AI 自由发挥
3. 一次只做一件事，做完验证再做下一件

# 不好的写法
"帮我写一个用户注册功能"

# 好的写法
"在 app/api/auth.py 中新增 POST /api/auth/register 端点。
要求：
- 入参用 Pydantic model 校验，包含 email/password/name
- password 用 bcrypt 哈希存储
- email 不可重复，重复时返回 409
- 成功时返回 201 和用户基本信息（不含密码）
- 参考 app/api/auth.py 中已有的 login 端点的代码风格"

3.3 如何组织 Few-shot 示例

我的做法是把示例做成独立的文档文件，需要时才加载。

# 项目结构
docs/
  examples/
    api-response-format.md   # API 响应格式示例
    error-handling.md        # 错误处理示例
    test-patterns.md         # 测试用例模板

这样做的优势：

• 不占用默认上下文
• 示例可以独立维护和更新
• 不同任务可以加载不同的示例集

3.4 长对话中的上下文管理

这是我踩坑最多的地方。几个经验：

什么时候开新会话：

• 切换到完全不同的任务时
• 对话已经超过 20 轮，感觉 AI 开始"忘记"之前说的东西时
• AI 开始重复自己的回答或给出矛盾信息时

怎么做交接：

• 在结束前让 AI 生成一个当前进度的总结
• 把总结保存为文件（比如 docs/plans/session-notes.md）
• 新会话开始时让 AI 先读这个文件

上下文清理：

• 使用 /clear 命令定期清理已完成任务的上下文
• 使用 todo 列表管理多步任务，让 AI 保持对全局目标的认识

3.5 项目文档怎么组织让 AI 更容易理解

一个关键发现：AI 对文档的理解能力取决于文档的结构化程度。

我的做法：

1. 用 Markdown 格式，AI 对 Markdown 的解析能力最强
2. 标题层级清晰，让 AI 能快速定位信息
3. 代码示例要完整可运行，不要只给片段
4. 文件之间用相对链接互相关联，形成知识网络

---

四、规格先行（Spec-First）方法论

这是 2026 年对我影响最大的一个方法论。

4.1 核心思想：先写规格，再让 AI 编码

规格先行（Spec-Driven Development，SDD）的核心观点是：把规格（而非代码）作为"真相来源"。你先想清楚要什么、写清楚要什么，再让 AI 去实现。

为什么这很重要？因为 AI 擅长"按规格执行"，但不擅长"猜你想做什么"。模棱两可的需求不会让 AI 稍微慢一点——它会让 AI 朝错误方向全力冲刺，产出一大堆你需要丢弃的代码。

Martin Fowler 的团队把 SDD 分为三个层级：

层级	描述	适用场景
Spec-first	先写规格，AI 按规格生成代码	大多数项目
Spec-anchored	规格和代码并存，互相约束	复杂项目
Spec-as-source	规格是唯一产物，代码完全自动生成	前沿探索

4.2 大任务拆小：50 行代码块原则

Google 的工程师分享过一个经验：将大任务拆分为小于 50 行的代码块，每个代码块单独验证。

这不是说每段代码只能 50 行，而是说每个交给 AI 的任务粒度应该小到可以快速验证。这样做的好处：

• 出错范围可控：50 行以内的 bug 比 500 行的 bug 好找得多
• 反馈循环快：写 50 行就能验证，不用等到写完几百行才发现方向错了
• 上下文利用效率高：小任务需要的上下文少，AI 更容易聚焦

有人做过统计，这种小步迭代的方式可以降低约 70% 的 bug 率。虽然具体数字因项目而异，但趋势是明确的：小步快跑，频繁验证。

4.3 四阶段工作流

我目前在用的 SDD 工作流分为四个阶段：

1. Specify（写规格）
   - 明确目标、约束、验收标准
   - 不涉及实现细节

2. Plan（做计划）
   - 让 AI 基于规格生成技术方案
   - 确认方案可行后再进入下一步

3. Tasks（拆任务）
   - 把计划拆成具体的、可独立执行的小任务
   - 每个任务有明确的完成标准

4. Implement（执行）
   - AI 逐个实现任务
   - 每个任务完成后验证，再开始下一个

---

五、踩坑经验

5.1 上下文太多反而效果变差

这是我最常犯的错误。总觉得多给点信息 AI 就能做得更好，结果适得其反。

具体表现：

• AI 开始"困惑"：上下文中存在相互矛盾的信息
• AI 开始"分心"：被无关信息干扰，输出偏离重点
• AI 开始"中毒"：之前的错误信息被反复放大

我的经验是：给 AI 的上下文，要像给新同事交接工作一样精炼——只说必要的，说清楚的。

5.2 不同工具对上下文的处理方式不同

Claude Code、Cursor、Windsurf 这几个工具对上下文的管理策略差异挺大的：

• Claude Code：通过 CLAUDE.md + rules/ 分层管理，支持 Skills 按需加载
• Cursor：通过 .cursorrules 配置，支持动态上下文发现，会自动把终端输出同步为文件
• Windsurf：有 Plan Mode，会先生成计划再编码

不要指望一套配置适配所有工具。了解你主要使用的工具的上下文管理机制，针对性地优化。

5.3 敏感信息不要放上下文里

这应该是最重要的一条安全规则：

• API Key、密码、token 绝对不要出现在 CLAUDE.md 或提示词里
• 数据库连接串用环境变量，不要硬编码
• 生产环境的数据不要直接粘贴到对话中
• CLAUDE.md 应该加入 .gitignore，或者只放非敏感的规则信息

---

六、推荐学习资源

以下是我在学习上下文工程过程中觉得最有价值的资源：

入门到系统学习：

• CE101（大模型上下文工程实践指南）：由 Leo 编写的一套系统性开源教程，从基础概念到实践应用覆盖得很全。网址：https://ce101.ifuryst.com/
• Context Engineering Guide（大模型上下文工程权威指南）：另一份高质量指南，包含 Agentic RAG、Graph RAG、MCP 等最新内容。网址：https://yeasy.gitbook.io/context_engineering_guide

官方文档：

• Anthropic 官方博客：Claude Code Best Practices 和 Context Engineering 相关文章，是最权威的实践参考。网址：https://docs.anthropic.com/
• Claude Code 最佳实践：Anthropic 官方的 agentic coding 最佳实践指南，涵盖 CLAUDE.md、权限管理、工作流等

深度阅读：

• LangChain 的 Context Engineering for Agents：从 Agent 角度系统讲解上下文管理的四种策略（写入、选择、压缩、隔离）
• Manus 团队的上下文工程实践：一线产品团队的实战经验分享，关于 KV-Cache 优化、文件系统作为外部记忆等话题非常有启发
• Anthropic 的 Advanced Tool Use：深入讲解大规模工具场景下的上下文管理，包括 Tool Search Tool、Programmatic Tool Calling 等新特性

行业趋势：

• 虎嗅的文章《提示词工程到上下文工程到 Harness 工程的时代演进》，对整个范式演进有很好的梳理
• Addy Osmani 的博客《My LLM Coding Workflow Going Into 2026》，Google 工程师的个人工作流分享

---

最后说几句

上下文工程不是什么高深的理论，它更像是 AI 时代的一种"沟通素养"。核心就是想清楚一个问题：在有限的注意力空间里，怎么让 AI 看到最有用的信息。

我个人的体会是，上下文工程最大的收益不在于"让 AI 写出更好的代码"，而在于"让整个开发流程变得可预测、可复现"。当你把项目规范、编码标准、工作流都沉淀为上下文资产后，新同事上手、AI 协作开发都会顺畅很多。

如果你刚开始接触，我的建议是从 CLAUDE.md 写起。先花 20 分钟把你的项目核心规则写下来，然后在日常开发中不断迭代。这是投入产出比最高的一步。