概述

本教程面向第一次接触 Claude Code 的开发者，聚焦一个最容易被忽略却最影响使用体验的核心机制——项目记忆文件 CLAUDE.md。学完你将掌握：用 /init 一键生成记忆、手写一份高质量的 CLAUDE.md、理解四级作用域与加载顺序、用 @ 引用和 .claude/rules/ 拆分模块、开启自动记忆并用 /memory 审计，以及写出"AI 真的会照做"的有效指令。适用人群：刚装好 Claude Code、想让它在每个项目里都"懂规矩"而不是每次重新解释的零基础用户。

前置条件

• 已安装 Claude Code（claude --version 能正常输出版本号；要使用自动记忆需 v2.1.59 或更高）。
• 终端里能进入一个代码项目目录（git 仓库最佳，非 git 目录也可）。
• 一台 macOS / Linux / Windows + WSL 机器，有基本的命令行操作能力。
• 无需任何编程语言基础——本教程以配置文件为核心，命令可直接复制运行。

第零步：先搞懂"为什么需要记忆文件"

每次启动 Claude Code，它都拿着一个全新的上下文窗口——也就是说，它对你昨天的对话、你的项目结构、你的代码风格一无所知。如果不做任何配置，你会发现自己一遍又一遍地重复同一句话："用 pnpm 不要用 npm""提交前先跑 npm test""API 处理函数放在 src/api/handlers/"。

Claude Code 用两套互补的记忆系统把知识跨会话保留下来：

一句话总结：CLAUDE.md 是你写给 AI 的"项目说明书"，自动记忆是 AI 给自己记的"笔记本"。本教程主要教你写好前者，顺带开启后者。

⚠️ 重要认知：CLAUDE.md 是被当作上下文注入的，而不是被强制执行的配置。Claude 会尽量遵守，但不会 100% 保证。要硬性拦截某个动作（比如禁止执行某条命令），应该用 PreToolUse 钩子，而不是只写在 CLAUDE.md 里。这一点决定了你"哪些规则放记忆文件、哪些规则放钩子"。

第一步：用 /init 一键生成项目记忆

最快的上手方式是让 Claude 帮你起草。进入项目根目录，启动 Claude Code，输入：

/init

会发生什么：Claude 会扫描你的代码库——读 package.json、构建脚本、测试目录、README、甚至已有的 .cursorrules、.devin/rules/、.windsurfrules、AGENTS.md 等其他工具的配置——然后自动生成一份包含构建命令、测试方式、项目约定的 CLAUDE.md。

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

# 项目：my-app

## 构建
- 安装依赖：`pnpm install`
- 启动开发服务器：`pnpm dev`
- 构建：`pnpm build`

## 测试
- 运行测试：`pnpm test`
- 单测在 `tests/` 目录

## 代码风格
- 使用 TypeScript 严格模式
- 组件放在 src/components/

关键细节： - 如果项目里已经有 CLAUDE.md，/init 不会覆盖，而是建议改进。这很重要——你不用担心心血被冲掉。 - 想体验更强大的"多阶段交互式初始化"，设置环境变量再跑：

bash CLAUDE_CODE_NEW_INIT=1 claude # 然后输入 /init

开启后，/init 会先问你要不要同时建立 CLAUDE.md、skills、hooks，用一个子代理深入探索代码库，通过追问补全信息，最后给出一个可审阅的方案，你确认后才真正写文件。对新手极其友好。

常见问题： - /init 生成的文件很简陋？ 正常。它能发现的是客观信息（构建命令），而你需要手动补充"它发现不了的东西"——比如架构决策、命名约定、为什么这么设计。 - 生成后没生效？ 退出当前会话重开一次（或重启 Claude Code），记忆文件在会话开始时才加载。

第二步：手动打造第一份高质量 CLAUDE.md

/init 给你的是骨架，真正的价值在于你手写的内容。下面是一个可直接套用的模板，对应一个 Node.js + TypeScript 后端项目：

# my-api 项目记忆

## 构建与运行
- 包管理器：pnpm（永远不要用 npm 或 yarn）
- 安装依赖：`pnpm install`
- 开发：`pnpm dev`（监听 3000 端口）
- 测试：`pnpm test`（提交前必须通过）

## 代码规范
- 使用 2 空格缩进
- 用双引号字符串
- 所有函数必须有显式返回类型

## 项目结构
- API 路由处理器：src/routes/
- 数据库模型：src/models/
- 业务逻辑：src/services/
- 类型定义：src/types/

## 关键约定
- 新增 API 必须写输入校验，用 zod
- 错误响应统一走 src/utils/errorHandler.ts
- 数据库迁移用 prisma migrate，不要手写 SQL 改表

写好它的四条铁律（官方文档反复强调）：

1. 体积：单个 CLAUDE.md 控制在 200 行以内。文件越长，消耗的上下文越多，遵守率反而下降。内容多就拆到 .claude/rules/（见第五步）。
2. 结构：用 Markdown 标题 + 项目符号分组。Claude 读结构和人一样——有分区的比一大段好懂。
3. 具体到可验证： - ❌ "格式化代码" → ✅ "用 2 空格缩进" - ❌ "测试你的改动" → ✅ "提交前运行 pnpm test" - ❌ "保持文件有序" → ✅ "API 处理器放在 src/routes/"
4. 一致性：两条互相矛盾的规则，Claude 会随便挑一条。定期检查，删掉过时的指令。

预期结果：保存后，新开的会话里 Claude 一上来就知道用 pnpm、知道去哪找路由——你再也不用重复解释。

常见问题： - Claude 没遵守我的规则？ 先用 /memory 命令确认文件真的被加载了（见第六步）。若已加载还不遵守，多半是规则太模糊或与别处冲突——改具体一点。 - 规则必须执行、不能有例外怎么办？ 那就不是 CLAUDE.md 的事，改用钩子（hook）强制拦截。

第三步：理解四级作用域与加载顺序

这是新手最容易迷糊的地方。CLAUDE.md 不是只能放一个地方，它有四种作用域，按"从宽到窄"的顺序加载：

| 作用域 | 位置 | 用途 | 与谁共享 | | :--- | :--- | :--- | | 托管策略（Managed） | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md | 组织级，由 IT/DevOps 下发 | 本机所有用户 | | 用户级（User） | ~/.claude/CLAUDE.md | 你在所有项目的个人偏好 | 只你自己 | | 项目级（Project） | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队共享的项目说明 | 通过 Git 共享给团队 | | 本地级（Local） | ./CLAUDE.local.md | 你在本项目的私有偏好，加入 .gitignore | 只你自己（当前项目） |

加载的关键规则： - 内容是拼接进上下文的，不是后者覆盖前者——所以四份文件可以同时生效。 - 顺序是从文件系统根向下到你的工作目录：越靠近你启动位置的文件，读得越晚，影响力相对越靠后。 - 同一目录里，CLAUDE.local.md 会追加在 CLAUDE.md 之后——你的私人笔记是"最后被读到的"。

实战建议： - 把"团队都要遵守的"放 ./CLAUDE.md，提交进 Git。 - 把"只有我这样干"的（比如你的沙箱地址、本地测试数据）放 ./CLAUDE.local.md，并加入 .gitignore。运行 /init 选 personal 选项会自动帮你加 gitignore。 - 把"所有项目通用"的（比如你个人偏好的代码风格）放 ~/.claude/CLAUDE.md。

常见问题： - 我在子目录启动 Claude，会读到上级的 CLAUDE.md 吗？ 会。Claude 会从当前目录向上逐级查找。在 foo/bar/ 启动，会读到 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及它们的 local 版本。 - 大型 monorepo 里别的团队的 CLAUDE.md 干扰我怎么办？ 用 claudeMdExcludes 设置按 glob 排除，写进 .claude/settings.local.json：

json { "claudeMdExcludes": [ "**/other-team/CLAUDE.md" ] }

第四步：用 @ 引用把外部文件拼进来

CLAUDE.md 支持用 @路径 语法导入其他文件，导入的内容会在启动时展开并一起进上下文。

# my-app

See @README for project overview
and @package.json for available npm commands.

# Git 工作流
@docs/git-instructions.md

要点： - 相对路径相对于包含 import 的那个文件解析，不是工作目录。 - 导入可以递归，但最多 4 层。 - 想在文中提到一个路径而不是导入它，用反引号包起来：`@README` 不会触发导入。 - 第一次遇到项目外的导入时，Claude Code 会弹审批对话框列出文件；你拒绝后该导入保持禁用，不再询问。 - 重要权衡：拆成 @ import 有助于组织，但不能减少上下文占用——导入的文件照样在启动时进上下文。真想省上下文，得用第五步的路径规则。

跨 worktree 共享个人偏好：如果你用多个 git worktree 操作同一仓库，CLAUDE.local.md 只存在于创建它的那个 worktree。想跨 worktree 共享，改用导入家目录文件：

# 个人偏好
- @~/.claude/my-project-instructions.md

第五步：用 .claude/rules/ 把规则拆成模块、按文件类型加载

当项目变大、CLAUDE.md 超过 200 行，就该用 .claude/rules/ 目录拆分了。它有两个杀手锏：模块化和按路径加载。

目录结构：

your-project/
├── .claude/
│   ├── CLAUDE.md            # 主记忆文件
│   └── rules/
│       ├── code-style.md    # 代码风格
│       ├── testing.md       # 测试约定
│       ├── security.md      # 安全要求
│       └── frontend/        # 可建子目录，递归发现
│           └── react.md

无条件规则（启动时和 .claude/CLAUDE.md 一起加载）：直接写 markdown 即可。

按路径触发的条件规则（只在 Claude 操作匹配文件时才加载，省上下文）：在文件头加 YAML frontmatter：

---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须有输入校验
- 用统一的错误响应格式
- 必须写 OpenAPI 文档注释

glob 模式速查：

用户级规则：放在 ~/.claude/rules/，对所有项目生效，且先于项目规则加载（项目规则优先级更高）。

区分清楚：rules（规则）用于"总要在上下文里或按文件类型加载"的长期约定；skills（技能）用于"偶尔才用、按需触发"的工作流。别把一次性流程塞进 rules。

第六步：开启自动记忆，用 /memory 审计一切

自动记忆（Auto memory）让 Claude 自己给自己记笔记——构建命令、调试心得、架构笔记、它发现的你的偏好。它默认开启，需要 v2.1.59+。

存储位置：每个项目一个独立目录 ~/.claude/projects/<hash>/memory/，其中 <hash> 由 git 仓库派生，所以同一仓库的所有 worktree 和子目录共享一份记忆。

目录结构：

~/.claude/projects/<hash>/memory/
├── MEMORY.md          # 精简索引，每次会话加载前 200 行/25KB
├── debugging.md       # 调试心得（按需读取，不在启动加载）
└── api-conventions.md # API 约定

工作机制： - 启动时只加载 MEMORY.md 的前 200 行或 25KB（取先到者）。所以 Claude 会把 MEMORY.md 保持精简，把细节挪到 topic 文件里——topic 文件不在启动加载，需要时再用文件工具现读。 - 当你在界面看到 "Writing memory" / "Recalled memory"，就是它在读写这个目录。

怎么用： - 开关：会话里输入 /memory，用其中的开关切换；或在 settings 里设 "autoMemoryEnabled": false；环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 也能关。 - 审计：/memory 会列出当前会话加载的所有 CLAUDE.md、CLAUDE.local.md、rules 文件，还能开关自动记忆、打开自动记忆文件夹。选任意文件可在编辑器打开。 - 让它记：直接说"记住我永远用 pnpm""记住 API 测试需要本地 Redis"，Claude 就会写进自动记忆。 - 写进 CLAUDE.md 而非自动记忆：明确说"把这条加到 CLAUDE.md"，或自己用 /memory 编辑。

自定义存储位置：在 settings.json 里设：

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

自动记忆是本机本地的，不会跨机器、不会进云端环境。它是纯 markdown，随时可读可改可删。

第七步：写给 AI 的有效指令（避坑清单）

把前面的原则凝练成一份"自检清单"，每次写规则前过一遍：

1. 每条都要具体到可验证——能写"运行 pnpm test"就别写"记得测试"。
2. 控制体积——单文件 < 200 行；膨胀就拆 .claude/rules/。
3. 善用标题与列表——别堆大段散文。
4. 消除矛盾——定期巡检，别让两条规则打架。
5. 分清三种机制： - 必须在固定时机执行的（提交前、编辑后）→ 钩子（强制） - 长期约定 → CLAUDE.md / rules（上下文引导） - 偶发工作流 → skills（按需加载）
6. 想确认为何不生效： - /memory 看文件是否在加载列表里。 - 确认文件位置对不对（项目级要放 ./CLAUDE.md 或 ./.claude/CLAUDE.md）。 - 指令改具体些。 - 排查跨文件冲突。 - 高级调试可用 InstructionsLoaded 钩子记录"哪些指令文件、何时、为何加载"。

实战案例：给一个 Express + TypeScript API 配齐记忆体系

假设你有一个目录 my-api/，下面用一个完整流程把它从"裸奔"变成"AI 全懂"。

1. 初始化（项目根目录）：

cd my-api
CLAUDE_CODE_NEW_INIT=1 claude
# 输入 /init，选择建立 CLAUDE.md，按提示确认方案

2. 编辑生成的 ./CLAUDE.md，替换为精炼版（保持 < 50 行）：

# my-api

## 运行
- 依赖：`pnpm install`
- 开发：`pnpm dev`（端口 3000）
- 测试：`pnpm test`（提交前必跑）

## 约定
- 包管理器只用 pnpm
- 新增 API 必须用 zod 校验输入
- 错误统一走 src/utils/errorHandler.ts

3. 拆分按文件类型生效的规则，建 .claude/rules/testing.md：

---
paths:
  - "tests/**/*.ts"
---
# 测试规则
- 每个公开函数都要有对应单测
- 测试文件与源文件同名加 .spec，如 user.ts → user.spec.ts
- 用 vitest，不要引 jest

4. 加个人私有偏好，建 ./CLAUDE.local.md（加进 .gitignore）：

# 本地偏好
- 我的本地数据库：postgresql://localhost:5432/myapi_dev
- 调试时倾向多打日志

5. 验证加载，新开会话输入 /memory，应看到 CLAUDE.md、CLAUDE.local.md、rules/testing.md 全部列出。

6. 让自动记忆沉淀，工作中直接对 Claude 说：

"记住：测试数据库迁移前要先把 docker compose up 起来。"

它会写进 ~/.claude/projects/<hash>/memory/，下次自动召回。

效果：从这一刻起，无论你隔多久、开多少个新会话，Claude 都默认知道用 pnpm、API 要校验、测试用 vitest、迁移前要先起 docker——而你一句都不用再解释。

整体工作流：记忆体系全景图

flowchart TD
    A[新会话启动·空上下文窗口] --> B{扫描记忆}
    B --> C[托管策略 CLAUDE.md<br/>组织级]
    B --> D[用户级 ~/.claude/CLAUDE.md<br/>+ ~/.claude/rules/]
    B --> E[项目级 ./CLAUDE.md<br/>./.claude/CLAUDE.md + .claude/rules/]
    B --> F[本地级 ./CLAUDE.local.md]
    B --> G[自动记忆<br/>MEMORY.md 前200行/25KB]
    C --> H[逐级拼接注入上下文]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[进入对话]
    I --> J{Claude 工作中}
    J -->|读到 src/api/*.ts| K[触发路径规则<br/>.claude/rules/*.md]
    J -->|你纠正/补充| L[Claude 自己记笔记<br/>写 auto memory]
    K --> J
    L --> G
    I --> M[/memory 命令<br/>审计·编辑·开关]
    M --> B

延伸阅读

• Claude Code 官方记忆文档：code.claude.com/docs/en/memory（本教程主要依据，权威性最高）
• Skills 文档：当你想把一次性流程做成可复用技能时深入
• Hooks 指南：当你需要"硬性强制"某条规则、而非靠上下文引导时
• Debug your configuration：当记忆文件死活不生效时的官方排障页
• Subagent memory：让子代理维护各自的自动记忆

进阶方向：把记忆体系与 skills、hooks 三者配合——记忆负责"长期约定"、skills 负责"按需工作流"、hooks 负责"强制拦截"，三者各司其职，就是一套成熟的 AI 协作工程化方案。

训练营适用性评估

• 适用训练营类型：Claude Code / AI 辅助开发入门营、企业研发提效训练营、团队 AI 工程化落地营。本主题是所有后续内容（skills、hooks、子代理）的地基，必须放在课程最前段。
• 教学时长：建议 1.5～2 小时。其中概念讲解 20 分钟、/init 与手写 CLAUDE.md 演示 30 分钟、作用域与 rules 实操 40 分钟、自动记忆与排障 20 分钟、综合实战 20 分钟。
• 学员产出：每个学员为自己的真实项目配齐一套记忆文件，并通过 /memory 验证加载成功，作为结业检查点。
• 难度系数：★☆☆☆☆（零基础友好，无需编程），但"写有效指令"这条需要反复练习，可设置 3～5 个"把模糊规则改具体"的小练习巩固。

参考来源

1. How Claude remembers your project — Claude Code Docs — Anthropic 官方记忆系统权威文档，涵盖 CLAUDE.md、自动记忆、rules、/init、/memory 全部机制（本文主要依据）
2. The Complete Guide to CLAUDE.md — TensorFeed.ai — 含示例与模板的 CLAUDE.md 完整指南，补充了实战写法与模板
3. Claude Code Instructions and Memory: The Complete Setup — Alex Rusin's Blog — 多文件规则系统与 /memory 的完整配置实战博客
4. What Does /init Do in Claude Code? — HowDoIUseAI — 详解 /init 如何扫描项目并生成 CLAUDE.md
5. The CLAUDE.md Memory System Tutorial — SFEIR Institute — 结构化的 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 等场景全覆盖。