接手一个跑了四年的后台系统两千多个文件核心领域层的循环依赖像蜘蛛网一样越缠越紧每次加需求都要在几个模块之间来回跳。这种项目常规排期重构至少三个月而且风险极高——动一发牵全身改到一半业务方还要继续提需求。我第一次尝试用Claude Code做这类重构时说实话并没有指望它能直接给出答案更多是抱着“让它帮我写点重复代码”的心态。但试过几次之后我意识到用对了方法它在大型重构里的价值远超预期用错了方法它也能在十分钟内给你制造出一堆匪夷所思的问题。这篇文章不打算做泛泛的工具介绍而是围绕“用Claude Code做大型项目重构与架构优化”这件事把我踩过的坑、验证过的工作流、以及现在团队里还在用的配置方式全部整理出来。内容覆盖安装配置、模型接入、Skill设计、CLAUDE.md上下文工程、依赖分析、增量重构、测试验证和团队协作适合已经会用Claude Code写小功能、但还没敢让它碰核心架构的人。1. 大型重构不是“让AI写代码”而是“让AI按你的架构意志施工”1.1 为什么我在踩坑三次之后才敢用它做重构第一次让Claude Code重构一个支付模块我给的指令是“把这段逻辑抽成策略模式”。它很快给出了一大版改动代码能编译功能测试也过了但我仔细一查发现它把策略工厂里的缓存逻辑连同状态字段一起挪走了第三方回调的状态机边界被悄悄改掉。那次之后我得出的结论是Claude Code本身不会理解“架构意图”它只会理解prompt里写出来的约束。重构这种高风险的场景最重要的是把它当作一个执行速度极快、但理解能力需要不断校准的工程师而不是一个能自己做架构决策的架构师。第二次我学乖了开始用文档约束它给它画模块边界、写清依赖规则再让它动手。那次重构虽然也出现了一些小问题但整体可控。连续做了几个模块之后我形成了一套固定流程。现在团队里新同学接入这个工作流基本两三天就能上手。所谓“用Claude Code做大型重构”核心其实是“把架构决策留给人、把重复劳动交给工具”。1.2 Claude Code在重构场景里的真实定位Claude Code本质上是一个跑在终端里的AI编程代理它比你在IDE里粘贴聊天更接近“一个协作者”的体验。它能读取项目文件、执行命令、修改代码甚至调用构建工具跑测试。这一点在大型重构里特别重要因为重构不是“写一个新函数”而是“理解一段纠缠在一起的旧逻辑再小心地把它拆开”。我更愿意把它定位成三个角色。第一代码考古学家。它可以快速扫描整个仓库帮你回答“这个模块到底被哪些地方引用了”“这段废弃逻辑还有没有调用方”这类问题。第二批量修改工人。当你要对几十个文件做同样的模式替换时它比人手高效得多。第三架构文档记录员。它可以基于现有代码生成模块说明、依赖关系清单和数据流描述这些材料对后续重构决策非常关键。但它不应该承担的角色是“架构决策者”。依赖该往哪个方向收、模块边界画在哪里、接口要不要兼容旧调用方这些必须由人来定。Claude Code擅长的是在边界确定后快速且一致地执行迁移。你给它越清晰的约束它的输出就越可控你越指望它“自己看着办”它就越容易给你办出一堆需要返工的事。1.3 适合Claude Code处理的重构类型与不适合的类型从实践来看适合交给Claude Code的重构主要有几类机械性重构、模块解耦、依赖清理、统一规范。机械性重构是指把某个公共函数的调用方全部替换为新接口这类模式统一的操作模块解耦是把模块之间对内部实现的直接引用改造成通过接口访问依赖清理则包括删除无用import、找出并移除死代码统一规范是把散落各处的日期处理、日志格式、错误码定义都收敛到一个公共位置。不适合的类型边界也很清楚。涉及核心业务规则、并发安全、分布式一致性这类强领域逻辑的改动不建议让AI直接动手必须由人完成设计AI只能做代码层面的辅助。另外跨模块的大规模数据迁移一旦出现错误影响面非常广也不适合让AI自动改。两类项目的区别在于“错误代价”。机械替换错了测试能兜住核心领域逻辑错了可能上线后很久才发现。所以我的原则是让Claude Code做高风险但低容错的工作用人和测试双保险低风险高重复的工作可以放开让它批量做。2. 开工前的装备装好CLI、接对模型、把Skill建立起来2.1 安装与三种运行形态CLI/桌面版/IDE插件Claude Code目前主流的运行形态有三类。第一类是CLI命令行工具这也是我最推荐做重构时使用的形态因为终端里可以配合git、grep、rg这些工具一起工作脚本化能力强能直接执行编译、测试命令。安装方式不复杂官方提供npm包全局安装即可如果你不想用npm也可以用桌面版安装包桌面版自带终端和项目文件管理界面适合不喜欢纯命令行的同学。第二类是VS Code插件在扩展市场搜索Claude Code即可安装适合平时写代码就在VS Code里的人。第三类是桌面应用适合把AI对话窗口独立出来的场景。实际选型上我的建议是日常重构用CLI写小功能验证用IDE插件完全命令行恐惧的用桌面版。Windows、macOS、Linux的安装包和命令略有差异但整体流程都是“安装-登录或配置密钥-进入项目-开始对话”四步。如果团队同学用IntelliJ IDEA开发也能找到类似集成方式只是生态成熟度不如VS Code。无论哪种形态安装前都建议确认一下Node环境版本别一上来就报各种依赖错误。2.2 settings.json与模型接入那些报错其实都是配置问题很多新手卡在第一步装好了Claude Code但不知道怎么接模型。默认情况下Claude Code会使用Anthropic官方的模型需要你有对应的账号和密钥。实际使用中很多人会希望接第三方模型或者本地模型这时候就要靠配置文件。常见做法是设置环境变量比如ANTHROPIC_BASE_URL指向你使用的模型服务地址ANTHROPIC_AUTH_TOKEN填对应的访问令牌然后在Claude Code的settings.json里指定模型名称。settings.json通常位于用户目录下Windows和macOS路径略有差异。如果你用的是ccswitch这类模型切换工具它会帮你管理多套服务商配置切换起来比较省事尤其适合团队里同时接多个模型服务商的场景。常见现象真正原因处理办法提示“xxx is not a model this version of claude code recognizes”模型名与服务商实际标识不一致或Claude Code版本太旧升级Claude Code并从服务商文档复制准确的模型标识同样配置在CLI生效、在插件不生效插件没有热加载配置文件重启插件窗口或统一只走CLI入口连续报529错误模型服务端当前负载过高等待几分钟重试不要反复重试加重压力回答全是英文没有声明语言偏好在CLAUDE.md里写“始终用中文回答”这里我踩得最深的坑就是模型名不匹配。第一次接第三方模型时控制台一直提示某个模型名不被当前版本识别我以为是配置写错了反复改settings.json结果真正原因是版本太旧。把Claude Code升级到最新版后同样的配置立刻生效。所以遇到模型相关报错先升级工具再核对模型标识最后检查配置是否冲突别一上来就怀疑环境变量写错。另一个高频问题是回答语言。默认情况下可能用英文回复你不希望在重构对话里还要做阅读理解。我习惯在CLAUDE.md开头写明“始终用中文回答”这样每次会话自动生效不用每次开头都补一句指令。2.3 Skill不是装饰品把重构流程固化成交互指令Claude Code的Skill机制是很多人的盲区。简单来说Skill是把一组指令、参考文档和示例打包到特定目录里让Claude Code在需要时自动调用。它特别适合用来固化“你希望AI按照你的团队标准执行的任务”。目录结构大致是在用户目录下建立skills文件夹每个Skill一个子目录里面放一个SKILL.md文件。这个文件有YAML格式的frontmatter包含name和description字段description里写清楚这个Skill在什么场景下启用正文部分就是具体的执行说明和模板。--- name: dependency-audit description: 扫描指定目录的依赖关系输出模块依赖矩阵与循环依赖清单用于重构前的边界分析。 --- 1. 先列出目标目录下的所有一级模块。 2. 对每个模块提取其对其他模块的import引用。 3. 汇总成模块依赖矩阵。 4. 标记出所有循环依赖路径。 5. 输出报告包含每个循环依赖涉及的文件与建议解耦方向。我为重构场景做了两个Skill一个是code-review要求AI按我们团队的Code Review清单逐条检查改动另一个是dependency-audit就是上面这个。这样一来每次重构前执行一次依赖审查改完代码执行一次审查流程稳定不会因为这次prompt写得详细、下次写得简单而波动。Skill真正的价值在于把团队公认的执行标准沉淀下来任何人用Claude Code时都能复用同一套流程。3. 重构前先给AI画地图CLAUDE.md、模块边界与任务拆解3.1 让AI记住项目上下文CLAUDE.md到底写什么大型重构最怕AI“失忆”。你上午让它分析了模块A的依赖下午它又跑去看模块B等你想让它基于上午的分析继续改它可能已经把上午的结论忘光了。CLAUDE.md就是用来对抗这个问题的主要手段。CLAUDE.md是放在项目根目录下的说明文件Claude Code每次启动对话时都会自动读取。很多人只会往里面写“这是一个某某项目使用了某某框架”这远远不够。我给项目写CLAUDE.md时至少包含四类内容# 项目背景 这个系统是订单中台核心职责是订单生命周期管理。 # 架构决策 - order-service 不允许直接调用 inventory-service 的实现类只能通过 InventoryGateway 接口。 - payment-service 的状态机枚举只能新增不允许修改或删除已有枚举值。 - 所有对外HTTP接口必须保持兼容字段不允许重命名新增字段需设置默认值。 # 代码约定 - 模块目录src/main/java/com/company/module - 编译命令mvn -pl module -am compile - 测试命令mvn -pl module test -DtestTestName # 重构禁忌 - 不允许修改数据库迁移脚本。 - 不允许改动公共API包的类签名。 - 不允许把多个类的公共逻辑合并到现有工具类中除非经过人工确认。CLAUDE.md写得好不好直接决定AI后续行为合不合规。它不是一次性写好的而是在重构过程中不断补充。每当AI出现一次“它不该这么改但我没约束过”的问题我就把对应规则加进去下次它就不会再犯。这个文件相当于给AI立规矩立得越详细重建工作越稳。3.2 模块边界识别从“哪里能改”到“哪里不能碰”真正的重构开始前我会花至少一两天时间先做模块边界梳理。这个过程可以完全交给Claude Code打辅助让它读取代码结构输出一份模块清单标出每个模块对外暴露的接口、依赖的其他模块以及可疑的循环依赖。这里有一个很实用的做法把“允许修改的文件白名单”和“禁止修改的文件黑名单”直接写进本次会话里。比如“本次重构只允许修改order-service下的main目录test目录只能新增不允许改动payment-service和user-service下的任何文件都不允许触碰。”这样能大幅降低越权改代码的风险。判断“哪里不能碰”比“哪里能改”更重要。重构失败通常不是因为AI改坏了某个模块而是因为它顺手把周边模块也改了。我最开始那几次翻车就是没有给AI画清楚“禁止区域”导致它抱着“让代码风格更统一”的心态改了不该改的文件。这个习惯沿用到现在几乎每一次危险改动都被提前拦住了。3.3 小步重构的任务切法为什么一次只动一个模块大型重构如果让AI一口气完成结果往往很难收场。上下文窗口有限AI中途会遗忘前面的决策改动范围越大冲突和回归风险越高代码审查时你也很难在一堆diff里找出真正的问题。所以我的任务按“模块-子任务-文件”三层来切。一个模块的重构会拆成先分析现状输出问题清单然后设计迁移方案明确新接口、调用方迁移顺序、兼容策略接着按文件批量执行迁移每批文件改完立即编译并跑相关测试最后提交一次带有清晰描述信息的commit。每次会话我只让Claude Code做一个子任务。它改完之后我review diff确认没问题再进入下一个子任务。这样做单个会话的上下文不会被塞满AI的表现更稳定diff更小review更轻松即使某个子任务出问题也可以安全回滚不影响其他模块。这个节奏看起来慢实际上比“让AI一次改完再疯狂修bug”要快得多。4. 一次完整重构的实操过程依赖分析、迁移、验证、文档4.1 用Claude Code做依赖分析与循环依赖定位实际重构的第一步我通常打开终端进入项目目录启动Claude Code然后给它一个明确的指令“扫描src/main/java目录下的所有import关系输出模块间的依赖矩阵标出循环依赖并列出order-service对payment-service内部类的直接引用。”Claude Code会自己读取文件、分析代码、甚至运行脚本最后给出报告。它比人肉grep高效的地方在于它能理解“这个类实际上是通过哪个接口被调用的”“这段引用是编译期依赖还是运行时反射”从而过滤掉大量噪音。不过要注意对于超大仓库一次扫描可能会读入大量文件导致上下文消耗很快。我的做法是先让它只扫目录和文件名再用rg等工具过滤关键引用最后把真正需要分析的文件路径发给它避免一次性读入整个仓库。拿到依赖报告后我会和它一起确定需要解耦的边界。比如它发现order-service里有一处直接new了payment-service的内部类PaymentProcessor那么重构目标就是把这一处改成调用payment-service对外暴露的PaymentService接口。边界确定之后再进入下一环节。4.2 增量迁移的执行顺序与提交节奏迁移执行阶段我遵循“先建接口再造实现再迁移调用方最后删除旧代码”的顺序。第一步让Claude Code在目标模块中创建新的接口或门面类。这通常是新增代码风险很低可以直接让它做。第二步让它把旧逻辑迁移到新接口的实现里保持行为不变。第三步迁移调用方。这里建议每次只迁移一部分调用方比如先迁移某个子包内的所有调用编译并运行相关测试没问题再迁移下一个子包。第四步等所有调用方都迁移完成后再统一删除旧的内部类或废弃方法。提交节奏上我的习惯是“每个子包迁移成功后就提交一次”。commit信息写成“refactor(order): 将订单模块对支付内部类的引用迁移至PaymentService接口”。这样不仅回滚方便后面生成重构报告时也直接有素材。这个过程中Claude Code是主要的代码执行者但我不会让它自己执行git commit。commit由我来执行和审查避免它把不该提交的东西一起带走。4.3 测试与回归重构后如何判断架构真的变好了重构最重要的底线是“行为不变”。我在迁移每个子包后会立刻让Claude Code编译项目、运行与该模块相关的单元测试和集成测试。如果测试没过我会先看是测试环境问题还是代码迁移问题把diff缩小到最小范围后再继续。除了自动化测试我还会做一次人工diff审查重点看四类改动接口签名是否被不必要地调整异常处理逻辑是否被简化并发控制相关的synchronized、锁、线程池配置是否被改动日志级别和时间格式是否被统一改掉。这四类是AI迁移逻辑时最常“好心办坏事”的地方。判断“架构真的变好了”不能只看测试通过。我还会让Claude Code输出重构前后的对比数据比如模块间依赖数量、循环依赖数量、核心模块的圈复杂度、文件行数等。下面是我习惯用的对照表指标项重构前重构后说明order-service→payment-service直接引用数230全部收敛到接口循环依赖路径数72剩余2条需要后续专项处理核心领域类平均圈复杂度1811拆出独立策略类后明显下降相关单测通过率100%100%行为未变这些指标下降说明重构有效只有测试通过但指标没变化说明改了个寂寞。4.4 生成架构文档与重构报告重构工程结束时我会安排Claude Code把整个过程沉淀成文档。包括两部分一份是模块架构说明描述当前模块的依赖关系、对外接口、演进方向另一份是重构报告列出每个模块的问题、迁移方案、改动文件、测试结果和遗留风险。我常用的做法是把“生成架构文档”也做成一个Skill。输入项目目录路径它就按固定模板输出文档。这样团队里的文档风格是一致的不会这次写得详细下次写得敷衍。架构文档的作用是给未来的维护者看的如果下次AI或者新人改这块代码他们可以先读这份文档再动手而不是重新考古。5. 踩坑现场上下文截断、幻觉改动、多会话冲突5.1 会话越长越笨上下文管理是重构项目的生死线这是我在所有坑里吃亏最多的一项。Claude Code刚开始表现得像一个很聪明的同事但当一个会话里塞入的信息超过一定量后它的行为会明显退步忘记你一开始强调的约束、回答变得宽泛、甚至在修改代码时开始自我发明。我的理解是它需要在“记住之前的对话”和“处理当前的文件内容”之间分配注意力一旦超出窗口它就会选择性遗忘。大型重构恰恰是信息量最大的场景所以必须主动控制上下文。我有几条硬规则单次会话不做超过一个子任务的分析与修改所有重要的约束和结论都写进CLAUDE.md或单独的报告文件不依赖对话记忆不让AI一次性读取几十个大型文件必要时先让它列出文件清单再分批读取每次新会话开始时先让它读取上次生成的报告文件把“记忆”转移到文件里。这招非常管用。把记忆外置到文件之后AI即使换了新会话也能快速恢复上下文而且不会因为对话内容太多而越改越乱。有一次项目重构持续了两周我每天开好几个新会话但因为有报告文件和CLAUDE.md接力整个过程中AI几乎没有出现过“忘记之前决定”的情况。5.2 越权与幻觉Claude Code改了我没让它动的文件第二个大坑是越权。AI天生有“让代码变得更好”的倾向所以它可能在改接口的时候顺手重命名了一个方法可能把两个看似重复的类合并了可能把旧的日志框架升级成了新的。这些改动单独看diff时可能没问题但合在一起就超出了“重构”的边界。我现在对付越权有两个办法。第一是权限控制Claude Code支持配置允许执行的命令和允许修改的路径我会在重构会话里明确只放行项目子目录的读写权限把无关路径全部设为只读或禁止访问。第二是diff纪律每次AI改完我都要逐个文件查看diff不放过任何涉及公共API、全局配置、数据库脚本的改动。看起来麻烦但大型重构本来就不能追求快追求的是稳。幻觉问题也同样常见。AI确实会生成一些看起来合理但实际并不存在的API或者依赖配置。最典型的是它引用了项目里根本不存在的工具类我追问之后它道歉然后重新生成。对付幻觉最有效的还是编译和测试。任何不经过编译验证的代码都不要相信。我甚至会让Claude Code在完成迁移后自己跑一遍编译命令并汇报结果因为它在“自证正确”的过程中通常会暴露问题。5.3 桌面版、CLI插件切换模型与服务商时的坑我平时会在CLI、VS Code插件、桌面版之间切换使用。这套组合本身很高效但也会带来配置不同步的问题。比如你在CLI的settings.json里配置了三方模型到VS Code插件里发现没生效原因往往是插件读取的是同一个配置文件但插件没有热加载配置需要重启窗口桌面版又可能有独立的配置入口导致同一个项目在不同入口下行为不一致。我的建议是固定一套配置尽量统一走CLI和同一个配置文件需要切换服务商时用ccswitch这样的工具统一管理切换后先跑一个最简单的命令确认模型生效比如让它输出“OK”再进入重构流程避免做到一半才发现模型不对。还有那个“xxx is not a model this version of claude code recognizes”的报错通常也是在一个入口改完配置另一个入口还沿用旧配置导致的。统一配置入口之后这个报错基本就消失了。5.4 多路并行重构在团队协作中的冲突与对策团队大了之后大家可能各自开一个Claude Code会话同时改不同模块。如果这些模块之间有依赖关系git冲突会非常严重。我有一次让两个人分别用AI重构订单模块和支付模块结果两个模块都认为自己可以控制某个公共接口提交时大量冲突最后只能手动合并。现在我们的做法是错峰执行。虽然大家同时都在用Claude Code但涉及共享接口或公共模块的改动一次只允许一个会话处理其他会话只做独立的、低层级的业务逻辑迁移。每当一个会话开始改公共区域我会把它对应的分支从主分支拉出来避免多人同时在同一条分支上操作AI。另外一定要强调代码审查。AI生成的代码无论看起来多专业都必须经过人类review才能合入。Claude Code能显著加速“生产代码”的过程但“承担责任”的仍然是人。团队协作时我会要求每个子任务的改动都必须附加“AI改动说明”方便review的人快速理解这次改动为什么这么写。6. 最后几句实在话用Claude Code做大型重构我的核心感悟是它最大的价值不是“替你想”而是“替你查、替你写、替你整理”。你真正要做的是把架构判断、边界约束和安全底线想清楚然后把那些重复、机械、消耗耐心的部分交给它。配置一套好用的环境、写好CLAUDE.md和Skill、把重构拆成可验证的小步骤这些前期功夫决定了AI是帮你还是坑你。如果你现在正准备重构一个老项目我的建议是从一个小模块开始先跑通这套工作流再逐步扩大到核心模块。别一上来就拿最复杂、最核心的领域层练手。等流程稳定了你会明显感觉到重构不再是一场豪赌而是一个可以迭代、可以回滚、可以积累经验的工程过程。