Memory 与 CLAUDE.md
把团队规则和项目约束沉淀为稳定的"长期上下文"
不再每次重复说明 — 让 Claude 记住你的规则重复的说明
你有没有发现，每次打开 Claude Code 都要从头解释一遍项目规则？
昨天说过的规则
你明确告诉过 Claude："这个项目用 TypeScript 严格模式，API 响应统一用 { code, data, message } 格式"。今天新开一个会话，它全忘了。
团队成员的困扰
每个人跟 Claude 解释的项目规则版本不同。A 说的命名规范是 camelCase，B 说是 snake_case。Claude 听谁的？
散落各处的约定
编码规范在 Slack 里，Git 工作流在 Notion 里，API 标准在某个人的脑子里。Claude 哪个都看不到。
CLAUDE.md，Claude 在每次会话中自动加载。一次写好，全团队共享，随代码一起版本化管理。
三种写入方式
往 Memory 里写规则，你有三个入口
1. /init — 初始化项目规则
Claude 根据当前项目自动生成 CLAUDE.md，包含项目概览、开发规范、常用命令等骨架。
$ /init2. # 快速追加
在输入框前加 #，一句话追加规则。适合在开发过程中随时记录发现。
# 这个项目始终使用 TypeScript 严格模式
# 提交前必须运行 npm test3. /memory — 分层编辑
打开记忆编辑器，在项目级、用户级、目录级之间切换管理。适合整理和维护规则。
$ /memory/init 生成骨架，开发中用 # 随时追加，定期用 /memory 整理。
用 /init 起步
30 秒生成你的第一个 CLAUDE.md
在项目根目录打开 Claude Code，输入：
$ /initClaude 会扫描项目结构，生成类似这样的文件：
# 项目配置
## 项目概览
- **名称**：电商平台
- **技术栈**：Node.js、PostgreSQL、React 18、Docker
- **团队规模**：5 名开发者
## 开发规范
### 代码风格
- 使用 Prettier 格式化
- 使用带 airbnb 配置的 ESLint
- 最大行长度：100 字符
- 使用 2 空格缩进
### 命名规范
- **文件**：kebab-case（`user-controller.js`）
- **类**：PascalCase（`UserService`）
- **函数/变量**：camelCase（`getUserById`）
- **数据库表**：snake_case（`user_accounts`）
## 常用命令
| 命令 | 作用 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm test` | 运行测试套件 |
| `npm run lint` | 检查代码风格 |好规则与坏规则
写得太模糊
# 项目配置
写好代码，注意质量。
前后端都要测试。
API 要设计好。"写好代码"——什么叫好？Claude 没法执行。
具体可验证
# 编码规范
- 使用 TypeScript 严格模式（noImplicitAny: true）
- 每次提交前运行 npm test，全部通过才能提交
- API 响应统一使用 { code, data, message } 格式
- 数据库字段使用 snake_case，代码使用 camelCase每条都能用命令检查，没有歧义。
七层作用域
规则写在哪，决定它影响谁、优先级多高
| 层级 | 文件位置 | 影响范围 | 典型内容 |
|---|---|---|---|
| 组织策略 | 企业管理员配置 | 整个组织 | 合规要求、安全红线、统一流程 |
| 项目记忆 | ./CLAUDE.md |
单个项目 | 架构、编码标准、Git 工作流 |
| 项目规则 | .claude/rules/*.md |
单个项目 | 模块化的项目约定（可拆分多文件） |
| 用户记忆 | ~/.claude/CLAUDE.md |
单个用户 | 个人偏好、默认设置 |
| 用户规则 | ~/.claude/rules/*.md |
单个用户 | 个人规则模块（跨项目通用） |
| 本地记忆 | .claude/local/CLAUDE.md |
本机 | 机器相关设置（不进 Git） |
| Auto Memory | 自动生成 | 会话级 | Claude 自动捕获的偏好与模式 |
CLAUDE.md 会覆盖项目根目录的规则。
举个例子：项目规则说"用 Jest 测试"，但你个人偏好 Vitest。在项目目录下工作时，Claude 会遵循项目规则用 Jest——这才是正确的行为。
项目级记忆
放在 ./CLAUDE.md，随代码一起版本管理
项目级记忆是最常用的层级。它解决的核心问题是：让所有人在同一个项目上获得一致的 Claude 行为。
# 项目配置
## 开发规范
### Git 工作流
- 分支命名：`feature/description` 或 `fix/description`
- 提交信息：遵循 conventional commits
- 合并前必须有 PR
- 所有 CI/CD 检查都必须通过
- 至少需要 1 个 approval
### 测试要求
- 最低 80% 代码覆盖率
- 所有关键路径都必须有测试
- 单元测试使用 Jest
- E2E 测试使用 Cypress
### API 规范
- 只允许 RESTful 端点
- API 版本路径：`/api/v1/`
- 请求/响应都使用 JSON
- 正确使用 HTTP 状态码CLAUDE.md 纳入 Git 仓库。这样团队规则随代码一起演进，PR review 时也能看到规则的变更。可以用 @docs/architecture.md 引用外部文档，避免把所有内容堆进一个文件。
模块化规则
用 .claude/rules/*.md 把规则拆成多个文件
当项目规则越来越多，一个 CLAUDE.md 会变得臃肿。Claude Code 支持把规则拆成独立的 Markdown 文件，放在 .claude/rules/ 目录下。
.claude/ ├── rules/ │ ├── typescript.md ← TypeScript 编码规范 │ ├── testing.md ← 测试策略和要求 │ ├── api-design.md ← API 设计标准 │ └── git-workflow.md ← Git 工作流规则
每个规则文件可以用 YAML frontmatter 加上描述，帮助 Claude 判断何时加载：
---
description: TypeScript 编码规范
---
# TypeScript 规范
- 使用严格模式（noImplicitAny: true）
- 优先使用 interface 而非 type
- 所有公共函数必须有返回类型标注~/.claude/rules/*.md。比如"始终使用中文回复"、"优先使用函数式写法"等。
目录级覆盖
子目录里的 CLAUDE.md 可以覆盖上级规则
project/ ├── CLAUDE.md ← 项目级：通用编码规范 ├── src/ │ ├── CLAUDE.md ← 源码级：组件结构规范 │ └── api/ │ └── CLAUDE.md ← API 模块：接口专属规范
当你在 src/api/ 目录下工作时，Claude 会同时加载三层规则，API 模块的局部规则优先于项目通用规则：
# 文件：src/api/CLAUDE.md
## API 专属规范
### 请求校验
- 使用 Zod 做 schema 校验
- 校验失败时返回 400
- 提供字段级别的错误详情
### 认证
- 所有端点都需要 JWT token
- token 放在 Authorization header 中
- token 24 小时后过期
### 响应格式
所有响应必须遵循：
{ "success": true, "data": {...}, "timestamp": "...", "version": "1.0" }
### 分页
- 使用基于 cursor 的分页，而不是 offset
- 单页最大数量限制为 100个人偏好
写在 ~/.claude/CLAUDE.md，只影响你自己
用户级记忆适合放那些不影响团队、只和你的工作习惯有关的规则：
# 我的开发偏好
## 关于我
- **经验水平**：8 年全栈开发经验
- **偏好语言**：TypeScript、Python
- **沟通风格**：直接，最好带例子
- **学习风格**：配合代码的可视化图示
## 代码偏好
### 错误处理
我偏好显式的错误处理，使用 try-catch 和有意义的错误消息。
### 注释
注释应解释"为什么"，而不是"是什么"。
代码本身应该尽量能自解释。
### 测试
我偏好 TDD（测试驱动开发）。
先写测试，再写实现。
## 调试偏好
- 使用带前缀的 console.log：[DEBUG]
- 日志里始终带时间戳~/.claude/CLAUDE.md 即可。之后你在任何项目里打开 Claude Code，它都会读取你的个人偏好。
安装与验证
三种安装方式与三步验证流程
手动安装命令
# 设置项目记忆
cp project-CLAUDE.md CLAUDE.md
# 设置个人记忆
cp personal-CLAUDE.md ~/.claude/CLAUDE.md
# 设置目录级记忆
cp directory-api-CLAUDE.md src/api/CLAUDE.md三步验证安装
- 重新打开 Claude Code 会话，确保配置被重新加载
- 检查加载：观察会话启动时
CLAUDE.md是否被自动加载（Claude 会提示） - 测试规则：用一条明显会受 memory 影响的提示词测试，验证规则是否生效
CLAUDE.md 模板文件 （点击文件名查看内容）
02-memory/
├── directory-api-CLAUDE.md
├── personal-CLAUDE.md
└── project-CLAUDE.md/init 自动生成，手动 cp 适合模板化部署到多个项目。用 # 快速追加适合开发中随时记录。
本地记忆
写在 .claude/local/CLAUDE.md，只在这台机器上生效
有些规则和具体机器有关，但不应进入 Git——比如你的本地数据库端口、调试用的特殊路径、临时的工作笔记。本地记忆就是为这些场景设计的。
# 本地开发环境配置
## 数据库
- 本地 PostgreSQL 端口：5433（非默认）
- 调试数据库：debug_local
## 临时配置
- 当前正在重构 auth 模块，允许跳过类型检查
- 本地测试时使用 mock 数据，不要连接真实 API.claude/local/ 目录应该在 .gitignore 中排除。它的内容只影响你自己在这台机器上的工作。
Auto Memory
Claude 在对话中自动捕获你的偏好和行为模式
Auto Memory 和前面那些"你手动写规则"的记忆层级不同——它是Claude 主动学习你习惯的机制。在对话过程中，Claude 会注意到：
Claude 会记住什么
- 你反复做的纠正（"别用 var，用 const"）
- 你的代码风格偏好（函数式 vs 面向对象）
- 你的框架选择（React 而不是 Vue）
- 你的沟通方式偏好（简洁 vs 详细）
工作方式
- 你在对话中表达了偏好或做了纠正
- Claude 识别到这是一个值得记住的模式
- 自动保存到对应的记忆文件中
- 后续会话中自动生效，无需重复说明
Auto 进阶
Auto Memory 的目录查找、自定义路径与启停控制
Claude 会根据当前工作目录、父目录和已配置路径，逐层查找相关记忆文件：
project/ ├── CLAUDE.md ← 项目级：通用编码规范 ├── src/ │ ├── CLAUDE.md ← 源码级：组件结构规范 │ └── api/ │ └── CLAUDE.md ← API 模块：接口专属规范
自定义 auto memory 目录
如果默认目录不适合你的项目结构，可以在设置中指定新的 memory 路径，让 Claude 从自定义位置加载规则。
启用 / 禁用 auto memory
你可以在当前会话中禁用 auto memory（临时关闭自动加载），也可以显式开启它。适合调试或需要干净上下文的场景。
协作与隔离
worktree 共享、Subagent 隔离与 symlink 复用
worktree 与仓库共享
在 worktree、monorepo 或多人协作场景中，auto memory 帮助保持规则一致。所有工作树共享同一套项目记忆，不会因为分支切换丢失约束。
Subagent 记忆隔离
Subagents 拥有独立的记忆范围。主 agent 的项目规则不会自动泄漏给 subagent，确保各执行者只在各自职责内保持一致性。
rules/api-standards.md 软链接到 src/api/CLAUDE.md，一次维护、多处生效。
规则加载机制
所有记忆文件在会话开始时自动查找并加载
你不需要手动告诉 Claude 去读哪个 CLAUDE.md。Claude Code 会在会话启动时自动完成以下查找：
查找过程
- 从当前目录开始，检查有没有
CLAUDE.md - 向上逐层查找父目录的
CLAUDE.md - 同时检查用户级
~/.claude/CLAUDE.md - 加载
.claude/rules/*.md和~/.claude/rules/*.md - 加载所有找到的规则，按优先级合并
排除不需要的规则
如果某些 CLAUDE.md 不应该被自动加载，可以在设置中通过 claudeMdExcludes 排除特定路径：
{
"claudeMdExcludes": [
"legacy/CLAUDE.md",
"vendor/**/CLAUDE.md"
]
}--add-dir 把额外目录加入 Claude 的可见范围，适合 monorepo 或跨项目协作场景。
作为底座
Memory 为 Slash Commands、Skills、Subagents 提供统一约束
底座约束
定义"应该怎样"
流程入口
定义"做什么"
能力包
定义"怎么做"
执行者
定义"谁来做"
当你执行一条 Slash Command 或调用一个 Skill 时，Memory 中定义的编码规范、测试要求、API 格式等规则会自动被继承。
举个例子：你在 CLAUDE.md 里写了"使用 TypeScript 严格模式"。之后无论你用哪个命令生成代码，Claude 都会遵循这个约束——不需要在每个命令里重复声明。
常见错误
写得太宽
"写好代码" — 无法验证，等于没写。
修复：改成"使用 TypeScript 严格模式，noImplicitAny: true"。
写得太细
把整个 README 复制进去 — 浪费 token，噪声太大，Claude 反而更难找到关键规则。
修复：只保留影响 Claude 行为的约束。在 CLAUDE.md 中用 @docs/api-standards.md 引用外部文档，Claude 需要时会去读原文，而不是全文粘贴。
规则冲突
项目级写"用 Jest"，目录级写"用 Vitest"，Claude 不知道听谁的。
修复：确保目录级规则是项目级的补充而非矛盾。如果确实要覆盖，在目录级规则中明确说明"替代项目级中的 XXX 规则"。
写入密钥
把 API key 或数据库密码写进 CLAUDE.md — 这个文件会进 Git！
修复：绝对不要写密钥。用环境变量和 .env 文件管理敏感信息。
过期规则
项目已经迁移到 Vite，规则还在说 Webpack。
修复：把 CLAUDE.md 当代码一样维护。技术栈变更时同步更新规则。
记忆维护
把 CLAUDE.md 当代码一样维护——它也需要重构
何时更新
- 技术栈变更时（如 Webpack → Vite）同步更新规则
- 团队编码规范调整时，更新项目记忆
- 发现 Claude 反复犯同一类错误时，追加约束
- 规则过期或矛盾时，立即清理
会话中更新
你可以在对话中直接要求 Claude 更新记忆：
记住：所有新组件优先使用 React hooks，
不用 class components。
→ Claude：我会把它加入记忆。
写入哪个文件？
1. 项目记忆（./CLAUDE.md）
2. 个人记忆（~/.claude/CLAUDE.md）CLAUDE.md。删掉过期的规则，合并重复的条目，确保每条规则仍然有效。
最佳实践
用好 Memory 的核心原则与常见陷阱
应该做的
- 用项目记忆保存团队标准，确保所有人获得一致行为
- 用目录记忆保存局部差异，不同模块可以有不同约束
- 先写简洁规则，再根据实际需要逐步补充
- 把可重复内容写进
CLAUDE.md，随代码一起版本管理
不应该做的
- 不要把 README 整份复制进
CLAUDE.md - 不要把明显属于代码的实现细节硬塞进 memory
- 不要让 memory 变成垃圾桶——过期、重复、矛盾的内容要及时清理
@docs/xxx.md）而不是重复粘贴；只保留真正影响 Claude 行为的信息；定期整理过期或冲突的规则。
动手练习
为你当前正在做的项目，编写 5 条"可验证"的 CLAUDE.md 规则
评估标准
- 每条规则是否具体——有没有具体的技术名词或数值
- 每条规则是否可验证——能不能用命令检查
- 规则之间是否无矛盾
- 是否放在正确的作用域——项目记忆 vs 项目规则 vs 目录级 vs 用户级 vs 本地记忆
- 是否需要拆成独立文件放入
.claude/rules/
参考答案
# 文件：CLAUDE.md
## 编码风格
- 使用 Java 21 record 类定义不可变 DTO
- 所有 public 方法必须添加 Javadoc 注释
## Git 工作流
- Commit 格式: type(scope): description（遵循 Conventional Commits）
- 提交前运行: mvn test，全部通过才能提交
## API 规范
- REST 端点路径使用复数名词：/api/users（不是 /api/user）
- 统一响应包装: ResponseEntity<Result<T>>
## 测试要求
- 新增代码的单元测试覆盖率不低于 80%
- 使用 @ParameterizedTest 测试边界条件
## 安全
- 禁止在代码和配置文件中硬编码任何密钥
- 所有外部输入必须校验后才能使用本章结束
下一章：在 Memory 之上构建可复用的能力包