## 概述
本教程面向零基础用户，系统讲解 Claude Code 的「项目记忆」机制。你将学会用 `CLAUDE.md` 文件给 Claude 持久化的项目指令，理解从企业级到本地的五层记忆层级，掌握 `@import` 文件导入、`/init` 自动生成、`auto memory` 自动学习三大核心能力，并配齐 `settings.json` 权限配置。学完后你能让 Claude 在每次新会话中「秒懂」你的代码规范、技术栈与个人偏好，而无需每次重复交代。适合刚装好 Claude Code、想从「能用」进阶到「好用」的所有开发者。
## 前置条件
- 已安装 Claude Code（CLI 形态，版本建议 2025 年 11 月之后，含完整 memory 子系统）
- 完成首次认证（API Key 或 Claude 订阅账号登录均可）
- 有一个可练习的代码目录（任意 git 仓库或空文件夹均可）
- 会用基础终端命令（`cd`、`cat`、文本编辑器）
---
## 一、先理解：为什么需要「记忆」
Claude Code 的一个根本设计是：**每一个会话都从一个干净的上下文窗口开始**。这意味着你昨晚告诉它「我们用 pnpm、用 ESLint、禁止 `any` 类型」的所有交代，今天新开会话时全部归零。
如果没有记忆机制，你会陷入两种痛苦：
1. **重复交代**：每个会话开头都要粘贴一遍项目背景、技术栈、代码规范。
2. **行为漂移**：Claude 凭「直觉」做决策——给 React 项目写 class 组件、给 Python 项目用 `print` 调试、给团队仓库擅自加分号。
Claude Code 用**两套互补的记忆系统**解决这个问题：
| 系统 | 谁来写 | 存放位置 | 特点 |
|------|--------|----------|------|
| **CLAUDE.md 文件** | 你（开发者） | 仓库内 / 用户目录 | 显式指令，精确可控，可提交到 git |
| **Auto memory（自动记忆）** | Claude 自己 | `.claude/memory/` | 自动积累，跨会话学习，无需你操心 |
理解这两套系统的分工，是配置好记忆的第一步。**CLAUDE.md 管「规则」，auto memory 管「事实」**。
---
## 二、CLAUDE.md 的五层层级
这是最容易让新手困惑的部分：到底把规则写在哪里？答案取决于「这条规则的适用范围」。Claude Code 定义了从最全局到最局部的层级，启动时按顺序加载，**越局部的优先级越高**。
```mermaid
flowchart TD
A["1. 企业策略 memory
由 IT 统一下发
最高优先级"] --> B["2. 用户级 memory
~/.claude/CLAUDE.md
跨所有项目"]
B --> C["3. 项目级 memory
./CLAUDE.md
提交到 git，团队共享"]
C --> D["4. 项目本地 memory
./CLAUDE.local.md
gitignore，个人专属"]
D --> E["5. 子目录 memory
子目录/CLAUDE.md
按需加载相关文件时生效"]
E --> F["6. Auto memory
.claude/memory/
Claude 自动学习"]
style A fill:#fde68a,stroke:#b45309
style C fill:#bfdbfe,stroke:#1d4ed8
style D fill:#fecaca,stroke:#b91c1c
style F fill:#c7d2fe,stroke:#4338ca
```
下面逐层拆解。
### 第 1 层：企业策略 memory（多数人用不到）
由公司 IT 部门通过系统级路径统一部署，例如 macOS 上的 `/Library/Application Support/ClaudeCode/CLAUDE.md`。它的指令优先级最高，通常用于强制合规要求（如「禁止将代码上传到外部服务」）。如果你是个人开发者，跳过这一层即可。
### 第 2 层：用户级 memory（强烈推荐配置）
路径：`~/.claude/CLAUDE.md`
这是**你的个人全局偏好**，对你机器上的所有项目生效。适合放那些「不管在哪个项目，我都是这么干活」的规则。
创建它：
```bash
# 在 home 目录的 .claude 下创建
cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人全局偏好
## 语言
- 默认用中文回复，代码注释可用英文
- 命名用中文标题，命令保持原文
## 工作习惯
- 修改代码前先读取目标文件，不要盲改
- 不要自动 git commit，只在明确要求时提交
- 不要主动创建文档文件，除非明确要求
- 回复简洁，避免冗长解释
## 技术偏好
- 包管理器优先用 pnpm，其次 npm
- TypeScript 项目禁止使用 any 类型
- 优先函数式风格，避免不必要的 class
EOF
```
**预期结果**：之后你打开任何项目，Claude 默认就讲中文、不乱 commit、不乱建 README。这一层价值极高，因为它消除了一类最高频的「重复交代」。
### 第 3 层：项目级 memory（团队协作核心）
路径：`<项目根目录>/CLAUDE.md`
这是**最重要的记忆文件**，提交到 git 后整个团队共享。它告诉 Claude「这个项目长什么样」。一个典型的项目级 CLAUDE.md 应包含：
```markdown
# 项目：订单中台（order-center）
## 技术栈
- 语言：Go 1.22
- Web 框架：Gin
- ORM：GORM（MySQL 8.0）
- 消息队列：Kafka
- 部署：Docker + K8s
## 目录结构
- cmd/ 程序入口
- internal/ 业务逻辑（禁止被外部 import）
- pkg/ 可复用包
- api/ HTTP handler 定义
- migrations/ 数据库迁移脚本
## 代码规范
- 错误必须显式处理，禁止 _ = err
- 数据库查询必须带 context 超时
- 新增 API 必须写单元测试，覆盖率不低于 70%
- commit message 格式：type(scope): desc，如 feat(order): 支持批量退款
## 常用命令
- 跑测试：make test
- 起本地服务：make run
- 代码检查：make lint
```
**为什么这一层要提交到 git**：因为团队的每个成员用 Claude Code 时都应读到同一份项目背景，保证行为一致。这正是 CLAUDE.md 区别于个人笔记的关键——它是**可版本控制的团队知识**。
### 第 4 层：项目本地 memory（个人专属，不提交）
路径：`<项目根目录>/CLAUDE.local.md`
它的内容**只对你自己生效**，应当加入 `.gitignore`。适合放个人化的、不想污染团队仓库的东西：
```markdown
# 本地个人偏好（不提交）
- 我在排查 #2331 这个 bug，重点关注订单状态机
- 本地数据库连接：root:123456@tcp(localhost:3306)/order
- 我习惯用 vim，生成的代码注释别用 IDE 特定格式
```
`.gitignore` 中务必加上：
```
CLAUDE.local.md
```
**常见坑**：很多人把敏感信息（数据库密码、token）写进了第 3 层 `CLAUDE.md` 并提交，造成泄露。记住：**敏感的、个人的 → CLAUDE.local.md；规范的、团队的 → CLAUDE.md**。
### 第 5 层：子目录 memory（按需加载）
路径：`<某子目录>/CLAUDE.md`
Claude Code 不是启动时把所有子目录的 CLAUDE.md 全塞进上下文（那样太费 token），而是**当你读取该子目录下的文件时，才把对应的 CLAUDE.md 加载进来**。这适合大型 monorepo：
```
my-monorepo/
├── CLAUDE.md ← 整个仓库的总则
├── frontend/
│ └── CLAUDE.md ← 前端专属规则（React + Vite）
├── backend/
│ └── CLAUDE.md ← 后端专属规则（Go + Gin）
└── infra/
└── CLAUDE.md ← 运维专属规则（Terraform）
```
当你说「帮我改 frontend 的登录页」时，Claude 读取 `frontend/` 下文件，自动加载 `frontend/CLAUDE.md`，而不会加载 backend 的规则。这种**渐进式加载**是大仓库省 token 的关键。
---
## 三、用 @import 拆分大型 CLAUDE.md
当项目规则越积越多，单个 CLAUDE.md 会膨胀到几百行，既难维护也费 token。Claude Code 支持 `@import` 语法把规则拆成多个文件按需引用。
### 基本用法
在 CLAUDE.md 中用 `@路径` 引用其他文件：
```markdown
# 项目记忆
@docs/coding-standards.md
@docs/architecture.md
@docs/api-conventions.md
```
被引用的文件内容会被**递归展开**进主 CLAUDE.md。这意味着：
- `coding-standards.md` 里还可以再 `@` 引用别的文件
- 支持 glob 通配符：`@docs/rules/*.md` 一次性导入整个目录
- 内置**循环引用检测**，A 引用 B、B 引用 A 不会无限递归
### 实践：模块化记忆目录
推荐的大项目结构：
```
.claude/
├── CLAUDE.md ← 主入口，只放索引和 @import
└── rules/
├── frontend.md
├── backend.md
├── testing.md
└── deployment.md
```
主 `.claude/CLAUDE.md` 内容：
```markdown
# 项目记忆索引
本文件只做导航，详细规则见各模块。
@rules/frontend.md
@rules/backend.md
@rules/testing.md
@rules/deployment.md
```
**好处**：改前端规则只动 `frontend.md`，git diff 清晰；不相关的模块不会被同时加载，省 token。
---
## 四、两条快捷命令：/init 与 /memory
### /init：一键生成项目记忆
进入一个新项目，最省事的起步方式是运行：
```
/init
```
Claude 会**自动扫描你的代码库**——分析目录结构、识别技术栈、读取配置文件、归纳常用命令——然后生成一份初稿 `CLAUDE.md`。你只需在其基础上微调。
**操作流程**：
1. `cd` 进入项目根目录
2. 启动 `claude`
3. 输入 `/init`
4. Claude 输出草稿，询问是否写入 `CLAUDE.md`
5. 确认后，用编辑器打开精修
**预期结果**：你会得到一份覆盖技术栈、目录、命令的可用初稿，比从零手写快十倍。
### /memory：在会话内编辑记忆
不想退出 Claude 去开编辑器？直接输入：
```
/memory
```
它会用系统编辑器（`$EDITOR`）打开当前生效的 CLAUDE.md 文件。保存退出后，**修改立即在当前会话生效**，无需重启。
> **注意**：`/memory` 默认打开的是当前工作目录的 CLAUDE.md。要编辑用户级的，得手动 `vim ~/.claude/CLAUDE.md`。
---
## 五、Auto Memory：让 Claude 自己记笔记
这是较新的能力，也是最省心的。开启后，Claude 会在交互中**自动判断哪些信息值得跨会话记住**，并写入 `.claude/memory/` 目录。
### 它和 CLAUDE.md 的区别
| 维度 | CLAUDE.md | Auto memory |
|------|-----------|-------------|
| 谁写的 | 你 | Claude |
| 内容性质 | 规则、指令 | 事实、偏好、项目背景 |
| 可控性 | 完全可控，精确 | 自动积累，需偶尔清理 |
| 提交 git | 通常提交 | 看情况，个人偏好可不提交 |
### 工作机制
1. Claude 在对话中发现一条值得记住的事实（如「用户偏好用 Rust 写 CLI 工具」）。
2. 它把这条事实写入 `.claude/memory/.md`，文件带 frontmatter（name、description、type）。
3. 同时在 `.claude/memory/MEMORY.md` 索引里加一行指针。
4. 下次新会话启动，`MEMORY.md` 索引被加载进上下文，Claude「想起来」这些事实。
**触发方式**：你可以主动说「记住：我们项目的部署目标是 staging.cluster.local」，Claude 会显式保存；也会在正常对话中隐式积累。
### 记忆类型
Auto memory 通常分四类：
- **user**：用户是谁（角色、专长、偏好）
- **feedback**：用户给的工作方式反馈（含原因）
- **project**：进行中的工作、目标、约束
- **reference**：外部资源指针（URL、面板、工单号）
**维护建议**：每隔一段时间用 `/memory` 或直接查看 `.claude/memory/`，删掉过时或错误的记忆。Claude 写的记忆反映的是「写入时为真」的事实，代码变了之后它不会自动失效——所以**引用了具体文件名/函数的记忆，用前最好核对一下**。
---
## 六、settings.json：配置行为与权限
CLAUDE.md 管「Claude 该懂什么」，`settings.json` 管「Claude 该怎么行动」。两者分工不同，配合使用。
### 文件层级（同样从全局到局部）
| 文件 | 作用域 | 是否提交 git |
|------|--------|--------------|
| `~/.claude/settings.json` | 用户全局 | 否 |
| `.claude/settings.json` | 项目级，团队共享 | 是 |
| `.claude/settings.local.json` | 项目级，个人专属 | 否（gitignore） |
| 企业级 managed settings | 全机器强制 | 由 IT 部署 |
### /config：图形化配置
最简单的入口是在 Claude 会话里输入：
```
/config
```
它会打开一个分页的设置界面，用方向键就能改主题、模型、权限等，改完自动写回对应的 settings.json。**新手优先用这个，别手撸 JSON**。
### 手写示例：项目级权限
`.claude/settings.json` 一个典型场景是预设命令权限，减少反复确认：
```json
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff:*)",
"Read(**/*.md)"
],
"deny": [
"Bash(rm -rf:*)",
"Bash(git push:*)",
"Read(**/.env*)"
],
"ask": [
"Bash(git commit:*)"
]
},
"model": "claude-sonnet-4-6",
"env": {
"DEBUG": "true"
}
}
```
字段含义：
- **allow**：这些命令直接执行，不再询问。
- **deny**：永远禁止，Claude 连试都不会试。
- **ask**：每次执行前弹出确认（适合 `git commit` 这类不可逆操作）。
- **model**：指定默认模型。
- **env**：注入环境变量。
> **安全提示**：`deny` 里把 `rm -rf`、`git push`、读取 `.env` 都拦住，是低成本高收益的护栏。团队共享的 `.claude/settings.json` 里写好这套，所有人受益。
---
## 七、实战案例：为一个真实项目配齐记忆
以一个「TypeScript + Express + Prisma 的博客后端」为例，从零搭好完整记忆体系。
### 步骤 1：用户级偏好（一次性，跨项目）
```bash
cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人偏好
- 默认中文回复
- 修改前先读文件
- 不自动 commit，不自动建文档
- 包管理器：pnpm
- TypeScript：禁止 any，开启 strict
EOF
```
### 步骤 2：进入项目，跑 /init
```bash
cd ~/code/blog-api
claude
# 在会话内输入：
/init
```
Claude 扫描后生成初稿，你精修为 `.claude/CLAUDE.md`：
```markdown
# 博客后端 blog-api
## 技术栈
- Node.js 20 + TypeScript 5.4（strict 模式）
- Express 4 + Prisma 5（PostgreSQL 16）
- 测试：Vitest
- 部署：Docker
## 目录
- src/routes/ 路由
- src/services/ 业务逻辑
- src/prisma/ schema 与迁移
- tests/ 测试
## 规范
- 所有 handler 必须用 zod 校验入参
- 数据库访问只通过 service 层，禁止 route 直接调 Prisma
- 错误统一抛 AppError，由中间件格式化
@.claude/rules/testing.md
@.claude/rules/api.md
```
### 步骤 3：拆分规则文件
`.claude/rules/testing.md`：
```markdown
# 测试规则
- 每个 service 方法必须有对应单测
- 测试用 in-memory SQLite，不连真实 PG
- 命名：describe('方法名') + it('行为')
```
`.claude/rules/api.md`：
```markdown
# API 规范
- 路径：/api/v1/资源，复数
- 响应统一：{ code, message, data }
- 分页参数：page（从1）、pageSize
```
### 步骤 4：个人本地记忆
```bash
cat > .claude/CLAUDE.local.md << 'EOF'
# 本地（不提交）
- 本地 PG：postgresql://dev:dev@localhost:5432/blog
- 我在重构 /posts 路由，目标是去掉 any
EOF
echo ".claude/CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore
```
### 步骤 5：权限配置
`.claude/settings.json`：
```json
{
"permissions": {
"allow": ["Bash(pnpm test)", "Bash(pnpm run lint)", "Bash(prisma validate)"],
"deny": ["Bash(rm -rf:*)", "Read(**/.env*)"],
"ask": ["Bash(git commit:*)", "Bash(prisma migrate:*)"]
}
}
```
### 步骤 6：验证记忆生效
新开一个会话测试：
```
你：我们用什么数据库？测试怎么跑？
Claude：PostgreSQL 16（生产），测试用 in-memory SQLite。跑测试执行 pnpm test。
```
如果 Claude 答对了，说明记忆链路打通。如果答错（比如建议用 npm 而非 pnpm），检查对应层级的 CLAUDE.md 是否生效。
---
## 八、完整工作流程
```mermaid
flowchart LR
A["新会话启动
干净上下文"] --> B["加载企业/用户级
CLAUDE.md"]
B --> C["加载项目级
CLAUDE.md + @import 展开"]
C --> D["读取 MEMORY.md
auto memory 索引"]
D --> E["按需加载
子目录 CLAUDE.md"]
E --> F["应用 settings.json
权限与行为"]
F --> G["开始交互"]
G --> H{"发现新事实?"}
H -- 是 --> I["写入
.claude/memory/"]
H -- 否 --> J["正常工作"]
I --> J
style A fill:#fef3c7,stroke:#b45309
style G fill:#d1fae5,stroke:#047857
style I fill:#c7d2fe,stroke:#4338ca
```
---
## 九、常见问题排查
**Q1：改了 CLAUDE.md 不生效？**
用 `/memory` 编辑可即时生效；用外部编辑器改的，重启会话或运行 `/memory` 重新加载。注意确认改的是正确的层级——项目根的 CLAUDE.md 而非别处。
**Q2：记忆太多，每次启动都吃很多 token？**
- 把大段规则拆到子目录，靠「按需加载」而非全量加载。
- 用 `@import` 让无关模块不被同时展开。
- 清理过时的 auto memory。
**Q3：CLAUDE.md 该写多详细？**
写「会重复出现的、需要约束的」，不写「一次性的任务」。一次性任务直接在对话里说，别污染记忆。
**Q4：CLAUDE.local.md 误提交了怎么办？**
立即 `git rm --cached CLAUDE.local.md`，加入 `.gitignore`，并轮换其中暴露的任何密钥。
**Q5：auto memory 记错了怎么办？**
Claude 写的记忆是「写入时为真」的快照。直接编辑或删除 `.claude/memory/` 下对应文件即可纠正。
---
## 十、记忆配置清单（抄作业）
- [ ] `~/.claude/CLAUDE.md` 写好个人全局偏好（语言、工作习惯）
- [ ] 每个项目跑一次 `/init` 生成项目级 CLAUDE.md
- [ ] 把团队规范放进项目级 CLAUDE.md 并提交 git
- [ ] 个人/敏感信息只放 CLAUDE.local.md，加入 .gitignore
- [ ] 大项目用 `@import` + 子目录 CLAUDE.md 做模块化
- [ ] `.claude/settings.json` 配好 allow/deny/ask 权限护栏
- [ ] 定期清理 `.claude/memory/` 中过时的自动记忆
---
## 延伸阅读
- **Claude Code 官方文档 · 记忆**：`code.claude.com/docs/en/memory` — 权威的五层记忆与 auto memory 说明
- **Claude Code 官方文档 · 设置**：`code.claude.com/docs/en/settings` — settings.json 全字段参考
- **Anthropic 官方博客 · Using CLAUDE.md files**（2025-11-25）：实战写法与最佳实践
- **The Definitive Guide to Every Claude Code Configuration File**：把所有配置文件（CLAUDE.md / rules / skills / hooks / settings）的关系一次讲透
---
## 训练营适用性评估
- **适合类型**：零基础开发者训练营、企业内部 Claude Code 推广营、前端/后端工程师 AI 提效入门营
- **教学时长**：约 45–60 分钟讲授 + 30 分钟动手实操（含 /init 与权限配置练习）
- **难度**：⭐⭐（满分五星），无需编程基础，但要理解「层级」与「作用域」概念
- **前置**：已完成 Claude Code 安装与首次认证
- **后续衔接**：本教程完成后，自然过渡到「自定义 Skill 开发」「Hooks 质量门禁」「MCP 服务器」等进阶主题
---
## 参考来源
1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方记忆系统文档，CLAUDE.md 与 auto memory 双机制的权威来源
2. [Claude Code settings — Claude Code Docs](https://code.claude.com/docs/en/settings) — settings.json 全局/项目层级与权限配置官方参考
3. [Using CLAUDE.md files: Customizing Claude Code for your codebase — Anthropic Blog](https://claude.com/blog/using-claude-md-files) — 官方实战博客，讲解如何为代码库编写有效记忆文件
4. [The Definitive Guide to Every Claude Code Configuration File](https://wittmannf.github.io/blog/claude-code-config-guide/) — 第三方深度指南，梳理 CLAUDE.md / CLAUDE.local.md / rules / settings / auto memory 的分工
5. [The Complete .claude Directory Guide for Claude Code [2026]](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — 2026 年 .claude 目录结构与模块化 rules 的全景指南
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
