最近我注意一个很有意思的现象很多人的 CLAUDE.md 从最初十几行的“项目说明书”慢慢滚成了上千行的“规则垃圾场”。这不是个别现象在 Agentic Coding 社区里几乎成了通病。文件无限膨胀之后Claude Code 这个 AI 编码代理并没有变得“更听话”反而开始行为漂移关键规则被忽略新规则覆盖旧规则甚至出现 D 错、A 对但代理坚持执行 D 的情况。这种现象现在被不少开发者叫做Catastrophic Remembering——灾难性记忆。它是经典机器学习里 Catastrophic Forgetting灾难性遗忘的镜像问题模型不是把旧知识忘了而是把“记忆文件”记录得太杂、太满导致它提取有效信息的能力反而下降。如果你也在用 Claude Code、Cursor 这类 Agentic Coding 工具并且维护着一个越来越长的 CLAUDE.md这篇文章会讲清楚三件事CLAUDE.md 为什么会不断增长背后有哪些工程原因Catastrophic Remembering 在 Agentic Coding 里具体怎么破坏编码智能体的行为怎么用分层记忆、索引式加载、定期重构等手段把 CLAUDE.md 治理成一份真正高信噪比的项目记忆。下面直接进入正文。1. CLAUDE.md 是什么Agentic Coding 的项目记忆层CLAUDE.md 是 Claude Code 在项目目录下读取的 Markdown 记忆文件。它通常放在仓库根目录Claude Code 每次启动会话时都会自动加载把它当作项目级系统提示词来使用。它的定位非常清晰给 AI 编码代理提供关于项目结构、技术栈、运行命令、代码规范、架构约束、常见坑位的长期记忆。理论上CLAUDE.md 写得越好代理在后续代码生成、重构、测试、排错时就越贴合项目实际。从 Agentic Coding 的角度看CLAUDE.md 属于“显式长期记忆层”。Agent 的工作记忆是会话上下文而 CLAUDE.md 是跨越会话持久存在的记忆载体。正因为它会被自动加载很多开发者会不自觉地往里面塞越来越多内容项目背景和技术栈说明常用命令和脚本路径代码风格约定架构注意事项历史踩坑记录用户的个人偏好团队成员补充的各类规则。问题在于CLAUDE.md 本身没有被当成“代码”来维护。没有 review、没有重构、没有删除策略内容只增不减。三周之后它就会从一份精炼的项目说明变成一份缺乏结构的巨型文档。这里有一个关键认知CLAUDE.md 不是知识库而是“行为约束文件”。它最重要的作用是让代理在行动之前知道边界在哪。当它膨胀之后边界就被淹没了。2. Catastrophic Remembering当“记得太多”反而破坏编码智能体Catastrophic Forgetting 是模型学新知识时忘掉旧知识。Agentic Coding 场景里的 Catastrophic Remembering 正好相反记忆系统试图记住一切结果导致模型对关键信息的提取和遵循能力下降。具体来说它有四个典型的破坏路径。第一注意力稀释。LLM 对长上下文的处理能力是有限的。CLAUDE.md 越长每条规则分配到的注意力权重就越低。项目开始时写下的“禁止修改 src/core 模块接口”这类强约束会被后面几十条“某某模块要加日志”的弱规则冲淡。最终表现是代理开始选择性失明看得到新写的规则看不到早先的核心约束。第二指令冲突累积。当 CLAUDE.md 超过一定体量后不同时间追加的规则必然产生矛盾。比如一个月前写“所有 API 返回类型统一使用 interface”两周后又写“新增服务模块使用 type 定义”。代理面对冲突指令时通常会采取“就近原则”或“合并原则”结果就是代码风格混乱而且是不可预测的混乱。第三幻觉性记忆合并。上下文越长模型越容易把语义相近但不相同的规则“合并”成一条新规则。这比直接遗忘更危险。代理可能把“测试目录不允许提交快照文件”和“测试文件允许快照断言”合并成“测试相关文件都放到 snapshot 目录”然后按照这个幻觉规则去生成代码开发者在 review 时往往很难发现。第四行为不可回放。一旦 CLAUDE.md 膨胀到几百行甚至上千行你就无法判断代理当时到底基于哪几条规则做出了决策。出了 bug 想回放结果发现文件已经变了。整个 Agentic Coding 流程失去可解释性。这是最让工程团队头疼的一点你没法对一个不可解释的编码代理追责只能不断加新规则然后陷入更深的膨胀循环。总结一句话Catastrophic Remembering 的本质是记忆信噪比崩溃。问题不在于模型记不住而在于记忆库里噪声太多模型无法判断什么是真正重要的事。3. CLAUDE.md 为什么会不断长大六大常见增长源要治理膨胀先要知道它是怎么发生的。根据大量 Agentic Coding 项目的实际维护情况CLAUDE.md 的增长主要有六个来源。3.1 “只追加不重构”的根因绝大多数 CLAUDE.md 的增长来自简单追加。代理解决了一个问题开发者在文件末尾补一段“以后遇到此类问题请这样做”。这种行为本身没错错在没有人做合并、去重、删除。长期累积文件就变成了流水账。3.2 每条经验都占一个独立小节很多人习惯一条经验一个小节。几十条经验就是几十个小节光目录就占了几十行。更麻烦的是很多小节内容高度重叠。比如“构建命令”可能被写了三次第一次写“使用 npm run build”第二次写“Windows 下使用 npm run build:win”第三次写“发布前必须先 npm run build”。内容不冲突但严重冗余。3.3 把 HOW 写成了 WHAT优质 CLAUDE.md 应该写“必须做什么、禁止做什么、为什么这样做”但实际增长中大量内容是“怎么做”。比如“如果遇到编译报错可以尝试删除 node_modules 重新安装”。这类 HOW 内容适合放进 docs/ 或者项目 README放在 CLAUDE.md 里只会稀释约束性指令。3.4 例子过多规则过少为了让代理理解很多 CLAUDE.md 会附带大量代码示例。代码示例不是不能用但每个示例都占用上下文。规范应该用一句话说清楚示例只保留一个最典型的。3.5 多人协作导致规则叠加团队项目里每个人都会按自己的偏好往 CLAUDE.md 里加内容。前端加一条代码风格后端加一条接口规范测试加一条夹具命名规则。每个人的单次追加都合理合在一起就是一个互相冲突的巨型文档。3.6 把 CLAUDE.md 当成了对话记录这是最隐蔽的增长源。有些开发者把和代理对话中获得的解决方案直接粘贴进 CLAUDE.md甚至保留“用户问xxx代理答xxx”的结构。这种内容对长期记忆完全无效只会让文件迅速膨胀。增长源明确后治理思路也就清晰了CLAUDE.md 必须像代码一样定期重构做减法。4. 快速自查你的 CLAUDE.md 是否已经失控在动手重构之前先用一张表自查。下面的信号如果命中三条以上说明 CLAUDE.md 已经处于失控边缘。警告信号可能原因处理动作文件总行数超过 200 行内容积累过久缺乏重构按章节拆分核心文件保留 80 行以内同一主题出现 3 个以上小节追加式维护没有合并合并同类项只保留一条规则包含大量“如果…可以尝试…”的 HOW 描述可执行步骤混入长期记忆移入 docs/CLAUDE.md 只保留索引新旧规则冲突代理行为不稳定指令矛盾未消解逐条冲突审查废弃旧规则团队成员各自追加无人审核缺少 CLAUDE.md 变更流程建立 review 制度变更需提交说明代理经常忽略文件里最开头的规则注意力稀释关键约束被淹没核心规则前移到顶部并缩短表述无法解释代理为什么执行了错误操作记忆不可回放信噪比崩溃做一次完整重构记录规则版本自查的目的是判断严重程度不需要精确量化。只要发现需要翻很久才能定位到某条规则就已经该治理了。5. 记忆架构设计构建可持续的 CLAUDE.md 分层体系CLAUDE.md 不是不能长而是要学会分层。合理的架构是核心文件保持短小详细内容通过按需加载获取。这里推荐一套三层记忆架构。5.1 第一层根目录 CLAUDE.md这一层只放全局性、不可协商的规则。目标控制在 80 行以内。它必须包含项目的核心用途和定位最重要的三条技术约束不可触碰的模块或目录常用命令的简短索引需要进一步阅读时指向哪些文件。核心原则是根目录 CLAUDE.md 里的每一条都应该值得代理每次都读。如果某条规则不是每次都生效它就不该存在这一层。5.2 第二层docs/ 下的主题文档把具体的技术细节、环境搭建、构建流程、API 设计规范拆到 docs/ 目录。CLAUDE.md 里只写一句话索引比如“API 设计规范见 docs/api-design.md新增接口前必须阅读”。这样做的原因是LLM 是按需读取的。代理在写接口代码时可以通过读取 docs/api-design.md 获取规范而不必在每次请求中携带全部规范。相比之下根目录 CLAUDE.md 是每次请求都会投入上下文的内容体积必须最小化。5.3 第三层CLAUDE.d/ 分类目录如果你的团队对 CLAUDE.md 有非常细的分类需求可以使用 CLAUDE.d/ 目录把规则按领域拆分CLAUDE.md CLAUDE.d/ frontend.md backend.md testing.md workflow.md根目录 CLAUDE.md 只写一行说明按领域规则阅读 CLAUDE.d/ 下的文件。这种方式适合大型仓库但要注意规则文件数量不宜过多否则代理在“该读哪个文件”上也会消耗上下文。5.4 三层架构的读取策略把“每次读”和“按需读”分开是控制 CLAUDE.md 膨胀的关键。每次读意味着消耗固定 token按需读只在相关任务出现时才消耗 token。这套策略能直接把上下文压力从“O(全部记忆)”降为“O(核心规则 当前任务相关规则)”。6. 实操从零重构一个高信噪比的 CLAUDE.md下面给出一套可直接执行的重构流程。6.1 第一步导出完整版 CLAUDE.md 并做分段标记先备份原始文件cp CLAUDE.md CLAUDE.md.bak然后给原文件按内容分组统计每个主题占用的行数。可以用下面这个 Python 脚本辅助分析章节分布from pathlib import Path content Path(CLAUDE.md).read_text(encodingutf-8) lines content.splitlines() current 开头 stats {} for line in lines: if line.startswith(#): current line.strip(# ).strip() stats.setdefault(current, {lines: 0}) else: stats.setdefault(current, {lines: 0})[lines] 1 for section, info in stats.items(): print(f{section}: {info[lines]} 行)这个脚本会输出每个小标题下的行数帮你快速找出哪些部分是膨胀重灾区。6.2 第二步标记“强制约束”和“参考资料”把原始内容分成三类A 类强制约束。比如“禁止修改 src/db/schema.ts”“提交信息必须包含 issue 编号”。这类内容保留在根目录 CLAUDE.md。B 类按需参考。比如“API 设计规范”“构建签发流程”。这类内容移到 docs/。C 类对话记录、重复内容、过时规则。直接删除或归档。分类时建议用表格记录决策原内容位置分类处理动作目标位置第 3 节构建命令B移出docs/build.md第 7 节禁止修改 schemaA保留并精简CLAUDE.md第 12 节某次 bug 排查记录C删除无6.3 第三步编写新的核心 CLAUDE.md重构后的 CLAUDE.md 应保持紧凑结构参考如下# 项目名称 ## 项目定位 一句话说明项目做什么服务于谁。 ## 技术栈 列出核心语言、框架、构建工具。不要展开版本历史。 ## 非协商规则 - 规则一禁止修改 src/db/schema.ts 中的已有字段。 - 规则二所有新增 HTTP 接口必须使用 错误码 200。 - 规则三提交信息必须包含关联 issue 编号。 ## 常用命令 - 本地启动npm run dev - 测试npm run test - 构建npm run build ## 按需阅读索引 - API 设计规范docs/api-design.md新增接口前必读。 - 构建发布docs/release.md发布前必读。 - 前端组件规范docs/frontend-components.md开发页面时阅读。这份文件大概 30 到 50 行。它把原始版本里最核心的信号保留下来其余全部外置。6.4 第四步拆分详细资料到 docs/按照索引把原始 CLAUDE.md 里的详细内容写入对应文档。以 docs/api-design.md 为例# API 设计规范 ## 通用原则 - 所有请求必须包含 request_id。 - 分页参数统一为 page 和 page_size。 ## 错误码 - 200成功。 - 400参数错误。 - 401未授权。 - 500服务端内部错误。 ## 示例 ...注意docs/ 下的文档也可以继续膨胀但它不会进入每次请求的默认上下文只有代理需要时才会读取。这就是记忆文件治理和普通文档管理的核心区别。7. 效果验证怎么确认规则回归与行为稳定性重构后不能只看文件行数变小还要验证代理行为真的更稳定。推荐做一组规则回归测试。7.1 建立回归测试任务集准备 5 到 10 个固定任务覆盖你最重要的规则。例如任务一运行完整测试套件观察代理是否正确执行了所有测试命令。任务二让代理新增一个模拟接口观察它是否遵守“必须返回错误码 200”的约束。任务三让代理修改一个受保护目录中的文件观察它是否主动拒绝或提出警告。任务四让代理编写一段提交信息检查是否包含 issue 编号。任务五让代理解释项目的技术栈观察引用是否准确。这组任务的核心不是看代理能不能完成而是看它有没有“记得”那条约束。7.2 对比清理前后的表现在重构前跑一遍任务集记录结果重构后重新启动新会话再跑一遍。对比维度维度重构前表现重构后表现关键规则遵循率主观观察代理是否忽略核心约束是否严格遵守命令执行正确性是否使用了过时命令是否按新命令执行回答信息密度是否夹带大量无关记忆是否直接命中要点上下文长度每次请求 token 消耗是否明显下降这个对比不需要做严格统计但建议保留任务输出截图或日志方便后续追溯。7.3 验证按需读取机制如果 CLAUDE.md 里写了“新增接口前阅读 docs/api-design.md”可以刻意在接口规范里加一条明显的标识规则比如“所有新增接口的注释必须以[API-DESIGN]开头”。然后在代理起草接口代码时观察它是否真的读取了 docs/api-design.md并遵守了新规则。如果它没有读取说明你的索引式指令不够强需要把“必须阅读”改得更明确。8. 接口与自动化用脚本辅助 CLAUDE.md 审计与拆分CLAUDE.md 的维护可以借助脚本实现半自动化。这里给出两个实用的自动化方向。8.1 行数与主题分布审计脚本在 CI 或 pre-commit 阶段加入一个简单检查防止 CLAUDE.md 超过行数阈值from pathlib import Path import sys MAX_LINES 200 path Path(CLAUDE.md) if not path.exists(): sys.exit(0) line_count len(path.read_text(encodingutf-8).splitlines()) if line_count MAX_LINES: print(fCLAUDE.md 行数超限{line_count} {MAX_LINES}请考虑拆分。) sys.exit(1) print(fCLAUDE.md 行数正常{line_count} 行。)这个脚本可以作为 CI 检查项让 CLAUDE.md 不通过“超长”检测。阈值可以根据项目实际情况调整初期可以设 300 行逐步收紧到 150 行。8.2 调用大模型 API 做规则摘要与冲突检测如果 CLAUDE.md 已经很长可以把它交给大模型 API 做结构化摘要。下面是一个通用示例实际接口路径和请求参数需要按你使用的模型服务调整import os import requests api_key os.environ.get(LLM_API_KEY) url https://api.anthropic.com/v1/messages # 示例按实际服务替换 content Path(CLAUDE.md).read_text(encodingutf-8) payload { model: claude-sonnet-4-5, # 按实际模型服务调整 max_tokens: 4000, messages: [ { role: user, content: ( 请对以下 CLAUDE.md 做结构化分析\n 1. 提取所有强制约束并为每条约束标注强弱程度\n 2. 找出互相冲突的两条规则\n 3. 将内容按‘必须遵守’‘按需参考’‘可删除’三类分组。\n\n f{content} ), } ], } headers { x-api-key: api_key, anthropic-version: 2023-06-01, content-type: application/json, } response requests.post(url, headersheaders, jsonpayload, timeout120) print(response.json())这个脚本的价值在于可以把人工 review 的工作量压缩到“审核 AI 分组结果”而不是从头读一遍几百行的 CLAUDE.md。与这种自动化辅助同理如果你把 CLAUDE.md 接入 MCP 记忆服务也可以做成“按需加载”的方式代理不再一次性读取全部记忆而是通过函数调用查询当前任务相关的规则。这比单纯拆分文档更进一步适合中大型团队。9. 性能观察CLAUDE.md 膨胀对 token、延迟与成本的影响很多人忽略一个问题CLAUDE.md 不是免费的。它的内容会进入每次请求的上下文窗口直接影响 token 消耗、推理延迟和处理成本。从工程角度看CLAUDE.md 相当于给每个请求增加了一个固定大小的“系统提示词前缀”。文件越长前缀越大。在 Agentic Coding 的一次长会话中Agent 可能要发起几十次甚至几百次模型请求每次请求都携带这段前缀token 消耗是按几何级数叠加的。不需要记住具体数字只需理解以下几个结论CLAUDE.md 从 50 行涨到 500 行每次请求的输入 token 会显著增加Agentic Coding 会话请求次数多累积成本增长远大于文件本身的字数上下文窗口接近上限后模型处理长文本的稳定性和响应速度都会下降如果同时启用 MCP 工具、代码索引、终端反馈CLAUDE.md 占用的上下文比例越高真正用来分析代码和生成内容的窗口就越小。用一句话说CLAUDE.md 是记忆也不是永久免费的记忆。每次读取都有成本。控制 CLAUDE.md 体量就是在控制 Agentic Coding 的运营成本。在实际工作流里建议每次重构后记录一次“单请求输入 token 数”。方法很简单在会话开始时请模型输出当前请求包含的 token 估算或者查看 API 日志里的 usage 字段。对比清理前后的 usage成本下降会很明显。10. 常见问题与排查方法这一节整理实践中容易遇到的问题。问题现象可能原因排查方式解决方案代理经常忽略 CLAUDE.md 里的核心规则规则被大量噪声稀释查看 CLAUDE.md 总行数和主题分布重构为核心文件 docs/ 索引新会话行为与上一次不一致上下文漂移或规则冲突检查是否有新增规则与旧规则矛盾清理冲突规则保留唯一版本代理引用了已删除的模块或接口记忆文件里残留过时信息搜索 CLAUDE.md 中的旧模块名删除过时内容加入“删除记录”说明CLAUDE.md 行数快速增长团队追加式维护无审核查看 git log 中 CLAUDE.md 变更建立 review 和 CI 行数检查代理在长会话中响应变慢上下文窗口占用过大观察 usage 字段或响应时间缩减 CLAUDE.md降低每次请求 token代理回答里出现幻觉性合并规则长上下文导致语义混淆对比原始规则和代理输出减少规则数量原子化表述按需阅读的 docs/ 文档没被读取索引指令不够明确在规范文档中加入唯一标识词在 CLAUDE.md 中使用“必须阅读”的强指令排查时有一个通用思路先定位上下文里哪些内容占用最大再看这些内容是否每次都需要。删除永远比新增更能稳定行为。11. 安全与合规边界CLAUDE.md 是项目记忆层但它也容易成为敏感信息泄露点。这里明确几条安全底线不要把密码、API Key、数据库连接串写入 CLAUDE.md也不要写入 docs/ 下的参考文档。如果发现代理在工作流中自动生成了包含密钥的 CLAUDE.md 内容立即清洗并轮换相关密钥。涉及商业项目时CLAUDE.md 里的架构描述不可过度详细防止仓库被分享或泄露时暴露关键设计。Agentic Coding 生成的代码尤其是重构、批量修改类任务必须经过人工 review。CLAUDE.md 可以约束行为但无法替代 code review。如果项目涉及用户数据、隐私数据务必在 CLAUDE.md 中写明“禁止将生产数据带入本地调试”并验证代理遵守情况。安全规则本身就是最高优先级的记忆。一旦安全约束被淹没在膨胀的 CLAUDE.md 里它就不再是保护而是隐患。12. 最佳实践让 CLAUDE.md 保持“小而有价值”基于前文的分析这里总结一套可行的维护规范。12.1 把 CLAUDE.md 当代码对待CLAUDE.md 应该有版本管理、review 流程、行数上限、变更说明。它和 src/ 下的源码没有本质区别都是需要维护、需要重构、需要删减的工程产物。12.2 采用“核心文件 按需索引”的结构根目录 CLAUDE.md 控制在 80 到 150 行只放非协商规则和常用命令索引。详细内容按主题拆分到 docs/ 或 CLAUDE.d/由代理按需读取。12.3 原子化表达规则每条规则只表达一个动作禁用“并且”“同时”堆叠多个约束。例如“所有接口必须返回错误码 200”是一条原子规则“所有接口必须返回错误码 200并且使用 interface 定义请求体同时日志里记录 request_id”就会增加冲突概率。12.4 定期做记忆清理建议每两周或每次里程碑结束后对 CLAUDE.md 做一次清理。重点检查哪些规则已经被默认执行不再需要显式声明哪些规则与当前项目状态冲突哪些内容可以移到 docs/哪些记录已经过时。12.5 维护规则变更日志如果团队多人维护建议在 CLAUDE.md 末尾保留一个极简变更记录区## 变更记录 - 2025-06-01新增接口错误码规范来源 PR #233。 - 2025-05-20移除旧版构建命令改用 pnpm。变更记录可以放在 CLAUDE.d/ 文件夹中避免占用核心 CLAUDE.md 的空间。它的作用是让开发者能追溯“代理为什么按这个规则执行”让记忆文件保留可解释性。13. 总结与下一步CLAUDE.md 增长的根源不是“AI 需要更多记忆”而是“开发者用追加代替了重构”。只要这个逻辑不变文件就会一直膨胀Catastrophic Remembering 就会持续破坏 Agentic Coding 的行为稳定性。这次重构的重点不是删行而是建立一套可持续的记忆架构核心文件保持短小、详细内容按需读取、规则原子化、变更可追踪。如果只做一件事建议先把根目录 CLAUDE.md 压到 100 行以内把其余内容拆到 docs/ 目录并加一条 CI 检查防止它再次膨胀。之后再观察代理的行为表现和数据表现你会发现同样一个模型同样的代码库只靠一份更干净的 CLAUDE.md执行质量就能肉眼可见地提升。下一步可以继续做几件事把 CLAUDE.md 接入版本管理并建立 review 规则用脚本做定期的规则冲突检测在团队内部推动“记忆清理周”机制。Agentic Coding 的价值在于代理能自主执行任务而 CLAUDE.md 的价值在于让这种自主执行始终不偏离项目边界。边界清晰代理才敢跑得更远。