📓记忆文件（CLAUDE.md 及其它）
智能体在两次会话之间会忘掉一切, 除了您写进它记忆文件里的东西。如何组织这些文件，让它记住上下文、您的规则和您的决定。
关于代码智能体，有一个有点令人沮丧的真相：它们没有任何记忆。 您可以花两个小时讲解您的项目，把同一个错误纠正十遍，立下您的规则, 可到了下一次会话，智能体又是一张白纸。它全忘了。LLM 只记得当前对话里装得下的东西。关掉窗口，一切烟消云散。
只有一样东西例外：记忆文件。这是一个文本文件，智能体会在每次会话启动时自动读取，甚至早在您打任何字之前。您只需写一次它该永远记住的东西。这正是让您不用再重复自己的东西。
这个文件，和它的全局孪生兄弟
所有智能体都会读一个记忆文件。名字随工具而变，但思路是一样的。
- Claude Code 读一个叫
CLAUDE.md的文件。 - OpenCode 读一个叫
AGENTS.md的文件, 这是正在逐渐成形的跨工具约定（Cursor、Codex 和其它一些工具也在向它靠拢）。
机制相同，只是文件名不同。而且两种情况下，都存在两个层级：
- 项目文件，在您仓库的根目录。它描述这一个项目：它的目标、技术栈、规则。它随代码一起走，所以任何打开仓库的人（或智能体）都会继承它。
- 全局文件，在您用户的层级。它承载您永久的偏好，对您所有项目都生效。对 Claude Code 来说，它是
~/.claude/CLAUDE.md。
Claude Code 读取的两个位置：
./CLAUDE.md # 项目记忆（仓库根目录）
~/.claude/CLAUDE.md # 全局记忆（您所有的会话）
该往里放什么（真正的干货）
一个好的记忆文件，四个板块就够了。不要更多。
- 项目的上下文。 它是什么，尤其是那个一句话的目标, 您已经在需求说明里提炼出来的那一句。它是智能体的指南针。
- 约定和规则。 那些智能体猜不出、而您又不想重新论证的选择：「执行 sudo 命令前总是先把它展示出来」「不准明文写密钥」「我们用 React，不用 Vue」「永远别碰
legacy/文件夹」。 - 重要的命令。 这个项目怎么运行、构建、测试、部署。智能体会忠实地复用它们，而不是编一个根本不存在的命令。
- 吃过苦才学到的教训。 反复出现的坑、违反直觉的窍门、那个让您们焦头烂额的 bug。「API 每秒被打超过 5 次就会返回 429，要限流。」这种知识价值连城，否则就丢失了。
不该往里放什么
一个臃肿的记忆文件，比一个空文件更糟：它每次会话都吃掉上下文却毫无贡献。让它保持精干。
- 代码已经说清楚的东西。 不用抄目录树，也不用列出每个文件：智能体会读仓库。记忆服务于那些不在代码里的东西。
- 密钥。 永远不要。一个 API key 都不行，一个密码都不行。这个文件随仓库一起走, 见保护访问。
- 某一次对话里的细节。 「昨天我们把某个按钮改名了」不该出现在这里。记忆是永久的东西，不是工作日志。
一个具体又可复用的例子
下面是一个小型网页项目里一份诚实的 CLAUDE.md 长什么样。密实、有用、没有赘肉：
# Kino, 电影看板
## 目标
汇总本周的电影上映（海报、评分、简介），
能从我的手机上查看。个人使用，单用户。
## 技术栈
- 前端：Astro + TypeScript，以静态方式部署。
- 数据：TMDB API（密钥放在环境变量 `TMDB_KEY`，绝不写死）。
- v1 不用数据库、不做鉴权、不做后端。
## 规则
- 破坏性命令（rm、git push --force）执行前总是先展示出来。
- 不准明文写密钥：一切走 .env（已 gitignore）。
- TypeScript 严格模式。不准用 `any`，除非有注释说明理由。
- 永远别碰 `vendor/` 文件夹（第三方代码已冻结）。
## 命令
- 开发：`npm run dev`（端口 4321）
- 构建：`npm run build`
- 测试：`npm test`（Vitest）
- Lint：`npm run lint`
## 坑
- TMDB 超过约 40 次/10 秒会返回 429：我们把响应缓存 24 小时。
- 缺失的海报返回的是 `null`，不是空字符串, 用 `== null` 判断。
您十五秒就能读完。这正是目标：一个在启动时吞下它的智能体，能带着您本该重新讲一遍的全部上下文出发。
全局记忆，放您自己的偏好
全局文件不针对任何具体项目。它承载您的工作方式，到哪都一样：
# 全局偏好
- 总是用中文回答。
- 偏好简单的方案：更少依赖，更少抽象。
- 任何 sudo 或破坏性命令之前，先展示它并等我同意。
- 代码里不写显而易见的注释。注释「为什么」，不注释「是什么」。
写这么一次，每个新项目一开始就已经合您的手。
如何起步而不从零白手开始
您不必对着一张白纸手写项目文件。大多数智能体都会通过扫描您的仓库来生成它，然后您再打磨。
运行初始化命令
站到项目根目录，让智能体起草这个文件。
在 Claude Code 里，打那个专用命令：
/init
它会遍历仓库并写出第一版 CLAUDE.md（检测到的技术栈、脚本、结构）。
精简并修正
生成的草稿往往啰嗦，有时还会列出显而易见的东西。砍掉。保留那四个有用的板块，删掉一切代码已经说清楚的内容。这是您的文件，不是它的。
补上智能体猜不到的东西
一句话的目标、那些坑、谨慎规则：这些任何扫描都找不到。得由您来写。
记忆在摩擦中成长
别想着一次就写出完美的文件。记忆是在使用中建起来的，而且有一个非常清晰的信号：当您就同一件事第二次纠正智能体那天，就把这个纠正提升为一条规则。
它又写了一句没转义的 SQL 查询？→ 记忆里加一行。它每次都忘了提交前先跑 lint？→ 加一行。每一次反复出现的摩擦都变成一条规则，于是摩擦消失。这正是厘清需求指南里那个「↻ 再循环」：项目在活，记忆随它一起学习。