上下文优化

理解上下文窗口

Claude Code 基于大语言模型工作，而每个模型都有一个**上下文窗口（Context Window）**的限制。你可以把上下文窗口想象成 Claude 的”工作记忆”——它能同时处理的信息总量是有限的。

上下文窗口中包含的内容有：

系统提示：Claude Code 的内置指令和你的 CLAUDE.md 内容
对话历史：你和 Claude 之前的所有对话轮次
文件内容：Claude 读取的代码文件
工具调用记录：Claude 执行的命令和结果
输出内容：Claude 生成的回复和代码

当上下文窗口被填满时，Claude 不得不丢弃较早的对话内容，这可能导致它”遗忘”之前讨论过的重要信息。优化上下文使用，就是让有限的窗口空间被最有价值的信息占据。

Claude Code 的自动上下文管理

Claude Code 在底层做了很多自动优化工作，但理解这些机制有助于你更好地配合它。

智能文件读取

当你提到某个文件时，Claude Code 会读取该文件的内容到上下文中。但它不会一次性读取整个代码库，而是根据需要按需加载：

# Claude 会读取你提到的文件
> 查看 src/utils/format.ts 的代码

# Claude 也会根据需要自动读取相关文件
> 修复 userService.ts 中的 bug
# （Claude 可能会自动读取 userService.ts 引用的类型定义文件）

对话压缩

在长时间的会话中，Claude Code 会自动压缩较早的对话内容，保留关键信息的同时释放上下文空间。这个过程对用户是透明的，但你可能会注意到，在很长的会话后，Claude 对早期讨论的记忆不如刚开始时精确。

CLAUDE.md 作为持久上下文

CLAUDE.md 是最重要的上下文优化工具。它在每次会话开始时自动加载，确保 Claude 始终了解项目的核心信息。

为什么 CLAUDE.md 是上下文优化的关键

没有 CLAUDE.md 时，你可能需要在每次会话中重复告诉 Claude：

> 这个项目用的是 Next.js 14，TypeScript strict mode，pnpm 管理依赖...

这些重复说明不仅浪费时间，还占用宝贵的上下文空间。把它们放在 CLAUDE.md 中，这些信息会以最高效的方式被加载。

CLAUDE.md 的最佳实践

# 项目概述（简洁明了，不超过 3 行）
电商平台前端，Next.js 14 + TypeScript + Tailwind CSS

# 关键约定（只写最重要的）
- 使用 pnpm
- 组件放在 src/components/，页面放在 app/
- API 请求统一使用 src/lib/api.ts
- 测试命令：pnpm test

# 注意事项（容易出错的地方）
- 不要修改 src/generated/ 下的自动生成文件
- 环境变量前缀必须是 NEXT_PUBLIC_

💡

提示

CLAUDE.md 应该简洁精炼。一个过于冗长的 CLAUDE.md 本身就会占用大量上下文空间，反而适得其反。只放那些每次会话都需要 Claude 知道的信息。

策略性文件读取

让 Claude 只读取真正需要的文件，是优化上下文的重要策略。

精准指定文件

# 好的做法：指定具体文件
> 阅读 src/services/orderService.ts 中的 createOrder 函数

# 不好的做法：让 Claude 搜索整个目录
> 帮我找到处理订单的代码

分阶段读取

对于涉及多个文件的任务，不要一次性让 Claude 读取所有文件：

# 分阶段方式（推荐）
> 先看 src/types/order.ts 的接口定义

# Claude 回复后...
> 好的，现在看 src/services/orderService.ts 的实现

# 而不是一次性说：
> 阅读 src/types/order.ts、src/services/orderService.ts、
> src/repositories/orderRepo.ts、src/routes/orders.ts 的所有代码

只读取关键部分

如果文件很大，告诉 Claude 你关心的部分：

> 只看 src/config/database.ts 中的连接池配置部分，
> 大概在文件的前 50 行

使用 /compact 压缩上下文

/compact 是 Claude Code 内置的上下文压缩命令。当你感觉对话变长、Claude 开始变慢或不够精确时，可以使用它。

/compact 的作用

/compact 会将当前的对话历史压缩为一个简洁的摘要，保留关键信息（如已做的决策、当前任务进度、重要的代码上下文），同时释放大量的上下文空间。

> /compact

执行后，Claude 会生成一个压缩后的对话摘要，然后在此基础上继续工作。

何时使用 /compact

对话进行了 15-20 轮以上：上下文开始变得拥挤
Claude 的回复开始变慢：处理大量上下文需要更多时间
Claude 开始重复之前说过的话：可能是上下文混乱的信号
准备开始任务的下一个阶段：压缩前一阶段的信息，为新阶段腾出空间

/compact 的自定义用法

你可以在 /compact 后面附加说明，告诉 Claude 在压缩时重点保留什么：

> /compact 保留关于数据库迁移方案的讨论和已确定的表结构设计

这样 Claude 在压缩时会优先保留你指定的信息。

ℹ️

信息

/compact 不会丢失已经对文件做出的修改。它只压缩对话记忆，代码变更已经保存到了文件系统中。

何时开启新会话

有时候，/compact 还不够，你需要使用 /clear 完全重置会话上下文。关于 /clear 的详细使用策略，参见本系列的《何时使用 /clear》一文。

这里简要说明两者的区别：

特性	/compact	/clear
保留对话摘要	是	否
保留任务上下文	部分保留	完全清除
适用场景	对话过长但任务未完成	切换到全新任务
上下文释放程度	中等	完全释放

项目结构对上下文的影响

一个组织良好的项目结构能帮助 Claude 更高效地定位和理解代码，从而减少不必要的上下文消耗。

清晰的目录结构

src/
  components/     # Claude 知道这里放 UI 组件
  services/       # Claude 知道这里放业务逻辑
  repositories/   # Claude 知道这里放数据库操作
  types/          # Claude 知道这里放类型定义
  utils/          # Claude 知道这里放工具函数

当项目结构遵循通用约定时，Claude 能更快地找到目标代码，减少探索式搜索带来的上下文消耗。

文件命名规范

# 好的命名：Claude 能从文件名推断内容
userService.ts
orderRepository.ts
authMiddleware.ts

# 不好的命名：Claude 需要读取文件才能知道内容
utils2.ts
handler.ts
index.ts（大量业务代码堆在 index 中）

合理的文件大小

超过 500 行的文件对 Claude 来说是一个负担——读取它需要消耗大量上下文空间。如果你的代码库中有很大的文件，考虑拆分它们：

# 不好：一个 1000 行的 utils.ts
src/utils.ts

# 好：按功能拆分为小文件
src/utils/
  date.ts
  format.ts
  validation.ts
  string.ts

避免上下文污染

上下文污染是指无关信息占据了上下文空间，降低了 Claude 的注意力质量。

常见的上下文污染源

无关的文件输出：Claude 执行 ls 或 find 时输出了大量无关的文件列表
冗长的错误日志：编译错误或测试输出包含大量重复的信息
无关的讨论：在一个技术对话中穿插无关的话题
反复修改同一段代码：多次失败的尝试堆积在上下文中

避免污染的策略

# 精确的命令，避免过多输出
> 运行 npm test -- --testPathPattern=userService
# 而不是
> 运行 npm test（可能输出所有测试的大量结果）

# 指定输出范围
> 只显示失败的测试用例
# 而不是让 Claude 看完整的测试报告

# 任务聚焦
> 我们现在只关注用户认证模块，暂时不管其他模块

使用 /cost 监控上下文

/cost 命令可以让你了解当前会话的 Token 使用情况：

> /cost

它会显示当前会话已使用的 Token 数量和对应的费用。定期检查 /cost 可以帮助你判断是否需要使用 /compact 或 /clear。

当你发现 Token 使用量快速增长时，通常意味着：

读取了很多大文件
对话轮次过多
执行的命令产生了大量输出

这时就是考虑优化上下文的好时机。