本教程面向零基础用户，系统讲解 Claude Code 的「项目记忆」机制。你将学会用 CLAUDE.md 文件给 Claude 持久化的项目指令，理解从企业级到本地的五层记忆层级，掌握 @import 文件导入、/init 自动生成、auto memory 自动学习三大核心能力，并配齐 settings.json 权限配置。学完后你能让 Claude 在每次新会话中「秒懂」你的代码规范、技术栈与个人偏好，而无需每次重复交代。适合刚装好 Claude Code、想从「能用」进阶到「好用」的所有开发者。
cd、cat、文本编辑器）Claude Code 的一个根本设计是：每一个会话都从一个干净的上下文窗口开始。这意味着你昨晚告诉它「我们用 pnpm、用 ESLint、禁止 any 类型」的所有交代，今天新开会话时全部归零。
如果没有记忆机制，你会陷入两种痛苦：
print 调试、给团队仓库擅自加分号。Claude Code 用两套互补的记忆系统解决这个问题：
| 系统 | 谁来写 | 存放位置 | 特点 |
|---|---|---|---|
| CLAUDE.md 文件 | 你（开发者） | 仓库内 / 用户目录 | 显式指令，精确可控，可提交到 git |
| Auto memory（自动记忆） | Claude 自己 | .claude/memory/ |
自动积累，跨会话学习，无需你操心 |
理解这两套系统的分工，是配置好记忆的第一步。CLAUDE.md 管「规则」，auto memory 管「事实」。
这是最容易让新手困惑的部分：到底把规则写在哪里？答案取决于「这条规则的适用范围」。Claude Code 定义了从最全局到最局部的层级，启动时按顺序加载，越局部的优先级越高。
flowchart TD
A["1. 企业策略 memory<br/>由 IT 统一下发<br/>最高优先级"] --> B["2. 用户级 memory<br/>~/.claude/CLAUDE.md<br/>跨所有项目"]
B --> C["3. 项目级 memory<br/>./CLAUDE.md<br/>提交到 git，团队共享"]
C --> D["4. 项目本地 memory<br/>./CLAUDE.local.md<br/>gitignore，个人专属"]
D --> E["5. 子目录 memory<br/>子目录/CLAUDE.md<br/>按需加载相关文件时生效"]
E --> F["6. Auto memory<br/>.claude/memory/<br/>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
下面逐层拆解。
由公司 IT 部门通过系统级路径统一部署，例如 macOS 上的 /Library/Application Support/ClaudeCode/CLAUDE.md。它的指令优先级最高，通常用于强制合规要求（如「禁止将代码上传到外部服务」）。如果你是个人开发者，跳过这一层即可。
路径：~/.claude/CLAUDE.md
这是你的个人全局偏好，对你机器上的所有项目生效。适合放那些「不管在哪个项目，我都是这么干活」的规则。
创建它：
# 在 home 目录的 .claude 下创建
cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人全局偏好
## 语言
- 默认用中文回复，代码注释可用英文
- 命名用中文标题，命令保持原文
## 工作习惯
- 修改代码前先读取目标文件，不要盲改
- 不要自动 git commit，只在明确要求时提交
- 不要主动创建文档文件，除非明确要求
- 回复简洁，避免冗长解释
## 技术偏好
- 包管理器优先用 pnpm，其次 npm
- TypeScript 项目禁止使用 any 类型
- 优先函数式风格，避免不必要的 class
EOF
预期结果：之后你打开任何项目，Claude 默认就讲中文、不乱 commit、不乱建 README。这一层价值极高，因为它消除了一类最高频的「重复交代」。
路径：<项目根目录>/CLAUDE.md
这是最重要的记忆文件，提交到 git 后整个团队共享。它告诉 Claude「这个项目长什么样」。一个典型的项目级 CLAUDE.md 应包含：
# 项目：订单中台（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 区别于个人笔记的关键——它是可版本控制的团队知识。
路径：<项目根目录>/CLAUDE.local.md
它的内容只对你自己生效，应当加入 .gitignore。适合放个人化的、不想污染团队仓库的东西：
# 本地个人偏好（不提交）
- 我在排查 #2331 这个 bug，重点关注订单状态机
- 本地数据库连接：root:123456@tcp(localhost:3306)/order
- 我习惯用 vim，生成的代码注释别用 IDE 特定格式
.gitignore 中务必加上：
CLAUDE.local.md
常见坑：很多人把敏感信息（数据库密码、token）写进了第 3 层 CLAUDE.md 并提交，造成泄露。记住：敏感的、个人的 → CLAUDE.local.md；规范的、团队的 → CLAUDE.md。
路径：<某子目录>/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 的关键。
当项目规则越积越多，单个 CLAUDE.md 会膨胀到几百行，既难维护也费 token。Claude Code 支持 @import 语法把规则拆成多个文件按需引用。
在 CLAUDE.md 中用 @路径 引用其他文件：
# 项目记忆
@docs/coding-standards.md
@docs/architecture.md
@docs/api-conventions.md
被引用的文件内容会被递归展开进主 CLAUDE.md。这意味着：
coding-standards.md 里还可以再 @ 引用别的文件@docs/rules/*.md 一次性导入整个目录推荐的大项目结构：
.claude/
├── CLAUDE.md ← 主入口，只放索引和 @import
└── rules/
├── frontend.md
├── backend.md
├── testing.md
└── deployment.md
主 .claude/CLAUDE.md 内容：
# 项目记忆索引
本文件只做导航，详细规则见各模块。
@rules/frontend.md
@rules/backend.md
@rules/testing.md
@rules/deployment.md
好处：改前端规则只动 frontend.md，git diff 清晰；不相关的模块不会被同时加载，省 token。
进入一个新项目，最省事的起步方式是运行：
/init
Claude 会自动扫描你的代码库——分析目录结构、识别技术栈、读取配置文件、归纳常用命令——然后生成一份初稿 CLAUDE.md。你只需在其基础上微调。
操作流程：
cd 进入项目根目录claude/initCLAUDE.md预期结果：你会得到一份覆盖技术栈、目录、命令的可用初稿，比从零手写快十倍。
不想退出 Claude 去开编辑器？直接输入：
/memory
它会用系统编辑器（$EDITOR）打开当前生效的 CLAUDE.md 文件。保存退出后，修改立即在当前会话生效，无需重启。
注意：
/memory默认打开的是当前工作目录的 CLAUDE.md。要编辑用户级的，得手动vim ~/.claude/CLAUDE.md。
这是较新的能力，也是最省心的。开启后，Claude 会在交互中自动判断哪些信息值得跨会话记住，并写入 .claude/memory/ 目录。
| 维度 | CLAUDE.md | Auto memory |
|---|---|---|
| 谁写的 | 你 | Claude |
| 内容性质 | 规则、指令 | 事实、偏好、项目背景 |
| 可控性 | 完全可控，精确 | 自动积累，需偶尔清理 |
| 提交 git | 通常提交 | 看情况，个人偏好可不提交 |
.claude/memory/<slug>.md，文件带 frontmatter（name、description、type）。.claude/memory/MEMORY.md 索引里加一行指针。MEMORY.md 索引被加载进上下文，Claude「想起来」这些事实。触发方式：你可以主动说「记住：我们项目的部署目标是 staging.cluster.local」，Claude 会显式保存；也会在正常对话中隐式积累。
Auto memory 通常分四类：
维护建议：每隔一段时间用 /memory 或直接查看 .claude/memory/，删掉过时或错误的记忆。Claude 写的记忆反映的是「写入时为真」的事实，代码变了之后它不会自动失效——所以引用了具体文件名/函数的记忆，用前最好核对一下。
CLAUDE.md 管「Claude 该懂什么」，settings.json 管「Claude 该怎么行动」。两者分工不同，配合使用。
| 文件 | 作用域 | 是否提交 git |
|---|---|---|
~/.claude/settings.json |
用户全局 | 否 |
.claude/settings.json |
项目级，团队共享 | 是 |
.claude/settings.local.json |
项目级，个人专属 | 否（gitignore） |
| 企业级 managed settings | 全机器强制 | 由 IT 部署 |
最简单的入口是在 Claude 会话里输入：
/config
它会打开一个分页的设置界面，用方向键就能改主题、模型、权限等，改完自动写回对应的 settings.json。新手优先用这个，别手撸 JSON。
.claude/settings.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"
}
}
字段含义：
git commit 这类不可逆操作）。安全提示：
deny里把rm -rf、git push、读取.env都拦住，是低成本高收益的护栏。团队共享的.claude/settings.json里写好这套，所有人受益。
以一个「TypeScript + Express + Prisma 的博客后端」为例，从零搭好完整记忆体系。
cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人偏好
- 默认中文回复
- 修改前先读文件
- 不自动 commit，不自动建文档
- 包管理器：pnpm
- TypeScript：禁止 any，开启 strict
EOF
cd ~/code/blog-api
claude
# 在会话内输入：
/init
Claude 扫描后生成初稿，你精修为 .claude/CLAUDE.md：
# 博客后端 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
.claude/rules/testing.md：
# 测试规则
- 每个 service 方法必须有对应单测
- 测试用 in-memory SQLite，不连真实 PG
- 命名：describe('方法名') + it('行为')
.claude/rules/api.md：
# API 规范
- 路径：/api/v1/资源，复数
- 响应统一：{ code, message, data }
- 分页参数：page（从1）、pageSize
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
.claude/settings.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:*)"]
}
}
新开一个会话测试：
你：我们用什么数据库？测试怎么跑？
Claude：PostgreSQL 16（生产），测试用 in-memory SQLite。跑测试执行 pnpm test。
如果 Claude 答对了，说明记忆链路打通。如果答错（比如建议用 npm 而非 pnpm），检查对应层级的 CLAUDE.md 是否生效。
flowchart LR
A["新会话启动<br/>干净上下文"] --> B["加载企业/用户级<br/>CLAUDE.md"]
B --> C["加载项目级<br/>CLAUDE.md + @import 展开"]
C --> D["读取 MEMORY.md<br/>auto memory 索引"]
D --> E["按需加载<br/>子目录 CLAUDE.md"]
E --> F["应用 settings.json<br/>权限与行为"]
F --> G["开始交互"]
G --> H{"发现新事实?"}
H -- 是 --> I["写入<br/>.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@import + 子目录 CLAUDE.md 做模块化.claude/settings.json 配好 allow/deny/ask 权限护栏.claude/memory/ 中过时的自动记忆code.claude.com/docs/en/memory — 权威的五层记忆与 auto memory 说明code.claude.com/docs/en/settings — settings.json 全字段参考[!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 等场景全覆盖。