# 记忆 · CLAUDE.md 是项目的长期记忆 · Claude Code · 终端里的编排台 **作者** Aklman · **章节** 03 / 11 · **首发** 2026.07 · **语言** 中文为主, 中英双语 **原文** https://library.aklman.com/books/claude-code/03-memory **全书 markdown** https://library.aklman.com/books/claude-code/llms.md **上一章** https://library.aklman.com/books/claude-code/02-loop/llms.md **下一章** https://library.aklman.com/books/claude-code/04-codify/llms.md > 本章来自 Aklman · Library, 完整免费阅读。允许 AI 摘读、引用、问答; 转载请保留作者署名与原文链接 (CC BY-NC-ND 4.0, https://library.aklman.com/license)。 --- > 同一件事你跟它说了十遍：用这个包管理器、按这个风格、别碰那个目录、跑测试用这条命令。模型不跨会话记事 —— 但 CLAUDE.md 会。它是每次开工自动加载的项目长期记忆，分项目级、用户级、企业级三层，还能用 @import 把别的文件拼进来。这一章讲什么该钉进去、什么不该（它不是文档垃圾场），三层怎么分工，以及为什么一份写得好的 CLAUDE.md，比你换一个更强的模型更能改善它干活的质量。 用这个包管理器,不是那个。测试要跑 npm test 不是 npx jest。migrations 目录别碰。—— 这些话你跟它说过十遍,因为模型不跨会话记事,每个新会话都是一张白纸。CLAUDE.md 就是治这个的:一份每次开工自动进入它脑子的文件。这一章讲什么该钉进去、钉在哪一层,以及一条容易被高估的边界:记忆是请求,不是规矩。 ### I · 放哪:四层记忆,各管一摊 CLAUDE.md 是普通的 markdown,特殊在于加载时机:每个会话开始,Claude 自动读它 —— 不用你贴、不用你提。[^1]起点不用手写:跑一次 `/init`,它会分析你的代码库,把探出来的构建命令、测试方式、项目惯例生成一份初稿;已经有 CLAUDE.md 的话,它提改进而不是覆盖。[^1]之后的问题只剩一个:哪句话放哪一层。 | 层级 | 位置 | 放什么 | |---|---|---| | 组织 | managed policy(IT 下发) | 全公司的编码与合规规范 | | 用户 | `~/.claude/CLAUDE.md` | 你个人的偏好,跟你走所有项目 | | 项目 | `./CLAUDE.md` | 团队共享:命令、架构、惯例,进版本库 | | 项目 · 个人 | `CLAUDE.local.md` | 你的沙盒地址、测试数据,进 .gitignore | 四层叠加生效,不互相覆盖。[^1]文件长了还有两个泄压阀:`@path` 语法把别的文件拼进来(比如 `@docs/git-instructions.md`,最多递归 4 层);`.claude/rules/` 目录把规则拆成多个主题文件,还能用 `paths` 限定 —— 只在 Claude 碰到匹配文件时才加载,不白占上下文。[^1] --- ### II · 写什么:一行一个否决问题 CLAUDE.md 的敌人不是太短,是太长:它整份进入每次会话的上下文,臃肿的文件会让真正要紧的规则被淹没 —— 官方直说,写得太满,Claude 反而开始忽略你的指令。[^2]纪律是对每一行问同一个问题:**删掉这行,它会不会因此犯错?**不会,就删。[^2] | 值得一行 | 不值得 | |---|---| | 它猜不到的构建 / 测试命令 | 读代码就能推断的结构 | | 和默认不同的风格规则 | 语言的通行惯例 | | 禁区目录、仓库礼仪、环境怪癖 | 经常变动的信息 | | 踩过的坑和非直觉行为 | 逐文件的代码库导览 | 什么时候写?用第 1 章那张触发表里的第一条:**同一个错误出现第二次,就是写一行的时候**。[^3]什么时候搬走?一段记忆长成了多步流程,它就不该住在这里 —— 那是 skill 的形状(第 4 章);只对某个目录有效的规则,搬进带 `paths` 的 rules 文件。[^1]200 行是个好的警戒线。[^1] --- ### III · 记忆是请求,不是规矩 把预期校准准确:文档对 CLAUDE.md 的定性是「上下文,不是强制配置」—— 它读了、大概率照做,但没有任何机制保证。[^1]所以「提交前必须跑 lint」写在这里是叮嘱,写成 hook 才是闸门(第 7 章);「绝不许碰 .env」想要硬拦,用 PreToolUse hook,不是加粗字体。分层记忆负责让它**懂你的项目**,hooks 负责让它**越不过线** —— 两件事,别用一个工具硬扛。 还有两个容易踩的时间差。其一:CLAUDE.md 在会话开始读入内存,**中途改了不生效** —— 新内容要等下次 `/clear`、`/compact` 或重启才加载。[^4]改完发现它还按旧规矩走,不是它叛逆,是你还没翻页。其二:除了你写的记忆,它也在自己记 —— auto memory 默认开启,构建命令、调试心得这类「下次会用上」的东西被它写进 `~/.claude/projects/` 下的项目记忆目录,每次会话带上索引。[^1]用 `/memory` 能看到两套记忆的全部文件:定期翻一翻,删掉过时的 —— 记忆也会腐烂,烂记忆比没记忆更误事。 > 维护也可以派出去:直接说「把这条加进 CLAUDE.md」,它会替你写;说「记住这个」,它会存进 auto memory。你要做的只是当编辑,不是当录入员。 动手 · 给你的项目铺第一层记忆: - 跑一次 /init;已有 CLAUDE.md 就让它提改进,逐条批。 - 回想最近两周你重复交代过两次以上的话,各压成一行写进去。 - 用「删掉会不会出错」的尺子删掉三行 —— 减法和加法一样重要。 > 同一句话说第三遍之前, > 把它变成一行记忆 ## 引用与参考 01 · Claude Code Docs · Memory —— CLAUDE.md 每次会话开始加载;位置分四级:组织(managed policy,IT 统一下发)、用户(~/.claude/CLAUDE.md,你的全部项目)、项目(./CLAUDE.md 或 ./.claude/CLAUDE.md,随版本库共享)、项目个人(CLAUDE.local.md,加进 .gitignore);@path 导入其他文件,最多递归 4 层;.claude/rules/ 可按路径限定加载;建议单文件 200 行以内,过长反而降低遵循度;/init 自动生成起点;明确一句「context, not enforced configuration」—— 要硬拦用 PreToolUse hook。auto memory:Claude 自己跨会话记笔记,存于 ~/.claude/projects/<项目>/memory/,MEMORY.md 索引每次加载前 200 行或 25KB,/memory 可查看、编辑、关闭。截至 2026-07-17。 (Claude Code Docs · Memory) 02 · Claude Code Docs · Best practices —— 写 CLAUDE.md 的取舍表:收录它猜不到的构建命令、和默认不同的风格规则、测试跑法、仓库礼仪、项目特有的架构决定与坑;排除读代码就能推断的、语言通识、频繁变动的信息、逐文件的代码库描述。每一行问一句「删掉它会不会导致出错」,不会就删;臃肿的 CLAUDE.md 会让真正的规则被忽略。截至 2026-07-17。 (Claude Code Docs · Best practices) 03 · Claude Code Docs · Extend Claude Code —— 各扩展机制的触发时机:同一个约定或命令错第二次,写进 CLAUDE.md;反复粘贴的多步流程,做成 skill;必须每次发生的,写 hook。截至 2026-07-17。 (Claude Code Docs · Extend Claude Code) 04 · Claude Code Docs · How Claude Code uses prompt caching —— 项目根与用户级 CLAUDE.md 在会话开始读入内存,中途编辑不废缓存、但也不生效,下次 /clear、/compact 或重启才加载新内容。截至 2026-07-17。 (Claude Code Docs · Prompt caching) --- *记忆 · CLAUDE.md 是项目的长期记忆 · Claude Code · 终端里的编排台 · Aklman 著 · CC BY-NC-ND 4.0 · https://library.aklman.com/books/claude-code/03-memory*