Rules / Memory / Notes 的分层组织
系列入口：如何使用 Agent。单个文件怎么写，看 CLAUDE.md 指南。
一、核心思路：按「作用域」分层
规则不是写得越多越好，关键是让每条约定在合适的范围内生效。一条只属于某个项目的约定，放进全局配置，就会污染你其他所有项目；一条全局通用的偏好，每个项目各写一遍，又没法统一维护。
主流 Agent（无论叫 CLAUDE.md、.cursorrules、.rules 还是 memory）普遍支持按位置决定作用域，通常分三层：
二、三层分别放什么
- 全局层（Global / User）：跟具体项目无关、你在任何项目里都希望如此的个人偏好，比如默认用中文交流、注释风格、提交信息的个人习惯。它解决「我不想每次都交代一遍」。
- 项目层（Project Root）：这个仓库的核心信息——技术栈和版本、目录结构怎么组织、用什么命令构建和测试、不能碰的架构红线、团队协作约定。它让任何人和 Agent 一进项目就按同一套规矩办事，应纳入版本控制随仓库共享。
- 目录层（Subdirectory）：只在某个子系统成立的局部规则，比如「这个 services/payment 目录改动必须同时更新对账逻辑」。范围越窄的规则越该放低层级，避免污染别处。
一个经验法则：判断这条规则「离开这个范围还成不成立」——所有地方都成立放全局，只在本仓库成立放项目，只在某目录成立放目录。
为了让分层判断更具体，给你一组直接对照的例子：
- 「回答尽量简洁、默认中文」——任何项目都成立，放全局；如果写进某个项目文件，其他项目享受不到，还得重复写。
- 「本项目固定使用 Node 20 + pnpm，依赖版本锁死不要擅自升级大版本」——只在本仓库成立，放项目层，并纳入 git 让团队所有人和 Agent 都遵守。
- 「本项目的构建命令是
pnpm build:legacy，不是默认的 build」——典型的项目事实，放项目层，能避免它想当然跑错命令。 - 「services/payment 下任何金额计算改动，必须同步检查对账逻辑，且金额一律以分为单位」——只在该子目录成立，放目录层；若放项目全局，会让其他无关服务也背上不适用的约束。
分层最大的价值是避免两类浪费：该窄的规则放太宽，污染无关范围（甚至误导别的项目）；该宽的规则放太低，要么不生效、要么每层重复、改一处要改好几处。写每一条之前多问一句「它的适用边界到底在哪」，就能避开这两类问题。
三、rules / memory / notes 三类怎么分工
除了按层级，还可以按信息性质拆成不同文件：
| 类型 | 记什么 | 特点 |
|---|---|---|
| rules（规则） | 每次都要遵守的硬约定 | 长期稳定、自动注入 |
| memory（记忆） | 关于项目/你的事实与背景 | 「是什么」，随认知更新 |
| notes（笔记） | 调研、决策记录、临时事项 | 参考性质，未必每次加载 |
把「必须遵守的规矩」和「仅供参考的背景」混在一个文件里，会让规则淹没在叙述中，Agent 抓不住重点。拆开后，规则保持精简权威，记忆和笔记可以更详细、按需读取。
四、推荐的组织结构
一个可落地的做法（不同工具命名略异，结构相通）：
全局配置/
└─ CLAUDE.md # 个人通用偏好
项目根/
├─ CLAUDE.md # 项目级总规则：栈/命令/红线（纳入 git）
└─ docs/ 或 .claude/
├─ memory.md # 项目背景、关键事实
└─ notes/ # 决策记录、调研笔记（按需引用）
services/payment/
└─ CLAUDE.md # 目录级局部规则要点：
- 入口文件保持短，把详细背景拆到 memory/notes，用路径引用（配合渐进式披露）。
- 规则去重，同一条约定只在一层定义，下层引用而不复制。
- 冲突时具体层优先，这是排查「规则没按预期生效」的关键。
- 纳入版本控制的只放团队共识，个人临时偏好留在本地层。
这里再强调一下「入口文件保持短」背后的道理，它和前面讲的窗口预算直接相关。入口规则通常是每次任务都会自动注入的，也就是说它的长度在每一轮都固定占用窗口。一个几百行的巨型入口，意味着你在任务还没开始前就先交出去一大块预算，而且随对话拉长，这个固定开销会一直存在。把详细背景下沉到 memory/notes、只在需要时引用，本质上是在省每一轮的固定成本，也让真正的硬规则更突出。
这也正是渐进式披露思想在规则组织上的应用：最关键、最常用的约束放在最上层一眼可见，详细的、低频的信息分层藏好、按需读取。 你不需要让 Agent 一开始就掌握所有背景，只要保证它在需要某类细节时能顺着引用找到即可。理解了「自动注入 = 持续成本」，你在往入口文件里加内容时就会更谨慎，先问一句「这是否值得每一轮都加载」。
五、三类文件具体怎么写、怎么更新
知道分文件还不够，这里把 rules、memory、notes 各自的写法和更新节奏讲具体。
rules（硬规则）的写法：用简短、可执行的条目，一条只说一件事，优先写「不要 / 必须」这类边界清晰的约束；只写 AI 容易搞错、又不是常识的内容。例如「不要手动编辑 generated/ 目录下的文件」「提交前必须跑 pnpm test:e2e」。规则要保持稳定，频繁改动会削弱权威性，也说明可能把不该进规则的东西写了进去。
memory（背景记忆）的写法：用陈述句记录事实，带上必要的时间或条件，例如「（2026-09 确认）预发环境的数据库只读，写操作会被静默丢弃」。记忆的关键在更新——当事实变化时要主动修正或标注过期，否则一条旧记忆会持续误导。可以在每条记忆后附一个「最后确认」时间，帮助判断可信度。
notes（笔记）的写法：自由记录调研过程、决策理由、临时事项，按主题或日期组织，不必每次加载，需要时再引用。它适合承接「为什么当初这么决定」这类上下文，避免团队反复重蹈覆辙。
三者的更新触发点也不同：规则在发现反复出现的错误模式时增补；记忆在认知到新事实或事实改变时更新；笔记则在每次重要调研或决策后追加。一个健康的节奏是任务收尾时顺手扫一眼：这次有没有暴露出该固化的规则、有没有值得记下的事实或决策。把这些沉淀动作和日常工作绑定，规则体系就会随项目自然生长，而不是靠专门抽时间「补文档」。
六、一个把混乱收敛成结构的实例
看一个改造前后的对比，帮你把原则落到实际。某项目最初只有一个根目录规则文件，随着时间堆积，里面混着：个人的回复偏好、项目技术栈、某两个服务的特殊约定、几次调试的临时笔记、以及已经过期的旧命令，长达几百行。结果是 Agent 常忽略其中真正关键的约束，新成员也读不到重点，而且个人偏好被提交进了仓库。
一次整理把它拆成了这样：个人偏好移到全局层；项目根规则只保留技术栈、构建/测试命令、架构红线等团队共识，精简成几十条；两个服务的特殊约定下沉到各自目录；项目事实背景放进 memory；历次调试和决策记录移到 notes；过期内容直接删除或标注。整理后入口文件短而清晰，细节按需读取，每条约定唯一定义。这个例子说明，分层和分文件不是为了形式，而是让信息重新变得「可被准确使用」——同样的内容，组织方式不同，Agent 的表现和团队的协作成本会差很多。
七、规则没按预期生效，怎么排查
实际使用中常会遇到「我明明写了，它却不照做」。按下面顺序排查，通常能快速定位：
- 确认文件真的被加载了：位置和命名是否符合当前工具的约定？有些工具只识别特定文件名或需要显式启用。
- 确认作用域：这条规则所在的层，是否覆盖了当前正在操作的目录？目录层规则不会在它范围外生效。
- 查冲突：是否另一层写了相反的约定？多层同时存在且互相矛盾时，通常更具体的层优先，但不同工具实现可能不同，最稳妥是直接消除矛盾。
- 看信息是否被淹没：规则文件是不是又长又杂，关键约定被埋在大段叙述里？规则要精简、条目化。
- 区分「规则」与「提示」：规则本质仍靠模型读取后遵守，不是硬强制。确实不能违反的事，要用钩子在程序层兜底。
这里要特别提醒一个常见误解：写进规则 ≠ 100% 保证执行。 规则提高了一致性，但它仍是提供给模型的信息，存在被忽略的可能。对「一旦违反就严重」的约束（比如禁止强推主分支、禁止删库），应同时用钩子做硬性拦截，把规则和强制机制叠加，而不是只寄希望于它「读完会记得」。
八、文件该合并还是该拆分，怎么拿捏
分层分文件做久了，又会遇到一个新问题：文件太碎也不好管理。这里给你判断「合并 vs 拆分」的实用标准。
该拆分的信号：一个文件里同时服务于不同目的（既有硬约束、又有长篇背景），导致关键内容被淹没；或者文件里只有一部分适用于当前范围；又或者文件大到每次加载都是明显负担。出现这些，就按目的或作用域拆开。
该合并的信号：你发现自己维护了一堆各自只有两三行、且总是一起被读取的小文件；或为了找一条规则要在十几个文件间跳转。过度碎片化同样增加认知负担，此时把强相关、同作用域的内容收敛到一起更清晰。
拿捏的核心标准其实只有一条：文件边界应尽量与「作用域」和「使用时机」对齐。 总是一起生效、一起被读取、作用域相同的信息，放在一起；生效范围不同、或加载时机不同的信息，分开。好的组织不是文件越多越好、也不是越少越好，而是让「在某个任务时刻需要的信息」能够成组地、精准地出现，既不夹带无关内容，也不必四处拼凑。
最后给一个动态维护的视角：规则体系不需要一次设计完美，它应该随项目演进持续小步调整。定期（比如每隔一段时间或大版本节点）回头看一眼——有没有过期内容、有没有重复定义、文件结构是否还贴合现在的项目。让结构跟着真实使用反馈演进，比一开始追求完美模板更可持续。这也是这类知识资产管理的共同规律：先建立、再使用、持续整理。
九、多文件组织的两个反模式
把组织层面的典型错误也点一下：
- 反模式一：所有东西塞进一个巨型文件。 规则、记忆、笔记、临时事项全堆在一起，文件越来越长。结果是关键规则被稀释、每次还整体占用窗口、维护困难。应按性质拆分，入口文件保持短，细节下沉。
- 反模式二：同条规则层层复制。 怕某层不生效，就在全局、项目、目录各写一遍。短期看保险，长期一改就漏、版本还会互相打架。正确做法是只在一层定义，其他地方引用。
健康的结构应该满足：入口短而权威、细节按需读取、每条约定唯一定义、作用域清晰。这样既好维护，也让 Agent 能快速抓住真正要遵守的东西。
十、常见问题
Q：全局规则我该写多少？会不会影响所有项目？ 正因为影响所有项目，全局层更要克制，只放真正跨项目稳定的个人偏好，别把某个项目的技术约定写进去。全局规则宜少而稳，项目相关的一律下沉。
Q：项目规则一定要提交到 git 吗？ 属于团队共识、项目事实的规则应提交，让团队和 CI 环境共用同一套约定；你个人的临时偏好则留在本地、不要提交，避免把个人习惯强加给团队。
Q：目录层规则是不是越多越细越好？ 不是。只有当某个子目录确实有别处不适用的特殊约定时才加目录层；为了「显得规范」而大量添加，会造成维护负担和规则碎片化。先问「这条是否真的只在这里成立」。
Q：我怎么判断一条信息该进 rules、memory 还是 notes？ 问自己它的性质：是「每次都必须遵守的约束」进 rules；是「关于项目/我的事实背景」进 memory；是「某次调研或决策的记录、仅供参考」进 notes。拿不准时优先想——它是用来约束行为，还是用来提供背景。
如果你刚接触这套分层，不必一上来就搭完整目录，可以从最小动作起步：先在项目根写一份精简规则，把真正关键的约定放进去；等发现某条规则只适用于某个子目录时，再把它下沉；等规则和背景开始混杂、文件变长时，再拆出 memory 和 notes。让结构由真实需求驱动、随使用自然长出来，比一开始套用复杂模板更容易坚持，也更贴合你的实际项目。等这套习惯稳定后，你会明显感受到 Agent 在不同范围里都能按预期方式工作，而这正是把使用经验沉淀成可复用资产的开始。
总结
把规则当成有作用域的系统来分层：通用偏好放全局、项目约定放根目录、局部规则放子目录，硬规矩和背景笔记再分文件管理——约定才能在正确的范围内自动生效，而不是要么不生效、要么全局污染。