首页 › tutorials › 给项目装记忆：CLAUDE.md 入门

给项目装记忆：CLAUDE.md 入门

概述

Claude Code 每一次会话都从一个全新的上下文窗口开始——它不会记得你上次说过的项目约定、构建命令或代码风格。本教程教你用 CLAUDE.md 这个纯文本文件，给项目装上一份持久记忆，让 Claude 在每个会话开头自动读取，从而稳定遵循你的规范。适合零基础开发者、刚装好 Claude Code 还没跑过真实项目、以及希望减少重复纠正的同学。读完你将掌握：记忆的四个层级、/init 一键生成、手写有效指令的诀窍、@import 引入、.claude/rules/ 路径限定，以及自动记忆（auto memory）。

前置条件

第一步：理解"为什么需要 CLAUDE.md"

先建立一个关键认知：Claude Code 没有跨会话记忆。

你今天告诉它"本项目用 4 空格缩进、提交前必须跑 pytest"，明天打开新会话，它又从零开始。于是你会发现自己反复输入同样的纠正：用 pnpm 不是 npm、API handler 放在 src/api/handlers/、不要碰 legacy/ 目录……

CLAUDE.md 就是解决这个问题的官方机制。它是一个 Markdown 文件，Claude Code 在每次会话开始时自动读取，把里面的内容当作持久的上下文。你写一次，长期受益。

官方文档给出一个简单的判断标准——当你满足以下任一情况，就该往 CLAUDE.md 加内容：

  1. Claude 第二次犯了同样的错误
  2. Code review 抓住了"它本应知道的"项目常识
  3. 你把上次的纠正又打了一遍
  4. 一个新同事需要同样的背景知识才能高效工作

一句话原则：CLAUDE.md 装的是"每次会话 Claude 都该知道的事实"，不是临时任务清单。

第二步：认识记忆的四个层级

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 团队共享的项目规范 通过版本控制共享给团队
本地级（Local） ./CLAUDE.local.md 你个人针对该项目的偏好（需加入 .gitignore） 仅自己（当前项目）

要点：

零基础起步，你只需要关心两件事：项目级 ./CLAUDE.md（团队共享）和 ./CLAUDE.local.md（只属于你）。用户级 ~/.claude/CLAUDE.md 可以放"我永远用中文回复"这类全局偏好。

第三步：用 /init 一键生成第一份 CLAUDE.md

最快的起步方式是让 Claude 自己分析代码库生成草稿。

操作：

cd 你的项目目录
claude

进入会话后输入：

/init

预期结果： Claude 会自动扫描你的代码库，生成一份初始 CLAUDE.md，内容通常包含：项目概述、构建/测试/lint 命令、它发现的项目约定、目录结构等。把它当作起点，再手动补充它发现不了的东西。

进阶：交互式多阶段流程

设置环境变量后，/init 会变成一个交互式向导：

CLAUDE_CODE_NEW_INIT=1 claude
# 会话内输入 /init

它会先问你"要设置哪些东西"（CLAUDE.md / skills / hooks），用子代理深入探索代码库，针对空白处追问，最后提交一份可审查的方案，你确认后才真正写文件——对零基础者更友好，不容易写坏。

常见问题：

第四步：手写有效指令——三个核心原则

CLAUDE.md 是"上下文"而非"强制配置"。Claude 会尽力遵循，但写得越具体、越简洁，遵循率越高。记住三个原则：

原则一：具体而非模糊

❌ 差："格式化好代码" ✅ 好："使用 2 空格缩进"

❌ 差："测试你的改动" ✅ 好："提交前运行 npm test"

❌ 差："保持文件整洁" ✅ 好："API 处理器放在 src/api/handlers/ 下"

原则二：简洁——目标 200 行以内

官方明确建议：单个 CLAUDE.md 控制在 200 行以内。越长，消耗的上下文越多，遵循率反而下降。

判断方法：如果某条规则只针对一部分代码，就别塞进主文件，用后面讲的 路径限定规则。

原则三：结构化

用 Markdown 标题和列表组织，而不是大段文字。Claude 扫描结构的方式和人类读者一样——分组的章节比密密麻麻的段落好读。

一份好的项目级 CLAUDE.md 模板：

# 项目：支付网关后端

## 构建与测试
- 启动开发服务：`make dev`
- 运行测试：`pytest -q`（必须先起本地 Redis）
- 类型检查：`mypy src/`
- 提交前必须全绿

## 代码规范
- Python 3.11，类型注解必填
- 4 空格缩进，行宽 100
- 新增 API 必须有输入校验和统一错误格式

## 架构
- src/api/handlers/  放 HTTP 入口
- src/domain/        放业务逻辑（禁止直接 import HTTP 层）
- src/infra/         放数据库、缓存、第三方客户端
- legacy/ 目录不要改，正在下线

## 注意
- 永远不要 push 到 main
- 数据库迁移用 alembic，禁止手写 SQL 改表

第五步：用 @import 引入其他文件

CLAUDE.md 支持 @路径 语法导入外部文件，导入的内容会在启动时展开并加载进上下文。

项目概览见 @README，npm 命令见 @package.json。

# 额外规范
- git 工作流见 @docs/git-instructions.md

要点：

配合 AGENTS.md： Claude Code 只读 CLAUDE.md，不读 AGENTS.md。如果你的仓库已有 AGENTS.md（给其他 AI 工具用），创建一个 CLAUDE.md 导入它即可，两边共享同一份指令：

@AGENTS.md

## Claude Code 专属
- 对 `src/billing/` 的改动请用 plan 模式。

Windows 不便建符号链接，用 @AGENTS.md 导入最省事。

第六步：理解加载顺序——目录会向上爬

这是最容易踩坑的点。Claude Code 从当前工作目录开始，沿目录树向上逐级查找 CLAUDE.md 和 CLAUDE.local.md。

假设你在 foo/bar/ 启动，它会加载：

加载顺序是从文件系统根向下到你的工作目录——离你启动位置越近的，越晚进入上下文（也最具体）。子目录里的 CLAUDE.md 不会在启动时加载，而是当 Claude 读取该子目录里的文件时按需加载。

flowchart TD
    A[claude 在 foo/bar/ 启动] --> B[向上逐级扫描]
    B --> C1[/CLAUDE.md]
    B --> C2[foo/CLAUDE.md]
    B --> C3[foo/bar/CLAUDE.md]
    C1 --> D1[1. 最早加载<br/>最宽泛]
    C2 --> D2[2. 中间加载]
    C3 --> D3[3. 最后加载<br/>最具体]
    D1 & D2 & D3 --> E[拼接进启动上下文]
    F[子目录 src/ 内的 CLAUDE.md] -.按需.-> G[读到该目录文件时才加载]
    E --> H[会话开始]

技巧： 用 HTML 注释 <!-- 维护者备注 --> 写只给人看的内容，Claude 不会把注释注入上下文，省 token。代码块里的注释则会保留。

第七步：用 .claude/rules/ 做路径限定规则

项目变大后，所有规则堆进一个 CLAUDE.md 会让它超长。这时用 .claude/rules/ 目录把指令拆成主题文件，并支持按文件路径限定——只在 Claude 处理匹配文件时才加载，省上下文、减噪音。

目录结构：

your-project/
├── .claude/
│   ├── CLAUDE.md          # 主指令
│   └── rules/
│       ├── code-style.md  # 代码风格
│       ├── testing.md     # 测试约定
│       └── security.md    # 安全要求

无条件规则（无 frontmatter）：和 .claude/CLAUDE.md 一样，每次会话加载。

路径限定规则（带 paths frontmatter）：只在 Claude 读取匹配文件时触发：

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

glob 写法速查：

模式 匹配
**/*.ts 任意目录下的 TypeScript 文件
src/**/* src/ 下所有文件
*.md 项目根的 Markdown
src/**/*.{ts,tsx} src 下所有 ts 和 tsx（花括号扩展）

个人规则：放 ~/.claude/rules/ 会对你机器上每个项目生效，且加载顺序在项目规则之前。

第八步：自动记忆（Auto Memory）——Claude 自己做笔记

除了你手写的 CLAUDE.md，Claude Code 还有一套自动记忆：它会在工作中自己记笔记——构建命令、调试心得、架构要点、你纠正过的风格偏好。它不会每次都记，只在判断"这对未来会话有用"时才存。

手动让 Claude 记： 直接说"记住：本项目 API 测试需要本地 Redis"，它会存进 auto memory。如果想存进 CLAUDE.md 而非 auto memory，明确说"把这个加到 CLAUDE.md"。

第九步：用 /memory 查看与编辑

/memory 命令是记忆的"控制台"，它能：

排查"Claude 没遵守我的 CLAUDE.md"的标准动作：

  1. 跑 /memory，确认你的文件真的在加载列表里——不在列表里，Claude 就看不到它。
  2. 检查文件位置是否在会被加载的层级。
  3. 把指令改得更具体（"2 空格缩进"优于"格式化好一点"）。
  4. 排查跨文件冲突指令——两个文件给出相反指导时，Claude 可能随机挑一个。
  5. 如果某事必须在固定时机执行（如提交前），别写 CLAUDE.md，改用 hook（钩子，硬执行）。

重要区分：CLAUDE.md 是"行为引导"，不是强制层。要硬性阻止某个动作（不管 Claude 怎么想），用 PreToolUse hook。

实战案例：为 Python 项目配置完整记忆

下面用一个虚构的"支付网关后端"项目，把上述所有步骤串起来，产出一套可直接抄走的配置。

目录结构：

payment-gateway/
├── CLAUDE.md                  # 团队共享（提交到 git）
├── CLAUDE.local.md            # 你个人（gitignore）
├── .claude/
│   ├── CLAUDE.md              # 与根 CLAUDE.md 二选一
│   └── rules/
│       ├── api.md             # 限定 src/api/**
│       └── db.md              # 限定 src/infra/db/**
├── .gitignore
└── ...源码...

1. 根 CLAUDE.md（精简、全员共享）：

# 支付网关后端（Python 3.11 / FastAPI）

## 常用命令
- 起服务：`make dev`
- 测试：`pytest -q`（需本地 Redis）
- 类型检查：`mypy src/`

## 红线
- 永不 push 到 main
- 改表走 alembic，禁手写 SQL DDL
- legacy/ 下线中，勿动

2. .claude/rules/api.md（路径限定）：

---
paths:
  - "src/api/**/*.py"
---
# API 层规范
- 每个端点必须有 Pydantic 输入模型
- 错误统一用 app.errors.PaymentError 体系
- 返回结构：{ "code": int, "data": ..., "msg": str }

3. .claude/rules/db.md（路径限定）：

---
paths:
  - "src/infra/db/**"
---
# 数据访问规范
- 仓库模式，禁止在 handler 直接写 SQL
- 查询必须走 src/infra/db/repositories/
- 涉及金额用 Decimal，禁 float

4. CLAUDE.local.md（个人，加入 .gitignore）：

# 我的本地偏好
- 本地沙箱地址：http://localhost:8080
- 测试数据用 fixtures/local_seed.json

5. .gitignore 追加：

CLAUDE.local.md

验证流程：

cd payment-gateway
claude
# 会话内
/memory        # 确认 4 个文件都在加载列表

然后让 Claude 写一个新端点，观察它是否：用了 Pydantic 校验、统一错误格式、把 SQL 放进 repositories/、用了 Decimal。符合就说明记忆生效了。

flowchart LR
    S[claude 启动] --> A[/init 生成草稿]
    A --> B[手写根 CLAUDE.md<br/>200 行内]
    B --> C[大规则拆 .claude/rules]
    C --> D[个人偏好放 .local.md]
    D --> E[/memory 验证加载]
    E --> F{Claude 遵守?}
    F -->|是| G[✅ 记忆生效]
    F -->|否| H[改具体/查冲突/转 hook]
    H --> E
    I[工作中] -->|自动| J[auto memory 自记笔记]
    J --> I

常见问题与解决方案

Q1：/init 后 Claude 还是犯了 CLAUDE.md 里写过的错？ A：先 /memory 确认文件在列表里；再把指令写具体；最后查跨文件冲突。CLAUDE.md 是"尽力遵循"而非"硬执行"。

Q2：CLAUDE.md 太长了（超 200 行）怎么办？ A：用路径限定规则 .claude/rules/，只让相关文件触发。注意 @import 只是组织手段，不省上下文——导入的文件照样在启动时加载。

Q3：/compact 压缩上下文后，指令"丢了"？ A：项目根的 CLAUDE.md 能在压缩后从磁盘重新注入；但子目录里的 CLAUDE.md 不会自动重注入，要等 Claude 再读该目录文件时才重新加载。关键规则放项目根。

Q4：auto memory 存了什么我不知道？ A：/memory → 选 auto memory 文件夹，全是纯 Markdown，可直接读、改、删。

Q5：团队 monorepo 里别的团队的 CLAUDE.md 干扰我？ A：用 claudeMdExcludes 设置按路径/glob 跳过（托管策略级除外）。

Q6：怎么让"提交前自动跑测试"成为铁律？ A：别写 CLAUDE.md，改写一个 hook（如 PreToolUse / Stop 钩子），它是脚本级的硬执行，不依赖 Claude 自觉。

延伸阅读

训练营适用性评估

参考来源

  1. How Claude remembers your project — Claude Code Docs — Anthropic 官方权威文档，覆盖 CLAUDE.md 层级、import、rules、auto memory 全部细节
  2. Commands — Claude Code Docs — 官方命令参考，含 /init、/memory、/compact 用法
  3. CLAUDE.md Files and Memory Hierarchy — DeepWiki — 图解记忆层级与加载优先级
  4. CLAUDE.md File: The Complete Guide With Examples & Templates — TensorFeed.ai — 含可直接套用的模板与实战示例（2026 年更新）
  5. Claude Code Memory Explained: How It Really Works — Jose Parreo Garcia — 各层记忆交互机制的深度拆解

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

📎 本分类最新文章