首页 › tutorials › Claude Code记忆入门：CLAUDE.md让AI秒懂项目

适用人群：刚装好 Claude Code、却每次开新会话都要重新解释"我们用 Fastify 不是 Express"的开发者。学习目标：理解 Claude Code 的记忆机制，写出第一份高质量的 CLAUDE.md，并掌握四层记忆层级与 /init、/memory 两大命令。预计学习时长 45 分钟，跟着做完即可拥有一个"秒懂你项目"的 AI 结对伙伴。

一、前置条件

二、痛点：你的 AI 怎么总在"失忆"

假设你刚把一位新同事拉进项目，让他"加一个用户登录接口"。如果他什么背景都不知道，多半会写出你们项目里格格不入的代码——比如用了错误的框架、错误的文件后缀、错误的目录。

Claude Code 默认就是这样一位"失忆同事"。每一个 Claude Code 会话都以一个全新的、空白的上下文窗口开始：上一次会话里你反复强调的"我们用 Fastify 不用 Express"、"所有文件必须是 TypeScript"、"接口放在 src/api/v2/ 下"——全部消失。

结果就是：每次开新会话，你都得把同一套项目约定、技术栈、代码风格重新口述一遍。这件事每天都在重复，是 Claude Code 使用体验里最普遍的磨损点。

好消息是：Claude Code 内置了一整套记忆系统（memory system），专门用来消除这种摩擦。它的核心载体，就是一个名叫 CLAUDE.md 的纯文本文件。本文就带你从零搭好它。

三、理解记忆机制：两条腿走路

在动手之前，先建立正确的认知模型。Claude Code 跨会话保留知识，靠的是两种互补机制：

  1. CLAUDE.md 文件——你主动写的指令。这是你写给 Claude 的"项目说明书"，明文 Markdown，每次会话启动时被注入到上下文里。
  2. Auto Memory（自动记忆）——Claude 自己积累的学习。当你在对话里说出"# 记住我们用 pnpm 而不是 npm"这类话，Claude 会判断是否值得长期记住，并自动追加到记忆文件里。

一句话总结：CLAUDE.md 是你喂给它的，auto memory 是它自己悟出来的。两者都在会话开始时被加载，共同构成 Claude 对你和项目的"长期记忆"。

下面这张图展示了从会话启动到 Claude"想起一切"的完整流程：

flowchart TD
    A[启动 claude 会话] --> B[读取四层 CLAUDE.md]
    B --> C1[企业级 /etc/claude-code]
    B --> C2[用户级 ~/.claude/CLAUDE.md]
    B --> C3[项目级 ./CLAUDE.md]
    B --> C4[本地级 ./CLAUDE.local.md]
    B --> C5[规则目录 .claude/rules/*.md]
    C1 & C2 & C3 & C4 & C5 --> D[合并注入会话上下文]
    D --> E[叠加 auto memory]
    E --> F[Claude 带着完整记忆开始工作]
    G[/init 自动生成] -.-> C3
    H[/memory 查看加载情况] -.-> D

四、四层记忆层级：谁覆盖谁

Claude Code 的配置采用作用域（scope）系统，CLAUDE.md 一共有四个层级，优先级从高到低依次为：

层级 文件位置 用途 是否提交 Git
Enterprise 企业级 系统级策略目录 全公司强制规范（如禁止外发密钥） 由 IT 管理
User 用户级 ~/.claude/CLAUDE.md 你个人的跨项目偏好（如"始终用中文回复"） —
Project 项目级 项目根 CLAUDE.md 团队共享的项目约定 ✅ 提交，团队共享
Local 本地级 项目根 CLAUDE.local.md 你的本地私有偏好 ❌ 加入 .gitignore

理解这四层的关键，在于分清"团队共享"和"个人私有"：

优先级规则：当多层之间出现冲突时，更具体的层级（local > project > user > enterprise）通常以更贴近的方式叠加，但企业级策略具有最高约束力。实践中应避免在多层里写相互矛盾的指令。

五、步骤一：用 /init 一键生成首份记忆

最快的入门方式是让 Claude 自己读你的代码库，然后替你写 CLAUDE.md。

操作：在你的项目根目录下启动 Claude Code，输入：

/init

Claude 会做什么：它会扫描目录结构、识别技术栈（package.json、go.mod、Cargo.toml 等）、查看构建脚本和测试命令，然后生成一份初稿 CLAUDE.md，并询问你是否接受。

预期结果：项目根目录出现一个 CLAUDE.md，大致长这样：

# 项目：my-api

## 技术栈
- Runtime: Node.js 20
- 语言: TypeScript 5.x（strict 模式）
- Web 框架: Fastify 4
- 包管理: pnpm

## 常用命令
- 安装依赖: `pnpm install`
- 开发服务器: `pnpm dev`
- 运行测试: `pnpm test`
- 单文件测试: `pnpm test path/to/file.test.ts`
- 代码检查: `pnpm lint`
- 构建: `pnpm build`

## 代码风格
- 使用 ESM 导入
- 函数式风格优先，避免 class
- ...

这一步的意义：你拿到了一个真实、可用的起点，而不是面对空白文件无从下笔。后续所有优化都在这份初稿上做加法。

六、步骤二：手写一份高质量的 CLAUDE.md

/init 的初稿只是及格线。真正让 Claude"秒懂"的，是你针对项目特性补充的那些约定和陷阱。下面是一个可以直接套用的模板，逐段说明该写什么：

# 项目说明：my-api

## 项目目标
一句话说清这是做什么的：面向 B 端的多租户 SaaS 后端，
核心域是订单与计费。

## 技术栈（必须遵守）
- 语言: TypeScript，strict 模式，禁用 any
- 框架: Fastify 4（不要用 Express！）
- ORM: Drizzle
- 测试: Vitest
- 包管理: pnpm（禁止使用 npm/yarn）

## 目录约定（写新代码时遵守）
- 路由处理器: src/api/v2/*.ts
- 业务逻辑: src/services/*.ts
- 数据访问: src/repositories/*.ts
- 不要在 src/api/ 里直接写 SQL

## 代码风格
- 优先函数式风格，避免 class
- 错误用 Result<T, E> 模式返回，不抛异常跨层
- 所有公开函数写 JSDoc

## 构建与测试命令
- 安装: pnpm install
- 开发: pnpm dev
- 全量测试: pnpm test
- 单文件测试: pnpm test src/services/order.test.ts
- 检查: pnpm lint && pnpm typecheck

## 已知陷阱（务必注意）
- 时区统一用 UTC 存储，展示时再转
- 金额用整数分表示，绝不用浮点
- env 读取必须通过 src/config.ts 的 schema 校验

## Git 约定
- 提交信息遵循 Conventional Commits
- 不要自动 commit，等用户明确指示

写好它的三条心法：

  1. 写"不该做什么"比写"该做什么"更值钱。一句"不要用 Express"能省掉无数次错误重生成。
  2. 写可执行的命令，而不是描述。pnpm test path/to/file 比"运行测试"有用得多——Claude 能直接复制粘贴执行。
  3. 保持精简。CLAUDE.md 会常驻上下文，写得越长越费 token，也越容易被淹没在噪声里。目标是"高密度的事实"，不是长篇大论。

七、步骤三：用 /memory 验证记忆是否生效

写完 CLAUDE.md，怎么确认它真的被加载了？用这条命令：

/memory

它做什么：列出当前会话实际加载的全部记忆来源——包括四层 CLAUDE.md、CLAUDE.local.md，以及 .claude/rules/ 目录下的所有规则文件，连同它们的路径和加载状态。

预期输出：你会看到一个清单，类似：

Enterprise policies: (none)
User memory:        ~/.claude/CLAUDE.md
Project memory:     ./CLAUDE.md ✅
Local memory:       ./CLAUDE.local.md (not found)
Rules:              .claude/rules/testing.md ✅
                    .claude/rules/api-conventions.md ✅

这一步的意义：/memory 是排错第一工具。当你发现 Claude"又忘了约定"，第一反应就该是 /memory 看看那份规则到底有没有被加载——十有八九是路径放错或文件名拼错。

八、步骤四：用 .claude/rules/ 做模块化记忆

当项目长大，单个 CLAUDE.md 会变成又长又难维护的怪物。Claude Code 支持把记忆拆成多个文件，放进 .claude/rules/ 目录。

关键规则：.claude/rules/ 下的每一个 .md 文件都会被自动当作项目记忆加载，无需你在 CLAUDE.md 里引用。

例如这样的目录结构：

.claude/
├── rules/
│   ├── testing.md          # 测试约定
│   ├── api-conventions.md  # API 设计规范
│   ├── database.md         # 数据库与迁移
│   └── git-workflow.md     # 分支与提交
└── settings.json

每个文件聚焦一个领域，团队成员各管一摊，维护负担骤降。

进阶——带作用域的规则（Gated Rules）：有些规则只在特定场景生效。你可以在规则文件顶部用 frontmatter 限定作用域，比如只在处理测试文件时加载：

---
description: 测试编写规范
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

# 测试规范
- 每个公开函数至少 3 个用例：正常、边界、异常
- 用 describe/it 组织，命名用"应该……"
- 禁止真实网络请求，一律 mock

加了 globs 之后，这份规则只在文件路径匹配时才注入上下文，平时不占 token——这正是"渐进式披露"的精髓：把记忆按需加载，而不是一股脑全塞进去。

九、步骤五：让 Claude 自己学习（Auto Memory）

除了你手写的 CLAUDE.md，Claude Code 还能自动积累学习。当你在对话里说出以 # 开头的一句话，例如：

# 我们项目统一用 dayjs 处理日期，不要用 moment

Claude 会判断这句话是否值得长期记住。如果值得，它会自动写入合适的记忆文件（通常是用户级或项目级 CLAUDE.md，取决于内容的作用范围），下次会话就不再需要你提醒。

适合用 auto memory 的场景： - 一次性的偏好纠正（"我习惯用 2 空格缩进"）。 - 跨会话反复出现的项目约定。

不适合的场景：长篇大论的架构说明——那种老老实实写进 CLAUDE.md 或 rules 文件，可控、可 review、可进版本库。auto memory 是"顺手记一笔"，正式文档还得手写。

十、实战案例：从"失忆"到"秒懂"

回到开头那个痛点场景，看看配好记忆系统前后的对比。

场景：让 Claude"加一个用户登录接口"。

配置前（无 CLAUDE.md）：

你: 加一个用户登录接口
Claude: [生成 src/routes/login.js]
        [用 Express 写路由]
        [把 SQL 直接写在路由里]
        [用浮点存金额]

四项全错：框架错、语言错、分层错、数据类型错。你得一处处纠正，反复拉扯。

配置后（有高质量 CLAUDE.md + rules）：

你: 加一个用户登录接口
Claude: [生成 src/api/v2/auth/login.ts]  ✅ 目录约定
        [用 Fastify 的 route handler]   ✅ 框架
        [业务逻辑放 src/services/auth.ts] ✅ 分层
        [SQL 抽到 src/repositories/userRepo.ts] ✅ 数据访问
        [用整数分表示……此处无金额，跳过]
        [补了 Vitest 测试用例]          ✅ 测试约定

一次到位。这就是记忆系统的价值：把团队约定固化成 AI 的肌肉记忆，让每次会话都站在"老熟人"的起点上，而不是从零开始。

flowchart LR
    subgraph 配置前
        A1[加登录接口] --> A2[生成 login.js]
        A2 --> A3[用 Express]
        A3 --> A4[SQL 塞路由里]
        A4 --> A5[❌ 四项全错 反复纠正]
    end
    subgraph 配置后
        B1[加登录接口] --> B2[读 CLAUDE.md+rules]
        B2 --> B3[api/v2/auth/login.ts]
        B3 --> B4[Fastify 分层]
        B4 --> B5[补测试用例]
        B5 --> B6[✅ 一次到位]
    end

十一、进阶：上下文管理与记忆的边界

CLAUDE.md 虽好，但它常驻上下文，写多了会挤占有效窗口。这里有两个进阶认知：

1. 60% 规则。当一次会话的上下文使用量逼近约 60% 时，Claude 的注意力会开始稀释、容易"走神"。这时应及时用 /compact 压缩当前会话历史，把核心结论保留、把冗长中间过程折叠。记忆系统管"跨会话"，/compact 管"会话内"——两者分工不同，别混淆。

2. 记忆不等于代码。CLAUDE.md 里写的约定，Claude 会尽量遵守但非强制。对于绝对不能违反的硬规则（如安全审计、CI 检查），应该用 hooks（在工具调用前后拦截）或 CI 流水线来兜底，而不是只指望 AI 自觉。记忆是"降低出错概率"，hooks 是"出错就拦下"。

3. 别在记忆里放密钥。CLAUDE.md 会进版本库、会进上下文，任何敏感信息（API key、密码、token）都绝不能写在里面。机密应走环境变量或 secrets 管理工具。

十二、常见问题与解决方案

Q1：我改了 CLAUDE.md，但 Claude 好像没更新？ A：会话启动时一次性加载记忆。如果你在会话中途修改了文件，需要重启会话（或重新进入项目），新内容才生效。用 /memory 可随时确认当前加载的是哪份。

Q2：/init 生成的初稿质量不行怎么办？ A：把 /init 当草稿，不当终稿。它的价值是给你一个结构化起点；真正决定质量的是你后续补的"已知陷阱"和"目录约定"。也可以直接对 Claude 说"读一下代码库，把测试命令和分层约定补进 CLAUDE.md"。

Q3：团队里每个人偏好不同，怎么避免冲突？ A：团队共享的写进项目级 CLAUDE.md（进 Git）；个人私有偏好写进 CLAUDE.local.md（加入 .gitignore）。例如"我喜欢 commit 信息带 emoji"这种个人习惯，就该进 local 层。

Q4：.claude/rules/ 和 CLAUDE.md 内容重复了怎么办？ A：让 CLAUDE.md 做"总览 + 入口"，指向具体规则；细节拆进 rules 文件。避免同一句话在多处重复——重复不仅浪费 token，还容易在某处更新后产生不一致。

Q5：auto memory 会乱写文件吗？ A：auto memory 的写入相对克制，且大多落点在用户级文件。如果你担心失控，可以定期 git diff 审查 CLAUDE.md 变更，或干脆关闭 auto memory、只用手写记忆，获得完全的可控性。

十三、延伸阅读

十四、训练营适用性评估

参考来源

  1. How Claude remembers your project — Claude Code Docs — 官方记忆机制说明，含 CLAUDE.md 与 auto memory 两套系统、/memory 命令。
  2. Explore the .claude directory — Claude Code Docs — 官方对 .claude 目录结构与配置作用域的完整说明。
  3. Using CLAUDE.md files — Anthropic Blog — 官方博客，CLAUDE.md 写作最佳实践。
  4. Claude Code Memory System — Developer Toolkit — 实战视角，含 onboarding 痛点案例与 .claude/rules/ 模块化用法。
  5. How to Use Claude Code Instructions and Memory — Alex Rusin — 从单文件到多文件规则系统的渐进式搭建指南。

[!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学通信知识星球海报-扫码加入

📎 本分类最新文章