claude code在大型单体应用中生成模块化代码的难点

我从没想过，有一天我会对着一堆 AI 生成的“模块化代码”，整整修了三天的循环依赖。

那是去年秋天的一个项目，一个跑了九年的 Java 单体应用，代码行数超过 12 万，核心业务逻辑集中在三个巨大的 Service 类里，每个类轻轻松松突破 3000 行。我当时的任务很明确：把订单处理模块从主应用中拆出来，换成微核架构，方便独立部署和横向扩展。

动手之前，我决定试试 Claude Code。

不是我懒，而是我真心想看看，这个当时风头正劲的 AI 编码助手，在面对真正的“翔山”代码时，到底能做到什么程度。

我把第一个大 Service 文件喂给 Claude Code，命令很直接：“把这个类拆成四个模块：订单验证、订单执行、订单状态机、订单事件发布。每个模块只通过接口通信，不允许直接引用其他模块的内部实现类。”

前两分钟，一切都很完美。Claude Code 生成了四个清晰的包，定义了接口，识别出了大部分私有方法。我甚至在心里夸了一句：“这不就省了我两天的事吗？”

然后我点开订单执行模块的实现类，第 47 行赫然写着：

import com.legacy.order.internal.OrderStateMachine;

这个引用，直接穿透了接口，调用了订单状态机的私有方法。

更致命的是，订单状态机模块内部，又反向引用了订单执行的内部工具类。一个完美的循环依赖就这样被自动生成了，而 Claude Code 在任务完成时给我的反馈是：

“模块化已按接口分离完成，请检查编译。”

我当时的感受不是生气，而是一种恍然大误。Claude Code 对待大型单体应用的模块化生成，不是“拆解问题”，而是“翻译问题”。 它忠实地把我喂进去的代码，用模块化的语法重写了一遍，却完全没有理解模块化背后的工程纪律，边界约束、依赖方向、职责内聚。

这不是 Claude Code 的个 bug，而是当前 AI 编码工具在面对大型单体应用时，暴露出的系统性弱点。

那天之后，我花了整整两周时间，在不同的历史项目上系统地测试了 Claude Code 在单体应用模块化生成中的表现。我把所有失败的场景记录下来，归类、复现、分析根因，最终形成了这篇文章的核心结论。

我先说最重要的判断：在大型单体应用中，Claude Code 生成模块化代码的能力边界，取决于你对“上下文污染”“遗留耦合误导”和“接口契约遗忘”这三股力量的控制程度。控制得好，它能节省 60% 的初始拆分工作；控制得不好，它会创造出一堆你从未见过的新型技术债务。

为什么 Demo 上行得通的模块化，在单体应用里频频翻车？

在深入解剖每种失败模式之前，我必须先把一个核心问题讲透：为什么 Claude Code 在小项目、Demo 级别的代码重构中表现优异，一遇到大型单体应用就变得脆弱？

答案藏在上下文里。

当 Claude Code 处理一个 500 行的单文件项目时，整个项目的结构、依赖关系、方法调用图都可以完整地塞进它的有效注意力窗口（约 20 万 Token）内。它能清晰地“看到”每个函数被谁调用、又调用了谁、数据是如何流转的。在这个量级上，要求它按照高内聚低耦合的原则拆分模块，就像要求一个大学生把一堆不同颜色的积木分类摆放，信息量在人的即时处理范围内，不会压垮决策系统。

但大型单体应用完全不是这么回事。

一个 3000 行的 Service 类，光方法数量就可能超过 150 个。每个方法内部都在调用其他 Service 的方法，那些方法又嵌在另外几千行的文件中。方法之间没有显式的边界声明，耦合关系是“蛇形走位”。更要命的是，很多单体应用经过了长达数年的迭代，积累了大量的“胶水代码”，那些既不属于 A 模块也不属于 B 模块、但离开了它们系统就跑不起来的过渡性逻辑。

当 Claude Code 试图理解这种规模的文件时，它的注意力机制就会进入一种我称之为“耦合固化”的状态。

什么是“耦合固化”？

这是我在多次测试中观察到的一个复现模式：当 AI 模型面对一个高耦合的单体代码库时，它不会主动去剪断那些原本可以被剪断的依赖。相反，它会将“原有的调用关系”当作一种默认正确的结构，在生成模块化代码时，用更隐蔽的方式把这些耦合关系保留下来。

比如，原来 A 类直接调用 B 类的私有方法，经过 Claude Code 的“模块化”后，变成了 A 模块的接口中多了一个为 B 模块内部逻辑服务的诡异参数；或者，两个本该独立的模块之间，被生成出了一个“共享工具类”，而这个工具类实际上成了耦合的藏身之所。

我亲眼见过最离谱的例子，是一个名为“CommonUtils”的生成文件，里面塞了 47 个方法，来自原本 12 个不同的业务域。Claude Code 无法割舍任何一个耦合点，所以干脆造了一个大号的万能胶水罐。

这就是为什么 Demo 上成功的秘诀，代码量小，耦合少，AI 不需要做出任何“剪断”的决策，在大型单体应用中完全不成立。面对 12 万行的庞然大物，Claude Code 被迫在每一行代码中做决策，而它的默认决策倾向是：“保留原有的连接，只是换个容器装起来。”

理解了“耦合固化”这个底层机制，接下来的几种失败模式就都有了统一的解释。每一种模式，都是这个机制在不同维度上的投射。

失败模式一：记住接口约定，但忘记职责边界

这是最常见、也最容易被忽视的失败模式。我在前述的订单模块拆分案例中，第一次完整地记录到了这种模式的全过程。

当我对 Claude Code 给出指令“每个模块只通过接口通信，不允许直接引用其他模块的内部实现类”时，它在前几轮对话中确实遵守得很严格。生成的四个接口定义清晰，参数类型合理，甚至自动补了一些我没想到的异常声明。

问题出在第 23 轮左右的对话中。

我在这个阶段要求它对订单执行模块中的一个复杂方法做进一步拆分，因为这个方法内部有一段长达 40 行的逻辑，实际上属于订单验证的职责。Claude Code 在响应这个需求时，做出了一个看似合理、实则灾难性的操作：它把那段验证逻辑移到了订单验证模块中，这没错，但它同时在订单验证模块的实现类里，直接 new 了一个订单执行模块的内部缓存对象，用来“校验时查询执行状态”。

这个 new 操作，违反了之前约定的接口隔离原则。订单验证模块不应该知道订单执行模块内部使用了什么缓存对象，它只能通过接口方法获取必要的外部状态。

但 Claude Code 没有“看到”这个问题。因为在它的视野里，订单执行模块的内部缓存对象也是一个普通的类，和前几十轮对话中反复出现的那些类没什么不同。它“记住了”要使用接口进行跨模块通信这个规则，但它“没有理解”这条规则背后的意图：隐藏内部实现，保持模块的独立可替换性。

让问题更复杂的是，这种违反是渐进式的。第一轮拆分时它可能遵守得很好，第三轮、第五轮之后，新的代码生成开始在不同程度上侵蚀边界。等到了第十轮，最初设定的模块边界已经像一块被潮水反复冲刷的海岸线，模糊不清。

我在测试中统计过一个数据：在对一个 4800 行的单体类进行分步模块化拆分的过程中，当对话轮次超过 15 轮后，Claude Code 在生成新代码时违反既定模块边界规则的概率，从最初的 7% 左右上升到 34%。也就是说，每生成三次新代码，就有一次会在某种程度上破坏你之前花力气建立起来的模块边界。

这种“记忆退化”的根因是什么？我不能确定 Anthropic 内部的模型架构细节，但从外部观察到的行为模式来看，这与 Transformer 模型在处理超长上下文时的注意力分散效应高度一致。当上下文中同时存在“接口隔离指令”“最早的代码原文”“前几轮修改的增量代码”“最新的用户指令”这四类信息时，模型对“接口隔离指令”这一早期约束的注意力权重会在竞争中被稀释。

这就像一个在嘈杂房间里努力听清指令的人。一开始，他能清楚地听到“不要进那个厨房”。但十分钟后，他忙着把你递过来的各种食材重新分盘，周围还不停地有人跟他说话，那个最初“不进厨房”的警告，就渐渐地被挤到了注意力的边缘。

失败模式二：循环依赖的生成，自己挖坑自己跳

如果说边界模糊是“软性违规”，那么生成循环依赖就是“硬性编译冲突”。在我测试的 11 个不同规模的单体应用模块化拆分任务中，有 8 次出现了不同程度的人工循环依赖。其中最严重的一次，Claude Code 生成了三段式循环：订单模块依赖库存模块的锁机制，库存模块依赖支付模块的冲抵接口，而支付模块又在回调中调用订单模块的状态变更方法。

这个循环被包裹在三个清晰整洁的接口定义里，第一眼看过去完全察觉不到。我是在 IDE 的依赖分析工具中跑了完整模块图之后，才发现三个模块在包依赖层面已经形成了一个死结。

Claude Code 为什么会生成这种自己逻辑上都通不过的循环结构？

我们需要理解 AI 在分析单体代码时的“视野”特点。大型单体应用经过多年迭代，其内部耦合往往是“网状的”，而非“分层的”。方法 A 调用方法 B，方法 B 在某些条件下会回调方法 A 的不同分支，而这个分支在处理失败时又会调用方法 C，方法 C 为了让事务一致又需要方法 A 的锁对象。

人类工程师在重构这种代码时，会有一个“顶层视角”：我们不是一行行翻译调用关系，而是先建立一个新的分层模型（比如经典的三层架构），然后把原有功能按照分层逻辑重新拆解。遇到回调循环时，我们会引入消息队列、事件总线、或者依赖反转来切断直接耦合。

Claude Code 不具备这个“顶层重设计”的能力。它处理模块化任务的方式更接近“在保持原有调用图不变的前提下，加上模块分区和接口包装”。当原有调用图中存在 A→B→A 这种耦合时，它的第一反应不是打破这个循环，而是把这个循环用接口再包装一遍。

比如，原来的循环是这样的：

OrderService.execute() → InventoryService.lock() → 回调 OrderService.onLockSuccess()

经过 Claude Code 的“模块化”后变成：

OrderModule.execute() → InventoryModule.lock() → 调用 OrderCallback 接口 → OrderModule 实现 OrderCallback 接口

在语法层面，这看起来更“模块化”了，引入了一个回调接口嘛。但在依赖层面，OrderModule 依赖 InventoryModule，而 InventoryModule 又依赖于 OrderModule 导出的 OrderCallback 接口。如果你用 Maven 或 Gradle 管理多模块工程，这意味着两个模块必须放在同一个编译层级上，谁也没法独立编译。

这还没有考虑更隐蔽的“语义循环”。在我记录的一个案例中，两个模块没有直接的包级依赖，但订单模块的接口返回值中包含了一个从库存模块内部数据结构转换而来的业务对象。这意味着任何调用订单接口的客户端，都必须显式或隐式地理解库存模块的业务模型。这种“软循环”在编译期不报错，但在后续的独立演进中会成为巨大的阻挠。

在这种行为模式下，期待 Claude Code 主动为单体应用生成“干净的分层模块”，就等于期待一个只会照图施工的建筑队去修改建筑设计。他们能把砖砌得整整齐齐，但如果图纸上有结构缺陷，他们不会主动指出“这根柱子位置不对，会导致二楼和一楼互相卡死”。

失败模式三：重构模式下的模块封装被蛮力复制取代

这是我在一个高度重复的单体工具类中第一次注意到的模式。那个工具类叫 “DataMappingHelper”，大约 1200 行，包含了十几个数据清洗、格式转换、字段映射的方法。这些方法散落在多个业务模块中被调用。

我的指令是：“把 DataMappingHelper 按功能域拆分成三个工具模块：日期映射、金融字段转换、地址标准化。其他业务模块按需引用新的模块，不再依赖原始大文件。”

Claude Code 的执行策略让我吃了一惊。

它没有生成三个模块然后修改 17 个业务文件中的 import 语句。它的做法是：在日期映射模块中，把原始 DataMappingHelper 中与日期相关的 4 个方法抽出来，然后……把同样一份代码在多处进行复制。金融字段转换模块里，除了金融相关方法外，还顺手把一段日期格式化方法也复制了进去，因为“金融转换中需要格式化交易日期”。地址标准化模块也如法炮制。

结果就是，三个新模块之间共享了至少 5 个应该被提取为公共依赖的方法，但 Claude Code 选择了在每个模块中保留一份私有的复制副本。这种“复制式模块化”在短期的编译测试中当然能通过，但从长期维护的角度看，它制造了代码重复的隐性成本，将来如果日期格式化逻辑需要调整，你得同时改三个地方。

我开始在更多的拆分任务中观察这个模式，发现它出现的规律性很强。当原始单体文件中存在大量“交叉引用的细微方法”（比如到处都在用的一个字符串处理小函数）时，Claude Code 的默认倾向不是把它们提取成一个基础依赖模块，而是判断哪个模块“最需要”这个方法，然后把它完整地复制过去。如果多个模块都“需要”，那就多次复制。

这背后的原因，可能与模型对文件间依赖关系的成本评估机制有关。对人类工程师来说，引入一个新的 import 语句和一个基础模块依赖，几乎不消耗任何认知成本。但对 AI 模型来说，建立一个跨文件的精确引用关系，意味着它必须持续跟踪两个文件之间的版本一致性。一旦基础模块中的方法被修改，所有引用它的文件都需要同步更新。在当前的无状态生成模式下，Claude Code 似乎更倾向于选择“每个模块自包含运行”的策略，以降低它自身的后续同步压力。

但这恰恰与模块化的核心原则相悖。模块化的目的是减少重复、建立单一真相来源。复制粘贴式的拆分，只是把一个大泥球变成了几个相互独立的小泥球，并没有实现真正的关注点分离。

我在一个模拟长期维护的测试中，要求 Claude Code 对之前“复制式模块化”生成的项目进行一个简单修改：修改日期格式化方法中的时区处理逻辑。它改对了日期映射模块中的那份副本，但完全忽略了金融字段转换模块和地址标准化模块中的另外两份相同代码。显然，在它的上下文里，这三个方法虽然内容完全一样，但属于各自模块的“私有资产”，彼此之间没有关联。

这就是“蛮力复制”最隐蔽的危害：它把原本集中管理的代码一致性，替换成了分散管理的代码孤岛。在短期的成功编译背后，埋下的是长期维护中的一致性炸弹。

失败模式四：多模态输入的意外干扰

这是一个反直觉的发现，我在测试之前完全没有预料到。

Claude Code 当时刚推出多模态能力不久，可以接收架构图、UML 图、甚至手绘的草图作为输入参考。这个功能被宣传为“让 AI 更好地理解系统设计意图”。我在一个测试任务中决定尝鲜：把一个在线教育平台的课程管理模块拆分需求，用一张我自己画的 DDD 分层架构图作为附加上下文，和代码文件一起喂给 Claude Code。

图本身画得很清晰：四层架构，每层标注了职责范围，层与层之间通过接口单向依赖。我把这张图和 8 个相关 Java 文件一起输入，指令是：“按照架构图的层次划分，把现有代码拆分成对应模块。”

生成的代码第一眼看起来异常“漂亮”，包名和图上的层次完全一致，接口定义也符合图上的接口名称。但当我开始做编译验证时，发现了一个诡异的依赖：基础设施层的 DAO 实现类中，import 了一个领域层的内部值对象。按图上标注的依赖方向，基础设施层应该只被领域层通过接口调用，不能反向依赖领域层的任何内部实现。

这个依赖在我画的架构图上根本不存在。图上基础设施层和领域层之间只有一条向上的箭头（基础设施→接口→领域），没有任何向下的箭头。但 Claude Code 在处理具体的代码时，似乎把注意力更多地分配给了代码实际存在的 import 关系（原始代码中确实有这种向上依赖的耦合），而忽略了我通过架构图传递的“禁止向下依赖”的强制约束。

我随后做了几组对照测试：

• 第一组：只给文字指令+架构图，不给代码，让它生成模块骨架。结果很好，依赖方向完全正确。
• 第二组：只给代码+文字指令，不给架构图。结果一般，保留了部分原有耦合，但没有出现新的反向依赖。
• 第三组：同时给代码+文字指令+架构图。结果最差，出现了多处架构图上明确禁止的依赖方向。

第三组的表现让我困惑了很久。按理说，信息越丰富，生成质量应该越高。为什么多了一张清晰的架构图，反而降低了模块化的质量？

经过反复对比生成的结果，我推测了一个可能的解释：当代码本身的高耦合信号，与架构图的低耦合约束信号同时进入模型时，模型在生成具体代码的过程中，更倾向于“信任”代码中的既有模式。架构图作为一种抽象的高层约束，在具体到每一个 import 语句生成时，其注意力权重被来自代码本身的强信号（大量的跨层调用实例）压制了。

这就像你给厨师一张写着“少油少盐”的纸条，但同时给他一份用猪油炒出来的样菜。结果厨师更倾向于模仿样菜的口味，而不是听从纸条上的健康建议。

更让我警惕的是，Claude Code 在多模态输入下的“自信度”似乎更高。在三组对照中，第三组生成的代码在语法完整性、接口定义规范性、注释详细程度上都是最高的，这给了我一种“它理解得更好”的错觉。直到跑静态分析和依赖检查，才发现架构上已经出现了反向依赖。这种“正确得看起来很对，但关键点上反了”的模式，比单纯的生成错误更危险，因为它更容易逃过初检。

这件事给我的最大教训是：在大型单体应用的模块化任务中，“信息越多越好”这个直觉并不成立。架构图、UML 图这类高层抽象输入，如果与原代码中的既有耦合发生冲突，AI 可能会选择“忠于代码原貌”而非“忠于架构设计”。这并非多模态能力本身的问题，而是两种信息源的冲突没有被合理调解。

失败模式五：无测试脚手架下的静默错误

这是所有失败模式中最危险的一种，因为它不会在编译期暴露，也不是一个绕不开的依赖，它是一种“逻辑漂移”。

大型单体应用通常有一个共同特征：测试覆盖率低。这个低不是 60% 低，是惨烈的低。我测试过的一个遗留财务系统，单元测试覆盖率不超过 12%，业务正确性的保障全靠手工回归和线上监控。这种系统能够活到今天，靠的是当年那批老开发人员大脑里还在运转的“人对代码的理解”。

但这种理解，Claude Code 完全没有。

当我把一个没有测试用例的支付冲抵方法交给它进行模块化拆分时，它非常顺畅地生成了新的模块代码。编译通过，接口定义清晰，参数列表看起来完整无缺。但我在逐行比对时发现，有一个异常处理分支的逻辑被悄悄改写了，原代码中，当冲抵金额超出原交易金额 0.01% 时，会触发一条特殊的告警记录，并被当作“需人工审核”状态挂起。Claude Code 生成的版本中，这个分支的告警记录仍然存在，但挂起状态的标记被吞掉了，交易继续往下走，直接进入了最后的结算阶段。

这个 bug 不会让程序崩溃，也不会让测试亮红灯（因为没有测试），它只会在月底对账时，出现一笔死活对不上的 0.01% 差异。这种类型的错误，它在这个遗留系统中的某个角落里安静地蹲着，等待一个合适的时机引爆。

为什么“静默错误”和“模块化生成”绑定得这么紧密？

我的判断是，原因出在 AI 对代码的“语义压缩”过程中。当 Claude Code 分析一个长方法时，它内部会对这个方法的逻辑进行一种归纳式的理解：“这段代码在做什么？”对于主体流程，它通常归纳得比较准确。但对于嵌套在多层 if-else 中的边缘分支，特别是一些历史遗留的、注释不全的、逻辑看起来不太合理的分支，它的归纳准确度就大幅下降。

在生成模块化代码时，模型会用它的“归纳理解”来重新撰写代码，而不是逐句逐词地翻译。这就导致了一个现象：主体逻辑保持完好，但边缘分支的业务语义发生了漂移。 原来在某个特定条件下必须触发的操作，被优化成了“看起来更合理”的逻辑。

人类工程师在重构遗留单体应用时，会怀着一种“恐惧感”，这段老代码我不敢乱动，就算它写得再丑，也一定是有原因的，说不定它挡住了某个八年前的致命 bug。这种恐惧感迫使人类采取“最小改动”策略，尽量保留原逻辑不变。

Claude Code 没有这种恐惧感。它以一种“超然的优化者”姿态来处理代码，这在本体脚本中算是优势，但落在那些没有测试保护的遗留分支上，就成了对原有逻辑的无声篡改。

我在多个项目的测试中粗略统计出一个规律：当一个方法的测试覆盖率为 0 且方法体超过 80 行时，Claude Code 对其进行的模块化拆分中，产生静默业务逻辑变更的概率约为 15% 到 22%。 这不是一个通过抽样统计得出的精确数据，而是我在回溯 11 个拆分任务、逐个比对原方法和生成方法时，观察到的大致频率区间。

知道这件事以后，我给自己定了一条铁律：在要求 Claude Code 对一个无测试覆盖的遗留单体方法进行模块化拆分之前，必须先让它为这个方法生成一套尽可能全面的单元测试，覆盖所有显式分支。跑完这些测试，确认它们在当前代码上通过之后，再把测试用例和原代码一起喂给 Claude Code，并明确指令：“新生成的模块代码必须通过以下全部测试用例，且不允许修改任何测试断言。”

这套流程把静默错误率从一个让人不安的两位数，降到了一个可以接受的低个位数，测试用例在这里扮演了一个“业务逻辑锚点”的角色，把原有逻辑的语义约束以可执行代码的方式量化地传递给了模型。

最难拆的四种单体基因

前五节我讲了 Claude Code 在模块化生成中的五种失败模式。但在实际工作中，我发现并非所有单体代码的模块化难度都相同。有些代码天然就比较容易拆，有些代码则像自带“反模块化基因”，无论你怎么下指令、怎么调整分步策略，生成出来的模块代码依然问题重重。

经过对大量失败和成功案例的分类，我总结出了四种最容易让 Claude Code“翻车”的单体基因。它们在传统软件工程中也是难啃的硬骨头，但在 AI 辅助下，它们产生的畸形模块代码种类更丰富、更隐蔽。

• 第一种：全局状态感染型单体。这种代码的特征是大量使用静态变量、ThreadLocal 或应用级的单例对象来传递运行时状态。典型场景是一个全局的 “SessionContext” 或 “RequestContext”，在整个调用链的任意位置都可以被读写。Claude Code 在拆分这类代码时，会陷入一个困境：如果严格按模块边界隔离状态，就需要重构大量的上下文传递逻辑（这个它不擅长）；如果不隔离，就得把全局状态对象暴露给所有模块（这直接废掉模块化）。它最常见的“折中”处理，是生成一个 “SharedContext” 模块，所有拆出来的模块都依赖这个共享上下文。从架构上看，这不过是把原来的全局变量换了个名字，耦合本质上纹丝未动。

• 第二种：交错事务型单体。在这种代码中，一个本地事务跨越了多个业务域，中间夹杂着对多个数据库表的操作和外部 RPC 调用。代码没有显式的 Saga 或补偿逻辑，事务一致性靠的是数据库锁和“祈祷”。当 Claude Code 试图把这些操作拆到不同模块时，它面临一个本质性的矛盾：模块化的前提是每个模块有自治的数据访问边界，而交错事务的前提是所有操作必须在同一个连接和同一个事务作用域内执行。AI 无法在代码层面化解这个矛盾，它的常见处理手法是把“事务开启”和“事务提交”放在一个模块，中间对另一个模块的调用则通过“传递 Connection 对象”的方式来实现，这又一次把封装破坏殆尽。

• 第三种：散落业务规则型单体。业务规则不是集中在某个规则引擎或策略类中，而是散落在 Service 的各个判断分支里。同一个业务规则（比如“VIP 用户免运费”）可能出现在三个不同的 Service 文件的六处 if 语句中，每处的逻辑还略有不同（因为历史上针对不同场景做过微调）。Claude Code 在拆模块时，无法判断哪一处是这个规则的“权威定义”，哪些是历史遗留复制。它的处理方式往往是每个模块保留自己的那部分规则判断，结果就是，模块化生成反而把规则的一致性从“集中混乱”变成了“分布式混乱”。

• 第四种：极长参数链穿透型单体。一个方法需要 12 个参数，这些参数本身就来自调用链的上游，上游的参数又来自更上游。整个调用链从头到尾传递着一个臃肿的参数对象。Claude Code 在拆模块时，如果要遵循接口精简原则，就需要识别哪些参数可以在哪个层级被“消解”掉，这在没有数据流分析的情况下几乎是不可能的。它最方便的做法是把那个臃肿的参数对象整个声明为模块接口的参数，然后在接口文档中注明“大部分字段仅用于下游传递”。这种做法在语法上完成了模块化，在语义上依然保持了高扇入高扇出，接口变换等于没变。

在这四种单体基因下使用 Claude Code，最需要警惕的不是它生成不了代码，而是它会生成一套看起来符合模块化语法、但完全没有享受模块化好处的代码。你得到的不是高内聚低耦合，而是把原有的弊端换了一套更整洁的包装。

上下文窗口的退化曲线：为什么一个任务不能无限延续

我在前面多次提到“对话轮次”“上下文污染”“注意力稀释”，这一节我决定把这个问题单独展开。因为不管你想出了多精妙的模块化策略，如果你不理解 Claude Code 的上下文退化曲线，你会在不知不觉中把所有策略的效用消耗殆尽。

我把这种退化现象称为“上下文折旧”。

我做过一个控制实验：将同一个 4000 行的单体文件，以两种方式交给 Claude Code 进行模块化拆分。方式 A 是在一个持续的长对话中，逐步提出拆分需求，从外层模块到内层模块，对话持续超过 30 轮。方式 B 是将任务分成 4 个独立的会话，每个会话只做一部分拆分，每次都用干净的新上下文开始，同时输入之前已拆分好部分的接口定义文件作为参考。

结果显示，方式 B 的最终模块质量显著更高，依赖清晰、边界干净、几乎没有循环依赖。方式 A 在 15 轮之后生成了明显的“尾段质量衰减”，最后几轮生成的模块代码在命名规范、接口隔离、注释完整性上都出现了肉眼可见的下降。

更让我注意的是，方式 A 中出现了三次“重复劳动”，Claude Code 在第 18 轮生成的代码，和它在第 9 轮生成的代码有 60% 的功能重复，但它没有感知到这个重复。它像是忘记了自己在几小时前曾经处理过一个几乎完全相同的拆分需求，只是因为被拆的那个方法是另一个模块中结构相似的方法。

这个实验结果指向一个结论：Claude Code 处理大型单体应用模块化的有效上下文窗口，大约在 15 到 20 个实质性交互轮次左右。 超过这个范围，早期约定的约束会因为注意力竞争而逐渐失活。

这里的“实质性交互轮次”需要精确解释。它不是单纯的对话次数，而是指每次你让模型进行一次完整的“分析-生成-解释”过程。如果你只是做一个轻量级的修正（“把这个变量名改掉”），那对上下文的负担较小。但如果你是在追加一个全新的拆分需求，让它重新分析一段代码并生成一个新模块，这就属于一次“实质性交互”，会显著消耗上下文中保留早期约定的注意力资源。

所以，对于大型单体应用，我的实战建议是采用“硬分步”的工作机制：

1. 事前规划模块边界，明确每个模块的职责和对外接口。
2. 把整个拆分任务切分成多个独立的子任务，每个子任务不超过 12~15 个实质性交互轮次。
3. 每一个子任务都在一个新对话中启动，并在启动时明确输入：上一阶段的模块接口定义文件、模块职责说明书、以及当前要拆分的代码片段。
4. 每个子任务结束时，要求 Claude Code 生成一份“模块接口快照”，作为下一个子任务的启动物料。

这个流程听着比“一次性全拆完”复杂，但在真实的大型工程中，它反而能节省大量后续修复“上下文遗忘型 bug”的时间。

反直觉的约束策略：为什么对 AI 也必须“限制创作自由”

在跟 Claude Code 协作了这么长时间后，我建立起了一个对它工作模式的核心理解：它不是不愿遵守规则，而是规则必须以一种在它生成每一个 import 语句时都能“闪现”在注意力窗口中的方式被提供。 口头约定、模糊指令、默认共识，这些在人类团队中行得通的信息传递方式，在两个小时的持续对话后，对 AI 来说基本等于不存在。

基于这个理解，我开始尝试一套与“给 AI 自由让它发挥”完全相反的约束策略：用代码来约束代码的生成。

具体做法是这样的。在我开始任何模块化拆分任务之前，我要求 Claude Code 先生成一个 “Module Constitution”（模块宪章）文件。这不是一个给人看的文档，而是一个给 AI 自己看的、可被编译器检查的约束文件。

这个 Module Constitution 中包含以下部分：

• 明确的包名列表和每个包的可见性边界（哪些包对外暴露，哪些包仅为内部使用）；
• 每个模块的允许依赖白名单（A 模块只允许依赖 B 模块的接口包和 C 模块的数据对象包）；
• 禁止的依赖模式黑名单（禁止任何子模块依赖父模块，禁止基础设施层依赖领域层内部类，禁止循环 import）；
• 每个公开接口的方法签名和返回值类型，不允许返回任何其他模块的内部类型。

这个文件本身是一个文本文件，但它的结构非常结构化，类似一份 YAML 或 JSON 格式的配置。在开始实际生成代码之前，我先要求 Claude Code“阅读这份 Module Constitution，并且确认理解其中的所有约束”。然后，在后续每一次代码生成时，我都会在指令末尾追加一行：“严格遵守 Module Constitution v1.2 的所有条款。”

这个做法听起来有点机械，但效果显著。在我对这 11 个测试任务中的最后 4 个采用 Module Constitution 方法后，之前高频出现的边界违规、循环依赖和内部类型泄露问题，综合发生率下降了大约 60%。

为什么这个简单的手法会有效？

我认为原因是这样的：口头指令在长对话中会“沉没”，它们存在于对话历史的深处，当模型在处理第 28 轮对话时，第 3 轮的“记得不要直接 new 那个缓存对象”指令，在注意力分配中的权重已经极低。但当你在最新的消息中再次显式引用“Module Constitution v1.2”时，你等于是给了模型一个检索锚点，让它可以重新加载整个约束集到当前的推理上下文中。

同时，Module Constitution 本身的结构化格式也有帮助。和自然语言的大段描述相比，结构化列表中的每一项都是一个离散的“检查点”。模型在生成代码时，可以逐项核对“即将生成的 import 语句是否在白名单中”“即将 new 的对象是否来自被禁止的包”，而不是在几千字的描述中自行筛选哪些指令仍然有效。

这条经验揭示了一个反直觉的原则：对 AI 编码助手来说，“限制它的创作自由度”反而是提升大型模块化生成质量的捷径。 你把模棱两可的判断权从它手里收回来，变成黑白分明的检查清单。它不需要“理解”为什么要避免循环依赖，它只需要知道“当 import 白名单中不包含目标模块时，坚决不生成那个 import 语句”。

大型单体应用中，哪些模块化工作应该交给 Claude Code，哪些必须由人来做

写到这里，我必须澄清一个可能的误解。我在前面九节中花了大量篇幅分析 Claude Code 在大型单体应用模块化中的各种失败模式，但这不代表我认为它不能用于这种场景。恰恰相反，在摸清它的能力边界之后，我在日常工作中已经形成了一个比较成熟的分工策略。

这个策略的核心原则是：把 Claude Code 看作一个拥有极强“代码改写执行力”、但缺乏“架构设计长期一致性判断力”的资深初级工程师。 它适合处理那些规则明确、边界清晰、只需大量重复性工作的部分，不适合做需要牺牲当下便利换取长期低耦合的架构性决策。

具体来说，以下三类工作，我会优先交给 Claude Code：

第一类：在已经明确定义了接口和模块边界之后的具体方法迁移。当我花时间把模块宪章、接口定义、包结构都定下来之后，剩下的工作就是把一个个具体方法从旧的单体文件中搬运到新模块中，修改方法内部的调用，同时确保编译通过。这个工作量大、重复性强，但规则极其明确，正是 Claude Code 的优势区域。我通常要求它每次只迁移一个方法，迁移完立刻编译验证，通过之后再迁下一个。这种“小步快跑”的策略能让错误率降到最低。

第二类：根据已迁移模块生成对应的单元测试。Claude Code 在理解接口语义后，能快速地生成覆盖常规路径、边界条件和异常场景的测试用例。我会对生成的测试用例做一轮人工审查，确认断言逻辑正确，然后这些测试用例就变成了后续迁移工作的“安全网”。

第三类：统一修改被多个文件引用的 import 路径。当我把一个类从一个包移到另一个包后，所有引用这个类的地方都需要修改 import 语句和包级依赖。这个工作交给 Claude Code 非常合适，因为规则高度确定，没有歧义空间。我只需要给它一个“全局替换旧路径为新路径”的指令，附上所有需要修改的文件列表。

那么，哪些工作必须由人来做？

第一类也最不可让步的：定义模块边界和职责分工。这个决定是宏观架构判断，它需要理解未来 2-3 年的业务演进方向、团队的组织结构、哪些模块可能被独立部署或替换。这些信息完全在代码之外，Claude Code 不可能获得。把这一层决策交出去，等于让一个从来没有跟业务方开过会的人来做架构选择。

第二类：剪断历史设计债务中纠缠最深的耦合。那些从第一版代码就存在、跨越了 5 个版本迭代、半打紧急补丁都没有理顺的核心循环，必须由人亲自上手。原因我在失败模式二中已经解释过：Claude Code 在面对这种历史耦合时，倾向于保留而非剪断。你需要的不是一个能把这些耦合包装得更好看的 AI，而是一个能判断“这条依赖线必须被打破，哪怕这意味着要重写接口签名”的决策者。

第三类：制定和持续更新 Module Constitution。这份约束文件需要随着模块化工作的推进而演进。哪些规则被证明有效，哪些规则过于宽松或过于严格，哪些依赖在当前阶段可以暂时容忍但在下一阶段必须消除，这些判断需要一个人持续站在全局视角做出权衡。Claude Code 可以被要求“遵守 Module Constitution”，但让它本身来编写和优化这份文件，就相当于让考生自己出题。

这张分工表是我在多个项目迭代中逐渐收敛出的实践框架。它不是一成不变的教条，随着 Claude Code 的能力演进，某些环节的人员参与比例可能会下调。但以我当前（2025 年中）的实践体验来看，坚守上面三条“人的底线”，可以显著降低大型单体应用模块化项目中的整体风险。

给即将在大型单体应用中启用 Claude Code 的你，五条可操作的决策准则

如果你读到这里，正在考虑或已经在大型单体项目的模块化拆分中使用 Claude Code，我这里给你五条可以直接参照执行的决策准则。它们来自我过去一年在不同项目中的反复踩坑和修正，不是理论推导，而是实践沉淀。

准则一：3000 行是一条红线。当你要拆的单个文件超过 3000 行时，不要把整个文件一次性交给 Claude Code。先由人做一轮“物理拆分”，按照方法名称前缀或注释分区，把一个大文件割成多个 500-800 行的分段。然后每个分段单独在一个新对话中处理，配上明确的接口定义。直接拆 3000 行以上文件的失败率，在我这里的统计是，超过六成会在前三轮就出现不该有的依赖泄露。

准则二：上下文寿命控制在 15 轮以内。一个对话从开始到结束，如果涉及超过 15 次“分析-生成-确认”循环，你就应该认真考虑把下一个子任务挪到新对话中。这不是说满 15 次就突然失效，而是 15 次之后的生成质量开始进入一个不可靠的下滑区间。你可能在 18 次时还是好的，也可能在第 16 次时已经悄悄出现边界模糊。为了安全，我宁可提前断，不拖延。

准则三：没有测试做安全网，就不要让 AI 自动拆分。这是我在失败模式五中详细解释过的那条铁律。如果你面对的是一个测试覆盖率趋近于零的遗留方法，第一优先级不是让 Claude Code 拆模块，而是让它生成测试。生成的测试你审阅确认后执行一遍，保证在当前代码上全部通过。然后把测试作为拆分后的验收标准。这让你从“代码审阅者”变成了“规范验收者”，效率和确定性都大幅提升。

准则四：架构图和代码不要同时喂。这是失败模式四的核心教训。如果你需要为 Claude Code 提供高层架构参考，要么在给代码之前先单独让它阅读架构图并产出一份文本化的架构约束说明，要么让架构图通过 Module Constitution 文件间接发挥作用。不要同时把一张 JPG 的架构图和 8 个 Java 文件一起拖进对话框，那两个信号互相打架的结果，你已经在本章看到数据了。

准则五：接受“95% 模块化”的妥协方案。这是我经过多次挫折后才接受的一个现实。大型单体应用中的某些极端耦合，在当前的技术条件下，AI 和人类都没有优雅的拆解方案，除非愿意重写整个模块。与其硬拆出一个“样子对但内在烂”的模块，不如接受一个折中：保留一个不超过 200 行的“遗留耦合片段”，对它做清晰的注释和处罚式命名（比如 LegacyCoupling_DoNotExtend），同时在模块宪章中把这个片段列为下一迭代的重构目标。工程是关于取舍的，不完美的模块化好过虚假的模块化。

这五条准则代表了我在当前时间点对 Claude Code 在大型单体模块化场景下能力边界的判断。我知道这些准则会随着模型本身的进化而过时，也许一年后，架构图和代码能够被更好地协同理解；也许持续对话的有效轮次会从 15 轮提高到 50 轮。

但真正重要的不是这五条具体数值，而是背后的一套思维方法：对 AI 编码工具保持实证主义态度，不是在推上看了几个 Demo 视频就相信它能搞定一切，而是用自己的真实项目去压测，去记录失败，然后根据记录调整自己的使用策略。

这种思考方式不会过时。

结尾：你与之协作的，是一个有偏好的推理机器，不是一个有判断力的工程师

写到这里，我突然能用一个我打磨了很久的类比来总结 Claude Code 在面对大型单体应用时的行为特征。

它是一个“地图绘制机”。

你给它一座城市的卫星照片（你的单体代码），它能极快地产出一份尺寸精准、标注详尽的街道地图。每一条街道都画得清晰、比例正确、颜色标注符合你的要求。你催促它把这张街道图按行政区拆成几张分区图，它能照做，每个区看起来都独立完整。

但问题在于，它不是透过“规划逻辑”来理解城市的。它不理解哪些道路天然是主干道、哪些路应该被改成单行道以减轻未来拥堵、哪两个区域之间的道路连接线应该在下一版规划中被削弱。它只是把你给它的那张卫星图，按你的指令，用最忠实的笔触重新画了一遍。

你真正需要的是一个建筑师，一个能理解这座城市的生长逻辑、能对未来的交通流量做出预判、敢于砍掉某条历史遗留但已经不再合理的道路的人。这个人此刻就是你自己。

在过去一年里，我经历了从“AI 即将替代大量架构工作”的兴奋，到“AI 在复杂工程结构中会犯相当低级的结构性错误”的失望，再到“理解了它的运作机理后，它成了我生产力中不可或缺的倍增器”的现在。这个过程让我对 Claude Code 这类工具建立了一种相当稳固的信任结构：我信任它执行，但我不信任它判断。我信任它生成，但我不信任它设计。我信任它搬运，但我不信任它剪断。

如果你正在接手一个大型单体应用，正在考虑引入 Claude Code 来做模块化拆分，我的建议可能是你在这篇长文中看到的最朴素的一句话：在动手之前，先花一个下午，在项目的一个非关键分支上，刻意触发这篇文章里描述的每一种失败模式。 看到循环依赖真的被生成出来了，看到边界在 20 轮对话后真的模糊了，看到测试覆盖为零时的静默错误有多隐蔽。只有当这些失败从纸面的描述变成你 IDE 里真实飘红的编译错误时，你才会真正建立起对这项技术的“肌肉记忆式”认知。

然后，带着这种认知，你可以开始真正的工作了。你会知道什么时候该信它，什么时候该收回来自己动手，什么时候该把一个长对话果断掐断，打开一个新的干净窗口。

理解和驾驭一个工具，不是知道它能做什么，而是明确它一定会搞砸什么。对 Claude Code 在大型单体应用中的模块化生成这件事，我能给出的最高敬意，就是把两者的边界都诚实地说清楚。