Appearance
记忆系统：让 Claude 记住你的项目
Claude Code 的每次会话都从一个全新的上下文开始，但有两种机制可以让知识跨会话传递：
- CLAUDE.md 文件：你写的持久指令，每次会话开始时自动读取
- 自动记忆（Auto Memory）：Claude 根据你的纠正和偏好自动写入的笔记
CLAUDE.md vs 自动记忆
| CLAUDE.md 文件 | 自动记忆 | |
|---|---|---|
| 谁来写 | 你 | Claude |
| 内容 | 指令和规则 | 发现和模式 |
| 范围 | 项目、用户或组织 | 每个工作目录 |
| 加载时机 | 每次会话开始 | 每次会话开始（前 200 行） |
| 用于 | 编码规范、工作流程、项目架构 | 构建命令、调试发现、Claude 发现的偏好 |
CLAUDE.md 文件
放在哪里？
| 范围 | 位置 | 适用场景 |
|---|---|---|
| 项目 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 提交到 git，团队共用的项目级规范 |
| 用户 | ~/.claude/CLAUDE.md | 适用于你所有项目的个人偏好 |
| 组织 | /etc/claude-code/CLAUDE.md（Linux）或 C:\Program Files\ClaudeCode\CLAUDE.md（Windows） | 企业统一规范，由 IT/DevOps 管理 |
更具体的位置优先级更高，会覆盖范围更广的设置。
快速创建 CLAUDE.md
运行 /init 自动生成：Claude 会分析你的代码库，创建包含构建命令、测试说明和项目规范的起始文件。
怎么写好 CLAUDE.md？
目标控制在 200 行以内。文件越长，Claude 遵守的可靠性越低（因为它占用上下文，会稀释指令的权重）。
用 Markdown 结构化组织。用标题和列表分组，Claude 扫描结构的方式和人类读者一样。
写具体可验证的指令：
✅ 好的写法：
markdown
# 代码风格
- 使用 2 空格缩进（不用 tab）
- 使用 ES modules (import/export)，不用 CommonJS (require)
# 工作流程
- 提交前运行 `npm test`
- API 处理器放在 `src/api/handlers/`
# 常用命令
- 开发：`bun run dev`
- 测试：`bun test`
- 构建：`bun run build`❌ 避免写这些：
markdown
- 写干净的代码（废话，Claude 本来就会）
- 保持文件有组织（太模糊）
- 参见 /docs 目录下的详细 API 文档（Claude 可以自己去找）应该包含什么：
- Claude 无法猜到的 Bash 命令
- 与默认值不同的代码风格规则
- 测试说明和首选测试运行器
- 仓库礼仪（分支命名、PR 规范）
- 项目特有的架构决策
- 常见的坑和非显而易见的行为
不应该包含什么：
- Claude 读代码就能发现的内容
- 标准语言约定（Claude 已经知道）
- 频繁变化的信息
- 文件级别的详细描述
引入外部文件
使用 @path/to/file 语法引入额外文件：
markdown
参见 @README.md 了解项目概述，@package.json 了解可用命令。
# 额外说明
- Git 工作流：@docs/git-instructions.md
- 个人偏好：@~/.claude/my-project-instructions.md用 .claude/rules/ 组织规则
对于大项目，可以把指令分散到多个文件：
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目说明
│ └── rules/
│ ├── code-style.md # 代码风格
│ ├── testing.md # 测试规范
│ └── security.md # 安全要求还可以按文件路径限定规则的作用范围：
markdown
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 接口必须包含输入验证
- 使用标准错误响应格式这样这些规则只在 Claude 处理 src/api/ 下的 TypeScript 文件时才加载，不会每次都占用上下文。
自动记忆（Auto Memory）
自动记忆让 Claude 在会话之间自动积累知识，你不需要手动写任何东西。Claude 会保存：构建命令、调试发现、架构说明、代码风格偏好、工作流习惯等。
需要 Claude Code v2.1.59 或更高版本。运行
claude --version检查版本。
开关自动记忆
自动记忆默认开启。要关闭：
json
// .claude/settings.json
{
"autoMemoryEnabled": false
}也可以设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
在会话中运行 /memory 可以切换开关，也可以查看和编辑记忆内容。
记忆存储在哪里
每个项目有独立的记忆目录：~/.claude/projects/<project>/memory/
~/.claude/projects/<project>/memory/
├── MEMORY.md # 简洁索引，每次会话都加载（前 200 行）
├── debugging.md # 调试模式的详细笔记
├── api-conventions.md # API 设计决策
└── ... # Claude 创建的其他主题文件MEMORY.md 是入口文件，每次会话开始时加载前 200 行。详细内容存在其他主题文件里，按需读取。
自动记忆是机器本地的，不会跨机器或云端环境共享。同一 git 仓库下的所有工作树共用一个记忆目录。
如何运作
Claude 在会话中判断什么值得记住。当你在会话界面看到"正在写入记忆"或"已召回记忆"时，说明 Claude 正在主动更新或读取记忆文件。
记忆文件是普通的 Markdown 格式，你可以随时编辑或删除。
告诉 Claude 记住某件事
始终使用 pnpm，不要用 npm记住：API 测试需要本地 Redis 实例Claude 会把这些保存到自动记忆中。如果你想添加到 CLAUDE.md 而不是自动记忆，直接说"把这个加到 CLAUDE.md"。
用 /memory 管理记忆
运行 /memory 命令可以：
- 查看当前会话中加载的所有 CLAUDE.md 和规则文件
- 开关自动记忆
- 打开自动记忆目录浏览内容
- 选中文件在编辑器中打开
常见问题排查
Claude 不遵守 CLAUDE.md 的指令？
- 运行
/memory确认文件被加载了 - 检查 CLAUDE.md 是否放在正确位置
- 把指令写得更具体："使用 2 空格缩进"而不是"格式化代码"
- 检查是否有冲突的指令
不知道自动记忆保存了什么？
- 运行
/memory，选择自动记忆目录，所有内容都是可读的 Markdown
CLAUDE.md 太大了？
- 超过 200 行会降低遵守率
- 把详细内容移到用
@path引入的独立文件，或者拆分到.claude/rules/中
/compact 之后指令丢失了？
- CLAUDE.md 在压缩后完全保留，Claude 会从磁盘重新读取
- 如果某条指令在压缩后消失了，说明它只存在于对话中，没写进 CLAUDE.md