CLAUDE.md越写越长，AI却越不听话？破解Agentic Coding的灾难性记忆

之前在一个 agentic coding 项目里我发现CLAUDE.md从最初几十行的“项目说明”慢慢长成了上千行的“规则大全”最后每次让 AI 助手改代码它反而越来越犹豫甚至会因为读了太多互相矛盾的规则而做出错误决定。这个现象很常见社区里也有人把它叫做 Agentic Coding 场景下的Catastrophic Remembering灾难性记忆。本文就从这个问题出发拆解 CLAUDE.md 为什么会不断膨胀、膨胀后会带来哪些危害以及如何设计一份真正“好用”的 CLAUDE.md。1. 从一个现象说起CLAUDE.md 为什么越来越长1.1 问题从“想让 AI 记住更多”开始CLAUDE.md是 Claude Code 等 agentic coding 工具中用来承载“项目级长期记忆”的约定文件。简单来说它是你给 AI 助手看的项目说明告诉它这个项目是干什么的、代码结构如何、有哪些约定、哪些命令不能乱执行。开发的直觉会告诉我们既然 AI 每次都重新开始对话容易“失忆”那我们就把约定写得越全越好让它记住更多项目背景。于是几乎所有团队都会经历这样一个过程第一次使用写 50 行的项目简介。运行时报错了把报错规避方法补进去。代码风格不统一把命名规范补进去。部署踩坑了把环境配置注意事项补进去。发现 AI 忽略了某个约束再把这约束用更强烈的语气写一遍。每一条补充看起来都很合理。但半年之后再打开CLAUDE.md你会发现前面写的内容和后面写的内容可能已经互相矛盾AI 读完整个文件后不仅没有变得更“懂你”反而不知道应该听谁的。1.2 这不是个例是一种系统性现象单独看某个团队会觉得这只是“文档管理差”。但把视角拉高你会发现这是 agentic coding 模式下必然会出现的系统性问题AI 助手本身有上下文窗口限制窗口再大也有边界记忆文件会随项目周期无限增长但窗口长度不会无限增长信息越多冲突越可能发生规则之间没有优先级排序时模型只能靠概率猜测取舍。所以我们看到的现象本质是在 Agentic Coding 中AI 的记忆不是越多越好而是越有效越好。如果“记住的东西”压制了“理解的东西”就会产生一种反向效果——AI 看似读取了很多信息实际执行能力反而下降。2. 核心概念CLAUDE.md、Agentic Coding 与灾难性记忆2.1 CLAUDE.mdAI 助手的“组织记忆”从形式上看CLAUDE.md就是一个 Markdown 文件放在项目根目录或者显式指定的目录中。AI 编码工具在启动后会优先读取它用于理解项目背景。它和一个普通README.md的区别在于README.md主要是给人看的侧重项目介绍、安装方式、使用示例CLAUDE.md主要是给 AI 看的侧重行为规则、代码约束、执行边界、禁止事项。换句话说CLAUDE.md是连接“团队隐性知识”和“AI 显式行为”之间的桥梁。如果团队有“数据库表结构变更必须写迁移脚本”这条约定但没有写进CLAUDE.md那么 AI 在生成代码时就不会主动遵守。2.2 Agentic Coding让 AI 自己规划并执行任务Agentic Coding 指的是一种新型编程模式AI 不再只是“自动补全工具”而是具备任务拆解、代码编写、命令执行、结果验证等多步能力的“智能体”。典型的流程是开发者提出一个需求AI 分析任务、拆解步骤AI 读取项目结构、搜索相关代码AI 修改代码并执行测试AI 根据结果自我修正。在这种模式下AI 不再只靠单轮 prompt 工作而是需要在一段较长的持续工作流中保持方向不偏。这就要求它必须有一个稳定、清晰、可检索的“长期记忆”文件作为行为基准。2.3 Catastrophic Remembering记住太多反而忘了重点机器学习领域有一个经典概念叫Catastrophic Forgetting灾难性遗忘指模型在学习新知识时可能会迅速遗忘旧知识。而Catastrophic Remembering并不是一个严谨的学术术语更多是 agentic coding 实践中总结出来的现象它的含义可以理解为当 AI 的记忆内容不断堆积且没有合理的分层、去重和优先级机制时AI 会因为“记住了太多信息”而丧失对关键信息的判断力最终表现得像“忘记”了最重要的规则。举个例子规则 A所有数据库修改必须通过 migration 脚本执行。 规则 B鉴于线上数据紧急修复场景较多可以临时修改线上数据库但要执行备份。 规则 C如果时间紧急可以跳过繁琐流程优先完成任务。单独看每一条都有道理。但三条放一起AI 在执行“紧急修复”需求时就会犹豫到底走 migration、还是直接改数据库、还是跳过备份。最后它选了一条最保守或最激进的路径但可能都不是团队真正想要的。2.4 三个概念怎么串起来Agentic Coding 让 AI 有了自主完成任务的能力CLAUDE.md 是 AI 完成任务的“记忆底座”而 Catastrophic Remembering 是“记忆底座失控”后的典型表现。也就是说CLAUDE.md 本身没有错错的是我们维护它的方式。本文后面所有内容都在围绕“如何让 CLAUDE.md 保持精炼、稳定、可执行”展开。3. 为什么 CLAUDE.md 会不断膨胀四大根因分析3.1 记忆累积的“正常机制”每条规则都曾解决过一个问题CLAUDE.md 膨胀的第一个原因是几乎每一条新增内容都曾经解决过某个真实问题。在 agentic coding 应用中AI 一旦犯错开发者最自然的反应不是去分析为何 AI 会“误解上下文”而是“把这条规则写进 CLAUDE.md下次它就不会再犯”。这种操作没有错但它会让 CLAUDE.md 变成一本“错误修补记录”。比如AI 误删了某个目录下的旧文件于是你写了“禁止删除 src/main/resources/legacy 目录”AI 使用了已经废弃的 API于是你写了“统一使用新版本 SDK”AI 执行 pytest 时没有先安装依赖于是你写了“运行测试前需要先执行 pip install -r requirements.txt”。每个补充都有价值。但这些价值是“局部价值”它没有考虑整份文件的信息密度、优先级、以及规则之间的逻辑关系。当这种“打补丁式”的追加持续半年文件必然膨胀。3.2 用户侧心理害怕 AI “忘记”而过度防御第二个原因藏在开发者心态里我们默认 AI 的上下文是有限的如果不把规则写全它就会在关键时刻“忘记”。这种心态催生出两种行为把未来可能用到的信息提前写进 CLAUDE.md把已经写在其他文档里的信息复制一份到 CLAUDE.md。结果就是文件里出现了大量“备用信息”它们当前没用但占用了 token它们和其他规则可能冲突但对 AI 来说都算数。心理学上这是一种“控制错觉”——你觉得写下来就安全了实际上信息越多关键信息被稀释得越严重。3.3 Agent 侧机制上下文里的任务痕迹会自然沉淀用户侧追加只是其中一部分原因。另一个重要原因是 agent 在执行任务过程中产生的中间信息也可能被回写或保留。例如在某个长任务里AI 需要处理临时目录、生成中间文件、执行各种调试命令。如果项目里的日志、脚本、工具链信息没有独立文档AI 可能会把这些中间信息写入记忆文件作为后续任务的参考。更常见的是开发者为了让 AI 在下一个任务里继续沿用上一轮的成功做法会把上一轮任务里的临时决策写进 CLAUDE.md上轮修复登录超时问题时确认了网关连接池大小调整为 50 有效。这个信息对一个具体的“登录超时问题”有效但它不是项目级长期约定。长此以往CLAUDE.md 会变成“问题修复流水账”而不是“行为规则清单”。3.4 项目侧缺失没有信息分层所有内容都往一个文件里塞第四个根因是 CLAUDE.md 没有和其他项目文档体系做职责划分。现实中一个项目通常有README给人看的项目简介docs/design.md架构设计文档docs/api.md接口说明CONTRIBUTING.md贡献规范Makefile / scripts自动化命令入口。但很多团队在接触 agentic coding 后并没有为 AI 建立一套“分层文档体系”而是选择把所有内容都塞进唯一的 CLAUDE.md。架构设计放进去、接口说明放进去、代码风格放进去、部署步骤放进去、排错经验也放进去。这样做的代价是文件越来越长更新越来越困难规则冲突越来越隐蔽AI 读取成本越来越高。3.5 灾难性记忆的形成路径从“信息累积”到“信号失效”把上述三个因素叠加我们可以总结出 Catastrophic Remembering 的形成路径信息持续追加文件长度超过模型有效阅读长度规则数量增加规则之间开始出现语义重叠或冲突没有优先级机制AI 无法判断哪条规则更重要重要规则被大量次要信息稀释模型检索到关键约束的概率下降AI 开始“看情况执行”不同任务表现出不一致的行为开发者发现问题后又追加“加强版”规则进一步加剧冲突。进入这个循环后CLAUDE.md 越长AI 的行为反而越不稳定。这就是为什么很多团队抱怨“CLAUDE.md 写的规则越来越多AI 却越来越不听话”。4. “灾难性记忆”带来的具体危害4.1 指令冲突导致行为漂移当 CLAUDE.md 中同时存在“禁止直接修改数据库”和“紧急情况可以直接修改数据库”时AI 无法稳定判断什么时候算“紧急”。相同的问题今天可能走 migration 流程明天可能直接执行 SQL。对团队来说这种“行为漂移”比 AI 犯错更可怕因为它让你没办法通过复盘来优化流程——每一次行为都像“薛定谔的规则”。4.2 token 成本与性能开销CLAUDE.md 是每个任务都要读取的基础上下文。文件越长消耗的 token 越多单次任务成本越高响应延迟也可能更长。假设一份 CLAUDE.md 有 3000 行约 3 万 token。在较长的上下文窗口中虽然放得下但每个任务都带着 3 万 token 的“包袱”对成本敏感的团队来说这不是一个可以忽略的数字。更重要的是大量 token 被“无效信息”占用留给当前任务实际代码分析的 token 比例就会下降最终影响代码生成质量。4.3 可维护性迅速恶化CLAUDE.md 超过一定规模后普通开发者已经很难完整阅读它。你会发现自己改一条规则时不敢确定它会不会和其他规则冲突你也不敢删除一条旧规则因为不知道是否有 AI 流程还在依赖它。最终CLAUDE.md 变成项目里一个“不敢动”的文件。它像一套代码库里的“祖传代码”大家都在上面打补丁但没人敢重构。4.4 规则误读与“幻觉式执行”模型在长上下文中对规则的理解并不总是可靠的。当规则之间存在相似表达、相互补充、甚至互相否定时模型可能产生“幻觉式执行”——它认为自己遵循了 CLAUDE.md但实际执行方案是规则之间拼凑出来的“中间产物”。这种误读最难排查因为 AI 给出的解释看起来非常合理但和团队真实意图相差很远。4.5 调试与协作成本上升当 AI 行为出现问题时你要先判断问题来自CLAUDE.md 规则冲突模型自身理解偏差当前任务描述不清代码库上下文缺失。如果 CLAUDE.md 本身已经是一团乱麻你很难定位问题是哪一个。团队协作时不同成员对 CLAUDE.md 的理解可能也不一样有人把它当“基线规则”有人把它当“完整手册”贡献方式自然不同。5. 实战设计一份不膨胀的 CLAUDE.md5.1 核心原则分层、稳定、可检索要对抗“灾难性记忆”关键不是禁止写入新规则而是为 CLAUDE.md 建立结构化约束。推荐四个核心原则分层项目级稳定规则和任务级临时经验分离稳定CLAUDE.md 只记录稳定的、长期的约定不记录单次任务结论可检索内容用目录、标签、短段落组织让模型能快速定位可仲裁规则必须写明冲突时的仲裁方式或优先级。5.2 推荐的项目记忆目录结构project-root/ ├── CLAUDE.md # 第一入口稳定、精简、全局有效 ├── docs/ │ ├── ai/ │ │ ├── architecture.md # 架构说明供 AI 按需读取 │ │ ├── coding-style.md # 代码风格细节 │ │ ├── stack.md # 技术栈与版本约定 │ │ ├── commands.md # 常用命令与执行规范 │ │ └── changelog.md # CLAUDE.md 变更记录 │ ├── design/ │ └── ops/ └── README.mdCLAUDE.md 里通过“引用路径 一句话摘要”的方式指向 docs/ai/ 下的文件而不是把所有内容复制进来。这样既控制了主文件长度也让 AI 在需要时能找到细节。5.3 一个可参考的 CLAUDE.md 模板这个模板的设计思路是在尽量少的篇幅内让 AI 知道“我是谁、项目是什么、什么时候必须停下来问人、细节去哪里查”。# CLAUDE.md 本文件是项目的稳定行为基线。修改需要走评审细节请写入 docs/ai/ 对应文件。 ## 项目一句话 支付网关服务负责交易路由、对账、商户通知。 ## 技术栈 - 语言Java 17 - 框架Spring Boot 3.x - 数据库MySQL 8.x连接串见 docs/ai/stack.md - 消息Kafka ## 核心约束优先级从高到低 1. 禁止删除或修改 src/main/resources/migrations 下的迁移脚本。 2. 数据库结构变更必须新增 migration 文件禁止直接改表。 3. 涉及线上数据修复必须先备份并输出修复 SQL经人工确认后执行。 4. 所有对外接口变更必须同步更新 docs/api.md。 ## 常用命令 - 本地启动./mvnw spring-boot:run - 单元测试./mvnw test - 契约测试./mvnw verify -Pcontract ## 高频规则 - 模块间禁止循环依赖新增依赖方向遵循 controller - service - repository。 - 日志使用 slf4j业务日志输出到 biz 开头 logger。 - 所有金额字段使用 BigDecimal禁止使用 double。 ## 冲突仲裁 规则冲突时优先执行第 1-4 条核心约束仍无法判断时停止操作并列出冲突项等待人工确认。 ## 细节索引 - 代码风格docs/ai/coding-style.md - 技术栈与版本docs/ai/stack.md - 历史变更记录docs/ai/changelog.md - 部署与运维docs/ops/deploy.md这个模板刻意控制了内容核心约束只有 4 条高频规则只有 3 条剩余信息全部外移到 docs/ai/ 目录。AI 不会因为信息过载而失去判断力。5.4 维护流程变更评审、变更记录、定期清理CLAUDE.md 必须有“变更流程”否则一段时间后又会膨胀回原样。推荐的流程提案把新增规则先写在 docs/ai/changelog.md 中说明“为什么加、解决什么问题、是否与其他规则冲突”。评审至少让另一位同事看一遍确认这不是单次任务的临时结论。合并将确认后的内容精简为 1-3 句话放回 CLAUDE.md 对应位置。沉底如果新增内容属于“细节型规则”优先进入 docs/ai/ 子文件而不是主文件。清理每个迭代周期检查一次删除不再适用的规则合并语义重复的规则。5.5 与其他文档的职责边界最后要明确 CLAUDE.md 和其他文档的分工。CLAUDE.md - AI 的第一层行为基线稳定、精简、冲突仲裁 docs/ai/*.md - AI 的按需细节库由 CLAUDE.md 引用 README.md - 人类阅读的项目总览 docs/design/* - 人类阅读的架构设计、决策记录 docs/ops/* - 人类与 AI 共同使用的运维说明有了这个边界你就不需要把所有信息都塞进 CLAUDE.mdAI 也能够在需要细节时通过索引找到对应文件。6. 常见问题与排查思路6.1 典型问题速查表问题现象常见原因解决思路AI 不遵守 CLAUDE.md 中的规则规则被大量低优先级信息稀释规则前后矛盾精简 CLAUDE.md给规则加优先级删除冲突项AI 对同一任务不同次表现不一致CLAUDE.md 中存在语义接近但结论不同的规则做规则去重与合并明确冲突仲裁方式上下文 token 消耗过高CLAUDE.md 过长引用文件被整体加载主文件只放基线细节外移到按需读取的文档修改 CLAUDE.md 后 AI 行为反而变差新增规则没有评审直接与旧规则冲突回滚本次变更走变更评审流程后再合并团队内不同人维护 CLAUDE.md 风格差异大缺少统一模板使用固定章节模板约定写入职责边界找不到某条规则放在哪里CLAUDE.md 结构缺失内容杂糅建立目录结构 索引按章节归类6.2 场景一AI 越来越“不听指令”一位开发者反馈CLAUDE.md 里写了“禁止使用 ThreadLocal 传递用户上下文”但 AI 多次生成 ThreadLocal 相关代码。排查步骤在 CLAUDE.md 中搜索 ThreadLocal确认规则是否存在搜索是否还有另一条规则间接允许使用比如“保持代码简洁优先使用 ThreadLocal 避免参数透传”检查该规则位于文件末尾还是被大量信息淹没检查最近变更记录是否在某个任务中被覆盖。解决方式把“禁止使用 ThreadLocal”提升到核心约束区删除语义冲突的规则并在索引文件中保留设计替代方案。6.3 场景二规则冲突但 AI 不报错有时 CLAUDE.md 里同时存在规则 A所有外部调用必须有超时时间。 规则 B支付回调处理要尽快返回不要做太多阻塞调用。AI 可能为了避免“阻塞调用”而给外部调用设置很短的超时结果导致正常请求也频繁超时。排查思路是检查这两条规则是否在描述同一件事如果是合并为一条带主次关系的规则支付回调处理要尽快返回外部调用必须有超时时间但超时不能低于 1s避免误杀正常请求。6.4 场景四CLAUDE.md 什么时候应该拆分为多个文件当满足以下条件时可以考虑拆分文件超过 300 行内容可以被划分为多个主题架构、风格、运维、排错不同任务类型只需要读取其中一部分新增规则时你不知道它应该放在哪个章节。拆分时不要把规则简单截断而是先拆分“章节边界”再逐步迁移。7. 最佳实践与工程建议7.1 把 CLAUDE.md 当成“宪法”而不是“日志”“宪法”规定稳定原则不会因为某个具体任务而频繁修改“日志”记录每天发生了什么细节多但指导性弱。CLAUDE.md 应该是前者。当你发现自己在里面写下“2024 年某次事故后的处理过程”时要警惕这属于“日志”内容除非能提炼成具有长期约束力的规则否则应放入 changelog 或普通文档。7.2 规则要可验证、可仲裁好的规则需要满足三个条件可验证代码评审时可以判断是否违反可执行AI 可以在真实任务中落实可仲裁多条规则冲突时有明确的处理顺序。比如“注意代码质量”不可验证“方法参数超过 5 个时必须封装为对象”可验证、可执行、可仲裁。后者才是值得写进 CLAUDE.md 的规则。7.3 每次变更都留下记录在 docs/ai/changelog.md 中维护 CLAUDE.md 的变更记录内容包含## 2025-06-10新增核心约束第 4 条 - 原因AI 在接口变更时经常漏更文档 - 影响所有对外接口变更必须同步更新 docs/api.md - 冲突检查与现有规则无冲突 - 提出人张三 - 评审人李四。这样做的价值在于定位问题时能回溯是谁、什么时候、为什么加了这条规则评审时能看到规则演进过程避免重复制造互相矛盾的内容定期清理时能判断某条规则是否还需要保留。7.4 控制篇幅设置“红线”项目里可以约定 CLAUDE.md 的“红线”规则主文件不超过 200 行核心约束不超过 10 条每条规则不超过两句话出现“酌情”“尽量”等词时必须补充“什么场景下例外”。超过红线时不是靠“再精简一下”解决而是启动一次正式治理把内容拆分到 docs/ai/ 下的子文件。7.5 结合代码库事实而不是脱离代码空谈CLAUDE.md 中描述的架构、命令、依赖应当与代码库实际情况一致。如果技术栈升级但 CLAUDE.md 没有同步更新AI 会基于过时信息生成错误代码。建议每迭代周期做一次“CLAUDE.md 与代码库一致性检查”至少校验技术栈版本是否准确构建命令是否还有效目录结构是否对得上约束规则是否仍然成立。7.6 为不同任务类型提供不同“入口”如果项目里存在多种 agentic 任务例如“后端接口开发”“前端页面实现”“数据库运维”“测试用例生成”可以设计多个入口文件而不是把所有任务的约束都塞进一个 CLAUDE.md。一种做法是CLAUDE.md # 全局项目简介、基础约束、仲裁规则 docs/ai/backend.md # 后端任务模块边界、接口规范 docs/ai/frontend.md # 前端任务组件规范、状态管理约定 docs/ai/database.md # 数据库任务迁移脚本、备份要求 docs/ai/testing.md # 测试任务单测、契约测试、覆盖率要求不同任务启动时AI 读取 CLAUDE.md 全局文件再根据任务类型加载对应的入口文件。这样既保持全局规则稳定又避免无关信息干扰当前任务。7.7 用“负面清单”替代大量正向描述与其写“你应该怎么做”不如先写“你禁止怎么做”。正向描述容易引发发散理解而负面清单更精确。例如“保证代码安全”不如“禁止硬编码密钥”“注意数据库性能”不如“禁止在循环中查数据库”“做好异常处理”不如“禁止捕获异常后吞掉不打印日志”。负面清单隔离了 AI 最容易犯的错误剩下的空间让 AI 在合理范围内自由发挥。8. 总结与下一步CLAUDE.md 不断膨胀是 agentic coding 实践中的常见现象核心原因是我们把 AI 的“长期记忆”当成了无限的容器不断追加规则、经验、任务细节却没有建立分层、优先级和淘汰机制最终引发了 Catastrophic Remembering——记住得越多关键信息反而越失效。解决这个问题的关键不在“让 AI 记住更多”而在“让 AI 记住得更有效”。有效记忆意味着精简稳定的主文件、明确分层的细节库、可验证可仲裁的规则、以及规范的变更流程。接下来的学习建议如果你刚开始接触 agentic coding可以从一份 100 行以内的 CLAUDE.md 开始只写项目简介、技术栈和核心约束如果你的 CLAUDE.md 已经超过 1000 行不要试图一次性重写先建立 docs/ai/ 分层目录逐步迁移内容在每个任务结束后复盘 AI 是否真的遵守了 CLAUDE.md把“违反规则”与“规则本身不合理”区分开避免盲目补充新约束。CLAUDE.md 是一份会呼吸的文档它的价值不在于篇幅而在于准确性和稳定性。只要把它当成项目的“宪法”来维护而不是流水账式的“记忆回收站”AI 助手就能真正成为稳定可靠的编程伙伴。