Agent 技术博客系列 ：CLAUDE.md —— Agent 记忆落地终极方案
声明：本文为 Agent 技术博客系列第三篇，前两篇分别探讨了 Agent 本质 与 记忆金字塔工程原理。
嗨，我是小z。上一期拆完记忆金字塔之后，这一期，我们就把CLAUDE.md 机制拆开揉碎了聊。
目录
- 一、认知颠覆：CLAUDE.md 绝不是 README
- 二、源码级揭秘：大厂 Agent 记忆的四层套娃
- 三、新手如何写好一份高性能的 agent.md？
- 四、给独立 Agent 开发者的工程启示
一、认知颠覆：CLAUDE.md 绝不是 README
很多新手第一次看到项目根目录下的 CLAUDE.md 或 agent.md 时，第一反应是：这不就是给 AI 读的 README.md 吗？
这是极其致命的误区。
| 维度 | README.md（人类手册） | CLAUDE.md / agent.md（行为契约） |
|---|---|---|
| 核心目的 | 通知与客观描述（Inform） | 约束与强力管辖（Govern） |
| 行文风格 | 宏观、包容、解释性长句 | 微观、绝对、可立即执行/校验 |
| 典型句式 | 「我们项目采用标准的 ESLint 规范…」 | 「提交前必须执行 npm run lint，不接受任何带 any 的代码。」 |
| 读者 | 人类开发者 | LLM / Agent 推理引擎 |
| 长度 | 可长可短，鼓励详尽 | 控制在 200 行以内，只写核心约束 |
大模型在长对话中具有「上下文首尾偏好」——更容易记住最开始和最后面的指令。CLAUDE.md 作为 Agent 启动时强制加载的第一个文件，作用就是在 Agent 的初始状态机里灌入一条钢印：你在这个项目里，必须像一个资深工程师一样恪守军规。
这不是文档，这是行为契约。
二、大厂 Agent 记忆的四层套娃
根据被公开的工程细节，顶尖 Agent 工具并不是盲目把所有对话历史往 Context Window 里塞。它的记忆系统分成了四层，非常接地气：
+-------------------------------------------------------------+ | 1. CLAUDE.md（项目级军规）: 手动编写的硬性约束、构建/测试命令 | +-------------------------------------------------------------+ | 2. Auto-Memory（自动记忆）: Agent 在循环中踩坑后自己记录的日志 | +-------------------------------------------------------------+ | 3. Auto-Dream（记忆清理）: 闲置时自动运行的记忆合并与退化机制 | +-------------------------------------------------------------+ | 4. 背景常识 / 环境感知: 本地系统状态、工具反馈、依赖树 | +-------------------------------------------------------------+第一层：CLAUDE.md（静态显式记忆）
规定项目长什么样（WHAT）、为什么这么做（WHY）、如何测试与运行（HOW）。这是开发者在项目启动前就手动撰写好的，是 Agent 的「出厂设置」。
第二层：Auto-Memory（动态自发记忆）
这是最让我觉得巧妙的一层。比如 Agent 在编译你的 Python 或 C 代码时报错了，它通过看报错折腾了 3 轮才修好。这时它会悄悄在本地写一条 MEMORY.md 索引：「在当前环境下，遇到 X 报错需要改动 Y 配置」。下次启动，直接读取，绝不犯第二次错。
上一期我们聊过「记忆不是能力，是工程基建」——Auto-Memory 就是这句话最好的注脚。
第三层：Auto-Dream（记忆梦境清理）
当你在终端停止敲击代码时，Agent 会在后台启动一个微型 LLM 进程，把白天凌乱、碎片化的 Auto-Memory 进行精简、归并、删除过期冲突信息。
这完美对应了人类在睡眠中通过「做梦」来巩固和修剪记忆的神经机制。上一期我们讲了衰减权重 e^(-λ×Δt)，Auto-Dream 就是把这个数学公式变成了一个实际运行的后台进程。
第四层：环境感知
本地系统状态、工具调用反馈、依赖树——这些不需要显式存储，Agent 在每次 Think 阶段自然能感知到。
三、新手如何写好一份高性能的 agent.md？
如果你正在开发自己的 Agent，或者使用各类 Coding Agent，以下四个黄金原则可以直接拿去用。
原则 1：字数克制，实行「渐进式暴露」
大模型的指令遵循能力随提示词长度增加呈线性下降。
错误做法：把 300 页 API 接口文档全塞进 CLAUDE.md。Agent 既消耗巨额 Token，又开始对里面的规则「选择性失明」。
正确做法：控制在 200 行以内，只写最核心的命令。对于特定模块的规则，使用路径关联声明：
「关于认证模块的详细规约，请在修改相关代码前主动读取 @docs/auth-spec.md。」
原则 2：用强语气词，给出明确的终止/校验条件
Agent 最怕「我觉得做完了就停下」——这会导致你成为它的肉眼测试机。必须给执行状态机加上硬性卡点。
反面教材：「写完代码记得测试一下是否运行正常。」（过于宽泛，大模型会敷衍了事）
正面硬核：「修改任何几何算法代码后，必须在终端执行 pytest tests/test_graphics.py。若测试未通过，绝对禁止交付或提交。」
原则 3：结构化模块划分
一份经过大厂生产环境验证的 CLAUDE.md 分为三个核心板块。你可以直接复制并根据自己的项目修改：
# CLAUDE.md ## 1. 项目技术栈与图谱（WHAT & WHY） - **核心定位**: 一个基于 Python Tkinter 手写几何算法的 3D 渲染引擎实验项目。 - **核心约束**: 为深刻理解底层逻辑，**绝对禁止**引入任何第三方图形矩阵库（如 NumPy、OpenGL）。 所有矩阵旋转、坐标投影、裁剪逻辑必须用原生 Python 列表和数学库手写。 - **结束标识**: 输入流解析时，若遇到字符 `#`，必须视为输入结束并安全退出程序。 ## 2. 常用构建与验证命令（HOW） - **运行程序**: `python main.py` - **代码规范检查**: `flake8 . --count --select=E9,F63,F7,F82 --show-source` - **单元测试**: `pytest tests/` ## 3. 代码风格与架构军规（CRITICAL RULES） - **类型安全**: 所有新函数必须严格标注 Type Hints。 - **性能红线**: 在 3D 渲染主循环中，必须维持 Roberts 背面剔除与 Z-Buffer 的混合双缓冲算法， 严禁为图省事改回纯暴力扫描，这会导致 Python UI 卡死。 - **深度裁剪**: 必须在 3D 投影阶段前置进行深度裁剪，若遇到 `z >= cop_z` 必须提前切除， 防止发生逆向穿透渲染错误。原则 4：持续迭代，把踩过的坑写成规则
CLAUDE.md 不是一成不变的。每次 Agent 翻车后，把新的约束补进去。这本质上是在用人类经验给 Agent 的 Auto-Memory 打补丁。
四、给独立 Agent 开发者的工程启示
如果你正在手写上一期聊到的那个带 while True 循环的最小 Agent，Claude Code 这套文件记忆机制给了一个极其重要的启发：
不要把长期记忆寄托在复杂的分布式中间件上。
对于绝大多数垂直领域的 Agent：
- 启动时：用一个简单的 Markdown 解析器读项目根目录下的 agent.md，直接拼进 System Prompt。
- 运行中：让 Agent 拥有一个特殊的工具
write_to_local_memory(key, val)，在 while True 循环内部把踩坑经验以纯文本写入本地的.agent_memory/文件夹。 - 新任务开始前：利用操作系统的 grep 或最简单的语义 Embedding，做一次捞取。
大道至简。真正的工业级 Agent 架构，从来不是追求算法的玄学涌现，而是用确定性的工程文件，把不确定性的大模型死死框在轨道里。
这期写得比较「实操」，和前两期偏原理的风格不太一样。我自己写 CLAUDE.md 也就一个月不到，最大的感受是：你写得越像军规，Agent 就越像一个靠谱的同事；你写得像散文，它就真的给你散着来。
评论区说说你在 CLAUDE.md 里写过最狠的一条规则是什么，我去偷学一波。
感谢看到这里，评论+关注比点赞更有价值。
)
