上下文管理

在使用 Claude Code 进行开发时，有效的上下文管理是提高工作效率的关键。Claude 需要理解你的代码库、项目结构和当前任务，才能提供精准的帮助。

为什么上下文管理很重要

Claude 的响应质量直接取决于它接收到的上下文信息。良好的上下文管理可以：

• 减少误解和错误的建议
• 提高代码生成的准确性
• 加快问题解决速度
• 降低来回沟通的成本
• 确保建议符合项目规范

上下文窗口的工作原理

Claude Code 维护一个对话上下文窗口，包含：

• 当前会话的所有消息历史
• 你明确添加的文件内容
• 通过工具调用读取的文件
• 项目结构信息
• 之前的命令执行结果

上下文窗口有大小限制，当接近限制时，早期的消息可能会被移除。因此，战略性地管理上下文至关重要。

主动提供上下文

使用 @mentions

Claude Code 支持 @ 语法来引用文件和目录：

@src/components/Button.tsx 这个组件有什么问题？

@docs/ 根据文档更新 README

这种方式可以精确控制 Claude 看到的内容，避免不必要的信息干扰。

项目概览

在开始新会话时，提供项目概览很有帮助：

这是一个 Next.js 14 项目，使用 TypeScript、Tailwind CSS 和 Prisma。
主要功能是用户认证和数据可视化。我们遵循 Airbnb 的代码规范。

相关背景

当询问特定问题时，提供相关背景：

我们的 API 使用 JWT 进行认证。现在需要添加刷新令牌功能，
但要保持与现有中间件的兼容性。

渐进式上下文构建

不要一次性提供所有信息。采用渐进式方法：

1. 从高层次问题开始
2. 根据 Claude 的回应提供更多细节
3. 在需要时引用特定文件
4. 逐步深入到具体实现

这种方法可以：

• 避免上下文窗口过早填满
• 让对话更自然流畅
• 确保信息的相关性

上下文优先级

并非所有信息都同等重要。按优先级组织上下文：

高优先级

• 当前正在修改的文件
• 直接相关的依赖文件
• 错误消息和堆栈跟踪
• 项目配置文件（package.json、tsconfig.json）

中优先级

• 相关的测试文件
• 类型定义文件
• 文档和注释
• 相似功能的参考实现

低优先级

• 项目历史和背景
• 通用的最佳实践
• 可选的优化建议

使用 .claudeignore

创建 .claudeignore 文件来排除不相关的内容：

# 依赖
node_modules/
.pnpm-store/

# 构建产物
dist/
build/
.next/

# 大型数据文件
*.log
*.csv
*.json.gz

# 敏感信息
.env
.env.local
secrets/

这可以防止 Claude 浪费上下文窗口在无关文件上。

上下文刷新策略

何时开始新会话

在以下情况下考虑开始新会话：

• 切换到完全不同的任务
• 上下文窗口接近限制
• 对话变得混乱或偏离主题
• 需要重新设定方向

保留重要信息

在开始新会话前，总结关键决策和发现：

总结一下我们刚才的讨论：
1. 决定使用 Redis 作为缓存层
2. API 限流设置为每分钟 100 次请求
3. 错误处理采用中间件模式

将这个总结作为新会话的开场白。

代码库导航技巧

使用搜索而非全量读取

不要让 Claude 读取整个目录。使用精确的搜索：

搜索所有使用 useAuth hook 的组件

找出定义 User 接口的文件

利用项目结构

引用项目结构来帮助 Claude 理解组织方式：

我们的项目结构：
- src/
  - features/ (按功能组织)
  - shared/ (共享组件和工具)
  - api/ (API 路由)

多文件任务的上下文管理

处理跨多个文件的任务时：

1. 先说明任务范围
2. 列出涉及的文件
3. 说明文件之间的关系
4. 逐个处理，保持焦点

示例：

需要重构认证流程，涉及：
- src/auth/login.ts (主要逻辑)
- src/middleware/auth.ts (中间件)
- src/types/user.ts (类型定义)

先从 login.ts 开始

上下文验证

定期验证 Claude 的理解：

在继续之前，确认一下你对当前架构的理解

我们讨论的更改会影响哪些其他部分？

这可以及早发现误解，避免后续问题。

处理上下文限制

当接近上下文限制时：

提取关键信息

将重要的代码片段和决策提取到新会话：

之前我们确定了以下接口：
[粘贴关键接口定义]

现在继续实现...

使用外部文档

对于复杂的架构决策，维护外部文档：

• 在项目中创建 docs/decisions/ 目录
• 记录重要的架构决策
• 在需要时引用这些文档

分解任务

将大任务分解为小任务，每个任务使用独立会话：

• 任务 1：设计 API 接口
• 任务 2：实现核心逻辑
• 任务 3：添加错误处理
• 任务 4：编写测试

上下文模板

为常见任务创建上下文模板：

Bug 修复模板

Bug 描述：[简要说明]
复现步骤：[步骤列表]
预期行为：[说明]
实际行为：[说明]
相关文件：[文件列表]
错误日志：[日志内容]

功能开发模板

功能需求：[说明]
技术栈：[列表]
相关文件：[文件列表]
设计约束：[约束条件]
参考实现：[如有]

最佳实践总结

1. 精确而非全面 - 提供相关信息，而非所有信息
2. 结构化表达 - 使用清晰的格式和层次
3. 及时更新 - 当情况变化时更新上下文
4. 验证理解 - 定期确认 Claude 的理解正确
5. 战略性刷新 - 在合适的时机开始新会话
6. 使用工具 - 利用 @mentions 和 .claudeignore
7. 保持焦点 - 一次处理一个主要任务
8. 记录决策 - 重要决策应该被记录和引用

通过掌握这些上下文管理技巧，你可以显著提高与 Claude Code 协作的效率和质量。