最近我把一个跑了快四年的老项目做了一次大规模重构整个过程里Claude Code 是我最得力的搭档。以前提起重构我脑子里全是“高风险、大动静、改一行挂三处”的惨痛回忆但这次借助 Claude Code把原来预估要两到三周的机械性改造压缩到了不到一周。这篇文章就把我这次实战中的完整思路、具体命令、参数取舍和踩坑记录整理出来给正准备用 Claude Code 做代码重构的朋友一个参考。先说清楚 Claude Code 是什么它是 Anthropic 官方的命令行 AI 编程助手能在终端里直接读取项目文件、调用工具、执行命令、修改代码。对比网页版 Claude 或者普通聊天式 AI它最大的差异是能真正“动手”而且带上下文感知可以理解整个仓库的结构而不是你复制一段代码它改一段代码。如果你要在现有工程里做重构这正好是刚需重构的本质是“在保持外部行为不变的前提下改善内部结构”这种工作极其依赖对代码库整体的理解而 Claude Code 的 Agent 式工作方式恰恰能把“读代码—分析—改代码—跑测试—迭代”串成闭环。这篇文章会按照我实际操作的顺序来组织先说为什么重构场景适合用 Claude Code然后是环境和权限准备接着是重构任务的方法论拆解再用一个真实模块的改造过程做完整演示最后是这几天高频踩坑的排查手册。无论你是刚接触 CLI 工具的新手还是已经在用 Claude Code 但觉得它“不够可控”的老手这篇文章应该都有值得借鉴的地方。1. 重构这事为什么值得交给 Claude Code1.1 了解它和聊天式 AI 的本质差异很多朋友问我我直接用 ChatGPT 或者 Claude 网页版把代码贴进去不也能改吗为什么非要单独搞一个 Claude Code我的回答通常是一句话网页版是“对话”Claude Code 是“协作”。在网页版里你贴一段代码它给你一段修改建议然后你手动应用到项目里。遇到跨文件的改动你得自己把相关文件一个个喂给它改完之后还得自己跑测试看结果。整个过程本质上仍然是“人肉搬运工”AI 只是你的注释工具。Claude Code 的工作模式完全不同。它运行在项目目录里自带文件读写、命令执行、搜索匹配等工具授权。你可以直接对它说“帮我把src/utils/date.ts里所有any类型改成具体的联合类型”它会自己去读文件、分析相关引用、执行修改、然后运行 TypeScript 编译器检查错误整个流程不再需要你复制粘贴。这省掉的不是几分钟而是重构中最消耗精力的“上下文切换”成本。1.2 重构场景天然适合 Agent 模式重构有一个核心约束外部行为不变内部结构优化。这意味着每一步改动都要站在“理解整段逻辑、识别副作用、确认没有破坏接口契约”的高度去执行。这恰恰是 Claude Code 这类 Agent 模式的强项。我们普通程序员做重构时最大的痛点不是不会改代码而是要维护的信息太多调用关系、依赖边界、历史设计意图、测试覆盖情况。这些东西散落在各个文件里人脑的工作记忆有限很难一次全记住。Claude Code 不同它能基于整个代码库做全局搜索把调用链一次性梳理出来然后按你的指令做修改。我这次重构的目标项目是一个用 TypeScript 写的后端服务有 300 多个文件。以前我用网页版 AI 做类似改造通常要人工分批把文件喂给它上下文稍微一长就丢失关键信息。这次全程用 Claude Code它会主动去读我指定的文件也能自己通过 grep 搜出所有相关引用这种“带着整个代码库的认知去工作”的能力是聊天式 AI 替代不了的。提示如果你只是改几行代码、写个临时脚本确实没必要用 Claude Code。它的价值在“跨文件、大规模、需要反复验证”的任务上才最明显。工具选型要想清楚场景匹配度。2. 环境准备安装、身份认证与权限配置2.1 安装方式与版本确认Claude Code 的安装有好几条路官方推荐的是通过 npm 全局安装对 macOS 和 Linux 都适用Windows 用户则可以通过 WSL 来跑。npm install -g anthropic-ai/claude-code安装完成后用版本号验证一下是否成功claude --version我这次是在 Ubuntu 服务器和本机 macOS 上各装了一份安装过程都很顺利。要注意的是Node.js 版本最好在 18 以上太老的版本会出现兼容性问题。装完建议跑一下claude doctor命令它会自动帮你检查环境变量、认证状态、网络连通性等关键项省得后面出问题了再一个个排查。国内用户比较关心的点是用第三方模型服务来驱动 Claude Code比如接入 DeepSeek 这类模型提供方。这个思路完全可行本质就是通过环境变量把 API 的地址和密钥替换掉。具体配置方式我放在后面问题排查章节里讲这里先提醒一句改模型提供方之前要确认服务商兼容 Anthropic 的接口协议否则容易在请求格式上报错。2.2 身份认证与 API Key 配置装好之后第一次运行claude会引导你登录。通常有两个选择一个是 OAuth 登录订阅账号另一个是直接用 Anthropic API Key。对我这种要频繁跑命令行工具的场景API Key 方式更稳定不容易遇到会话过期的问题。设置方式是在~/.bashrc或~/.zshrc里加环境变量export ANTHROPIC_API_KEY你的_api_key设置完记得source ~/.bashrc或者重开终端。有一点要特别注意不要让 API Key 出现在任何会提交到 Git 仓库的文件里尤其是项目根目录的.env文件很容易被误提交。我在实际项目中见过太多次这种事故。推荐的做法是把密钥放在~/.claude/.env里Claude Code 官方支持这个文件并且它天然在你的用户目录下不会被项目仓库追踪。2.3 权限配置让 Claude 干活但别乱来用过 Claude Code 的朋友应该都有印象默认情况下它每执行一个命令、每修改一个文件都会弹出来问你“是否允许”。安全是安全但频繁确认会严重打断重构的心流。这也是热词里很多人搜“claude code cli 怎么避开每次确认的动作”的原因。我的建议分两级来配置。第一级是改项目级别的配置文件.claude/settings.json用白名单的方式放行特定命令{ permissions: { allow: [ npm test, npm run lint, git diff, git status, git log ] } }这样配置后Claude Code 执行这几个命令时不会再逐条询问但其他命令仍然需要确认。第二级是针对某些极端信任的场景可以临时用--dangerously-skip-permissions参数启动完全免确认模式claude --dangerously-skip-permissions这个模式我是强烈不建议默认使用的。我自己只有在跑已经非常熟的重构流程、并且每个步骤都有 git 随时兜底时才会用这种方式。一旦放开全部权限Claude Code 可能执行任何它认为合理的命令包括rm -rf node_modules这种破坏性操作。保险起见我通常会再设置deny规则把高危命令直接禁掉。关于“怎么完全访问权限”这个问题社区里经常有人搞混。其实并不存在一个“全局完全访问”的开关正确的思路是组合使用项目的.claude/settings.json放行常规开发命令~/.claude/settings.json放行你个人约定俗成的通用操作再用deny规则对危险命令做兜底。这样既不用每次都点确认也不会把家门钥匙直接交给陌生人。2.4 用 CLAUDE.md 给 Claude 立规矩这是我觉得整个准备阶段最有价值的一步但也是最容易被忽略的。Claude Code 支持在项目根目录放一个CLAUDE.md文件它会自动读取这个文件作为项目级上下文相当于给 AI 一份“项目说明书 行为准则”。我这次重构前专门花了一个小时写了这个文件内容包括项目技术栈TypeScript、NestJS、Prisma 等版本目录结构说明哪个目录放控制器、哪个放服务、哪个放工具函数代码风格要求函数式优先、禁止any、错误处理统一用Result类型测试命令和覆盖率要求重构时的硬性约束不允许改公共接口签名、不允许跳过类型检查等有了这份文件Claude Code 在生成代码和修改代码时会更贴合项目的既有风格。这比每次在提示词里反复强调要可靠得多。我的体会是写 CLAUDE.md 就像带新人入职时的第一课你把规则讲清楚后面它干活就会省心很多。3. 重构方法论怎么把大任务拆给 AI 干3.1 先扫描诊断再动手修改拿到一个老项目别急着让 Claude Code 上来就改代码。我先让它做了一轮全库诊断把重构的方向定下来。常用的指令是这样claude 扫描 src/ 目录下所有 TypeScript 文件找出重复代码块、过长的函数和明显的反模式按照严重程度排序输出并标明涉及的文件路径和行号Claude Code 会调用它的搜索工具逐个文件扫描最后输出一份诊断报告。这个环节的价值在于它能帮你快速建立“问题地图”。我原来的项目里有一个utils/format.ts文件里面有大量 copy-paste 的函数只是参数略有不同。人工看可能要翻很久Claude Code 几分钟就能把相似度最高的代码块按照匹配度列出来。拿到报告之后我会要求它把每个问题标记为 P0/P1/P2 三个等级P0 是会导致维护成本极高的结构性缺陷P1 是不影响功能但明显冗余的逻辑P2 是纯风格类问题。然后再决定重构的优先级。注意这一步是“只读扫描”我会刻意在指令里强调“不要修改任何文件”。扫描阶段的输出直接决定了后续重构的节奏如果 AI 边扫边改输出就会混入太多变更反而不容易理清思路。3.2 小步重构一次只改一个模式重构领域有一句经典原则出自 Martin Fowler 的《重构》小步修改每步都能编译、测试通过。Claude Code 虽然执行效率高但它同样不应该一次性做超大范围的重构。原因有两个。第一是上下文窗口的限制改动范围一大它容易在后面的文件里忘记前面的修改逻辑造成前后不一致。第二是可控性范围越大出 Bug 之后的排查成本就越高你很难定位到底是哪一步改挂了。所以我通常会把任务拆成这样提取公共函数把utils/format.ts里最明显的那组重复逻辑合并成一个函数替换所有调用点用新函数替换旧代码并确保参数映射不变跑测试和类型检查确认没有破坏任何调用关系提交一次 git commit并写清提交信息再进入下一个重构项每拆一步我都会明确告诉 Claude Code 这一步只做一件事。比如“抽取parseTimeStamp函数替换掉utils/format.ts里所有重复的时间戳格式化逻辑但不要动其他文件。”这样指令清晰AI 的产出质量会高很多。3.3 用 git 做安全网允许 AI “犯错”重构必须建立在 git 的版本控制之上这是我这次实战最深的体会。Claude Code 的 Agent 模式再聪明本质上还是在做模式匹配和统计概率生成它完全有可能改错。我的工作流是这样每个重构任务开始之前确保当前分支是干净的然后让 Claude Code 执行修改。改完第一件事不是 review 代码而是用git diff看变更内容。确认没有诡异的大段删除后再跑测试。测试通过后立刻 commitgit add . git commit -m refactor: extract parseTimestamp helper一旦在后面的步骤中发现这次改动有问题可以随时用git revert commit_id回滚到之前的状态整个过程对业务代码零影响。实际上在这次重构中Claude Code 有过三次改出了类型错误或者逻辑偏差因为每一步都有独立的 commit我把它改回去或者让它在当前 commit 基础上继续修复都非常从容完全不会像以前那样“改到一半项目就处于一个既不是新版也不是旧版的尴尬状态”。3.4 约束边界防止 AI 顺手牵羊用了几天 Claude Code 之后你会发现一个问题它有时候会“过度热情”。你让它改format.ts它可能顺便把parse.ts里跟日期解析相关的函数也改了理由是“这些代码模式相同应该是想一起优化”。听起来挺贴心但放在重构场景里就是灾难。因为没有经过单独验证的修改一旦挂了你会非常难定位原因。我做了一个简单粗暴的规定任何一次任务只允许修改我明确指定的文件如果发现其他需要修改的地方让它单独列出来等下个任务再处理。在指令里可以这样约束只允许编辑以下文件src/utils/format.ts。 其他文件一律不要修改即使你觉得它们有相同的问题。 如果发现相关的问题请单独列出但不要自行改动。这招非常管用。Claude Code 会严格遵循可操作的文件白名单不会“顺手牵羊”。记住重构的节奏应该是“你掌握方向盘AI 踩油门”而不是反过来。4. 完整实战演示将一个 300 行的工具模块重构到清晰可维护4.1 演示目标重构utils/format.ts絮絮叨叨说了这么多方法论我们来看一个实际的完整案例。项目里有个src/utils/format.ts文件大约 300 行全是日期格式化、金额格式化和字符串补全的工具函数。这个文件是典型的重灾区多个函数逻辑重复、命名混乱、大量使用any类型、依赖一个全局的moment实例。在看原始代码之前我先把src/utils/format.ts和src/utils/__tests__/format.test.ts两个文件一起拖进 Claude Code 的会话里让它先梳理一下当前代码的行为表现claude 请阅读 src/utils/format.ts 和它的测试文件总结这个模块的公共接口有哪些、每个接口的输出规则是什么重点标注可能存在重复逻辑的地方Claude Code 的总结输出非常清晰。它识别出了几个关键信息这个模块对外暴露了 6 个函数其中formatDate和formatDateTime的内部实现高度相似区别只在于时间格式模板toAmount函数同时兼顾了国际化和普通场景导致条件分支复杂还有一个splitByStep函数使用了any类型内部处理逻辑也不够健壮。4.2 渐进式重构从抽取公共逻辑开始第一步我把最明显的目标交给 Claude Code合并formatDate和formatDateTime的公共逻辑。我给出的指令是重构 src/utils/format.ts 中的 formatDate 和 formatDateTime 1. 抽取一个内部函数 formatWithPattern(value: Date, pattern: string): string 2. formatDate 调用 formatWithPattern(value, YYYY-MM-DD) 3. formatDateTime 调用 formatWithPattern(value, YYYY-MM-DD HH:mm:ss) 4. 所有行为必须保持不变 5. 只允许修改 format.ts不要动 test 文件Claude Code 的执行过程很快它在几分钟内完成了修改。生成的代码大致是这样function formatWithPattern(value: Date, pattern: string): string { const y value.getFullYear(); const m String(value.getMonth() 1).padStart(2, 0); const d String(value.getDate()).padStart(2, 0); const hh String(value.getHours()).padStart(2, 0); const mm String(value.getMinutes()).padStart(2, 0); const ss String(value.getSeconds()).padStart(2, 0); return pattern .replace(YYYY, String(y)) .replace(MM, m) .replace(DD, d) .replace(HH, hh) .replace(mm, mm) .replace(ss, ss); } export function formatDate(value: Date): string { return formatWithPattern(value, YYYY-MM-DD); } export function formatDateTime(value: Date): string { return formatWithPattern(value, YYYY-MM-DD HH:mm:ss); }我这边跑了一遍编译和测试原来的用例全部通过于是提交了第一次 commit。实操心得这类提取公共函数的机械操作Claude Code 的准确率相当高。你只需要把输入输出的边界定义清楚它基本不会跑偏。真正需要你重点盯的是那些“业务规则暗藏在实现里”的函数那种要小心。4.3 处理any类型和隐含业务逻辑第二步是处理splitByStep。这个函数接收一个数字数组和一个步长值把数组按步长切成若干子数组但参数类型是any逻辑里还有一处诡异的if (i % step 0 i ! 0)分支而且没有处理step 0的边界情况。我让 Claude Code 做了一次小范围的类型安全修复修复 splitByStep 的类型安全和边界 1. 参数类型改为 number[] 2. 增加 step 0 时返回空数组的处理 3. 逻辑保持原有的切分规则不变 4. 补充适当的注释说明注意这里我特意没有要求“简化逻辑”因为原有的切分规则可能是有意为之改掉行为就是功能变更而不是重构了。Claude Code 的修改也表现得相当克制它保留了原始切分规则只是把类型约束收紧并且增加了边界判断。export function splitByStep(items: number[], step: number): number[][] { if (step 0) return []; const result: number[][] []; for (let i 0; i items.length; i step) { result.push(items.slice(i, i step)); } return result; }4.4 修复全局依赖消除隐式耦合这个模块还依赖一个全局的moment实例而这个实例是在项目入口文件里通过moment.locale(zh-cn)设置的全局状态。这在重构里是一个经典的问题模块的输出来自于一个隐藏的全局副作用测试环境里很容易因为没跑入口文件而导致输出结果不一致。我的指令是移除 format.ts 对全局 moment 实例的隐式依赖 1. 在 format.ts 内部独立实例化 moment并显式设置 zh-cn locale 2. 禁止修改项目入口文件 3. 跑一遍测试确认行为不变这个修改说大不大说小不小。它把一个“依赖运行顺序才能正常工作”的函数变成了“自带上下文”的纯模块后续的测试和调用都稳定了很多。这也是重构里最有价值的一类改进——表面上代码行数没怎么变但整体的可维护性提升了一个台阶。经过这三步操作format.ts从 300 行缩减到 220 行左右公共逻辑被抽取、any类型被消灭、全局依赖被移除。最关键的是每个步骤都走完了“修改—编译—测试—提交”的闭环没有一步让项目处于不可运行的状态。5. 常见问题与排查技巧实录5.1 连接服务失败“unable to connect to anthropic services”这是搜索热词里出现频率最高的一个问题。表现形式是启动 Claude Code 后报类似welcome to claude code v2.1.272 unable to connect to anthropic services fail的错误。排查路径我已经走过很多遍了按顺序排除第一检查 API Key 是否配置正确。在终端执行echo $ANTHROPIC_API_KEY确认输出不是空的且不是被截断的旧值。很多时候是改了.bashrc之后忘记source导致环境变量没有刷新进当前 shell。第二确认网络访问到 Anthropic 服务是否正常。可以在终端里用curl -I https://api.anthropic.com/测试一下看 HTTP 状态码是否正常返回。如果返回连接超时那就要从网络层面找原因了。第三查看 Claude Code 的日志。日志位置在~/.claude/logs最新的日志文件里会有详细的请求信息和错误码比终端里的报错信息有用得多。注意任何情况下都不要尝试所谓的“特殊网络方案”来访问 API 服务。这不仅违反服务条款也可能带来安全隐患。如果你的网络访问受限请优先考虑合规的替代方案比如使用国内可正常访问的兼容 API 服务商通过环境变量切换接入地址。5.2 接入 DeepSeek 等第三方模型的配置方法热词里关于“claude code 接 deepseek”的搜索量很高我在这里把配置逻辑说清楚。Claude Code 默认连接的是 Anthropic 官方服务但它支持通过环境变量覆盖 API 地址和密钥。只要第三方服务兼容 Anthropic 的接口消息格式就可以切换。export ANTHROPIC_BASE_URLhttps://你的服务商地址 export ANTHROPIC_AUTH_TOKEN你的密钥 export ANTHROPIC_MODEL服务商对应的模型名设置完这些环境变量后重新启动claude它就会把请求发到新的服务商那边。注意三个细节一是ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY不要同时设置否则 Claude Code 会优先读ANTHROPIC_AUTH_TOKEN容易造成混淆。二是新版 Claude Code 也支持通过/model斜杠命令在会话中直接切换模型你可以先启动会话再输入/model查看可用列表。三是不同服务商对工具调用function calling的支持度不一样如果发现 Claude Code 无法正常读写文件大概率是模型服务商对 Anthropic 的 tool-use 协议支持不完整这种情况建议换回官方服务或者选一个兼容性更好的服务商。5.3 权限提示过多怎么办前面提到过通过项目级.claude/settings.json配置permissions.allow白名单可以解决大部分确认弹窗问题。但如果你已经配好了发现某些命令还是会弹确认那检查一下两条第一配置文件的路径对不对。项目级配置必须放在项目根目录下的.claude/settings.json而不是放在你当前用户目录的~/.claude/settings.json里。后者是全局配置对指定项目的覆盖优先级反而更低。第二命令匹配方式是不是精确的。Claude Code 的权限规则做的是前缀匹配npm test会匹配npm test -- --watch这类带参数的命令但不会匹配pnpm test或者yarn test。我用 npm 的时候觉得这个规则很顺手但如果项目用的包管理器不一致就要把对应的命令前缀都加进去。{ permissions: { allow: [ npm test, npm run lint, git * ], deny: [ rm -rf *, git push --force ] } }git *通配符能放行所有 git 命令这个在重构场景下非常方便因为 Claude Code 做版本操作时不会频繁打断你。但deny里的两条建议保留git push --force这种操作一旦误触发历史记录直接损坏得不偿失。5.4 修改范围失控怎么办这个问题我在第三节方法论里已经介绍过预防措施在指令里指定文件白名单。但如果你已经遇到 Claude Code 擅自改了其他文件该怎么补救第一步不要慌用git status看变更文件清单用git diff --name-only列出所有被修改的文件。第二步对于那些你不想保留的改动做精确还原git checkout -- 文件路径第三步重新在会话里强调规则甚至可以启动一个新的会话避免旧的上下文污染。一般来说Claude Code 在同一个会话里会持续贯彻你最初设置的指令但如果它已经偏离过一次最好就是中断重开而不是在错误的上下文里继续修正。5.5 长期会话上下文丢失关键词里有人搜“claude code 会话恢复”其实官方支持用claude --resume恢复历史会话。这个功能在重构一个大型模块时特别实用你今天改到一半明天想继续直接claude --resume就能把昨天的上下文全部拉回来不用重新描述项目背景和约束。不过我的经验是一个会话不要持续超过半天。对话太长之后Claude Code 的注意力会明显下降开始出现忘记早期约束、重复生成相似代码、甚至自己在两个文件之间产生逻辑冲突的情况。遇到这种情况最有效的做法是开一个新会话然后在第一条消息里附上CLAUDE.md的文件路径让它重新加载上下文。这比我之前提到过的任何小技巧都更能提升生成质量。6. 回顾这次实践的几点真实体会写到这里这次用 Claude Code 做代码重构的实战记录已经覆盖了从准备、方法、实操到排障的完整链路。最后说几点我个人在实操中最真实的体感。第一Claude Code 最擅长的是执行而不是规划。它能把“同类替换”“抽取重复代码”“批量加类型”这类机械工作做得又稳又快但“这个模块该不该拆”“拆成什么样的结构最合理”这类架构判断它给的建议只能当参考不能当圣旨。最终的设计决策还是得你自己拍板。第二CLAUDE.md 的投入回报率高得惊人。我花了一个小时写这份项目说明后续每次会话都受益。它不只是给 Claude Code 看的更像是我自己重新梳理了一遍项目的设计约束和代码规范很多模糊的边界在写这份文档的过程中也被想清楚了。第三git 是重构的生命线。没有 git 安全网我绝对不敢放开权限让 AI 大规模改代码。一个可随时回滚的干净分支是让 AI 大胆干活的前提条件。反过来如果你发现 Claude Code 在某个任务里反复改错先别急着怪它检查一下自己是不是没把任务拆够小、指令没写够清楚。大多数“AI 不听话”的案例根因都在任务定义不够清晰。重构本身就是一件需要耐心和控制力的工作Claude Code 不会替你做判断但它能让你从繁琐的机械劳动里解放出来把精力集中在真正需要人脑的地方。希望这篇实战记录能帮你在自己的项目里少踩几个坑更快地体会到“AI 结对编程”带来的效率提升。
