CLAUDE.md 是 Claude Code 持久上下文管理的核心，采用 8 层优先级记忆结构，将组织策略、团队规范、个人偏好与 Claude 自动学习有机结合。通过项目、用户、目录、自动等多种 CLAUDE.md 文件，开发者可灵活管理和继承上下文，实现团队协作、个性化开发和自动知识积累。本指南详解每层适用场景、配置方法与最佳实践，助你高效掌控 Claude Code 记忆体系。

CLAUDE.md 深度指南：8 层记忆层级与持久上下文管理

Claude Code 的记忆系统（Memory）让 AI 能够跨会话、跨项目持久记住你的规则、标准和偏好。其核心是 CLAUDE.md 及其多层级结构，不仅支持团队协作、个人定制，还能让 Claude 自动积累知识。本文将分层讲解 CLAUDE.md 的 8 层记忆体系、常用命令、自动记忆（Auto Memory）亮点、排除/定制配置及最佳实践，助你从新手到进阶高效掌控 Claude 的上下文管理。

CLAUDE.md 记忆体系概览

Claude Code 的记忆体系采用多层优先级架构，支持以下 8 层（优先级从高到低）：

1. Managed Policy（组织策略）
   适合写：公司安全合规要求、强制性开发规范
   位置：如 /Library/Application Support/ClaudeCode/CLAUDE.md
   示例：

   # 公司安全策略
   - 禁止代码中出现明文密码
   - 所有 API 必须有认证和日志

2. Managed Drop-ins（策略补充）
   适合写：模块化政策、部门特定规则
   位置：managed-settings.d/ 目录下多个 .md 文件，按字母顺序合并
   示例：

   • security.md：安全加固要求
   • frontend.md：前端专属规范

3. Project Memory（项目记忆）
   适合写：团队协作规范、架构说明、开发流程
   位置：./CLAUDE.md 或 ./.claude/CLAUDE.md（建议 git 管理）
   示例：见下方项目 CLAUDE.md 示例

4. Project Rules（项目规则）
   适合写：目录/模块专属规则、API 约定、测试要求
   位置：./.claude/rules/*.md
   支持子目录和路径前缀
   示例：

   ---
   paths: src/api/**/*.ts
   ---
   # API 规则
   - 所有接口必须有 Zod 校验

5. User Memory（用户记忆）
   适合写：个人开发偏好、沟通风格、常用工具
   位置：~/.claude/CLAUDE.md
   示例：见下方个人 CLAUDE.md 示例

6. User-Level Rules（用户规则）
   适合写：个人跨项目通用规则、代码风格补充
   位置：~/.claude/rules/*.md

7. Local Project Memory（本地项目记忆）
   适合写：仅自己在本项目的临时偏好（不建议新项目用）
   位置：./CLAUDE.local.md（git 忽略）

8. Auto Memory（自动记忆）
   适合写：Claude AI 自动总结的项目知识、常见问题、调试经验
   位置：~/.claude/projects/<project>/memory/
   亮点：无需手动维护，Claude 会自动记录和加载（详见下文）

记忆层级加载顺序

Claude Code 启动时会自动从高到低加载上述所有记忆文件，前面的内容会覆盖后面同名规则。你可以通过 /memory 命令查看和编辑各层文件。

快速入门与常用命令

1. 初始化项目记忆 /init

首次在项目中使用 Claude Code，推荐用 /init 快速生成标准化的 CLAUDE.md：

/init

• 自动生成项目规范模板，包含项目简介、技术栈、团队成员、开发标准等结构化内容。
• 支持交互式引导（设置 CLAUDE_CODE_NEW_INIT=true），适合团队首次落地。

2. 快速添加规则 #

在任意会话中，输入以 # 开头的内容，即可快速添加规则到记忆：

# 所有新组件优先用 React Hooks
# 记住：API 设计遵循 RESTful

Claude 会提示你选择写入项目还是个人 CLAUDE.md，适合随时补充具体细则。

3. 编辑记忆 /memory

需要大规模编辑、重组或查阅所有记忆内容时，使用：

/memory

• 支持选择具体记忆层级（如项目、个人、组织等）
• 自动打开系统编辑器，保存后 Claude 会自动加载最新内容

4. 导入外部文档 @path/to/file

在 CLAUDE.md 内可用 @README.md、@docs/api.md 等语法直接引用项目现有文档，避免重复维护。例如：

# 项目架构
@docs/architecture.md

支持相对/绝对路径、递归嵌套（最多 5 层），首次导入需确认安全。

8 层记忆层级详解与适用示例

层级	适合写什么	示例
Managed Policy	公司安全、合规、强制规范	禁止明文密码，所有接口需鉴权
Managed Drop-ins	部门/模块专属策略	前端规范、后端 API 标准
Project Memory	项目通用标准、团队约定	技术栈、测试要求、CI 流程
Project Rules	目录/模块专属规则	API 校验、测试覆盖率要求
User Memory	个人偏好、沟通风格	喜好 TDD、喜欢图示讲解
User Rules	个人通用代码风格	注释习惯、命名规则
Local Project Memory	临时个人偏好	本地调试配置
Auto Memory	Claude 自动总结	常见报错、调试经验、API 变更

实用建议：团队规范建议写在 Project Memory 并提交 git，个人偏好写在 User Memory，自动知识交给 Auto Memory。

示例1：项目 CLAUDE.md

# Project Configuration

## Project Overview
- **Name**: E-commerce Platform
- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker

## Architecture
@docs/architecture.md
@docs/api-standards.md

## Development Standards
- Use Prettier for formatting
- Use ESLint with airbnb config
- Minimum 80% code coverage

示例2：目录专属规则

---
paths: src/api/**/*.ts
---
# API 规则
- 所有接口必须有 Zod 校验
- 返回统一 JSON 结构

示例3：个人 CLAUDE.md

# My Development Preferences
- 喜欢 TDD，优先写测试
- 代码注释只写 WHY
- 喜欢用 VS Code + vim 键位

Auto Memory（自动记忆）：Claude 自动学习的亮点

Auto Memory 是 Claude Code 的一大亮点。它会自动在 ~/.claude/projects/<project>/memory/ 目录记录 AI 在项目中的观察、总结与经验，无需手动维护。
典型用途：

• Claude 自动记录常见报错、调试方法、API 变更历史
• 自动归纳代码风格、命名习惯
• 你每次与 Claude 互动，AI 都会补充/调整 MEMORY.md

加载机制：

• 启动时自动加载 MEMORY.md 前 200 行（可定制目录 via autoMemoryDirectory 配置）
• 主题文件（如 debugging.md）按需加载
• 可通过设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 关闭

适用场景举例：

• 团队成员无需手动同步经验，Claude 自动积累、共享
• 适合记录项目历史、调试经验、AI 观察到的反复问题

高级配置与排除机制

排除无关 CLAUDE.md：claudeMdExcludes

在大型 monorepo 或多项目仓库中，部分 CLAUDE.md 可能与你当前工作无关。可在 ~/.claude/settings.json 或 .claude/settings.json 配置：

{
  "claudeMdExcludes": [
    "packages/legacy-app/CLAUDE.md",
    "vendors/**/CLAUDE.md"
  ]
}

支持通配符，适合排除历史、第三方、无关子项目的记忆文件，减少 Claude 上下文噪音。

自定义自动记忆目录：autoMemoryDirectory

如需将 Auto Memory 存储到自定义位置（如云盘、特殊目录），可在用户或本地设置：

{
  "autoMemoryDirectory": "/path/to/custom/memory"
}

注意：只能在用户级/本地设置，不能写入项目或组织策略。

记忆管理最佳实践

• 项目规范用 CLAUDE.md + git，团队共享、持续演进
• 个人偏好用 ~/.claude/CLAUDE.md，不影响团队
• 目录/模块规则用 .claude/rules/，支持路径前缀、YAML frontmatter
• Auto Memory 让 AI 自动补充知识，减少重复沟通
• 善用导入语法 @path/to/file，避免内容重复
• 定期 review & 清理，防止记忆陈旧、冲突

更多模块化技能与自动化用法，参见 Claude Code 完全入门：从安装到掌握核心功能 及 Claude Code Skills 体系详解：构建可复用、可自动触发的 AI 技能。

---

FAQ

Q: CLAUDE.md 和 Auto Memory 有什么区别？
A: CLAUDE.md 由用户/团队手动维护，适合写标准、规范和偏好；Auto Memory 由 Claude 自动生成，记录 AI 观察到的项目知识和经验，两者互补。

Q: 如何让 Claude 只加载部分 CLAUDE.md 文件？
A: 使用 claudeMdExcludes 配置排除无关文件，或通过 --add-dir 指定额外目录，灵活控制记忆加载范围。

Q: 项目和个人 CLAUDE.md 冲突时，Claude 以哪个为准？
A: 按优先级加载，项目 CLAUDE.md 会覆盖个人 CLAUDE.md 的同名规则，组织策略（Managed Policy）优先级最高。

---