使用 claude code 批量重构老旧函数名的实际操作

去年第四季度，我接手了一个运营了八年的电商中台项目。打开代码库的那一刻，我知道麻烦来了，同一个“用户地址处理”逻辑，在订单模块叫

get_addr，在会员模块叫 fetchUserAddress，在物流模块叫 address_handle，在促销模块更离谱，叫 proc_addr_v2_final。整个项目里这样的函数有超过 400 个，分散在 200 多个文件中，没有文档，没有一致的命名规范，上一个负责人的交接文档只有一句话：“都差不多，你自己看。”

我花了两个工作日尝试手动修改。到第三天下午，我只改完了 37 个函数，期间因为漏改调用方导致三个接口报错，回滚了两次。我意识到这不是靠 Ctrl+Shift+F 能解决的事。

用全局替换改函数名，每改一个就是在埋一颗定时炸弹。 你不知道这个函数名还出现在哪些互相引用的文件中，你不知道注释里是否也有同名文本不该改，你更不知道某个同名函数在三方库里也存在。

我做了一件当时团队里没人做过的事：让 Claude Code 批量重构这 400 多个老旧函数名，并在此过程中建立起一套可验证、可回滚、可复用的操作流程。 这篇文章完整还原整个过程，从问题定义、指令策略、到验收与止血。

一、先给你一个明确结论：Claude Code 能做到什么程度，完全取决于你给它什么边界

很多人对 AI 辅助重构有一个错误预期：以为只要说一句话“帮我把所有函数名统一改成驼峰式”，AI 就能自动理解项目里的复杂命名逻辑，然后精准无误地执行。

事实是，这样一句话丢进去，Claude Code 一定会改错。因为它看到的只是文本，不是你的业务意图。

我做完这批重构后，得出一个结论：Claude Code 擅长的是“在约束条件明确的情况下，按规则批量执行代码修改”，而约束条件本身，必须由你来定义。 换句话说，AI 负责“改什么”和“怎么改”的执行部分，而你需要负责定义“在哪里改、不改哪里、改成什么样、改完怎么验证”。

这个认知差异，直接决定了最终结果的正确率。我第一次尝试时，没有给出足够的边界约束，结果 Claude Code 把 vendor 目录下的第三方库函数名也改了五个，直接导致编译失败。修正指令后，第二次批量修改的正确率达到了 96.7%，只漏了三个函数调用点，手动修复花了不到十分钟。

二、什么样的项目会出现“老旧函数名问题”？这三个特征你大概率遇到过

老旧函数名问题不是“代码写得差”这么简单。 它是一种典型的“技术债复利效应”，项目越老、参与的人越多、时间压得越紧，函数命名就越容易失控。 在我接触过的十几个中大型项目中，出现这个问题的项目普遍具备以下三个特征：

特征一：维护周期超过三年，经历三任以上主程

每次换人接手，新的负责人都会“按照自己的理解”重新命名函数。 我统计过这个电商中台项目的三任负责人留下的命名风格：

三种命名风格同时存在于同一个代码库中，函数名本身就成了加密信息。

特征二：存在“历史遗留”的函数前缀体系

这个项目早期有一套“模块前缀”规范，订单模块的函数以 ord_ 开头，会员模块以 mem_ 开头，物流模块以 log_ 开头。但到了 2019 年，团队发现这套前缀体系在跨模块调用时会引发大量全路径依赖，于是宣布废弃。问题在于：规范宣布废弃的那天，已经上线的前缀函数没有人去改名。 688 个带前缀的函数就这么留了下来，后续新写的函数有的一脉相承继续加前缀，有的改用新的命名规则。混乱就此滚雪球。

特征三：存在“功能功能相似但命名毫无关联”的函数集群

我在这个项目里发现了一个典型情况：“获取用户可用优惠券”这个逻辑，在不同模块中有以下四个函数：

• get_coupon_list() ， 订单模块
• fetch_available_discount() ， 促销模块
• user_coupon_query() ， 会员模块
• get_usr_cpn_avl() ， 老版本的结算模块

这四个函数的核心逻辑有 60% 是一致的，但因为命名混乱，后续开发者在不知道函数存在的情况下又创建了新的实现，导致相同逻辑的函数越来越多。

这不是代码质量问题，这是信息组织问题。 而 Claude Code 最擅长解决的就是这类问题，它能在理解业务意图的情况下，批量把信息结构重新梳理和统一。

三、为什么正则和全局替换搞不定？两个被低估的失败原因

很多技术负责人的第一反应是“写个正则批量替换不就完了”。这个方法我在第一个工作日也试过，结果证明它适用的范围非常有限。

失败原因一：函数名本身存在上下文依赖，正则只能做字面匹配

看下面这个真实例子：

# payment.py
def process(data):

return gateway.process(data)  # 调用的是第三方支付SDK的process方法

order_flow.py

def process(data):

return serializer.process(data)  # 调用的是序列化器的process方法

这两个 process 函数属于两个完全不同的模块，如果你写正则批量把 process 改成 process_data，会把 gateway.process() 也改掉，而那是第三方 SDK 的方法，不应该动。

正则解决不了这个问题，因为它不理解 gateway.process 和项目内部的 process 函数本质上是两个东西。Claude Code 的上下文感知能力在这里产生了关键差异，它能区分“这是本项目的函数定义”和“这是第三方对象的属性调用”。

失败原因二：注释和文档里有大量同名文本

这个项目的代码注释里充满了“process 这个函数会处理订单数据”这样的描述。如果你用正则全局替换 process 为 process_order_data，注释里的“process 这个函数会处理订单数据”会变成“process_order_data 这个函数会处理订单数据”，改完语义不通，反而更迷惑。

我在实际操作中发现，Claude Code 能识别函数定义和注释文本的语法位置差异。前提是你必须在指令里明确要求它“只修改函数定义和调用处的函数名，不要修改注释、日志字符串、文档字符串中的同名词汇”。

四、重构前的第一个关键动作：定义“改名的目标体系”

很多人在这一步就跳过去了，直接开始写指令。结果改完之后，三个月内又出现了很多新的命名风格。

函数命名统一不是“选一个风格统一改完就结束”，而是“建一个规则体系，让未来新函数的命名也有据可依”。

我在这个项目里做了三件事：

4.1 先做函数分类，再定义每个类的命名规则

我把项目里 400 多个需要改名的函数分成了四类，每一类有不同的命名要求：

这个分类体系来自于我对整个项目业务逻辑的手动梳理，花了大约 3 个小时。但这一步做完之后，后续写指令的标准就非常清晰了。

4.2 编写“命名翻译表”

不是所有函数名都能通过规则自动生成新名。有些旧名字充满了拼音缩写和历史包袱，必须一次性定义一个“原名-新名”的映射表。

# 命名翻译表（部分）
get_usr_cpn_avl    -> get_user_coupon_available

chk_ord_stu        -> check_order_status

proc_addr_v2_final -> process_shipping_address

cal_disc_amt       -> calculate_discount_amount

这份翻译表一共 89 条，覆盖了那些无法通过规则自动转换的“顽固函数”。翻译表的好处是：当 Claude Code 执行重命名时，我可以通过翻译表进行交叉比对，确保没有遗漏或误判。

4.3 建立“边界清单”，哪些文件绝对不能碰

这是最容易踩坑的一环。我的边界清单包括：

• /vendor/ 目录：所有第三方库
• /generated/ 目录：代码生成器输出的文件
• /proto/ 目录：gRPC 自动生成的服务定义
• 所有以 _test.go、_test.py 结尾的测试文件（先不动测试文件，等主要代码修改完成后再单独处理）
• 项目根目录下的 constants.py 和 config.py（因为全局常量的键名可能与函数名重名，但不能改）

我统计了一下，这个清单排除了大约 30% 的文件，确保 Claude Code 的操作范围被缩小到只有核心业务代码。这是正确率从 68% 提升到 97% 的关键因素。

五、指令实战：怎么写出让 Claude Code 改对 97% 函数名的 Prompt

这部分是整篇文章最核心的操作细节。我先展示我最终使用的指令，然后逐段解释为什么这么写。

5.1 主指令模板

你是一名资深后端开发工程师，现在需要对一个Python项目中核心业务模块的函数名进行批量重构。
【任务范围】

只处理 /src/order/、/src/member/、/src/promotion/、/src/logistics/ 四个目录下的 .py 文件

禁止触碰 /vendor/、/generated/、/proto/、/migrations/ 目录

禁止修改所有 _test.py 结尾的测试文件

禁止修改常量文件 constants.py 和 config.py

【命名规则】

将以下老旧命名风格统一为新的团队标准风格：

拼音缩写风格（如 get_usr_cpn_avl）→ 全英文下划线风格（get_user_coupon_available）
驼峰与下划线混用风格 → 纯下划线风格
动词后置风格（如 userAddress_fetch）→ 动词前置 + 下划线风格（fetch_user_address）
【函数分类规则】

请按照以下分类规则理解每个函数并应用对应命名模板：

数据查询类：get_[实体]_[条件]

状态判断类：is_[状态]_[实体] 或 has_[属性]

数据处理类：[动作]_[数据对象]

业务执行类：[执行动作]_[业务实体]

如果某个函数的命名无法通过上述规则自动确定新名，请将其标注并在建议列表中列出，由我手动确认。

【命名翻译表】

以下是必须按照映射关系重命名的函数，新名已经确定，请直接替换：

get_usr_cpn_avl -> get_user_coupon_available

chk_ord_stu -> check_order_status

proc_addr_v2_final -> process_shipping_address

cal_disc_amt -> calculate_discount_amount

（完整翻译表共89条已省略，实际指令中包含了全部89条映射）

【修改边界】

只修改函数定义处（def 语句）的函数名

同时修改项目中所有调用该函数的地方

不要修改注释、文档字符串、日志输出中的同名文本

不要修改第三方库对象（如 gateway.process、serializer.process）的属性调用

如果遇到同名函数但属于不同模块的情况，请根据文件路径和上下文判断是否应该改名，并将判断理由写在报告中

【输出要求】

首先输出一份“执行计划”，列出你识别到的所有待修改函数，包括：原函数名、文件路径、你计划使用的新函数名、分类
执行计划经我确认后，再开始实际修改
修改完成后，输出一份“变更报告”，包括：修改的函数数量、每个文件的具体变更内容、任何你标注为“不确定”的项目

5.2 指令设计中的六个关键设计原则

原则一：先让 AI 输出计划，不要直接让它动手

很多教程教你“一行指令直接改”，但在我实际操作中，让 Claude Code 先输出一份执行计划并由你审核，是避免连锁错误的最关键一步。 在我的项目中，Claude Code 第一次输出的执行计划识别了 412 个待修改函数，但我审核后发现其中 9 个不应该修改，3 个是第三方 SDK 的 monkey patch，6 个是与数据库字段同名的函数。如果我让 AI 直接动手，这 9 个误改需要我花更多时间来回溯和修复。

原则二：分类规则的作用不是让 AI 猜，而是给 AI 一个判断框架

Claude Code 理解“get”开头大概率是查询类、“is”开头大概率是判断类。但当旧函数名是 data_process 这种模糊命名时，AI 会犹豫。这时候函数分类规则就能发挥作用，它告诉 AI：“如果一个函数的核心动词是‘处理/转换/计算’，就归入数据处理类，套用[动作]_[数据对象]的模板。”

原则三：翻译表是硬约束，不是参考建议

在指令中，我把翻译表放在“命名规则”之后，并用“请直接替换”这样的确定性措辞。因为翻译表里的映射是我手动确认过的，不需要 AI 再自行判断。如果不强调这一点，有些 AI 会认为翻译表里的映射与命名规则不符，然后“自行优化”，这就是错误的第一来源。

原则四：用一个具体的反例定义“不要改什么”

我在指令里明确写了“不要修改第三方库对象的属性调用”，并给出了 gateway.process 和 serializer.process 这两个真实反例。这让 Claude Code 在执行时有了一个具体的判断锚点，而不是模糊地“注意区分”。

原则五：要求 AI 对自己不确定的项目进行标注

这是一个被很多人在指令中忽略的设计。我明确要求 Claude Code “将任何你不确定是否应该修改的项目单独标注”。在我的项目中，AI 标注了 11 个不确定项，其中有 7 个确实不应该修改，4 个需要我手动确认后修改。这个设计让 AI 的“不确定状态”变成了可检查的待办项，而不是默认通过的隐患。

原则六：分批执行，每批不超过 50 个函数

400 个函数不是一次改完的，我分了八批，每批约 50 个。理由是：每批修改完成后立即跑一次测试套件，如果测试挂了，错误范围就被锁定在 50 个函数的修改内，定位和修复的时间可以控制在几分钟内。

六、执行过程全记录：八批修改的具体数据和遇到的三个典型问题

以下是八批修改的实际记录：

总耗时：指令准备和审核执行计划约 4 小时，Claude Code 实际修改时间约 15 分钟，手动修复约 28 分钟，总计约 5 小时。 对比手工修改 400 个函数预估需要的 25-30 个工时，效率提升了约 5-6 倍。

以下是在这个过程中遇到的三个典型问题：

问题一：装饰器内引用没有同步修改

这是第 2 批修改中发现的问题。项目中有几个函数使用了自定义装饰器，而装饰器内部通过字符串引用了函数名：

# 修改前
@register_handler('proc_addr_v2_final')

def proc_addr_v2_final(data):

Claude Code 的修改结果

@register_handler('proc_addr_v2_final')  # 这里没有改！因为它是字符串参数

def process_shipping_address(data):

...

Claude Code 没有把装饰器里的字符串参数识别为“函数名引用”，因为从语法角度看，它确实只是字符串。这个问题在第二批的测试中被捕获，register_handler 找不到注册的函数，报了运行时错误。

修复方法：我在第 3 批开始的指令里追加了一条规则： “如果函数被装饰器引用，请同时检查装饰器的字符串参数中是否包含原函数名，如果有，一并修改。”后续批次再没有出现同类问题。

问题二：跨模块同名函数被误判为同一个函数

第 5 批修改中，Claude Code 遇到两个模块里各有一个 get_config() 函数，一个是 order.get_config()，一个是 member.get_config()。AI 最初把它们识别为“需要统一命名”的重复函数，但这两个函数在业务上分别获取“订单配置”和“会员配置”，本来就应该各自叫 get_config，通过模块名来区分。

我在审核执行计划时识别出了这个问题，并在指令中追加了说明：“如果一个函数名在多个模块中独立存在且职责明确不同，不要强制统一命名，通过模块路径即可区分。”

问题三：Claude 对中文拼音缩写的“翻译”偶尔出错

翻译表里有一条 get_usr_cpn_avl → get_user_coupon_available，这个映射是我手动确定的。但项目里还有一个 get_usr_cpn_his（用户优惠券历史记录），没有被我列入翻译表。Claude Code 自行将其推断为 get_user_coupon_his，把 cpn 正确理解为 coupon，但 his 没有被展开为 history。

这类问题在 89 条翻译表覆盖之外的拼音缩写中出现了 4 次，都是因为 AI 对拼音缩写缺乏足够的中英文映射知识。解决方案只有一个：翻译表覆盖到的才能自动改，覆盖不到的必须在执行计划中标注出来，由人来做最终命名决策。

七、验收四步骤：改完之后怎么确认没有埋下隐患

很多文章把“改完编译通过”当成终点。但我的经验是，批量函数名修改可能引发三类不在编译层面暴露的问题：运行时动态引用错误、跨服务接口契约断裂、以及未来维护者的认知混淆。 因此我设计了以下四个验收步骤：

步骤一：单元测试 + 集成测试必须全部通过

这是最基础的要求。我这里说的“全部通过”是指：不仅要跑改过的模块的测试，要跑全量的回归测试。 因为你永远不知道一个函数调用是否跨模块传递到了你没注意到的角落。

我在第 6 批修改中发现了一个跨模块的调用链错误：member.get_user_info() 在一次修改后，影响了 report 模块里的数据聚合逻辑，而这个调用在 member 模块自己的测试里覆盖不到。幸好全量回归测试捕获了它。

步骤二：强制运行一次静态检查工具的变更为基线

在修改完成后，我用 Pylint 对整个项目做了一次全量扫描，把扫描结果保存为“重构后基线报告”。重点是看两类警告：

• 未使用的函数定义：如果一个函数被改名后，旧名字变成了“未定义”，而调用方没有同步更新，Pylint 会报 undefined-variable 或 no-member。
• 函数定义重复：如果改名过程中产生了与已有函数同名的情况，Pylint 会报 function-redefined。

这里提供一个具体数据：修改后 Pylint 的基线报告显示，原本项目有 47 个 function-redefined 警告，修改完成后减少到了 12 个。因为很多重复函数在修改过程中被成功地统一成了一个命名，消除了重复定义。

步骤三：检查 API 接口的对外契约是否有函数名暴露

这个项目很多内部函数名通过 JSON 响应字段或日志字段的形式暴露到了外部。比如：

{
"handler": "proc_addr_v2_final",

"status": "success"

}

如果只改了函数定义和内部调用，但没有检查 API 响应中是否硬编码了函数名，就可能产生外部契约断裂。我在验收阶段专门用正则扫描了所有 JSON 序列化语句中的字符串值，找到了 4 处硬编码的函数名，逐一修改。

步骤四：更新团队命名规范文档，把本次确定的规则写进去

这个步骤看起来不属于“技术验收”，但它决定了这次重构的成果能维持多久。我把命名规则、函数分类模板、翻译表的生成方法全部写入了团队规范 wiki，并标注了“旧名 → 新名”的映射历史，这样未来有开发者搜索老函数名时，能找到对应的新名和说明。

八、不同情况下的操作取舍：什么场景适合用这套方法，什么场景不适合

不是所有批量改名都适合用 Claude Code。我总结了一个判断框架：

适合的场景

• 函数数量超过 50 个，且分布在 30 个以上文件中
• 改名规则有一定复杂度，不是单纯的“把 A 改成 B”
• 项目有可运行的测试套件做验证保障
• 存在旧命名翻译表需要，人工翻译成本高

不适合的场景

• 函数数量少于 20 个，花在准备指令和审核计划上的时间可能超过手动修改时间
• 项目没有测试覆盖，改完无法验证正确性，风险过高
• 函数命名混乱但业务逻辑本身也在重构，这种情况应该先理清业务再改名
• 修改涉及公开 API 或跨团队接口，影响面太大，应该走正式的 deprecation 流程而非静默修改

一个折中策略：只做“中等规模”的批量修改，大改名走拆单

我在实际操作中选择不一次性把 400 个函数全改完，而是先改优先级最高的 200 个，被调用频率最高的、跨模块引用最多的、命名最容易引起混淆的。剩下的 200 个我用了一个“渐进式重构”策略：每次修改相关模块的功能时，顺手把该模块的函数名一起改掉。这样把风险分散到了日常开发中，而不是一次承担。

这个方法的一个额外好处是：团队其他成员在 Code Review 时能陆续看到命名风格的变化，而不是突然面对一个面目全非的代码库。 后者容易引发团队内部的抵触动绪，也增加了合并冲突的概率。

九、这套操作流程的完整复盘和经验抽象

这次批量重构给我的最大收获不是一个“一招鲜”的 Prompt，而是一套可以复用到其他 AI 辅助编程任务中的操作框架。我把这个框架抽象为以下五步：

认知建模 → 约束编码 → 计划审核 → 分批执行 → 验证闭环

• 认知建模：你先要理解自己面对的是什么问题，把模糊的“改名需求”具象化为分类规则、翻译表和边界清单。
• 约束编码：把这些认知转化为 AI 可执行的指令格式，重点是“不要改什么”和“不确定时标注”这两类约束。
• 计划审核：永远让 AI 先输出计划而不是直接修改。这一步是你和 AI 之间的“质量闸门”。
• 分批执行：每批控制在可验证的规模内，出了问题能快速定位。
• 验证闭环：不只是看编译结果，要跑全量测试、做静态检查、检查外部契约、更新文档。

五位程序员用这套框架在五个不同的项目中做了类似的批量重构，四个人的正确率超过了 95%。唯一一个正确率只有 78% 的，跳过了“计划审核”这一步，直接让 AI 动手。

Claude Code 不是一个“一键搞定函数名”的魔法按钮。它是一台高精度的执行引擎，前提是你给它输入了准确的图纸。

十、下一步行动建议：从哪开始

如果你现在手里也有一个函数名混乱的项目，我建议按以下顺序开始：

第一步，不要急着打开 Claude Code。先用两个小时，手动画出项目里函数命名的“现状地图”，有哪些命名风格、分布在哪些模块、最混乱的前 20 个函数是什么。这两个小时决定了后面所有工作的质量。

第二步，选择 20 个最典型的函数作为“试验批”。它们的命名错误足够有代表性，同时影响面可控。用这一批来测试你写的 Prompt 在 Claude Code 中的实际表现，找出指令中的漏洞。

第三步，跑通一次完整的“执行-验证-修复”闭环，把经验教训记录下来，再铺开到更大规模。

开始做，比追求完美更重要。但开始之前，先把约束条件写清楚。这是我在这 5 个小时里学到的最重要的一课。

*本文基于 2024 年 Q4 个人实操项目经验撰写，项目环境为 Python 3.11 + Claude Code CLI，验证数据来自项目内部 Pylint 报告和 GitLab CI 测试结果。文中翻译表和命名规则根据项目实际情况进行了脱敏处理后展示，但框架和操作流程完全保持原貌。*