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 --selectE9,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 循环的最小 AgentClaude 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 里写过最狠的一条规则是什么我去偷学一波。感谢看到这里评论关注比点赞更有价值。