Claude Code 上下文管理

上下文管理是高效使用 Claude Code 的核心技能。本章深入讲解如何通过 CLAUDE.md 项目记忆、/memories 持久化记忆、上下文窗口优化等技术，让 Claude 在长会话和跨会话中保持对项目的深度理解，避免重复解释，实现真正的持续协作。

上下文管理概述

Claude Code 的上下文系统由多个层级组成，从即时会话上下文到跨会话持久记忆，不同层级的上下文有不同的加载时机和行为特点。理解这套系统的工作原理，是提升 Claude Code 使用效率的关键。

1、上下文层级架构

Claude Code 的上下文可以分为以下四个主要层级：

层级 来源 生命周期 主要作用
会话上下文 当前对话历史 单次会话 当前任务的即时信息
CLAUDE.md 项目根目录或用户目录 永久 项目级配置和规范
/memories ~/.claude/ 目录 跨会话 跨项目长期记忆
工具结果 Read/Grep/Bash 等 即时 代码库实时状态

2、上下文加载顺序

当你在项目目录下启动 Claude Code 时，上下文的加载顺序如下：

1. Claude Code 系统提示词（CLI 行为规范）
2. 用户级 CLAUDE.md（~/.claude/CLAUDE.md）
3. 项目级 CLAUDE.md（./CLAUDE.md）
4. 工具结果（Read/Grep/Bash 输出）
5. 对话历史（本次会话内容）
6. /memories 内容（如有调用）

Claude Code 会自动按上述顺序将上下文加载到模型的上下文窗口中。了解加载顺序有助于理解为什么某些配置会覆盖其他配置。

CLAUDE.md 项目记忆文件

CLAUDE.md 是 Claude Code 中最重要的上下文管理工具。它是一个特殊的 Markdown 文件，Claude 在开始对话时会自动将其内容加载到上下文窗口中。这使得它成为记录项目信息、代码规范和开发约定的理想场所。

1、CLAUDE.md 的作用

CLAUDE.md 的核心价值体现在以下几个方面：

  • 减少重复说明：首次在新项目中使用 Claude Code 时，无需每次都解释项目架构和技术栈
  • 统一代码风格：在文件中定义团队的代码规范，Claude 会自动遵循
  • 记录特殊约束：记录哪些文件不允许修改、哪些命令不能执行
  • 沉淀开发经验：记录常见的 Bug、已知问题和解决方案

2、CLAUDE.md 的存放位置

Claude Code 支持多级目录放置 CLAUDE.md，作用范围和优先级如下：

存放位置 作用范围 优先级 适用场景
./CLAUDE.md 当前项目 最高 项目专属配置，随代码一起提交
./docs/CLAUDE.md 当前项目 次高 项目配置，与代码分离
~/.claude/CLAUDE.md 所有项目 低 个人偏好和通用设置

当多个位置都存在 CLAUDE.md 时，内容会按优先级合并。优先级高的文件内容会覆盖优先级低的同名配置项。

3、创建 CLAUDE.md

Claude Code 提供了便捷的初始化命令，可以自动分析项目结构并生成 CLAUDE.md：

/init

执行此命令后，Claude 会分析项目目录，生成包含以下内容的 CLAUDE.md：

  • 项目架构和目录结构说明
  • 主要技术栈和依赖
  • 常用的开发命令
  • 代码规范和约定

实例

# CLAUDE.md 示例内容

## 项目概述
这是一个使用 React + TypeScript 构建的电商后台管理系统。

## 技术栈
- 前端框架：React 18 + TypeScript
- 状态管理：Zustand
- UI 组件：Ant Design 5
- 构建工具：Vite
- 包管理：pnpm

## 常用命令
- 开发模式：pnpm dev
- 构建生产版本：pnpm build
- 运行测试：pnpm test
- 代码检查：pnpm lint

## 代码规范
- 使用 TypeScript strict 模式
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
- 所有组件必须添加 Props 类型定义

## 注意事项
- 不要直接修改 node_modules 目录
- API 接口在 src/api/ 目录下集中管理
- 数据库连接配置在 .env.local 中

4、CLAUDE.md 推荐内容

根据最佳实践，CLAUDE.md 应该包含以下内容：

必须包含的内容

  • 项目简介：项目名称、功能描述、目标用户
  • 技术栈：使用的框架、语言、关键依赖及其版本
  • 常用命令：开发、构建、测试、部署的常用命令
  • 目录结构：主要目录及其用途说明

推荐包含的内容

  • 代码规范：命名约定、文件组织规则、代码风格要求
  • 架构说明：模块划分、设计模式、核心逻辑说明
  • API 文档位置：内部接口文档、外部服务集成说明
  • 环境配置：环境变量说明、敏感文件列表

可选包含的内容

  • 已知问题：已知的 Bug、临时解决方案、技术债务
  • 开发约定：Git 工作流、代码审查要求、提交流程
  • 团队信息：主要联系人、值班安排、沟通渠道

5、CLAUDE.md 维护建议

CLAUDE.md 不是一次性创建后就束之高阁的文件，需要持续维护：

  • 每次完成重要功能后，更新架构说明和代码规范
  • 发现新的项目特性时，及时补充到文件中
  • 定期回顾 CLAUDE.md，移除过时或不准确的信息
  • 在项目中共享 CLAUDE.md，确保团队成员都能受益

持久化记忆系统（/memories）

CLAUDE.md 解决的是项目级别的上下文问题，但跨会话的长期记忆需要另一套机制。Claude Code 提供了 /memories 持久化记忆系统，允许 Claude 在会话之间保存和检索重要信息。

1、/memories 工作原理

/memories 系统通过以下方式工作：

  • 将对话中的关键信息保存到本地文件系统
  • 下次启动会话时，Claude 可以主动检索相关记忆
  • 记忆文件使用 Markdown 格式，可直接编辑
  • 支持按需加载，而非每次都全部注入

2、查看记忆内容

使用以下命令查看当前记忆内容：

/memories

此命令会打开记忆编辑器，显示已保存的所有记忆条目。每个条目通常包含：

  • 记忆标题：快速识别记忆主题
  • 创建时间：了解记忆的新旧程度
  • 内容摘要：记忆的核心信息
  • 关联项目：哪些项目使用了这条记忆

3、主动保存记忆

当你发现 Claude 学到了重要信息，可以主动让它保存到记忆中：

把这个架构设计保存到记忆中，下次讨论类似问题时参考
记住我们达成的共识：API 返回错误时统一返回 { code, message } 格式

Claude 会在合适的时机将重要信息写入记忆系统。下次需要时，它会自动检索相关记忆。

4、记忆存储位置

/memories 的默认存储位置在 ~/.claude/memories/ 目录下，文件结构如下：

~/.claude/memories/
├── notes.md          # 一般性笔记
├── projects/        # 项目相关记忆
│   ├── myapp/      # 具体项目的记忆
│   └── myapp/*     # ...
└── skills/          # 技能相关记忆

5、清除和重置记忆

如果需要清除特定记忆，可以使用：

/memories --clear

或者在记忆编辑器中直接删除不需要的条目。清除后 Claude 将不再记得这些信息。

上下文窗口优化

Claude Code 的上下文窗口容量是有限的（约 20 万 Token），随着对话进行，上下文会逐渐填满。掌握上下文窗口优化技巧，可以让你的会话运行得更长、更高效。

1、上下文消耗的来源

以下内容会消耗上下文窗口：

  • 对话历史：你和 Claude 的所有交换内容
  • 工具结果：Read、Grep、Bash 等命令的输出
  • 文件内容：通过 @ 引用或工具读取的文件内容
  • CLAUDE.md：项目配置文件的内容

2、压缩上下文（/compact）

当对话变得很长时，可以使用压缩命令释放上下文空间：

/compact

执行此命令后，Claude 会将当前对话内容总结为精简摘要，保留关键信息，删除中间过程的冗余细节。压缩后的上下文更紧凑，让 Claude 可以继续高效工作。

压缩是有损操作，会丢失一些对话细节。如果某些信息很重要，请在压缩前主动保存到 CLAUDE.md 或 /memories 中。

3、清除上下文（/clear）

当需要开始全新任务时，可以清除所有上下文：

/clear

清除后，Claude 将只保留 CLAUDE.md 和 /memories 中的内容，对话历史和临时上下文全部清空。这对于切换到完全不相关的任务非常有用。

4、合理拆分任务

复杂任务不要一次性全部丢给 Claude，拆分成多个步骤效果更好：

❌ 不好的做法：一次性描述太多内容。

"帮我重构整个用户模块，包括修改 UserService、UserController、
UserModel，更新所有调用的地方，同时添加单元测试和集成测试，
还要更新 API 文档，最后部署到测试环境"

✅ 好的做法：按逻辑顺序拆分成独立步骤。

第一步："先分析 src/services/UserService.ts，找出需要修改的方法"
第二步："修改 UserService 中的业务逻辑"
第三步："更新 UserController 的调用代码"
第四步："添加 UserService 的单元测试"
第五步："更新 API 文档"

5、选择性引用文件

使用 @ 语法明确指定需要参考的文件，避免 Claude 自动读取过多内容：

@src/types/user.ts 参考这个类型定义，帮我完善 UserService
@docs/api-spec.md 对照规范检查实现是否符合要求

明确的文件引用可以让 Claude 聚焦于相关代码，减少不必要的上下文消耗。

会话管理命令

Claude Code 提供了一系列斜杠命令用于管理会话和上下文：

1、会话操作命令

命令 功能 使用场景
/clear 清除当前对话历史，保留 CLAUDE.md 和记忆 切换到全新任务
/compact 压缩对话上下文为精简摘要 会话变长但需要继续当前任务
/resume 恢复之前的会话继续工作 继续昨天未完成的任务
/retry 重新执行上一次操作 上次结果不理想

2、继续会话（-c 参数）

Claude Code 会保存对话历史。使用 -c 参数可以继续最近一次未完成的对话：

claude -c

这对于需要跨终端或跨日期继续工作非常有用。Claude 会加载最近一次会话的上下文，无需手动恢复。

3、查看会话历史

查看之前的会话记录：

/sessions

此命令会列出所有历史会话，包括：

  • 会话时间和持续时长
  • 会话摘要和主要任务
  • 快速恢复选项

上下文引用技巧

1、@ 文件引用语法

使用 @ 符号可以明确告诉 Claude 需要参考哪个文件：

@src/utils/format.ts  参考这个文件的实现，帮我完善新文件
@package.json  看看项目的依赖情况

这种引用方式比模糊描述更精确，可以帮助 Claude 更快找到正确的代码。

2、@ 多文件引用

可以同时引用多个文件：

@src/types/user.ts @src/services/user.ts @src/api/user.ts
   分析这三个文件中 User 相关的代码结构

3、@ 目录引用

引用整个目录让 Claude 了解代码组织：

@src/components/  分析这个目录下的组件结构

Claude 会读取目录下的所有文件（不会递归），帮助理解模块划分。

4、引用错误信息

遇到编译或运行时错误时，直接把错误信息粘贴到对话中：

运行 npm run build 时报了这个错误：
Error: Cannot find module './utils/date'
    at resolve (node:internal/modules/cjs/loader:1234:18)

帮我定位问题并修复

5、引用 Git diff

让 Claude 审查你的代码改动时，直接引用 diff：

审查我这次的改动：
git diff HEAD~1

改动内容：
[diff 内容...]

上下文加载时机

1、首次启动

当你首次在新项目目录下启动 Claude Code 时：

  • 加载用户级 CLAUDE.md（~/.claude/CLAUDE.md）
  • 加载项目级 CLAUDE.md（./CLAUDE.md 或 ./docs/CLAUDE.md）
  • 扫描项目结构获取基本信息
  • 可用的 /memories 会被检索

2、工具调用后

当你使用 Read、Grep、Bash 等工具时：

  • 工具结果会自动添加到上下文
  • Claude 根据结果决定下一步操作
  • 大量输出可能快速消耗上下文空间

3、压缩后

执行 /compact 后：

  • 对话历史被总结为摘要
  • CLAUDE.md 和 /memories 内容保留
  • 最近的关键决策和约定会被突出保留

最佳实践

1、项目初始化时创建 CLAUDE.md

进入新项目后，第一件事是创建或更新 CLAUDE.md：

实例

# 工作流
1. 进入项目目录
   cd ~/projects/my-app

2. 启动 Claude Code
   claude

3. 初始化项目说明
   > 帮我分析这个项目，然后创建一个 CLAUDE.md 文件

4. 审查并补充
   > 查看生成的 CLAUDE.md，补充你发现的遗漏信息

2、定期维护 CLAUDE.md

CLAUDE.md 需要持续维护，保持与项目同步：

  • 新增模块后更新架构说明
  • 添加新依赖后更新技术栈
  • 发现项目特性后补充注意事项
  • 每季度回顾一次，清理过时内容

3、主动使用 /memories

当你和 Claude 达成重要共识时，主动保存：

记住这个项目的 API 错误处理规范...
把我们讨论的架构决策记录到记忆中

4、任务完成后清理

完成一个任务后，如果要开始新任务，考虑使用 /clear：

/clear

这样可以让 Claude 专注于新任务，不被旧上下文干扰。

5、复杂任务使用子代理

对于会产生大量中间输出的任务，考虑使用子代理隔离：

使用子代理分析所有日志文件，找出性能瓶颈

子代理在独立上下文中运行，主对话只接收结论摘要，避免上下文被大量日志淹没。

常见问题与解决方案

问题一：Claude 似乎"忘记"了之前讨论的内容

这通常是因为上下文窗口已满或任务切换了。解决方案：

  • 使用 /compact 压缩上下文
  • 将重要信息保存到 CLAUDE.md
  • 使用 /memories 保存跨会话记忆

问题二：Claude 读取了错误的文件

使用 @ 语法明确指定文件路径：

@src/auth/login.ts  参考这个文件，不是 src/authentication/

问题三：上下文压缩后信息丢失

压缩是有损操作。重要信息应提前保存：

  • 在压缩前将关键结论写入 CLAUDE.md
  • 使用 /memories 保存需要跨会话保留的信息
  • 避免在对话中期讨论极端重要的决策

问题四：新会话没有加载之前的上下文

Claude Code 默认只保留最近会话。使用以下方式继续：

  • 使用 claude -c 继续最近会话
  • 使用 /resume 选择特定会话恢复
  • 将需要延续的信息写入 CLAUDE.md

总结

Claude Code 的上下文管理系统是高效协作的基础。掌握以下核心要点：

  • CLAUDE.md：项目级记忆文件，创建后长期使用，随项目维护
  • /memories：跨会话持久记忆，重要共识主动保存
  • /compact：上下文满时压缩，保留关键信息
  • /clear：切换任务时清除，获得干净起点
  • @ 引用：明确指定文件，避免歧义
  • 任务拆分：复杂任务分步骤执行，减少上下文压力

通过合理运用这些上下文管理技巧，你可以让 Claude Code 在长期项目中保持对项目的一致性理解，实现真正的持续协作。