教程

Claude Code CLAUDE.md 深度指南：5 种存储位置、Token 预算、Auto Memory 和 .claude/rules/

Claude Code CLAUDE.md 系统完整整理：CLAUDE.md vs Auto Memory 两套机制对比；5 种存储位置层级（Managed Policy/User Global/Project/Local/Subdirectory）；加载顺序详解；@import 语法；.claude/rules/ 路径限定规则；Token 预算与遵从度（150-200 条上限）；Auto Memory 存储路径；CLAUDE.md vs Hooks 分工；Compaction 保留行为；Monorepo 配置；以及 vs AGENTS.md vs .cursorrules 对比表。

2026/5/1310分钟 阅读ClaudeEagle

CLAUDE.md 是提升 Claude Code 输出质量成本最低的单一操作。但大多数人只知道"在项目根目录建一个文件"，不知道它背后有完整的层级系统——5 种存储位置、不同的加载时机、独立的 Auto Memory 机制、以及 .claude/rules/ 路径限定规则。本文是官方文档 + morphllm 深度分析的完整整理。

CLAUDE.md vs Auto Memory：两种记忆机制

Claude Code 有两套互补的记忆机制，每次会话开始时都加载：

CLAUDE.mdAuto Memory（MEMORY.md）
谁写你Claude 自动写
写什么规则和指令Claude 发现的模式和偏好
作用范围项目/用户/组织每个 Repository，跨 Worktree 共享
加载方式每次会话全量加载每次会话只加载前 200 行（或 25KB）
版本控制提交到 Git，团队共享机器本地，不共享
适合编码规范、工作流、项目架构构建命令、调试心得、Claude 发现的偏好

原则：CLAUDE.md 放你想让整个团队知道的事，Auto Memory 放 Claude 自己学到的东西。

5 种存储位置（从高到低优先级）

1. Managed Policy（组织级，最高优先级）

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md

由 IT/DevOps 管理，所有用户强制加载，无法排除。适合：公司编码规范、安全策略、合规要求。

2. User Global（个人全局）

~/.claude/CLAUDE.md

适用于你的所有项目。放个人偏好：

markdown
# 个人偏好（~/.claude/CLAUDE.md）

- 使用 TypeScript strict 模式
- 优先 const over let
- 用 early return 代替嵌套 if/else
- commit 消息使用 Conventional Commits 格式
- 公共函数必须有 JSDoc 注释

3. Project Instructions（项目级）

./CLAUDE.md 或 ./.claude/CLAUDE.md

提交到版本控制，团队共享。放项目规则（不是个人偏好）：

markdown
# 项目：电商 API（./CLAUDE.md）

## 构建命令
- 开发：`npm run dev`
- 测试：`npm test`
- 构建：`npm run build`

## 技术栈
- Node.js 20 + TypeScript 5.4
- Express + Zod 验证
- PostgreSQL + Prisma ORM

## 代码规范
- API 响应格式：`{ data, error, meta }`
- 错误处理通过 `src/utils/errors.ts` 的 AppError 类
- 所有 SQL 查询通过 `src/repositories/` 的 Repository 模式

## 目录结构
- src/routes/ — Express 路由
- src/services/ — 业务逻辑
- src/repositories/ — 数据库访问

4. Local Instructions（个人项目级）

./CLAUDE.local.md

不提交到 Git（自动加入 .gitignore），只影响你自己。放个人专属配置：

markdown
# 我的本地配置（CLAUDE.local.md，不提交）

- 本地测试数据库：postgresql://localhost:5432/myapp_dev
- 测试账户：test@example.com / password123
- 跳过 Stripe 支付测试（本地没有 API Key）
- 我的个人 staging URL：https://myapp-staging.ngrok.io

5. Subdirectory CLAUDE.md（按需加载）

src/components/CLAUDE.md src/api/CLAUDE.md

与上面几种的关键区别：不在启动时加载，在 Claude 读取该目录的文件时才按需加载。

适合：只在特定模块工作时才需要的详细规范。

加载顺序详解

Claude Code 从当前工作目录向上遍历目录树，加载所有 CLAUDE.md 和 CLAUDE.local.md 文件。所有文件拼接（不是覆盖），按从文件系统根到工作目录的顺序排列。

你在 ~/projects/myapp/src/api/ 里运行 claude 加载顺序（从早到晚）： 1. /Library/.../CLAUDE.md（Managed Policy） 2. ~/.claude/CLAUDE.md（User Global） 3. ~/projects/CLAUDE.md（如果存在） 4. ~/projects/myapp/CLAUDE.md 5. ~/projects/myapp/.claude/CLAUDE.md 6. ~/projects/myapp/CLAUDE.local.md 7. ~/projects/myapp/src/CLAUDE.md（如果存在） 8. ~/projects/myapp/src/api/CLAUDE.md（启动时加载） 按需加载（当 Claude 读取对应目录文件时）： - ~/projects/myapp/src/components/CLAUDE.md - ~/projects/myapp/src/services/CLAUDE.md

更靠近工作目录的文件后读取，意味着更具体的规则可以覆盖上层规则（有冲突时，下层读取更晚，优先级更高）。

@import 语法：模块化组织

CLAUDE.md 可以引用其他文件（启动时内联展开，不是懒加载）：

markdown
# CLAUDE.md

参考 @README.md 了解项目概述，@package.json 了解可用命令。

## 额外指令
- Git 工作流规范：@docs/git-workflow.md
- 安全规范：@docs/security-rules.md
- API 设计规范：@docs/api-design.md

规则：

  • 相对路径相对于包含 @import 的 CLAUDE.md 文件（不是工作目录）
  • 最多 5 层递归
  • 首次遇到外部导入时，显示批准对话框

跨 Worktree 共享个人配置（CLAUDE.local.md 只在创建它的 Worktree 里存在）：

markdown
# CLAUDE.local.md
@~/.claude/my-project-personal-notes.md

.claude/rules/：路径限定规则

更大的项目用 .claude/rules/ 目录把规则模块化，每个文件一个主题：

your-project/ ├── CLAUDE.md # 主要项目指令（保持精简） └── .claude/ └── rules/ ├── code-style.md # 代码风格（全局） ├── testing.md # 测试规范（全局） ├── security.md # 安全要求（全局） ├── api/ │ └── api-design.md # API 设计（路径限定） └── frontend/ └── react.md # React 规范（路径限定）

无 paths 字段的 Rule：启动时加载，和 .claude/CLAUDE.md 优先级相同。

有 paths 字段的 Rule（路径限定）：

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

# API 开发规范

- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式 `{ code, message, details }`
- 包含 OpenAPI 文档注释
- 认证中间件必须在路由处理器之前运行
markdown
---
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# React 组件规范

- 使用函数式组件和 Hooks（不用 Class 组件）
- Props 用 interface 而非 type
- 纯展示组件用 React.memo
- 回调传给子组件时用 useCallback

触发时机：当 Claude 读取匹配路径的文件时（不是每次工具调用）。这样 TypeScript 规范只在 Claude 处理 .ts 文件时加载，不会总占着上下文空间。

与 Skills 的区别：

.claude/rules/Skills
触发读取匹配文件时自动手动调用或 Claude 判断相关时
内容类型持续有效的规范可复用的工作流步骤
适合"写这类文件时始终遵守""执行这个操作时按步骤做"

Token 预算和遵从度

核心原则：不是 Token 用多了不行，而是指令太多会被忽略。

  • Claude Code 上下文窗口：约 200K Token（标准），1M Token（Beta）
  • 100 行 CLAUDE.md ≈ 500–2000 Token（取决于内容密度）
  • Token 成本本身不是问题

真正的问题：指令密度

研究表明，前沿 LLM 可以可靠遵循约 150–200 条独立指令。Claude Code 内置系统 Prompt 已包含约 50 条。这意味着你的有效指令预算约为 100–150 条。超过这个数量，Claude 开始"丢失"规则——不是 Token 溢出，而是注意力降级。

Prompt 缓存的影响：

CLAUDE.md 内容是缓存系统 Prompt 前缀的一部分。多轮会话中：

  • 第一次调用：全量 Token 费用（如 1500 Token）
  • 后续调用：从缓存读取，约便宜 90%

所以更长的 CLAUDE.md 只增加第一次调用的成本，后续调用几乎没有额外开销。

精简测试：对每一行问"删掉这行，Claude 会犯什么具体的错？"如果答不上来，删掉它。

Auto Memory（自动记忆）详解

存储位置

~/.claude/projects/<repo-hash>/memory/ ├── MEMORY.md # 主索引文件（每次会话加载前 200 行） ├── debugging.md # 调试相关（按需加载） ├── api-conventions.md # API 约定（按需加载） └── patterns.md # 代码模式（按需加载）

<repo-hash> 是 Repository 路径的哈希。同一 Repository 的所有 Worktree 共享同一个 Auto Memory 目录。

不可用的情况：

  • 云端会话（Routines、Web）没有你的本地 Auto Memory
  • 跨机器不共享（在服务器上运行的 Claude 看不到你笔记本的 Auto Memory）

Auto Memory 如何工作

  1. 你告诉 Claude "记住这个"（或 Claude 从你的纠正中自动学习）
  2. Claude 把信息存入 ~/.claude/projects/<hash>/memory/MEMORY.md
  3. 下次会话开始时，Claude 加载 MEMORY.md 的前 200 行
  4. 需要时，Claude 主动读取具体话题文件（debugging.md 等）

启用/禁用

json
// settings.json
{
  "autoMemory": true   // 默认启用
}

或在会话内：/memory enable / /memory disable

查看和编辑

bash
# 在会话内查看
/memory

# 直接编辑文件
cat ~/.claude/projects/$(ls ~/.claude/projects/)/memory/MEMORY.md

# 告诉 Claude 记住某件事
> 记住：我们的项目不使用 Jest，用的是 Vitest

CLAUDE.md 与 Hooks 的分工

一个常见错误：在 CLAUDE.md 里写"每次修改文件后运行 ESLint"，同时在 Hooks 里也配置了 PostToolUse 自动运行 ESLint。

这会产生冲突：Hook 自动运行后，Claude 又手动运行一次，产生重复执行。

正确的分工：

用途用哪个
需要判断的规则（"如果是 React 组件，用 memo"）CLAUDE.md
每次必须执行，无例外（lint 检查、危险命令拦截）Hooks
步骤化流程（"如何部署到生产"）Skills

原则：CLAUDE.md 是建议性的（Claude 读了会尽量遵守），Hooks 是确定性的（一定执行）。不要用 CLAUDE.md 来表达"每次都必须做某件事"，用 Hook。

Compaction（上下文压缩）后怎么办

好消息：CLAUDE.md 完全在压缩后保留。

运行 /compact 后，Claude Code 从磁盘重新读取 CLAUDE.md 并重新注入。你的指令不会被摘要、截断或丢失。

坏消息：只在对话中说过的指令（没有写入文件的）会被压缩丢失。

结论：任何你希望在整个会话里持续有效的规则，必须写入 CLAUDE.md（或 Auto Memory），不要只在对话里说一遍。

Monorepo 配置模式

my-monorepo/ ├── CLAUDE.md # 组织级规则，精简 ├── .claude/ │ └── rules/ │ ├── code-style.md # 全局代码风格 │ └── git-workflow.md # 全局 Git 规范 ├── packages/ │ ├── frontend/ │ │ ├── CLAUDE.md # Frontend 专属规则 │ │ └── .claude/rules/ │ │ └── react.md # React 组件规范（路径限定） │ ├── backend/ │ │ ├── CLAUDE.md # Backend 专属规则 │ │ └── .claude/rules/ │ │ └── api.md # API 规范（路径限定） │ └── shared/ │ └── CLAUDE.md # 共享包规则 └── tools/ └── CLAUDE.md # 构建工具规则

使用 claudeMdExcludes（当其他团队的 CLAUDE.md 被意外加载时）：

json
// settings.json
{
  "claudeMdExcludes": [
    "packages/legacy-app/**"
  ]
}

CLAUDE.md vs AGENTS.md vs .cursorrules

特性CLAUDE.mdAGENTS.md.cursorrules/.mdc
工具Claude Code多工具（Codex/Cursor/Copilot/Gemini/Windsurf）Cursor IDE
发现方式从工作目录向上遍历从 Git 根向下到工作目录项目根
全局范围~/.claude/CLAUDE.md~/.codex/AGENTS.md不支持
路径限定规则✅ .claude/rules/（paths 字段）❌✅（.mdc globs）
@import 语法✅（最多 5 层）❌❌
组织级 Policy✅❌❌
个人覆盖文件CLAUDE.local.mdAGENTS.override.md无

团队用多个工具时：创建 CLAUDE.md 并 @AGENTS.md 导入，再追加 Claude Code 专属指令：

markdown
# CLAUDE.md
@AGENTS.md

## Claude Code 专属
- 在 `src/billing/` 里的变更使用 Plan Mode
- 部署操作必须通过 /deploy Skill，不要直接运行部署命令

来源：Claude Code 官方文档 - Memory | morphllm - CLAUDE.md 深度分析 | 整理：ClaudeEagle

相关文章推荐

教程Claude Code CLAUDE.md 深度指南：跨会话持久记忆、路径规则作用域与 Auto Memory 自动学习Claude Code CLAUDE.md 完整指南：两大记忆机制对比（CLAUDE.md 手动指令 vs Auto Memory 自动学习）、四级作用域（托管策略/项目/用户/本地）及优先级、/init 快速初始化、@ 导入语法、.claude/rules/ 路径级规则（YAML frontmatter 限定文件范围）、跨项目 symlink 共享，以及 Auto Memory 的工作原理、存储位置和四大常见问题排查。2026/3/5教程Claude Code 记忆系统完全指南：CLAUDE.md、Auto Memory 与规则文件组织Claude Code 记忆系统完全指南：CLAUDE.md 四种作用范围（组织/项目/用户/本地）、有效指令写作原则、.claude/rules/ 规则文件组织和路径范围限定、Auto Memory 自动笔记机制、记忆查看与编辑，以及常见问题排查。2026/3/2教程CLAUDE.md 完全指南：让 Claude Code 记住你的项目规范（2026）CLAUDE.md 完全指南：四级文件作用范围（组织/项目/用户/子目录）、高效写法原则（具体可验证、200行限制、结构化Markdown）、.claude/rules/按路径限定规则、@import语法、Auto Memory自动记忆机制、常见问题排查与团队协作建议。2026/3/12教程Claude Code 2026 完整新手指南：从安装到高级工作流（官方权威版）Claude Code 2026 全面入门教程：安装（4 种方式）、登录（包含 WSL2 粘贴 OAuth 代码）、定价对比（Pro/Max/Teams/Enterprise/Console）；核心命令速查（启动模式/15 个 Slash 命令/键盘快捷键/权限确认说明）；五大核心工作流（写代码/理解代码/修复 Bug/测试/Git 和 PR）；CLAUDE.md 配置（/init 生成 + 最佳实践）；Hooks 事件自动化；Skills 按需加载；成本优化技巧；Auto Mode + hard_deny 安全配置；以及 2026 年高级功能（Routines/Sub-agents/Computer Use/Remote Control/AutoDream/Ultraplan）。2026/5/12教程CLAUDE.md 10 段黄金模板：让 Claude Code 每次启动都像资深开发者一样了解你的项目CLAUDE.md 完整指南：10 段黄金模板（项目概述/技术栈/核心命令/项目结构/代码规范/禁止修改区域/测试规范/数据库规范/代码风格/当前工作）逐段详解，以及会话级动态更新、.claude/rules/ 领域规则拆分、废弃代码标记等高级技巧。2026/4/21教程Claude Code Routines 深度指南：在 CLAUDE.md 中定义团队级可复用工作流Claude Code CLAUDE.md Routines 完整教程：与 Cloud Routines 的区别厘清、10 个真实项目模板（组件脚手架/API 端点/Debug 溯源/安全审查/完整功能实现等），以及团队 Routine 与个人 Routine 的最佳实践。2026/4/17