上下文管理策略

即使有了 agents.md 和模板，怎么用好上下文仍是一门艺术。本章讲单次任务的上下文用量控制。

核心问题

LLM 的上下文窗口有限且昂贵。一个真实项目可能 500K-5M tokens，远超单次合理输入量。

上下文的颗粒度

太粗：把整个项目塞进去
  → 噪声大，关键信息被淹没，成本高

太细：只给当前文件
  → 缺乏上下文，AI 不知道项目约定

最佳：恰到好处的"上下文包"
  → 针对具体任务，给出相关文件 + 关键规范

上下文的 4 个维度

1. 时间维度：什么时候给

反例：每个对话都重复一遍
> 我们用 React 18 + TypeScript，组件库是 Ant Design，状态用 Zustand...

正例：一次性建立
# 第一次：写好 agents.md
# 之后：AI 自动应用
> 写一个用户列表组件
（AI 自动从 agents.md 读取约定）

2. 空间维度：给多少

黄金法则：给出完成任务所需的最小上下文集。

以"生成新组件"为例：

需要给：
  ✅ agents.md（项目规范）
  ✅ 类似组件的代码示例（如 OrderList）
  ✅ 类型定义（src/types/user.ts）
  ✅ API service（如已存在）

不需要给：
  ❌ 所有其他组件的代码
  ❌ 整个 types/ 目录
  ❌ 测试文件
  ❌ 配置文件细节

3. 顺序维度：怎么排序

LLM 对长上下文有**"中间遗忘"**问题。关键信息放首尾：

[开头：最重要的约束]
1. 使用 React 18 + TypeScript 严格模式
2. 不要使用 any
3. 所有 API 走 src/services/

[中间：具体任务描述]
写一个用户列表组件...

[结尾：再次强调关键约束]
完成后请验证：
- 没有使用 any
- 所有 API 调用走 services

4. 形态维度：什么形式

不同形式的上下文对 AI 的理解度差异显著：

形式	理解度	适用场景
代码示例	⭐⭐⭐⭐⭐	风格、规范
TypeScript 类型	⭐⭐⭐⭐	数据结构
结构化 Markdown	⭐⭐⭐⭐	规范说明
Mermaid 图	⭐⭐⭐	架构关系
自然语言描述	⭐⭐	业务逻辑
截图/图片	⭐⭐	UI 设计

优先级：代码 > 类型 > 图示 > 文字。

实战技巧

技巧 1：分层引用

用 @ 引用精准的上下文包：

> 写一个订单详情组件
> 参考：
>   - 项目规范：@agents.md
>   - 类似组件：@src/components/UserDetail.tsx
>   - 数据类型：@src/types/order.ts
>   - API：@src/services/order.ts

技巧 2：明确范围

不明确：
> 重构这个项目

明确：
> 重构 src/components/UserCard/ 目录下的组件：
> - UserCard.tsx
> - UserCard.test.tsx
> 要求：拆分为展示组件 + 容器组件
> 不修改：父组件调用方式、对外 Props

技巧 3：分批处理

一次给 10 个任务：
> 做用户管理、订单管理、产品管理、库存管理、财务管理...

分批：
# 第一轮
> 做用户管理的列表 + 详情
# 第二轮
> 做订单管理的列表 + 详情

每一轮聚焦、独立、可验证

技巧 4：上下文"瘦身"

当 AI 抱怨"上下文不够"时，与其扩大上下文，不如优化内容：

优化前：整个 src/types/ 目录（100+ 文件）
优化后：只给相关的 user.ts、order.ts

优化前：把所有 README 都给
优化后：只给主 README 和相关模块的 README

技巧 5：使用摘要

长文件给 AI 时，先用摘要：

> 这是 src/services/user.ts 的摘要：
> 模块功能：用户管理 API
> 导出方法：list(params), get(id), create(data), update(id, data), delete(id)
> 数据类型：参考 src/types/user.ts
> 
> 请基于此写一个新的角色管理 service，风格保持一致。

AI 看摘要比看完整代码更快、更准。

上下文"污染"的常见问题

问题	表现	对策
信息过载	过多无关信息干扰	精简到最小必要集
信息冲突	agents.md 与示例代码不一致	保持一致，定期 review
信息陈旧	已迁移到 Zustand 但 agents.md 还写 MobX	随代码同步更新
上下文漂移	长对话中早期指令被遗忘	关键任务重新发起对话；用 plan mode 固化

上下文预算参考

单任务 Token 用量

任务类型	推荐上下文量
简单补全	2K-10K
组件生成	10K-50K
复杂 Bug 排查	50K-200K
大型重构	200K-1M

成本控制技巧

1. 先用便宜模型：能用低成本模型解决的别用旗舰模型
2. 避免重复：不要每次粘贴同样的上下文
3. 及时清理：对话太长时主动开新会话
4. 批处理：多个小任务合并执行

工具特定的引用语法

Cursor

@file           # 单个文件
@folder         # 文件夹
@codebase       # 整个代码库
@docs           # 文档
@web            # 网络
@git            # Git 历史

Cmd+Shift+L     # 添加到对话
Cmd+Shift+K     # 切换上下文

Claude Code

> 参考 src/components/UserCard.tsx 和 src/types/user.ts
> 看一下 src/services/ 目录
> 帮我看下我们项目的 User 模型（自动搜索）

通用建议

场景	策略
简单问题	不需要额外上下文
组件开发	@相关组件 + @类型
跨文件重构	@Codebase + 明确范围
Bug 排查	@报错文件 + @相关代码
新模块开发	@agents.md + @类似模块

上下文调试

检查 AI 是否"懂"了

方法 1：让 AI 先复述

> 在开始前，先告诉我你对这个任务的理解：
> 1. 你打算用什么技术栈？
> 2. 你打算修改哪些文件？
> 3. 你对需求有什么疑问？

方法 2：先问后做

> 先不要写代码，告诉我你会怎么做。

方法 3：小步验证

> 先只写一个函数，跑通后再继续。

相关概念区分

概念	含义
上下文（Context）	单次对话中的输入信息
Prompt 工程	优化单次 Prompt 的技术
上下文管理	控制单次任务的输入量
上下文工程	持续管理项目上下文的实践
记忆（Memory）	跨会话保留的信息

层层递进：

Prompt 工程：写好一次对话
  ↓
上下文管理：管好一次任务
  ↓
上下文工程：管好整个项目的 AI 协作

总结

上下文管理的核心五原则：

1. 恰到好处的信息量——不多不少
2. 精准的引用——用 @ 而不是复制粘贴
3. 明确的任务边界——不让 AI 猜范围
4. 分层与分批——复杂任务拆解
5. 成本意识——跟踪 Token 消耗

下一节：多 Agent 角色协同 — 当单 Agent 不够用时拆分专业角色。