<!-- title: 用CLAUDE.md打造项目专属记忆 -->

# 用 CLAUDE.md 打造项目专属记忆：Claude Code 入门配置实战

## 概述

每个 Claude Code 会话都从**全新的上下文窗口**开始——上一轮对话里告诉它的技术栈、命令、规范，下次启动就忘得一干二净。本教程教你用 `CLAUDE.md` 记忆文件为 Claude Code 装上"项目长期记忆"，让它在任何会话都能秒懂你的项目。适合零基础用户，学完能独立完成记忆文件的创建、分层、导入与自动维护。

## 前置条件

- 已安装 Claude Code（`claude` 命令可在终端运行）
- 有一个可进入的项目目录（任意语言，本文以 Node.js 为例）
- 会基本的终端操作（`cd`、编辑文本）
- 一个代码编辑器（VS Code 或任何文本编辑器均可）

---

## 一、先理解：Claude Code 有两套记忆系统

很多初学者以为"记不住项目"是 bug，其实这是设计使然。Claude Code 官方文档明确指出：**每个会话都从干净上下文开始**，跨会话传递知识靠两套互补的机制：

| 机制 | 谁来写 | 作用 |
|------|--------|------|
| **CLAUDE.md 文件** | **你**（开发者手动编写） | 持久的项目指令、规范、命令 |
| **auto memory（自动记忆）** | **Claude 自己**积累 | 会话中沉淀的经验与偏好 |

本教程聚焦第一套——**你手写的 CLAUDE.md**，这是入门阶段最重要、收益最高的一项配置。一个写得好的 `CLAUDE.md`，能让 Claude 从"通用助手"变成"懂你项目的工程师"。

**核心理解**：`CLAUDE.md` 不是配置文件（不是 JSON/YAML），它就是**纯文本的 Markdown**，里面写的是给 Claude 看的自然语言指令。Claude 在每次会话启动时自动读取它，作为系统级上下文注入。

---

## 二、记忆层级：三套文件各管什么

Claude Code 会从**多个位置**按优先级加载记忆文件，理解这套层级是入门的关键：

1. **用户记忆** `~/.claude/CLAUDE.md`
   - 位置：你的家目录下
   - 作用：对你**所有项目**生效的全局偏好（如"默认用中文回复""commit 不要自动加版本号"）
   - 特点：跨项目通用，适合放个人习惯

2. **项目记忆** `./CLAUDE.md`
   - 位置：项目根目录
   - 作用：对**当前项目**生效的团队共享规则
   - 特点：**应该提交到 git**，团队成员共享

3. **本地项目记忆** `./CLAUDE.local.md`
   - 位置：项目根目录
   - 作用：你**个人**对当前项目的私有覆盖
   - 特点：**必须 gitignore**，放本地密钥路径、个人测试账号等

此外还有**子目录 CLAUDE.md**（放在子文件夹里，Claude 进入该目录工作时会读取）和**父目录向上查找**（Claude 会沿目录树向上找父级 CLAUDE.md）。

**一句话记忆口诀**：用户级管全局，项目级管团队，本地级管个人。

---

## 三、第一步：用 `/init` 自动生成首个 CLAUDE.md

### 操作说明

进入你的项目目录，启动 Claude Code，输入斜杠命令：

```bash
cd ~/my-api-project
claude
```

在交互界面输入：

```
/init
```

### 预期结果

Claude 会自动**扫描你的代码库**（读取 README、package.json、目录结构、关键源码），然后生成一份结构化的 `CLAUDE.md` 草稿，通常包含：

- 项目概述（它推断出的项目用途）
- 技术栈（语言、框架、数据库）
- 构建与测试命令（从 package.json 等推断）
- 目录结构说明

生成的草稿会让你确认后再写入磁盘。这是**零成本起步**的最佳方式——不需要从空白文件硬写。

### 常见问题

- **Q：`/init` 生成的命令是错的怎么办？**
  A：正常。自动推断有误差，生成后**手动修正**命令和版本号即可。`/init` 是起点不是终点。
- **Q：提示"未找到项目特征"？**
  A：可能目录太空或没有标准配置文件。先放一个 `package.json` 或 `README.md`，或直接跳过 `/init`，手动创建 `CLAUDE.md`。

---

## 四、第二步：手写核心四块内容

无论 `/init` 还是手建，一个高信号 `CLAUDE.md` 应包含**四块核心内容**。下面是 Anthropic 官方博客和社区指南反复强调的结构。

### 4.1 项目概览与技术栈

```markdown
# 项目：订单管理 API

## 概览
这是一个面向电商后台的订单管理 REST API，采用领域驱动设计。

## 技术栈
- 语言：TypeScript 5.4（严格模式）
- 框架：Express 4 + Zod 校验
- 数据库：PostgreSQL 16 + Prisma ORM
- 测试：Vitest + Supertest
- 运行时：Node.js 20 LTS
```

### 4.2 构建 / 测试 / 运行命令

这是 Claude 最常查的部分——它需要知道怎么验证自己写的代码：

```markdown
## 命令
- `npm run dev` — 启动开发服务器（热重载，端口 3000）
- `npm test` — 运行全部单元测试
- `npm run test:integration` — 运行集成测试（需启动测试数据库）
- `npm run lint` — ESLint 检查
- `npm run build` — 生产构建到 dist/
- `npx prisma migrate dev` — 数据库迁移（开发环境）
- `npx prisma studio` — 打开数据库可视化管理
```

### 4.3 编码规范

```markdown
## 编码规范
- 统一使用命名导出，禁止默认导出
- 所有 API 响应遵循 { code, data, message } 信封结构
- 业务逻辑放在 services/ 层，控制器只做参数校验与转发
- 数据库访问一律通过 Prisma，禁止裸 SQL
- 提交信息遵循 Conventional Commits（feat: / fix: / chore:）
```

### 4.4 不要做的事（红线）

**这一块极其重要**——告诉 Claude 边界在哪，比告诉它做什么更能防止事故：

```markdown
## 禁止事项
- 绝不修改 prisma/migrations/ 下已应用的迁移文件，一律新增迁移
- 不要修改已发布的 API 响应字段结构（破坏性变更需先讨论）
- 不要在控制器里直接写业务逻辑
- 不要提交 .env 文件
- 禁止使用 any 类型
```

### 预期结果

保存后，重启会话或输入 `/memory` 查看，Claude 在后续对话中会自觉遵守这些规则——比如生成代码时自动用命名导出、写完自觉运行 `npm test`。

### 常见问题

- **Q：CLAUDE.md 写多长合适？**
  A：**宁可精炼，不要冗长**。官方和社区共识是聚焦"非显而易见、项目特有"的规则。几百字的精准文件，效果远胜几千字的流水账。冗长文件反而稀释关键指令。
- **Q：通用编程常识要不要写？**
  A：不要。Claude 已知"函数命名用驼峰"这类常识，写了浪费上下文。只写**项目特有**的约定。

---

## 五、第三步：用 `#` 和 `/memory` 快速追加记忆

写 `CLAUDE.md` 不是一次性工程，项目在演进，记忆要持续追加。Claude Code 提供两种快捷方式，避免反复切到编辑器。

### 方式一：`#` 快速记忆

在交互会话中，**以 `#` 开头输入一行**，Claude 会把它当作"待记忆内容"，并询问是否追加到 `CLAUDE.md`：

```
> # 新增订单时必须同时写入审计日志表 audit_log
```

Claude 会确认并自动插入。适合会话中冒出的"这条规则该记下来"的瞬间。

### 方式二：`/memory` 命令

输入 `/memory` 会打开编辑器直接编辑记忆文件，适合批量调整。

### 预期结果

记忆文件随项目成长，且无需离开 Claude Code 终端。

### 常见问题

- **Q：用 `#` 加的内容会不会重复堆积？**
  A：会。长期使用需定期**用 `/memory` 整理去重**，把零散条目归类合并。社区把这种维护叫"记忆压缩"。
- **Q：`#` 追加到了哪个文件？**
  A：默认追加到项目级 `./CLAUDE.md`。全局偏好请手动放 `~/.claude/CLAUDE.md`。

---

## 六、第四步：import 语法拆分大型规则

当项目规则变多（前端规范、后端规范、API 文档、安全策略），单个 `CLAUDE.md` 会臃肿。Claude Code 支持 **import 语法**把规则拆成多个文件再引用。

### 操作说明

在 `CLAUDE.md` 中用 `@` 开头的行引入其他文件：

```markdown
# 订单管理 API

@docs/coding-standards.md
@docs/api-conventions.md
@docs/security-policy.md
@~/.claude/shared-rules.md
```

### 关键规则

- `@` 必须在**行首**
- 路径相对当前 `CLAUDE.md` 所在目录，也支持绝对路径和 `~` 家目录
- **支持递归**：被导入的文件里若也有 `@` 引用，会继续解析
- 适合把团队规范文档（往往已存在）直接复用，不必复制粘贴

### 预期结果

主 `CLAUDE.md` 保持精简索引，详细规则分散在专门文档中，各团队按需维护自己的片段。

### 常见问题

- **Q：import 的文件也要提交 git 吗？**
  A：是的，被 import 的规则文件和主 `CLAUDE.md` 一样应纳入版本控制，团队才能共享。
- **Q：循环 import 会死循环吗？**
  A：Claude Code 有递归深度保护，但建议保持 import 关系为**树形结构**（DAG），避免循环引用造成混乱。

---

## 七、auto memory：让 Claude 自动学习

这是与 `CLAUDE.md` 互补的第二套系统。开启后，Claude 会在会话中**自动捕获**值得记住的项目知识（例如"这个项目的测试数据库密码在 X""构建前必须先跑 Y 脚本"），并沉淀到自动记忆区，下次会话自动加载。

- **CLAUDE.md** = 你主动写的**显式指令**
- **auto memory** = Claude 被动积累的**隐式经验**

两者在会话启动时一起注入上下文。入门阶段先掌握 `CLAUDE.md`，待项目复杂后再逐步引入 auto memory。务必**定期回顾** auto memory 的内容，剔除过时或错误的学习——自动记忆偶尔会沉淀噪音。

---

## 八、实战案例：为 Express API 项目完整配置记忆

下面是一个可落地的完整示例。假设项目结构：

```
order-api/
├── src/
│   ├── controllers/
│   ├── services/
│   └── routes/
├── prisma/
│   └── migrations/
├── docs/
│   └── api-conventions.md
├── .gitignore
└── package.json
```

### 步骤 1：创建项目级记忆（提交 git）

`order-api/CLAUDE.md`：

```markdown
# 订单管理 API

## 概览
电商后台订单 REST API，领域驱动分层架构。

## 技术栈
- TypeScript 5.4 + Express 4 + Zod
- PostgreSQL 16 + Prisma ORM
- Vitest + Supertest 测试

## 命令
- `npm run dev` — 开发服务器（端口 3000）
- `npm test` — 全部单元测试
- `npm run test:integration` — 集成测试
- `npm run lint` — ESLint
- `npx prisma migrate dev` — 数据库迁移

## 规范
- 命名导出，禁止默认导出
- 响应信封：{ code, data, message }
- 业务逻辑在 services/，控制器只做校验和转发
- 数据库访问一律走 Prisma

@api-conventions.md

## 禁止事项
- 绝不修改已应用的 prisma 迁移，一律新增
- 不改已发布 API 字段结构
- 不提交 .env，禁止 any 类型
```

### 步骤 2：创建本地私有记忆（gitignore）

`order-api/CLAUDE.local.md`：

```markdown
## 本地私有配置
- 测试数据库连接串在 ~/.secrets/order-api-test.env
- 我的本地测试账号：tester@local / test1234
- 用 pnpm 而非 npm（仅本地偏好）
```

并确保 `.gitignore` 包含：

```
CLAUDE.local.md
.env
```

### 步骤 3：创建全局用户记忆

`~/.claude/CLAUDE.md`（对所有项目生效）：

```markdown
## 全局偏好
- 默认用中文回复，代码注释可用英文
- 不要自动 git commit，仅在明确要求时执行
- 不要自动 git add，只提交我已暂存的文件
- 始终先读取文件再编辑
```

### 验证效果

重启 `claude` 会话，问它："这个项目怎么跑测试？数据库迁移怎么做？" 它会直接答出 `npm test` 和 `npx prisma migrate dev`，而无需你解释——这就是记忆文件的价值。

---

## 工作流程图

```text
flowchart TD
    A[启动 Claude Code 会话] --> B[加载记忆上下文]
    B --> C{记忆从哪来}
    C --> D[~/.claude/CLAUDE.md<br/>用户全局记忆]
    C --> E[./CLAUDE.md<br/>项目团队记忆]
    C --> F[./CLAUDE.local.md<br/>本地私有记忆]
    C --> G[子目录/父目录 CLAUDE.md]
    C --> H[auto memory<br/>自动积累的学习]
    D --> I[合并注入会话上下文]
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J[Claude 带着项目记忆工作]
    J --> K{需要更新记忆?}
    K -->|# 快速追加| L[追加到 CLAUDE.md]
    K -->[/memory 编辑| M[整理/去重记忆文件]
    L --> N[下次会话自动生效]
    M --> N
```

---

## CLAUDE.md 维护检查清单

把以下要点当作入门后的日常自检：

- [ ] 项目根有 `CLAUDE.md` 且已提交 git
- [ ] 个人私有内容放进了 `CLAUDE.local.md` 并已 gitignore
- [ ] 命令块准确（构建、测试、迁移命令真实可跑）
- [ ] 包含"禁止事项"红线，约束边界清晰
- [ ] 没有堆砌通用编程常识，聚焦项目特有规则
- [ ] 规则变多时用 `@import` 拆分，避免单文件臃肿
- [ ] 定期用 `/memory` 整理去重，压缩历史条目
- [ ] 回顾 auto memory，剔除过时的自动学习

---

## 延伸阅读

- **Anthropic 官方记忆文档**：`code.claude.com/docs/en/memory` —— CLAUDE.md 与 auto memory 双系统的权威说明
- **Using CLAUDE.md files 官方博客**：`claude.com/blog/using-claude-md-files` —— Anthropic 工程团队的实战配置指南
- **centminmod/my-claude-code-setup（GitHub）**：`github.com/centminmod/my-claude-code-setup` —— 一个可直接 fork 的 CLAUDE.md 记忆库模板
- 继续深入学习 `/config`、权限模式（plan / accept-edits）与 hooks，把记忆系统与自动化行为结合

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 编程入门营、企业 AI 工具落地营、团队提效工作坊 |
| **学员基础** | 零基础可学，会终端和文本编辑即可 |
| **教学时长** | 讲授 + 实操约 **1.5–2 小时**（含动手为自己的项目配置记忆） |
| **可考核成果** | 学员产出一份可提交 git 的项目 CLAUDE.md，并通过会话验证生效 |
| **难度** | ★★☆☆☆（概念简单，难点在"写什么、不写什么"的取舍判断） |

## 参考来源

1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方文档，定义 CLAUDE.md 与 auto memory 双记忆系统及加载机制
2. [Using CLAUDE.md files: Customizing Claude Code for your codebase — Anthropic Blog](https://claude.com/blog/using-claude-md-files) — 官方实践指南，CLAUDE.md 写什么、怎么分层
3. [The CLAUDE.md Memory System Tutorial — SFEIR Institute](https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/tutorial/) — 面向入门者的分步配置教程
4. [CLAUDE.md & Memory Management: The Complete Guide (2026) — ProductBuilder](https://www.productbuilder.net/learn/claude-code-memory) — 记忆文件结构、规则与配置的完整指南
5. [centminmod/my-claude-code-setup — GitHub](https://github.com/centminmod/my-claude-code-setup) — 可直接复用的 CLAUDE.md 记忆库与配置模板代码仓库

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)