记忆文件（CLAUDE.md 及其它）

关于代码智能体，有一个有点令人沮丧的真相：它们没有任何记忆。 您可以花两个小时讲解您的项目，把同一个错误纠正十遍，立下您的规则，可到了下一次会话，智能体又是一张白纸。它全忘了。LLM 只记得当前对话里装得下的东西。关掉窗口，一切烟消云散。

只有一样东西例外：记忆文件。这是一个文本文件，智能体会在每次会话启动时自动读取，甚至早在您打任何字之前。您只需写一次它该永远记住的东西。这正是让您不用再重复自己的东西。

这个文件，和它的全局孪生兄弟

所有智能体都会读一个记忆文件。名字随工具而变，但思路是一样的。

• Claude Code 读一个叫 CLAUDE.md 的文件。从 2.1.277 版起，项目里没有 CLAUDE.md 时，它也会读 AGENTS.md。
• Codex 读一个叫 AGENTS.md 的文件，从仓库根目录开始，一直读到您当前工作的子目录。它不会自己去读 CLAUDE.md，但在 ~/.codex/config.toml 里加一行，就能让它在缺少 AGENTS.md 的地方读取 CLAUDE.md：project_doc_fallback_filenames = ["CLAUDE.md"]。
• OpenCode 读一个叫 AGENTS.md 的文件，找不到时会退而读取 CLAUDE.md。

AGENTS.md 已经成为通用约定：除了 Codex 和 OpenCode，Cursor、Gemini CLI、GitHub Copilot 以及许多其他工具都会读它，这个格式如今由 Linux 基金会旗下的 Agentic AI Foundation 维护（agents.md）。想知道有哪些代码工具、各自提供哪些模型，可以看 Quelle IA 的工具页面（法语网站）。

机制相同，只是文件名不同。而且两种情况下，都存在两个层级：

• 项目文件，在您仓库的根目录。它描述这一个项目：它的目标、技术栈、规则。它随代码一起走，所以任何打开仓库的人（或智能体）都会继承它。
• 全局文件，在您用户的层级。它承载您永久的偏好，对您所有项目都生效。对 Claude Code 来说，它是 ~/.claude/CLAUDE.md；对 Codex 是 ~/.codex/AGENTS.md；对 OpenCode 是 ~/.config/opencode/AGENTS.md。

./CLAUDE.md          # 项目记忆（仓库根目录）
~/.claude/CLAUDE.md  # 全局记忆（您所有的会话）

./AGENTS.md              # 项目记忆（仓库根目录）
~/.config/opencode/AGENTS.md  # 全局记忆（您所有的会话）

./AGENTS.md              # 项目记忆（仓库根目录）
./子目录/AGENTS.md        # 某个目录专属的规则，在根目录的规则之后读取
~/.codex/AGENTS.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 或破坏性命令之前，先展示它并等我同意。
- 代码里不写显而易见的注释。注释「为什么」，不注释「是什么」。

写这么一次，每个新项目一开始就已经合您的手。

如何起步而不从零白手开始

您不必对着一张白纸手写项目文件。大多数智能体都会通过扫描您的仓库来生成它，然后您再打磨。

记忆在摩擦中成长

别想着一次就写出完美的文件。记忆是在使用中建起来的，而且有一个非常清晰的信号：当您就同一件事第二次纠正智能体那天，就把这个纠正提升为一条规则。

它又写了一句没转义的 SQL 查询？→ 记忆里加一行。它每次都忘了提交前先跑 lint？→ 加一行。每一次反复出现的摩擦都变成一条规则，于是摩擦消失。这正是厘清需求指南里那个「↻ 再循环」：项目在活，记忆随它一起学习。