Claude Code CLAUDE.md 记忆系统完全指南

教 Claude 理解你的项目、遵守你的规范，让每次对话都有记忆。

什么是 CLAUDE.md？

CLAUDE.md 是给 Claude Code 的指令文件，类似于一个"项目规范书"。Claude 在每次对话开始时会自动读取这些文件，将内容作为上下文来指导自己的行为。

类比：

• CLAUDE.md ≈ 给 Claude 的 .editorconfig + 项目规范文档
• 就像 .eslintrc 告诉 ESLint 如何工作，CLAUDE.md 告诉 Claude 如何编码

记忆文件类型

按文件分类

优先级（从低到高）

1. /etc/claude-code/CLAUDE.md     (企业管理级)
2. ~/.claude/CLAUDE.md             (全局用户级)
3. CLAUDE.md / .claude/rules/*.md  (项目级)
4. CLAUDE.local.md                 (个人本地级，最高)

源码中的加载顺序

src/context.ts 中的 getClaudeMds() 会在会话启动（约 150-190 行）时收集所有可用的 CLAUDE 规则，并在系统 prompt 中注入编译后的内容，因此对话一开始就带着这些规则。发现顺序由 src/utils/claudemd.ts 控制：

1. /etc/claude-code/CLAUDE.md（运维/企业级）
2. ~/.claude/CLAUDE.md（用户全局）
3. 当前项目内的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md
4. 最近的 CLAUDE.local.md

靠近当前工作目录的文件会覆盖前面读取的规则，而且 @path 引入会递归解析，重复内容会在编译器阶段去重。若需要临时禁用，可设置环境变量 CLAUDE_CODE_DISABLE_CLAUDE_MDS=true 或运行 --bare（裸模式）启动，这两种策略在同一个 context 初始化逻辑中受支持。

编写 CLAUDE.md

团队共享版（CLAUDE.md）

# 项目规范


## 技术栈

- React 18 + TypeScript 5
- 状态管理：Zustand
- 样式：TailwindCSS 4
- 测试：Vitest + React Testing Library
- 包管理：pnpm

## 编码规范

### TypeScript

- 严格模式，不使用 `any`
- 所有公开 API 必须有 JSDoc 注释
- 优先使用 `const` 和箭头函数
- 接口命名不加 `I` 前缀

### React

- 只使用函数组件
- Hooks 抽取到 `src/hooks/` 目录
- 组件文件使用 PascalCase 命名

### 文件结构

src/
├── components/    # UI 组件
├── hooks/         # 自定义 Hooks
├── stores/        # Zustand stores
├── utils/         # 工具函数
├── types/         # 类型定义
└── services/      # API 调用层

## Git 提交

- 使用 Conventional Commits 格式
- feat: / fix: / docs: / refactor: / test:
- 每个提交只做一件事

## 测试

- 新功能必须有对应的测试
- 运行测试：`pnpm test`
- 运行 lint：`pnpm lint`

个人偏好版（CLAUDE.local.md）

# 个人偏好

## 语言
- 所有回复使用中文
- 代码注释使用英文

## 工作习惯
- 修改代码前先说明你要做什么
- 每次修改后自动运行 `pnpm typecheck`
- 优先使用 vim 风格的键位

## 常用路径
- 我主要在 `src/features/auth` 目录工作
- 测试文件放在同级的 `__tests__/` 目录

子目录规则

子目录中的 CLAUDE.md 会在 Claude 进入该目录工作时自动加载：

src/
├── CLAUDE.md           # 根目录规则
├── components/
│   └── CLAUDE.md       # 组件开发规则
├── api/
│   └── CLAUDE.md       # API 开发规则
└── tests/
    └── CLAUDE.md       # 测试规则

示例 — src/components/CLAUDE.md：

# 组件开发规则

- 每个组件一个目录：ComponentName/index.tsx
- 必须导出 Props 类型
- Storybook story 文件必须和组件同目录
- 使用 `cn()` 工具函数合并 className

模块化规则（.claude/rules/）

将不同领域的规则拆分到独立文件：

.claude/rules/
├── code-style.md      # 代码风格
├── testing.md         # 测试规范
├── security.md        # 安全规则
├── api-design.md      # API 设计
└── git-workflow.md    # Git 工作流

所有 .claude/rules/*.md 文件会自动加载，无需手动引入。

示例 — .claude/rules/security.md：

# 安全规则

## 绝对禁止
- 不要在代码中硬编码密钥、密码、Token
- 不要使用 eval() 或 new Function()
- 不要在日志中输出敏感信息

## 必须遵守
- 所有用户输入必须验证和消毒
- SQL 查询必须使用参数化查询
- API 端点必须有认证和授权检查
- 文件上传必须验证类型和大小

高级特性

@引入外部文件

# CLAUDE.md

## 项目规范

@docs/coding-standards.md
@docs/api-guidelines.md
@.github/CONTRIBUTING.md

@path/to/file 语法会将外部文件内容内联到 CLAUDE.md 中。

paths 限定作用范围

---
paths: src/components/**, *.tsx
---

# React 组件规范

这些规则仅在操作 src/components 目录或 .tsx 文件时生效。

排除特定文件

在 settings.json 中：

{
  "claudeMdExcludes": [
    "**/vendor/CLAUDE.md",
    "/home/user/monorepo/legacy/CLAUDE.md"
  ]
}

自动记忆系统

除了手动编写的 CLAUDE.md，Claude Code 还有自动记忆功能：

{
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "~/.claude/projects/<path>/memory/"
}

自动记忆会存储在：

~/.claude/projects/<sanitized-project-path>/memory/
├── MEMORY.md              # 入口文件
└── logs/
    └── 2025/01/
        └── 2025-01-15.md  # 每日日志

Claude 会自动将重要的项目发现、架构决策等记录到记忆中，在后续对话中自动引用。

何时持久化会话

是否启用自动记忆由 src/memdir/paths.ts 中的逻辑判定：环境变量拥有最高优先级，其次是 settings.json 的 autoMemoryEnabled，若远程会话不允许写入也会被禁止。一旦允许，src/services/extractMemories/extractMemories.ts 会在每次完整轮次（无进一步工具调用）结束时，通过 runForkedAgent 分叉辅助代理扫描对话记录，并将记忆写入 ~/.claude/projects/<path>/memory/，若主代理已写入则跳过。src/memdir/memdir.ts 保证 MEMORY.md 截断在 200 行 / 25KB 以内，并提醒不要保存任何敏感信息。若通过环境变量或设置关闭自动记忆，或当前会话因远程环境无法创建存储目录，则整个抽取流程会被完全跳过。

全局 CLAUDE.md

~/.claude/CLAUDE.md 适合存放所有项目通用的个人偏好：

# 全局规范

## 通用偏好
- 回复使用中文
- 代码注释使用英文
- 优先使用现代语法特性
- 解释代码改动的原因

## 通用安全规则
- 永远不要在终端输出密钥
- 不要读取 ~/.ssh/ 目录下的文件
- 不要执行 rm -rf 不带确认的命令

## 输出风格
- 修改文件前先说明计划
- 修改后总结变更点
- 遇到不确定的地方主动提问

最佳实践

1. 团队规范放 CLAUDE.md — 编码风格、架构约定、测试要求
2. 个人偏好放 CLAUDE.local.md — 语言、习惯、快捷方式
3. 领域规则拆到 .claude/rules/ — 安全、性能、API 设计各一个文件
4. 子目录规则要精简 — 只写该目录特有的规则，不要重复根目录内容
5. 善用 paths 限定范围 — 避免不相关的规则干扰 Claude
6. 及时更新 — 项目的技术栈、架构变化后同步更新 CLAUDE.md
7. 别写太长 — CLAUDE.md 消耗 token，保持精练、重点突出