CLAUDE.md 怎么写？Claude Code 记忆配置完全指南（2026）

用 Claude Code 写代码时，是不是每开一个新会话都要从头交代一遍「这个项目怎么构建、用什么风格、测试怎么跑」？解决办法就是写好一个 CLAUDE.md。它是放在项目里的纯文本 Markdown 文件，Claude Code 每次启动都会自动读取，把里面的内容当成持久上下文。这篇就把 CLAUDE.md 怎么写讲透：放在哪、写什么、四层记忆层级怎么生效，以及一份可以直接抄的模板。

CLAUDE.md 是什么，和自动记忆有何区别

Claude Code 有两套互补的记忆机制，每次对话开始都会加载，但分工不同。简单说：CLAUDE.md 是「你写给 Claude 的规则」，自动记忆是「Claude 自己记的笔记」。

四层记忆层级：CLAUDE.md 该放在哪

CLAUDE.md 可以放在多个位置，范围从大到小、按加载顺序依次注入上下文。范围越小的越靠后读到、优先级越高。所有发现的文件是「拼接」而不是「覆盖」。

加载逻辑是：Claude 从当前目录向上遍历目录树，把沿途每个目录的 CLAUDE.md 和 CLAUDE.local.md 都读进来；子目录里的 CLAUDE.md 不在启动时加载，而是等 Claude 真正读到那个子目录的文件时再按需加载。所以 monorepo 里可以给每个子包单独写一份。

用 /init 一键生成起始文件

不用从零手写。在项目根目录跑 /init，Claude 会分析你的代码库，自动生成一份包含构建命令、测试方式、它发现的项目约定的 CLAUDE.md。如果文件已存在，/init 会提出改进建议而不是覆盖。生成后再手动补上那些 Claude 自己发现不了的规则即可。

# 在项目根目录的 Claude Code 会话里输入
/init

# 想要交互式多阶段流程（会顺带询问要不要建 skills / hooks）：
# 先设环境变量再启动
export CLAUDE_CODE_NEW_INIT=1
claude

怎么写才有效：四条可验证的原则

1. 1具体到能验证：写「使用 2 空格缩进」而不是「正确格式化代码」；写「提交前运行 npm test」而不是「测试你的更改」；写「API 处理器在 src/api/handlers/」而不是「保持文件有条理」。
2. 2控制体量：单个文件尽量在 200 行以内。文件越长越费上下文、遵守度反而下降。内容多就拆分。
3. 3结构化：用 Markdown 标题和项目符号分组。Claude 和人一样靠结构扫描，分好节比一大段密集文字更容易被遵循。
4. 4保持一致：两条规则互相矛盾时 Claude 可能随机挑一条。定期清理过时和冲突的条目。

@import 导入与 AGENTS.md 复用

CLAUDE.md 支持用 @path/to/file 语法导入其它文件，导入的内容会在启动时展开进上下文。相对路径相对于「包含导入的文件」解析，支持递归导入，最大深度四跳。注意：导入只是为了组织模块化，并不省上下文——被导入的文件一样会在启动时全部加载。想在文中提到某个路径却不想真导入它，用反引号包起来即可。

# 项目概览见 @README，可用命令见 @package.json

# 复用已有的 AGENTS.md（很多仓库给其它 AI 工具写的）
@AGENTS.md

## Claude Code 专属
- 改动 src/billing/ 下的代码时使用 Plan Mode

# 跨多个 git worktree 共享个人偏好，从主目录导入
- @~/.claude/my-project-instructions.md

进阶：用 .claude/rules/ 做路径范围规则

项目大了，把所有规则塞进一个 CLAUDE.md 会臃肿。可以改用 .claude/rules/ 目录，每个 .md 文件管一个主题（如 testing.md、security.md）。更妙的是，规则文件可以用 YAML frontmatter 的 paths 字段限定生效范围——只有当 Claude 处理匹配该 glob 的文件时才加载，平时不占上下文。

# .claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则
- 所有端点必须做输入校验
- 使用统一的错误响应格式
- 补全 OpenAPI 文档注释

自动记忆与 /memory 命令

除了你手写的 CLAUDE.md，Claude Code（v2.1.59 及以上）还有「自动记忆」：它把构建命令、调试心得、代码风格偏好等自己存进 ~/.claude/projects/<项目>/memory/ 目录，由 MEMORY.md 做索引，每次会话开始加载 MEMORY.md 的前 200 行或 25KB。你也可以直接对 Claude 说「记住：本项目统一用 pnpm 而不是 npm」，它会写进自动记忆。

• /memory：列出当前会话加载了哪些 CLAUDE.md / CLAUDE.local.md / rules 文件，可切换自动记忆开关、打开记忆文件夹。排查「为什么我的规则没生效」第一步就跑它，确认文件被加载。
• 想把某条对话里的指令变成手写规则，直接说「把它加到 CLAUDE.md」，或自己用 /memory 编辑。
• /compact 之后项目根 CLAUDE.md 会从磁盘重新注入；子目录里的嵌套 CLAUDE.md 不会自动重注入，等下次读到该目录文件时才重新加载。

写好一份 CLAUDE.md，本质上是把「怎么和 AI 协作」沉淀成可复用的工程规范——这正是用好 Claude Code 这类 agentic 工具的核心功夫。如果你想系统地学会用 AI 工具做真实项目（从环境配置、上下文工程到完整工作流），可以来 IMAI 看看我们的体系化实战课程，少走弯路。