agent 每开一个新会话都是失忆的。项目记忆文件就是你留给它的那张便条。 但便条写长了等于没写——约束的力度和数量成反比。 这一篇讲怎么写才真的生效，以及一条最常见的泄漏路径。
本文写什么该写什么、不该写什么、怎么验证生效。 本文不写我们自己的记忆文件内容。
不同工具叫法不同（CLAUDE.md、AGENTS.md……），
机制是一样的：把这个文件的内容塞进每次会话的开头。
知道机制就能推出两条结论，后面全部由此而来：
| 因为 | 所以 |
|---|---|
| 它占的是上下文预算 | 写得越长，留给真正干活的空间越少，而且每一条的相对权重都被摊薄 |
| 它是文本，不是执行的规则 | 模型是「读到并倾向遵守」，不是「被强制」。真要拦住的事，得靠权限配置 |
50 条规则和 5 条规则，遵守率不是一回事。50 条里每一条都只是背景噪声中的一行； 5 条里每一条都显眼。
所以正确的动作不是「想到什么加什么」，而是定期删。 一条规则如果三个月没救过你一次，它就是在稀释别的规则。
判据一句话：它能从代码里看出来的，就别写。
| 写 | 不写 | |
|---|---|---|
| 构建 | 「测试要用 make test，不是包管理器默认那条」 | 项目用什么语言（它自己看得见） |
| 约定 | 「这个目录下的文件是生成的，别手改」 | 缩进几个空格（配置文件里有） |
| 边界 | 「别碰 migrations/，那要人工审」 | 泛泛的「请写高质量代码」 |
| 陷阱 | 「本地跑要先起某个依赖服务，否则报错很误导」 | 能从 README 读到的 |
| 口味 | 「回答用中文」「先说结论」 | — |
一个好用的自检：每一条前面都能补上「不然它会……」。补不出来的，删掉。
这是最常见的泄漏路径，而且泄漏方式有三层，很多人只想到第一层：
① 这个文件通常要进 git（团队共享才有意义）→ 进了 git 就进了历史，删掉也还在；
② 它每次会话都被读进上下文 → 等于每一次请求都把它发出去一遍；
③ 团队里任何人 clone 都拿到，包括以后离职的人。
正确做法：文件里只写「去哪里取」——「密钥在环境变量 SOME_KEY 里」。
写位置，不写值。
这个文件的内容会被当成上下文读入。如果你把外部来源的文本（issue 正文、爬来的网页、 第三方 README）整段粘进去，里面万一夹着「请执行……」这样的句子， 就成了一条你亲手放进来的指令。
要引用外部内容，自己转述一遍，别原样搬运。
写完别假设它在起作用，花一分钟验一下：
| 验什么 | 怎么验 |
|---|---|
| 读到了吗 | 新开一个会话，直接问它「这个项目有哪些约定」，看它复述得对不对 |
| 照做了吗 | 让它做一件会触碰某条规则的小事，看它有没有绕开 |
| 哪一份生效 | 项目层和用户层可能都有；拿不准就直接问它读到了哪些 |
第一版一定写多了。跑一周，把「从来没被触发过」的条目删掉。 项目记忆是要修剪的，不是要积累的。
CLAUDE.md、AGENTS.md 等）。deny），不能指望写在记忆文件里。