Claude Code Memory 系统完全指南：CLAUDE.md vs Auto Memory、.claude/rules/ 路径规则与大团队管理

Claude Code 的记忆系统由两个互补机制构成：你写的 CLAUDE.md 文件（给 Claude 的持久指令），和 Claude 自动写的 Auto Memory（从你的纠正和偏好中学习）。两者在每次会话开始时都会加载。

CLAUDE.md vs Auto Memory 对比#

CLAUDE.md 文件系统#

四个作用域#

更具体的位置优先级更高：Local > Project > User > Managed。

快速创建项目 CLAUDE.md#

/init

Claude 分析代码库，自动生成包含构建命令、测试指令和项目约定的 CLAUDE.md。若文件已存在，只给出改进建议，不会覆盖。

编写高效指令的 4 条原则#

1. 控制大小（< 200 行）

CLAUDE.md 每次会话都消耗 Token。目标每个文件 200 行以内；超出时用 imports 或 .claude/rules/ 拆分。

2. 结构化

用 Markdown 标题和列表分组相关指令。Claude 扫描结构的方式和读者相同：有组织的章节比密集段落更易遵循。

3. 具体可验证

# 好的写法
- 使用 2 空格缩进
- 提交前运行 `npm test`
- API handler 放在 `src/api/handlers/`

# 不好的写法
- 规范地格式化代码
- 测试你的变更
- 保持文件有序

4. 保持一致

若两条规则互相矛盾，Claude 可能随机选一条。定期审查 CLAUDE.md、嵌套子目录的 CLAUDE.md 和 .claude/rules/ 文件，移除过时或冲突的指令。

导入其他文件（@ 语法）#

# CLAUDE.md
参见 @README 了解项目概览，@package.json 查看可用 npm 命令。

# 额外指令
- git 工作流：@docs/git-instructions.md

• 相对路径相对于包含 @ 语法的文件，而非工作目录
• 最多递归 5 层
• 首次遇到外部 imports 时，会显示批准对话框；拒绝后不再提示

跨 worktree 共享个人指令：

# CLAUDE.local.md
# 个人偏好
- @~/.claude/my-project-instructions.md

CLAUDE.md 加载机制#

Claude Code 从当前工作目录向上遍历目录树，加载每个目录的 CLAUDE.md 和 CLAUDE.local.md。例如在 foo/bar/ 运行时，加载 foo/bar/CLAUDE.md 和 foo/CLAUDE.md。子目录的 CLAUDE.md 在 Claude 读取那些子目录中的文件时按需加载。

加载额外目录的 CLAUDE.md（配合 --add-dir 使用）：

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

.claude/rules/ 路径规则系统#

对于大型项目，将指令拆分到多个文件，按主题组织：

没有 paths frontmatter 的规则文件，与 .claude/CLAUDE.md 同优先级，在启动时加载。

路径特定规则（按需加载）#

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

# API 开发规则

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

仅当 Claude 读取匹配文件时才加载，减少不相关任务的 Token 消耗。

支持的 glob 模式：

多模式和花括号展开：

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

任务特定的指令（不需要一直在上下文中）使用 Skills 代替 .claude/rules/——Skills 只在调用时或 Claude 判断相关时加载。

用 symlink 跨项目共享规则#

# 在 shared-standards 仓库维护标准规则
# 在各项目中 symlink
ln -s /path/to/shared-standards/.claude/rules/security.md .claude/rules/security.md

大团队 CLAUDE.md 管理#

组织级统一部署#

# macOS（via MDM）
/Library/Application Support/ClaudeCode/CLAUDE.md

# Linux
/etc/claude-code/CLAUDE.md

用 MDM 工具分发到所有设备，所有用户自动应用组织编码标准、安全策略和合规要求。

排除无关的 CLAUDE.md#

在 Monorepo 中，其他团队的 CLAUDE.md 可能被自动拾取，用 claudeMdExcludes 跳过：

// settings.json
{
  "claudeMdExcludes": [
    "packages/other-team/**",
    "legacy/**"
  ]
}

Auto Memory（自动记忆）#

工作机制#

Claude 在对话中发现值得记住的信息时，自动将其保存到内存文件。触发条件：

• 你纠正了 Claude 的行为（「不要用 var，用 const」）
• Claude 发现了有用的项目规律（构建命令、首选库）
• 你表达了工作流偏好

Subagent 也可以维护自己的 Auto Memory（见 subagent 配置）。

存储位置#

Auto Memory 按工作目录树存储：

每个工作目录独立，切换项目时记忆不会混淆。

启用/禁用#

界面中可以：

• 查看 Auto Memory 条目
• 编辑或删除特定记忆
• 启用/禁用 Auto Memory
• 查看哪个目录的记忆正在被加载

全局禁用：

{ "autoMemory": false }

故障排查#

原文：How Claude remembers your project - Claude Code Docs | 来源：Anthropic 官方文档