如何在 Claude Code 中使用 CLAUDE.md 实现持久记忆和上下文管理

如果你每次打开 Claude Code，都要重新解释一次项目规则，CLAUDE.md 就是最直接的解决方案。它本质上是 Claude Code 的记忆文件，用来保存常用命令、代码规范、架构约束和工作偏好。

这篇文章只讲实操路径：CLAUDE.md 是什么、放在哪里、该写什么、不该写什么，以及怎样让它一直保持有用。

CLAUDE.md 到底是干什么的

CLAUDE.md 是一个 Markdown 文件。Claude Code 启动会话时会把它读进上下文里。你可以把它理解成一份长期有效的项目说明书，典型内容包括：

• 常用的 build、test、lint 命令
• 项目目录约定
• 编码规范
• 你希望 Claude 每次都遵守的工作规则

它和 Claude 的自动记忆不是一回事。简单区分：

• CLAUDE.md 适合放你想主动写下来的稳定规则
• 自动记忆适合放 Claude 在协作过程中逐渐学会的习惯和偏好

Claude Code 会去哪些地方找记忆

根据 Anthropic 官方文档，Claude Code 支持这些记忆位置：

记忆类型	位置	适合放什么	是否共享
企业级策略	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\ProgramData\ClaudeCode\CLAUDE.md	公司统一规则	全组织
项目级记忆	./CLAUDE.md	项目命令、规范、架构说明	团队共享
用户级记忆	~/.claude/CLAUDE.md	你跨项目的个人偏好	仅自己
项目本地记忆	./CLAUDE.local.md	旧式个人项目笔记	仅自己

有两个点很关键：

• Claude Code 启动时会自动加载这些记忆文件。
• CLAUDE.local.md 现在已经偏向废弃用法，官方更推荐使用 imports，因为它在多个 Git worktree 下更稳定。

另外，Claude 会从当前工作目录向上查找 CLAUDE.md。如果你在仓库子目录里运行 Claude，它也能读到上层目录的记忆文件。子目录里的嵌套 CLAUDE.md 则会在 Claude 读取该子树文件时再加载。

最快上手方法

最推荐的起点是先建立项目级记忆。

第一步：在项目根目录启动 Claude Code

cd /path/to/your/project
claude

第二步：生成一个初始版本

进入 Claude Code 之后，执行：

/init

Anthropic 官方把 /init 作为生成 CLAUDE.md 起始文件的标准做法。它会帮你从代码库里提取常用命令和一些项目约定，比你从空白文件硬写快很多。

第三步：手动删减

不要把生成出来的所有内容都留下。只保留三类信息：

• 稳定的
• 会跨很多次会话反复用到的
• 和这个仓库或你的工作流强相关的

只对某一个任务有用的说明，不应该放进 CLAUDE.md。

一个够用的起步模板

对大多数项目来说，像下面这样一份短文件就已经够用了：

# Project Memory

## Commands

- Install dependencies: `npm install`
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Run lint: `npm run lint`

## Code Style

- Use TypeScript for new files
- Prefer small focused functions
- Do not introduce new dependencies without a clear reason

## Architecture Notes

- API routes live in `src/app/api`
- Shared UI components live in `src/components`
- Domain logic should stay out of page components

## Workflow Rules

- Explain risky changes before making them
- Run relevant tests after edits
- Keep diffs small when possible

这类模板好用的原因很简单：短、具体、可执行。

不要把所有东西都塞进一个文件，改用 Imports

CLAUDE.md 支持用 @path/to/file 的语法导入其他文件。官方推荐的方向就是：顶层文件尽量短，把更细的资料拆出去。

示例：

# Project Memory

See @README.md for project overview.
See @package.json for available scripts.

## Additional Instructions

- Follow the Git workflow in @docs/git-workflow.md
- Use the deployment notes in @docs/deploy.md
- Load my personal project notes from @~/.claude/my-project-notes.md

结合官方文档，这里有几个实用细节：

• 支持相对路径和绝对路径
• 被导入的文件还可以继续导入其他文件
• 最大递归深度是 5 层
• 代码块和行内代码里的 @... 不会被当成 import 处理

这也是为什么 imports 现在比 CLAUDE.local.md 更值得优先使用。

两个很好用的快捷方式

用 # 快速加一条记忆

如果你在工作过程中临时发现了一条应该长期保留的规则，可以直接这样输入：

# Always run `npm run lint` before opening a PR

Claude Code 会让你选择把这条内容写进哪个记忆文件。

用 /memory 直接整理记忆文件

如果你想系统地编辑或清理记忆内容，可以在会话里执行：

/memory

它会在系统编辑器里打开记忆文件，适合做结构整理。

什么适合放进 CLAUDE.md

适合放的：

• Claude 否则每次都要重新找的命令
• 仓库特有的目录约定
• 测试和验证要求
• 团队在意的命名规则
• 不看就容易踩坑的架构限制

不适合放的：

• 临时 bug 备注
• 一次性任务说明
• 随手的 brainstorming
• 很长但信息密度很低的废话
• 已经在别处清楚存在的重复内容

如果三段话能压成一条 bullet，就压。

常见错误

1. 规则写得太虚

不好的写法：

• "格式化代码"

更好的写法：

• "使用 2 个空格缩进"
• "改动后端代码后运行 npm test"

越具体，Claude 越容易真正执行。

2. 把 CLAUDE.md 当成垃圾堆

文件一旦变得很大，Claude 每次启动都要读一堆低信噪比内容。解决办法不是继续加，而是把细节拆到 imports 里，让顶层文件保持聚焦。

3. 规则过期了还不更新

如果你的构建命令三个月前就变了，但 CLAUDE.md 还保留旧写法，那你其实是在持续给 Claude 喂错误上下文。

4. 团队文件里混入纯个人笔记

如果某条说明只有你自己需要，就放到 ~/.claude/CLAUDE.md，或者从家目录导入一份个人文件，而不是直接提交进项目。

一个简单的维护习惯

你可以在每周一次，或者项目工作流明显变化时，做这 5 件事：

1. 打开 CLAUDE.md
2. 删掉临时内容
3. 检查命令是否还有效
4. 把很长的细节移到 imports
5. 确保顶层文件 1 分钟内能看完

对大多数团队来说，这已经够用了。

快速检查清单

• 在项目根目录运行 /init
• 保持文件简短且具体
• 只记录命令、规范、架构说明这类稳定信息
• 更长的资料放进 imports
• 用 # 快速追加规则
• 用 /memory 定期整理
• 工作流变化时顺手更新

官方参考

• Manage Claude's memory
• Slash commands
• Claude Code tutorials