每个 Claude Code 会话都从全新的上下文窗口开始——上一轮对话里告诉它的技术栈、命令、规范，下次启动就忘得一干二净。本教程教你用 CLAUDE.md 记忆文件为 Claude Code 装上"项目长期记忆"，让它在任何会话都能秒懂你的项目。适合零基础用户，学完能独立完成记忆文件的创建、分层、导入与自动维护。
claude 命令可在终端运行）cd、编辑文本）很多初学者以为"记不住项目"是 bug，其实这是设计使然。Claude Code 官方文档明确指出：每个会话都从干净上下文开始，跨会话传递知识靠两套互补的机制：
| 机制 | 谁来写 | 作用 |
|---|---|---|
| CLAUDE.md 文件 | 你（开发者手动编写） | 持久的项目指令、规范、命令 |
| auto memory（自动记忆） | Claude 自己积累 | 会话中沉淀的经验与偏好 |
本教程聚焦第一套——你手写的 CLAUDE.md，这是入门阶段最重要、收益最高的一项配置。一个写得好的 CLAUDE.md，能让 Claude 从"通用助手"变成"懂你项目的工程师"。
核心理解：CLAUDE.md 不是配置文件（不是 JSON/YAML），它就是纯文本的 Markdown，里面写的是给 Claude 看的自然语言指令。Claude 在每次会话启动时自动读取它，作为系统级上下文注入。
Claude Code 会从多个位置按优先级加载记忆文件，理解这套层级是入门的关键：
用户记忆 ~/.claude/CLAUDE.md
- 位置：你的家目录下
- 作用：对你所有项目生效的全局偏好（如"默认用中文回复""commit 不要自动加版本号"）
- 特点：跨项目通用，适合放个人习惯
项目记忆 ./CLAUDE.md
- 位置：项目根目录
- 作用：对当前项目生效的团队共享规则
- 特点：应该提交到 git，团队成员共享
本地项目记忆 ./CLAUDE.local.md
- 位置：项目根目录
- 作用：你个人对当前项目的私有覆盖
- 特点：必须 gitignore，放本地密钥路径、个人测试账号等
此外还有子目录 CLAUDE.md（放在子文件夹里，Claude 进入该目录工作时会读取）和父目录向上查找（Claude 会沿目录树向上找父级 CLAUDE.md）。
一句话记忆口诀：用户级管全局，项目级管团队，本地级管个人。
/init 自动生成首个 CLAUDE.md进入你的项目目录，启动 Claude Code，输入斜杠命令：
cd ~/my-api-project
claude
在交互界面输入：
/init
Claude 会自动扫描你的代码库（读取 README、package.json、目录结构、关键源码），然后生成一份结构化的 CLAUDE.md 草稿，通常包含：
生成的草稿会让你确认后再写入磁盘。这是零成本起步的最佳方式——不需要从空白文件硬写。
/init 生成的命令是错的怎么办？
A：正常。自动推断有误差，生成后手动修正命令和版本号即可。/init 是起点不是终点。package.json 或 README.md，或直接跳过 /init，手动创建 CLAUDE.md。无论 /init 还是手建，一个高信号 CLAUDE.md 应包含四块核心内容。下面是 Anthropic 官方博客和社区指南反复强调的结构。
# 项目：订单管理 API
## 概览
这是一个面向电商后台的订单管理 REST API，采用领域驱动设计。
## 技术栈
- 语言：TypeScript 5.4（严格模式）
- 框架：Express 4 + Zod 校验
- 数据库：PostgreSQL 16 + Prisma ORM
- 测试：Vitest + Supertest
- 运行时：Node.js 20 LTS
这是 Claude 最常查的部分——它需要知道怎么验证自己写的代码：
## 命令
- `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` — 打开数据库可视化管理
## 编码规范
- 统一使用命名导出，禁止默认导出
- 所有 API 响应遵循 { code, data, message } 信封结构
- 业务逻辑放在 services/ 层，控制器只做参数校验与转发
- 数据库访问一律通过 Prisma，禁止裸 SQL
- 提交信息遵循 Conventional Commits（feat: / fix: / chore:）
这一块极其重要——告诉 Claude 边界在哪，比告诉它做什么更能防止事故：
## 禁止事项
- 绝不修改 prisma/migrations/ 下已应用的迁移文件，一律新增迁移
- 不要修改已发布的 API 响应字段结构（破坏性变更需先讨论）
- 不要在控制器里直接写业务逻辑
- 不要提交 .env 文件
- 禁止使用 any 类型
保存后，重启会话或输入 /memory 查看，Claude 在后续对话中会自觉遵守这些规则——比如生成代码时自动用命名导出、写完自觉运行 npm test。
# 和 /memory 快速追加记忆写 CLAUDE.md 不是一次性工程，项目在演进，记忆要持续追加。Claude Code 提供两种快捷方式，避免反复切到编辑器。
# 快速记忆在交互会话中，以 # 开头输入一行，Claude 会把它当作"待记忆内容"，并询问是否追加到 CLAUDE.md：
> # 新增订单时必须同时写入审计日志表 audit_log
Claude 会确认并自动插入。适合会话中冒出的"这条规则该记下来"的瞬间。
/memory 命令输入 /memory 会打开编辑器直接编辑记忆文件，适合批量调整。
记忆文件随项目成长，且无需离开 Claude Code 终端。
# 加的内容会不会重复堆积？
A：会。长期使用需定期用 /memory 整理去重，把零散条目归类合并。社区把这种维护叫"记忆压缩"。# 追加到了哪个文件？
A：默认追加到项目级 ./CLAUDE.md。全局偏好请手动放 ~/.claude/CLAUDE.md。当项目规则变多（前端规范、后端规范、API 文档、安全策略），单个 CLAUDE.md 会臃肿。Claude Code 支持 import 语法把规则拆成多个文件再引用。
在 CLAUDE.md 中用 @ 开头的行引入其他文件：
# 订单管理 API
@docs/coding-standards.md
@docs/api-conventions.md
@docs/security-policy.md
@~/.claude/shared-rules.md
@ 必须在行首CLAUDE.md 所在目录，也支持绝对路径和 ~ 家目录@ 引用，会继续解析主 CLAUDE.md 保持精简索引，详细规则分散在专门文档中，各团队按需维护自己的片段。
CLAUDE.md 一样应纳入版本控制，团队才能共享。这是与 CLAUDE.md 互补的第二套系统。开启后，Claude 会在会话中自动捕获值得记住的项目知识（例如"这个项目的测试数据库密码在 X""构建前必须先跑 Y 脚本"），并沉淀到自动记忆区，下次会话自动加载。
两者在会话启动时一起注入上下文。入门阶段先掌握 CLAUDE.md，待项目复杂后再逐步引入 auto memory。务必定期回顾 auto memory 的内容，剔除过时或错误的学习——自动记忆偶尔会沉淀噪音。
下面是一个可落地的完整示例。假设项目结构：
order-api/
├── src/
│ ├── controllers/
│ ├── services/
│ └── routes/
├── prisma/
│ └── migrations/
├── docs/
│ └── api-conventions.md
├── .gitignore
└── package.json
order-api/CLAUDE.md：
# 订单管理 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 类型
order-api/CLAUDE.local.md：
## 本地私有配置
- 测试数据库连接串在 ~/.secrets/order-api-test.env
- 我的本地测试账号：tester@local / test1234
- 用 pnpm 而非 npm（仅本地偏好）
并确保 .gitignore 包含：
CLAUDE.local.md
.env
~/.claude/CLAUDE.md（对所有项目生效）：
## 全局偏好
- 默认用中文回复，代码注释可用英文
- 不要自动 git commit，仅在明确要求时执行
- 不要自动 git add，只提交我已暂存的文件
- 始终先读取文件再编辑
重启 claude 会话，问它："这个项目怎么跑测试？数据库迁移怎么做？" 它会直接答出 npm test 和 npx prisma migrate dev，而无需你解释——这就是记忆文件的价值。
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 且已提交 gitCLAUDE.local.md 并已 gitignore@import 拆分，避免单文件臃肿/memory 整理去重，压缩历史条目code.claude.com/docs/en/memory —— CLAUDE.md 与 auto memory 双系统的权威说明claude.com/blog/using-claude-md-files —— Anthropic 工程团队的实战配置指南github.com/centminmod/my-claude-code-setup —— 一个可直接 fork 的 CLAUDE.md 记忆库模板/config、权限模式（plan / accept-edits）与 hooks，把记忆系统与自动化行为结合| 维度 | 评估 |
|---|---|
| 适合训练营类型 | AI 编程入门营、企业 AI 工具落地营、团队提效工作坊 |
| 学员基础 | 零基础可学，会终端和文本编辑即可 |
| 教学时长 | 讲授 + 实操约 1.5–2 小时（含动手为自己的项目配置记忆） |
| 可考核成果 | 学员产出一份可提交 git 的项目 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 等场景全覆盖。