Auto-Memory + CLAUDE.md

来源 https://zhuanlan.zhihu.com/p/2013213227740325799

Anthropic 近日为其命令行编码工具 Claude Code 上线了自动记忆（Auto Memory）功能，进一步提升了 AI 在真实开发环境中的上下文理解能力。这一更新的目标很明确：让模型在长期项目中逐步积累对项目的理解，减少开发者反复提供背景信息的负担。

在此之前，Claude Code 已支持 CLAUDE.md 文件，用于开发者向模型提供明确的项目规则和指令。而这次新增的 MEMORY.md 则扮演了相反的角色——它更像是 Claude 自己维护的一本「项目笔记」。当开发者在协作过程中表达一些偏好，例如：“记住我们使用 pnpm 而不是 npm”，Claude 会把这些信息写入记忆文件，并在后续任务中优先遵循这些约定。

本文将系统介绍这套项目记忆机制的工作方式、配置方法以及实践经验，帮助你在项目中逐步建立一套可持续使用的 AI 编程知识体系。

什么是项目记忆

Claude Code 的项目记忆功能可以让 AI 助手逐渐「了解」你的项目，比如目录结构、编码风格以及一些架构上的约定。每次会话启动时，这些保存下来的信息都会自动加载，让 Claude 一开始就能更好地理解项目背景，从而提供更准确、更一致的代码建议。

这个体系主要由两个部分组成：

Auto Memory（自动记忆）：Claude 会在会话过程中记录一些有价值的信息，例如常见模式、调试经验或项目架构细节。比如你说：“记住我们使用 ESM，而不是 CommonJS”，Claude 就会把这条信息写入 MEMORY.md。

CLAUDE.md 文件（显式指导）：这是由开发者自己编写和维护的规则文件，用来说明项目约定、开发规范或个人偏好。CLAUDE.md 支持层级结构，越具体的规则优先级越高。

简单来说，Auto Memory 用来自动记录经验，而 CLAUDE.md 用来明确规则，两者一起构成项目记忆体系。

Auto Memory vs CLAUDE.md

在深入细节之前，先弄清楚 Auto Memory 和 CLAUDE.md 的区别。

简单来说：CLAUDE.md 是开发者主动告诉 Claude 的规则，而 Auto Memory 是 Claude 在使用过程中逐渐记录下来的经验。

为什么需要项目记忆

如果没有项目记忆，Claude 每次启动会话都要重新了解项目背景，比如：

• 「我们使用 TypeScript」
• 「代码缩进是 2 个空格」
• 「错误处理遵循这套模式」

这些信息在每次对话里都要重新说明。

这不仅浪费时间，还会打断开发节奏。很多时候你正专注在某个问题上，结果 AI 助手突然问一句：「这个项目用什么包管理器？」思路一下就被打断了。

有了项目记忆之后，这些信息会在会话开始时自动加载。Claude 从一开始就能理解项目的基本情况，你也不需要再重复解释背景，可以直接进入具体问题。

这样一来，AI 更像是一个熟悉项目的协作伙伴，而不是每次都需要重新培训的新人

CLAUDE.md 文件指令机制

CLAUDE.md 是一个 Markdown 格式的配置文件，用来写入希望 Claude 遵循的指令。每次启动会话时，Claude 都会读取这些文件。

文件位置与作用域

CLAUDE.md 可以放在不同的位置，不同位置对应不同的作用范围。路径越具体，优先级越高。

Claude 会从当前工作目录开始向上遍历目录树，并加载沿途的所有 CLAUDE.md 文件。
例如在 foo/bar/ 目录中运行 Claude 时，它会同时读取 foo/bar/CLAUDE.md 和 foo/CLAUDE.md。

快速生成项目配置

如果不想从零编写配置，可以使用 /init 命令让 Claude 自动生成一份基础配置。

Claude 会扫描项目结构，识别常见的构建命令、测试方式以及一些项目约定，并生成一份 CLAUDE.md 草稿。如果文件已经存在，它通常只会提出改进建议，而不会直接覆盖。

编写有效指令

CLAUDE.md 会占用上下文窗口，所以写法很重要。可以遵循以下原则：

1. 控制篇幅

每个 CLAUDE.md 文件最好不要超过 200 行。文件过长会消耗大量 token，可能导致 Claude 难以完全遵循指令。如果指令太多，可以考虑拆分成多个文件，或者使用导入功能来管理。

2. 结构清晰

使用 markdown 的标题和列表来组织内容。Claude 会像人一样读取结构化信息，有组织的章节比大段文字更容易遵循。

# 项目约定

## 构建命令
- 开发环境: `pnpm dev`
- 构建: `pnpm build`
- 测试: `pnpm test`

## 代码规范
- 使用 2 空格缩进
- 组件放在 `src/components/`
- API 路由放在 `src/api/routes/`

3. 具体明确

指令要尽量具体，最好可以直接验证执行结果。模糊的说明容易被忽略或理解错误。

4. 避免冲突

如果多个 CLAUDE.md 文件中存在相互矛盾的指令，Claude 可能会选择其中之一执行。建议定期检查项目中的指令，清理过时或冲突的内容，保持配置一致。

使用 @ 语法导入文件

CLAUDE.md 支持使用 @path/to/file 导入其他文件的内容，这对于复用现有文档（如 README、package.json）或集中管理指令非常方便。

# 项目概述
参见 @README 获取项目简介

# 可用命令
参见 @package.json 了解所有 npm scripts

# 工作流程
遵循 @docs/git-workflow.md 中的 Git 分支策略

相对路径是相对于包含 @ 的文件解析，而不是工作目录。导入最多支持 5 层嵌套。

对于不希望提交到版本控制的个人配置，可以使用 CLAUDE.local.md，该文件会自动添加到 .gitignore 中。

如果你在多个 Git worktree 中工作，可以导入主目录的配置文件，以确保所有 worktree 共享相同的个人指令：

# 个人偏好
- @~/.claude/my-preferences.md

⚠️ 注意：首次导入外部文件时，Claude 会弹出批准对话框。如果选择拒绝，该导入将保持禁用状态。

使用 .claude/rules/ 组织大型项目

在大型项目中，可以使用 .claude/rules/ 目录将指令拆分为多个主题文件。这样可以让指令更模块化，同时便于团队统一管理和维护。

目录结构示例：

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码风格指南
│       ├── testing.md      # 测试约定
│       ├── api-design.md   # API 设计规范
│       └── security.md     # 安全要求

所有 .md 文件会被递归加载，也可以通过子目录进一步分类，例如 frontend/ 或 backend/。

路径特定规则

规则文件可以在 YAML frontmatter 中使用 paths 字段来限定作用范围。只有当 Claude 处理匹配的文件时，这些规则才会被加载。

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有 API 端点必须包含输入校验
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释

未指定 paths 字段的规则会无条件加载，适用于所有文件。

路径匹配示例：

你可以指定多个模式，或使用花括号扩展匹配多种扩展名，例如：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

跨项目共享规则

.claude/rules/ 目录支持符号链接，你可以维护一套共享规则，并将其链接到多个项目中：

# 链接整个共享规则目录
ln -s ~/shared-claude-rules .claude/rules/shared

# 链接单个规则文件
ln -s ~/company-standards/security.md .claude/rules/security.md

用户级规则

放在 ~/.claude/rules/ 下的规则适用于所有项目，适合存放非项目特定的个人偏好：

~/.claude/rules/
├── preferences.md    # 编码偏好
└── workflows.md      # 工作流程习惯

用户级规则的优先级低于项目级规则，确保项目配置可以覆盖个人设置。

Auto Memory 自动学习机制

Auto Memory 让 Claude 在工作过程中自动积累项目知识，无需手动干预。它会记录会话中的各种信息，例如：构建命令、调试心得、架构笔记、代码风格偏好以及工作流程习惯。

工作原理：200 行限制

Auto Memory 的核心机制很简单：每次会话启动时，只会加载 MEMORY.md 的前 200 行。

限制的作用包括：

• 控制上下文消耗：防止记忆文件无限增长，占用过多 token
• 保持信息新鲜：Claude 会将详细内容拆分到主题文件，保证 MEMORY.md 简洁
• 按需加载：主题文件（如 debugging.md）仅在需要时才被读取

📌 注意：200 行限制只针对 MEMORY.md 生效。CLAUDE.md 会完整加载，但仍建议保持文件简洁，以提高指令的遵循效果。

存储位置与文件结构

每个项目都有独立的记忆目录：~/.claude/projects/<project>/memory/

<project> 路径从 git 仓库路径推导而来，这意味着同一仓库的所有 worktree 和子目录共享同一个 Auto Memory 目录。非 git 项目使用项目根目录。

典型的记忆目录结构：

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话加载
├── debugging.md       # 调试模式详细笔记
├── api-conventions.md # API 设计决策
└── ...                # 其他主题文件

MEMORY.md 是整个记忆目录的索引，Claude 会在会话中读写这些文件，并使用 MEMORY.md 跟踪存储位置。

启用与禁用

Auto Memory 默认处于开启状态。可以通过以下方式切换启用或禁用状态：

方法 1：在会话中使用 /memory

打开记忆管理界面，使用开关切换。

方法 2：修改项目配置

在项目设置中添加：

{
  "autoMemoryEnabled": false
}

方法 3：使用环境变量

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

审查和编辑记忆

Auto Memory 文件采用纯 Markdown 格式，可以随时查看、编辑或删除。

运行 /memory 命令可以：

• 查看当前会话加载的所有 CLAUDE.md 和规则文件
• 切换 Auto Memory 开关
• 打开 Auto Memory 文件夹
• 在编辑器中打开任意文件

当你告诉 Claude 例如“记住用 pnpm 而不是 npm”或“记住 API 测试需要本地 Redis”时，它会自动保存到 Auto Memory。

如果希望将这些指令固化到 CLAUDE.md，可以直接告诉 Claude “把这个加到 CLAUDE.md”，或者通过 /memory 命令手动编辑。

子智能体的持久化记忆

Claude Code 的子智能体（subagent）也可以拥有自己的持久化记忆。

配置方法：

在子智能体的 markdown 文件中添加 memory 字段：

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

你是一个代码审查员。在审查代码时，将发现的模式、约定和常见问题更新到你的代理记忆中。

作用域选择：

启用记忆后，子智能体会：

• 在系统提示中包含对记忆目录的读写指令
• 自动加载记忆目录下 MEMORY.md 的前 200 行
• 自动启用 Read、Write 和 Edit 工具来管理记忆文件

最佳实践：

• 默认使用 user 作用域
• 在子智能体开始任务前，让它先查询记忆：“检查你的记忆，看看之前见过哪些模式”
• 完成任务后，让子智能体更新记忆：“把你学到的东西保存到记忆中”

实战最佳实践

项目初始化：自动生成配置

开始新项目时，无需从零编写 CLAUDE.md。使用 /init 命令，让 Claude 自动分析代码库并生成配置：

Claude 会扫描项目结构，自动识别：

• 构建系统（npm、pnpm、yarn、make、cargo 等）
• 测试框架与测试命令
• 项目目录结构
• 常见代码模式

生成的初始配置通常已经可用，你只需补充 Claude 无法自动发现的内容，例如团队约定或架构决策。

团队协作：共享规则 vs 个人偏好

团队共享（放入 CLAUDE.md）：

• 项目架构与目录结构
• 编码规范（缩进、命名约定）
• 构建和测试命令
• API 设计规范
• 安全要求

个人偏好（放入个人配置）：

• 编辑器快捷键习惯
• 调试偏好
• 私有开发环境 URL
• 个人工具链配置

建议：团队规则放在项目级 CLAUDE.md 或 .claude/rules/ 并通过版本控制共享；个人偏好放在 ~/.claude/CLAUDE.md 或 CLAUDE.local.md（自动忽略）。

大型项目组织策略

对于大型 monorepo，可以采取以下方法避免指令混乱：

1. 模块化管理 .claude/rules/

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styling.md
├── backend/
│   ├── api.md
│   └── database.md
└── shared/
    └── security.md

2. 路径特定规则

让规则只在相关文件被处理时加载，节省上下文、减少干扰。

3. 排除无关配置

在 settings.local.json 中使用 claudeMdExcludes 忽略其他团队的 CLAUDE.md：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

4. 符号链接共享通用规则

ln -s ~/company-standards .claude/rules/company

常见问题

问题 1：Claude 没有按预期执行 CLAUDE.md 中的指令

• 运行 /memory，确认文件已被加载
• 检查 CLAUDE.md 是否放在 Claude 会读取的位置
• 确保指令具体明确，例如：“使用 2 空格缩进”比“格式化代码”更有效
• 检查是否存在冲突或重复的指令

问题 2：不清楚 Auto Memory 保存了什么

运行 /memory 并打开 Auto Memory 文件夹即可查看内容。所有文件都是 Markdown 格式，可直接阅读、编辑或删除。

问题 3：CLAUDE.md 文件过大

超过 200 行的 CLAUDE.md 会占用过多上下文，影响遵循度。解决方法：

• 使用 @path/to/file 导入，将详细内容移到单独文件
• 拆分成 .claude/rules/ 目录下的多个主题文件
• 删除过时或重复的指令

问题 4：执行 /compact 后指令丢失

CLAUDE.md 在执行 /compact 后不会丢失内容。如果你发现指令消失，说明它们只是出现在对话中，并未写入 CLAUDE.md。需要手动将这些指令添加到文件中以保持持久化。

总结与展望

Claude Code 的项目记忆机制让 AI 助手能够逐步理解项目的结构和约定。通过 Auto Memory 的自动学习、CLAUDE.md 的显式规则，以及模块化的配置方式，可以更系统地管理大型项目。

在 AI 编程工具快速发展的背景下，「会话即失忆」一直是影响生产效率的问题。Claude Code 的自动记忆机制试图从工程实践层面解决这一点，通过持续积累项目上下文，让模型不再只是一次性的协作助手，而是能够长期参与项目的「虚拟成员」。

随着使用时间的增加，Claude 对项目的理解会逐渐加深，从而减少重复沟通的成本，提高开发效率。充分利用 Claude Code 的项目记忆机制，可以让代码辅助变得更加稳定和一致。

既然看到这里了，如果觉得有启发，随手点个赞、推荐、转发三连吧，你的支持是我持续分享干货的动力。

========= End