用 agent 久了，仓库总会长出一份越来越胖的 AGENTS.md 或 CLAUDE.md：某次踩坑加一条，审查时再补一条，三个月后它像部门制度汇编。模型不是完全不看，而是每次开工先吞下一大段过期背景；真正重要的规则埋在中间，遵守率反而下降。

问题不在于“记住经验”，而在于没有区分经验的寿命。一次排障结论、已经确认的仓库事实、反复出现的纠错，以及必须阻断的安全动作，应该去不同地方。Codex 把项目指导、记忆、技能、MCP 和子代理视为互补层，而不是让一份 AGENTS.md 包办全部。[4] Claude Code 也明确把人工指令和自动记忆分开：前者放规则，后者放项目中学到的模式。[2]

我会给每条新信息先贴一个“待晋升”标签。它默认只是一条候选，不进根目录指令文件。连续两次影响交付，或者一次就能造成数据、安全、兼容性事故，才进入下一层。这个门槛很小，却能挡住大部分情绪化规则：一次失败也许是偶然，第二次才说明它是环境里的稳定摩擦。

四层，不要混用#

第一层是会话证据：日志、临时笔记、失败命令和链接。它服务于当前任务，任务结束可以删除。第二层是 agent 的自动记忆，适合保存“这个仓库的迁移脚本要先生成快照”这类会在以后派上用场的事实。Claude 的自动记忆按仓库保存；子代理若启用自己的 memory，则使用独立目录，主会话的自动记忆不会直接传给普通子代理。[1][2]

第三层才是项目指令：稳定、每次都要遵守、能够直接验收的规则，例如构建命令、接口兼容边界、测试位置。Claude 建议把 CLAUDE.md 控制在约 200 行以内，把多步骤流程移到 skill 或按路径生效的规则里。[2] Codex 也建议 AGENTS.md 保持小，只记录每次都重要的仓库规则。[4]

第四层是可执行约束：pre-commit、CI、类型检查和 PreToolUse。它们不是“更强的文字提醒”，而是唯一能在模型判断失误时真正挡住动作的层。Claude 文档说得直接，记忆与指令只是上下文；若要无条件阻止某操作，应使用 PreToolUse hook。[2] 把“绝不能发布私钥”写进提示词还不够，扫描和阻断必须在代码路径上。

快速上手：把纠错变成可审计候选#

先在仓库创建一个很轻的登记文件。下面命令不会改运行配置，只会记录事实、触发次数和候选去向；date 的结果由本机生成，避免手填日期：

mkdir -p .agent
printf '%s\n' \
  '# 记忆晋升候选' \
  '' \
  '## 2026-09-30｜迁移脚本必须先 dry-run' \
  '- 证据：本周第二次因参数顺序导致错误环境被选中。' \
  '- 频次：2' \
  '- 建议去向：AGENTS.md（每次迁移前都适用）' \
  '- 验收：CI 运行 scripts/migrate --dry-run。' \
  >> .agent/promotion-candidates.md

每次复盘只填四项：证据、频次、建议去向、验收方式。没有证据的“模型总是很笨”不许入库；没有验收的“注意安全”也不许晋升。这样做并不追求文档漂亮，只是让下一次修改有东西可查。

然后用下面的规则做分类。反复发生且跨目录都成立的，写进根 AGENTS.md 或 CLAUDE.md；只和一个目录有关的，放到最近的目录指令或路径规则；需要多个步骤、示例或脚本的，做成 skill；能由机器判定的，直接进 CI。Codex 会从项目根向当前目录合并指导文件，靠近工作目录的文件后加载，能够覆盖较宽泛的规则。[3] 因此别把支付目录的约束写在根文件里，既浪费其他任务的上下文，也会让它看起来像一条可选建议。

# 每周只审候选，不自动“晋升”
grep -nE '频次：([2-9]|[1-9][0-9]+)|建议去向：CI' \
  .agent/promotion-candidates.md

审查时问一个不太舒服但很有用的问题：删掉这条以后，agent 会不会重复犯同一个、可描述的错？答案是否定，就保留在候选或记忆里。答案肯定，再看它能不能写成“运行什么、禁止什么、如何验收”。不能写清楚的规则，通常还没找对根因。

别让记忆变成暗箱#

自动记忆方便，但不要把它当权威配置。Claude 的文档指出，自动记忆与 CLAUDE.md 都是上下文而非强制配置；同时，自动记忆会由 agent 根据纠正和偏好积累。[2] 我会把影响发布、权限和数据的决定同时落到版本控制里的指令、测试或 hook，记忆只留原因、排查路径和易漏细节。

子代理尤其要克制。让一个专门的迁移 agent 维护项目级 memory，可以减少它反复摸索脚本位置；但把通用故障笔记塞给所有 agent，只会制造无关上下文。Claude 的项目级子代理 memory 可以随版本控制共享，官方也把它列为推荐默认范围。[1] 这不等于每个 agent 都该有 memory：一次性调研、短命的代码搜索，返回摘要更便宜。

最后，把晋升当成一次小型变更：候选链接到故障或 PR，规则写入恰当层级，补一条可执行验证，并在两周后回看是否还触发。规则从“有人提醒过”变成“仓库能证明”，agent 才不会在下一轮上下文压缩后又把同一个坑踩一遍。

Sources#

[1] https://docs.anthropic.com/en/docs/claude-code/sub-agents — Create custom subagents - Claude Code Docs [2] https://docs.anthropic.com/en/docs/claude-code/memory — How Claude remembers your project - Claude Code Docs [3] https://developers.openai.com/codex/guides/agents-md — Custom instructions with AGENTS.md | OpenAI Developers [4] https://developers.openai.com/codex/customization/overview — Customization | OpenAI Developers