在claude code中衡量代码复杂度并给出简化建议

上周一个朋友发来段 Clojure 代码,让我帮忙看看为什么上线三个月后每次改动都要花两天。我扫了一眼，单个函数 417 行,嵌套最深处 8 层 if-let,没有测试,注释只有一句“TODO: 重构”。更麻烦的是,这是支付对账模块,没人敢动。我问团队当初怎么让它上线的,他说:“code review 时大家都觉得‘有点绕’,但说不清哪里有问题。”

问题就在这。“感觉代码复杂”不是决策依据,但你把它量化成数字,它就变成了无可辩驳的工程事实。

我用 Claude Code 跑了一次复杂度分析,圈复杂度 94,认知复杂度 127。我把这两个数字贴到 PR 评论里,当天下午就批了重构预算。这篇文章就是我过去 18 个月在多个项目中使用 Claude Code 做代码复杂度治理的完整记录,包括哪些指标真正有效、如何下达分析指令、以及 AI 给出的简化建议什么时候该采纳、什么时候该拒绝。

一、先给结论:在 Claude Code 里做复杂度治理的核心逻辑

如果你时间有限,以下五条就是我想传递的全部核心判断:

第一,Claude Code 本身没有内置复杂度分析器,但它可以成为调用专业工具的 Agent。 你不需要手动安装 lizard、radon、eslint-complexity 等分析器,直接让 Claude Code 去安装、执行、解读报告。它的价值在于把“原始数据”翻译成“重构方案”。

第二,单一指标不够,至少需要三位一体:圈复杂度 + 认知复杂度 + 改动热点。 圈复杂度告诉你“测试要写多少用例”,认知复杂度告诉你“人在阅读时会被打断多少次思路”,改动热点告诉你“哪些复杂文件还在频繁变更,风险最高”。

第三,简化建议的质量取决于你给的约束条件。 直接说“帮我简化”效果很差。你必须告诉 Claude Code:保持接口签名不变、保持所有现有测试通过、优先使用提取方法而非引入新抽象层次、禁止改变异常传播路径。

第四,AI 的简化容易产生两种“负优化”:抽象泛滥和语义偏移。 前者把一个大函数拆成 30 个只有 3 行的小函数,虽然圈复杂度降了但认知负担没降;后者在重构时悄悄改变了边界条件,外面看起来一样但内部行为变了。

第五,真正降复杂度不是一次性的“清理行动”,而应该嵌入 CI/CD 成为持续约束。 我在三个项目中设置了复杂度阈值门禁，当圈复杂度超过 20 的代码提交时,Claude Code 自动介入,生成简化建议并阻止合并,直到复杂度回落。这套机制让代码基线持续改善,而非反复反弹。

下面我会逐条展开,讲清楚每一步的操作方法、背后原理以及踩过的坑。

二、复杂度到底在“衡量”什么:从主观感受到客观数字

很多人分不清“代码多”和“代码复杂”。一个有 500 行的 switch-case 可能是简单的,一个只有 80 行但包含 6 层回调嵌套的异步逻辑可能复杂到无法测试。我们需要先对齐几个关键概念。

2.1 圈复杂度:测试视角的“分支爆炸”

圈复杂度(Cyclomatic Complexity) 由 Thomas McCabe 在 1976 年提出,计算的是代码中线性独立路径的数量。公式可以简化为:每遇到一个 if、else、while、for、case、&&、||、catch,计数加 1。

它真正的工程含义是:这个函数至少需要多少个测试用例才能覆盖所有路径。

一个圈复杂度为 1 的函数只需要 1 个测试;圈复杂度为 10 的函数至少需要 10 个;圈复杂度为 94 的，就像我开头提到的那个对账函数，理论上需要 94 个测试用例,但没人会写,所以它永远不会被充分测试。

我见过的经验阈值:

• 1-5:简单,可接受
• 6-10:开始需要认真写测试
• 11-20:风险区域,强烈建议拆分
• 20-50:高危,线上故障高发区
• 50+:灾难,任何改动都是赌博

2.2 认知复杂度:人脑视角的“理解成本”

圈复杂度的缺陷是:不区分嵌套层级。一个平铺的 switch 有 20 个 case,圈复杂度为 20;一个 5 层嵌套的 if-else,圈复杂度可能只有 6,但后者更难读。

认知复杂度(Cognitive Complexity) 由 SonarSource 在 2016 年提出,它的计算逻辑更贴合人的阅读体验:

• 每增加一层嵌套,权重递增
• 线性结构(如一连串 if-else-if)不计额外权重
• 遇到 break、continue、return 等打断连续阅读的结构,计分增加
• 递归的计分固定为 1,不因递归深度增加

这意味着,认知复杂度可以捕捉到“虽然分支不多但结构非常不友好的代码”。我见过一个认知复杂度 45 但圈复杂度只有 8 的函数，它是一个递归下降解析器,虽然外部调用简单,但要在脑子里模拟 5 层递归回溯才能理解。

2.3 为什么只用眼睛看不够:一个 15 分钟的实验

去年我给一个团队做 Workshop,做了这样一个实验:

1. 展示一段 60 行的 Python 函数,让所有人打分(1-10 分,越复杂分越高)
2. 用 radon 计算圈复杂度和认知复杂度
3. 对比结果

15 个开发者,主观评分范围从 3 到 8,标准差 1.8。最低分来自这段代码的原始作者,他说“我写的我当然觉得挺清晰”;最高分来自一个刚接手维护的同事,他说“每个条件分支都可能有隐藏的边界情况,我不敢改”。

而 radon 给出的结果:圈复杂度 14(F 级),认知复杂度 31。这个客观数据终结了这场讨论:不管原作者觉得多清晰,这段代码需要至少 14 个测试用例,且认知负担超过 30,属于高风险。

这个实验让我确信一件事:代码复杂度不能靠肉眼评估,必须靠工具量化。 而这正是 Claude Code 可以介入的关键点，它不但能调用工具跑量化数据,还能把这些数据解读成团队能理解的工程语言。

三、在 Claude Code 中启动复杂度分析:复合指令的威力

很多人第一次尝试让 Claude Code 分析代码时会写:

“请分析这个项目的代码复杂度。”

这种模糊指令的结果通常很糟糕，Claude 可能会随机读几个文件,给出一段笼统的、类似教科书定义的总结,然后建议你“考虑提取方法、减少嵌套、使用设计模式”。这对实际工作毫无帮助。

正确的方式是:给出一个包含工具安装、执行参数、输出解读和提问触发的复合指令。

3.1 基础版指令模板

以下是我经过多次迭代后确认有效的 Python 项目分析指令模板:

我需要对当前 Python 项目进行代码复杂度分析。请你按以下步骤执行:

1. 先检查 radon 是否已安装,如果没有,执行 pip install radon
2. 运行 radon cc src/ -a -s 获取所有函数的圈复杂度,按分数从高到低排列
3. 运行 radon mi src/ -s 获取可维护性指数
4. 基于以上输出,识别出圈复杂度超过 10 的前 20 个函数,按严重程度列出
5. 对 Top 5 最复杂的函数,逐一给出具体的重构建议,要求:(a) 保持接口不变 (b) 说明每一步拆分的原因 (c) 预估拆分后的圈复杂度分值
6. 最后,生成一份 Markdown 格式的分析报告,包含:总体评分、高风险函数清单、重构优先级排序、以及建议采取的简化策略

这个指令的关键点:

• 步骤化:Claude Code 会把每个步骤当作独立任务执行,不会跳步
• 参数明确:-a 表示展示所有函数,-s 表示按分数排序
• 约束条件:第 5 步的三个要求(a/b/c)是防止 AI 乱改的关键
• 输出格式化:要求 Markdown 报告,方便直接贴到 PR 或文档中

3.2 多语言适配指令

Python 是 radon;JavaScript/TypeScript 用 ESLint 的 complexity 规则;Go 用 gocyclo;Ruby 用 flog。我通常会这样覆盖多语言项目:

分析当前项目代码复杂度。这是一个多语言项目,需要你:

• Python 部分:使用 radon
• TypeScript 部分:检查 ESLint 配置中是否已有 complexity 规则,如果有则运行,如果没有则临时添加规则 complexity: ["error", 10] 并运行 ESLint
• Go 部分:先 go install github.com/fzipp/gocyclo/cmd/gocyclo@latest,然后运行 gocyclo -over 10 ./...
• 汇总所有语言的复杂度报告,按“复杂度/行数”排序,找出跨语言的高风险区域

这里有个细节:对 TypeScript 使用 ESLint 时,我先让 Claude Code 检查是否已有配置。因为直接修改 ESLint 配置可能破坏团队已有的规则设置,让 AI 先检查再操作,是一个重要安全习惯。

3.3 当分析工具覆盖不到时:让 Claude Code 做静态推理

有个场景很常见:代码用了一种冷门语言,或者项目环境受限无法安装第三方分析工具。这时可以退一步,让 Claude Code 直接阅读代码进行估算:

无法安装分析工具,请你直接阅读项目中的核心业务文件。对于每个函数,估算其圈复杂度(基于 McCabe 公式),并标记出你认为认知复杂度最高的 5 个函数。说明你的估算依据。

这里必须强调“说明估算依据”,否则 Claude 容易给出看似合理但缺乏证据的判断。AI 估算不如工具精确,但在紧急情况下可以作为“快速扫描”的替代方案。

四、拆解常见误区:AI 简化不是“减肥”,是“外科手术”

在真正让 Claude Code 介入简化之前,有几个根深蒂固的认知误区需要澄清。这些误区直接导致了很多 AI 辅助重构的失败案例。

4.1 误区一:“行数减少就等于复杂度降低”

这是最普遍也最危险的认知。我见过一个案例:同事用 Claude Code 简化了一个 200 行的函数,AI 的“优化”结果是把它变成了 45 个只有 2-5 行的小函数。圈复杂度确实从 28 降到了平均 3,但任何人想要理解这个模块都必须同时跟踪 45 个函数之间的调用链，认知复杂度不降反升。

衡量简化的质量,应该看三个数字的变化方向:

• 圈复杂度:应下降
• 认知复杂度:应下降
• 函数间耦合度:不应显著上升(如果从 5 个函数变成 25 个,说明拆太细了)

一个实用经验:拆分后新函数的平均行数最好在 8-25 行之间。 低于 8 行意味着可能过度拆分,超过 25 行说明还可能继续拆分。

4.2 误区二:“让 AI 自己决定怎么简化最省事”

完全放手的简化容易带来两种问题:

语义偏移:AI 在提取方法时可能改变异常传播路径。例如原始代码在中间某个环节 catch 了异常并返回默认值,AI 重构时可能把 catch 移到外层,导致以前被吞掉的异常现在向上传播,改变了调用方的行为。

领域逻辑丢失:某些看似冗余的 if-else 其实是业务规则,比如“当用户是 VIP 且订单金额超过 500 时免运费”。从代码结构角度,这可以简化成一行;但如果你让 AI 简化时丢失了“为什么是这个数值”的上下文,后续维护者会不知道 500 这个阈值能不能改。

正确做法是:把简化指令拆成两阶段。

• 第一阶段:让 Claude Code 提出简化方案,同时要求它逐条标注每个改动背后的假设(比如“我假设这个 null 检查是防御性的,可以上移到调用方”)
• 第二阶段:你审查这些假设,把错的挑出来,然后让 Claude Code 基于修正后的假设重新执行简化

4.3 误区三:“复杂度低就是好代码”

我曾经执着于把所有函数的圈复杂度压到 10 以下,直到遇到一个反例。

一个对账模块的核心函数,圈复杂度 32,但 3 年来只改过 2 次,每次改动不超过 5 行,线上零事故。它的逻辑就是“逐行比对 A 和 B 两个数据源,根据不同字段类型采取不同对账策略”，虽然条件分支多,但每个分支都极其简单且经过充分测试。

而另一个模块的圈复杂度只有 6,但 6 个月内有 14 次改动,因为业务规则频繁变化,每次都要小心翼翼地改那个简洁函数里的某几行,旁边的人都不敢动。

结论:复杂度指标需要与改动频率交叉分析。 一个高复杂度但极稳定的函数,重构的性价比可能很低;一个中等复杂度但频繁改动的函数,才是最该被简化的对象。

五、专业判断逻辑:建立“复杂度治理决策矩阵”

基于上一节的最后一个误区,我建立了一套 2×2 决策矩阵,用于判断“哪些复杂代码该立即动手,哪些该暂时放过”。

5.1 复杂度 × 改动频率:四象限决策模型

这个矩阵让我在多个项目中避免了对“僵尸复杂代码”的过度投入。一次一个技术负责人执意要重构一个圈复杂度 40+的遗留报表模块,我用矩阵分析发现该模块过去两年只改过一次，重构它相当于花 2 周时间换一个 0 故障率模块的“美观”,ROI 极低。最终我们把那 2 周投入到三个高改动频率的中等复杂度模块上,第一季度生产事故下降了 60%。

5.2 让 Claude Code 帮你执行这个决策逻辑

你可以直接在 Claude Code 中这样问:

我已经对项目进行了复杂度分析(报告在 complexity_report.md)。现在请执行以下任务:

1. 用 git log 分析过去 3 个月内每个高风险函数所在文件的改动次数
2. 交叉复杂度数据和改动频率数据,生成一个“重构优先级排序表”
3. 对优先级 Top 3 的函数,生成简化的详细方案,同时标注:(a) 重构预计耗时 (b) 需要的测试覆盖 (c) 对上下游的影响范围

这里用了 git log 命令来获取改动频率,这些数据 Claude Code 可以直接调用并解析。把复杂度从“静态数字”变成“风险信号”,需要和历史变更数据联动。

5.3 一个在金融项目中踩过的坑:业务周期的影响

2023 年我在一个金融交易系统上应用了上述矩阵,结果发现一个现象:某个对账模块平时改动频率很低,所以被归到了“监控区”。但到了季度末财务关账期,它突然频繁改动，因为业务方会提出一堆关账相关的临时规则。

教训:改动频率的窗口不能只看“近 3 个月”,还要结合业务周期。 对于有明显周期性(月末、季末、年末)的模块,应该拉长统计窗口到 12 个月,并标记峰值期。

修改后的指令:

git log 分析近 12 个月的文件改动,按月聚合,识别出有周期性改动高峰的文件。如果一个文件在特定月份改动频率显著高于其他月份,标记为“周期敏感模块”,即使平均复杂度不高,也应在高峰来临前安排预防性重构。

六、动手简化:三个“Before/After”的真实案例

下面三个案例都来自我实际参与的项目。每个案例都包含:原始代码特征、使用的 Claude Code 指令、AI 输出的简化方案、以及我对方案的审查和修正。这三个案例覆盖了三种典型场景:遗留系统的巨型函数、过度设计的抽象链、以及异步回调地狱。

6.1 案例一:300 行的对账函数(遗留系统)

原始状态:

一个 Python 函数 reconcile_orders,圈复杂度 94,认知复杂度 127,开头注释日期是 2019 年。它的逻辑大致是:读取两个 CSV 文件,按订单号匹配,然后根据 7 种订单状态分别做不同处理,每种状态内部还有 3-5 层的条件分支。

使用的指令:

分析 reconcile_orders 函数(reconciliation/engine.py, 178-511行)。

1. 先用 radon 给出它的圈复杂度和认知复杂度
2. 识别出该函数中的 7 个订单状态处理分支,对每个分支进行圈复杂度评估
3. 给出重构方案:将每个状态处理分支提取为独立函数,但注意识别各分支之间的共享逻辑,将其提取为公共辅助函数
4. 重构方案必须满足:(a) 所有现有测试保持通过 (b) 不改变 CSV 文件的读取方式 (c) 异常处理逻辑保持不变
5. 预估重构后主函数的圈复杂度

AI 的输出:

• 识别出 7 个状态分支,其中“已退款”分支最复杂(CC=23),“已签收”最简单(CC=5)
• 发现 3 个共享逻辑:(a) 金额校验 (b) 时间窗口检查 (c) 异常订单标记
• 建议提取 3 个公共函数 + 7 个状态处理函数,主函数 CC 预估降到 9

我的审查和修正:

AI 的原始方案中,把“金额校验”提取为一个公共函数 validate_amount,但在 7 个状态分支中,实际上只有 5 个使用完全相同的金额校验规则,“待支付”和“已取消”使用的是另一套规则。如果强行统一,会导致后两个分支的行为改变。

我让 Claude Code 修正:

你的方案假设所有 7 个分支使用相同的金额校验逻辑。请重新检查“待支付”和“已取消”分支,确认它们是否与其他分支共享校验逻辑。如果不是,请为它们保留独立的校验函数。

AI 重新分析后确认,validate_amount 只适用于 5 个状态,另外两个需要各自的校验函数。

最终结果:

• 主函数从 300+ 行缩减到 52 行,CC 从 94 降到 9
• 新增 12 个函数(3 个公共 + 7 个状态处理 + 2 个特殊校验)
• 所有 35 个已有测试通过,未修改测试
• 重构后第一次上线零事故

6.2 案例二:被过度设计的策略模式(TypeScript)

原始状态:

一个 TypeScript 的支付渠道适配层,最初只有微信和支付宝两个渠道,开发者为了“面向未来扩展”,实现了完整的策略模式 + 工厂模式 + 模板方法模式。当业务发展到需要接 3 个新渠道时,反而没人敢动，因为要理解 6 个抽象类和 4 个接口之间的继承关系才能添加一个具体实现。

核心症状:圈复杂度不高(大部分类 CC 在 3-5),但类之间的继承和实现关系形成了一张密集网,认知复杂度极高。

使用的指令:

分析 payment/adapters 目录下的 TypeScript 代码。

1. 绘制类之间的继承和实现关系图(以 Markdown 的 Mermaid 语法输出)
2. 评估当前设计对“添加新支付渠道”的操作复杂度:需要接触多少个文件、修改多少个类
3. 如果目标是“添加新渠道时只需要创建 1 个文件、实现 3 个方法”,应该如何简化现有结构
4. 给出简化前后继承深度的对比

AI 的输出:

• 绘制了完整的类图,揭示了问题:BasePaymentAdapter → AbstractGatewayAdapter → TemplatePaymentProcessor,三层继承,而实际上 AbstractGatewayAdapter 只被 TemplatePaymentProcessor 使用,中间层完全可以合并
• 依赖倒置原则被过度使用:4 个接口中,有两个各只有一个实现类
• 建议:保留工厂模式,去掉模板方法和中间抽象层,让具体渠道直接实现一个简单的接口

我的审查:

这个简化方案方向正确,但我注意到 AI 忽略了一个问题:这 4 个接口中有一个 Refundable 用于标识支持退款功能的渠道,虽然目前支付宝和微信都实现了它,但新渠道中有一个“银联扫码”不支持退款。如果按 AI 的方案把退款逻辑直接放入渠道类中,反而会让不支持退款的渠道多出不必要的方法。

我追加指令:

保留 Refundable 接口,因为它表达的是“能力”而非“实现层次”。请基于这个约束重新生成简化方案。

最终结果:

• 从 6 个抽象类缩减到 1 个抽象基类 + 1 个接口
• 添加新渠道从“修改 5 个文件”变为“创建 1 个文件,实现接口的 3 个方法”
• 团队从不敢碰变成主动接了 3 个新渠道

6.3 案例三:金字塔式的回调地狱(Go)

原始状态:

一个 Go 的异步任务调度函数,因为历史原因使用了层层回调的写法(类似 Node.js 早期风格),圈复杂度 18,但认知复杂度高达 58，因为每个回调内部还嵌套着错误处理和状态检查。

特别之处:Go 语言通常不会出现经典的回调地狱,但这个项目最初由 Node.js 团队迁移而来,把 JS 的思维带了过来。

使用的指令:

分析 scheduler/async_chain.go 中的 ProcessTaskChain 函数。

1. 用 gocyclo 给出圈复杂度
2. 识别所有回调函数,列出其嵌套层次
3. 提出使用 Go 的 goroutine + channel 替代回调的方案
4. 对比两种方案的圈复杂度、认知复杂度和可测试性
5. 注意:不改变任务的处理顺序和幂等性保证

AI 的输出:

• 识别出 5 层回调嵌套,最深的一层同时处理 4 种错误情况
• 建议使用 pipeline 模式:每个步骤作为独立 goroutine,通过 channel 传递结果,错误通过单独的 error channel 传播
• 预估 CC 从 18 降到每个步骤平均 4,认知复杂度从 58 降到 22

我的审查和补充:

AI 的方案在技术上合理,但忽略了 goroutine 泄漏的风险，如果在 pipeline 中间某个步骤失败,后续的 channel 如果没有正确关闭,会导致 goroutine 永远阻塞。

我让 Claude Code 补充:

在方案中增加对 channel 关闭和 goroutine 退出的完整处理,确保在任一步骤失败时整个 pipeline 干净退出,不留泄漏的 goroutine。

AI 补充了使用 context.Context 进行取消传播的机制,以及在 defer 中关闭 channel 的逻辑。

最终结果:

• 函数从 280 行缩减到 45 行(主控制流部分),每个步骤独立为一个 40-60 行的函数
• CC 从 18 降到每个步骤 3-5,总认知复杂度从 58 降到 22
• 可测试性飞跃:原来需要模拟完整的 5 层回调,现在可以对每个步骤独立单元测试

七、安全审查:如何验证 AI 的简化没有引入新问题

这是全文最关键的一章。很多人跳过这一步直接合并 AI 生成的简化代码,相当于把自动驾驶的汽车直接开到高速公路上而不检查刹车。

7.1 三类 AI 简化最常见的“负优化”

基于我审查过超过 200 次 Claude Code 的简化建议,我把 AI 的常见失误分成三类:

第一类:抽象泄漏

AI 喜欢提取“看起来重复”的代码,但当它不理解业务语义时,会创建出语义模糊的抽象。例如:

# 原始代码
def process_vip_order(order):

if order.amount > 500 and order.user.level == 'VIP':

apply_discount(order, 0.2)

def process_holiday_order(order):

if order.date in HOLIDAYS and order.amount > 300:

apply_discount(order, 0.15)

AI 可能会简化为:

def should_discount(order, threshold, condition_fn):
return order.amount > threshold and condition_fn(order)

这个抽象把“VIP 身份的 0.2 折扣”和“节假日的 0.15 折扣”强行统一成同一个函数签名,但实际上它们背后的业务规则完全不同(一个是用户属性,一个是时间属性)。后续如果要修改 VIP 规则,就不得不在通用的 should_discount 里加逻辑分支,反而制造了新的复杂度。

识别方法:当 AI 提取的公共函数名字中包含 process、handle、do 等模糊动词,或者参数列表中有布尔/回调类型的“策略参数”时,大概率是抽象泄漏。

第二类:防御性逻辑丢失

原始代码中常见的“看起来多余”的检查,实际上可能在防御某种罕见但致命的边界情况。例如:

# AI 可能觉得这个 if 是多余的
if items is not None and len(items) > 0:

process(items)

简化为

process(items)  # 如果 items 可能为 None,这里就会崩溃

更隐蔽的是:原始代码的 len(items) > 0 和 if items: 在 Python 中行为不完全相同，后者对空字符串、0 等 falsy 值也会判断为 False,但前者的语义更明确。

识别方法:让 Claude Code 在简化后逐个标注被删除的条件判断,并解释为什么认为它们是冗余的。如果一个条件判断涉及 null/nil/undefined 的防御,就需要特别谨慎。

第三类:隐式行为改变

这类失误最危险,典型表现是改变了异常传播路径或副作用执行顺序:

# 原始
def create_order(data):

validate(data)

log("creating order")  # 即使后面失败,这条日志也会写

result = db.insert(data)

notify(result)

return result

AI 简化后

def create_order(data):

validate(data)

result = db.insert(data)

log_and_notify(result)  # 合并了 log 和 notify,但如果 insert 失败,日志也不写了

return result

日志写入和通知发送在原始代码中是两个独立步骤,AI 合并后改变了执行顺序和异常发生时的行为。

识别方法:

要求 Claude Code 输出一份“行为等价性声明”,列出:

1. 哪些操作被合并了
2. 合并后的执行顺序是否与原始代码完全一致
3. 异常发生时的行为是否有任何变化

7.2 三步安全审查流程

综合以上三类失误,我建立了一个标准化的审查流程,每次 AI 简化后必须走完这三步:

第一步:差异审查

让 Claude Code 生成一份“人类可读的 diff 说明”:

请输出你对代码所做的每一项改动的说明,按以下格式:

• 改动位置: [文件名:行号]
• 改动类型: [提取函数/合并分支/简化条件/删除代码/重命名/其他]
• 原始逻辑: [简短描述]
• 新逻辑: [简短描述]
• 行为等价性: [说明为什么新逻辑与原始逻辑行为完全一致,或标注不一致的地方]
• 风险评级: [低/中/高]

对于风险评级为“中”或“高”的改动,必须人工审查。

第二步:测试验证

如果项目已有测试,直接运行:请运行所有现有测试,确认全部通过。

如果项目没有测试(这是常态),让 Claude Code 为被修改的函数生成测试:

对被修改的每个函数,生成单元测试,要求:

1. 覆盖正常路径
2. 覆盖边界条件(null、空集合、极大值/极小值)
3. 覆盖异常路径(依赖失败、超时、格式错误)
4. 运行这些测试,报告结果

第三步:边界值演练

这是我自创的一个审查方法:故意给简化后的代码抛出极端输入,看它的行为是否与原始代码一致:

我现在要对简化后的代码进行边界值测试。请你在不查看原始代码的情况下,回答以下问题:

• 如果传入 null/nil,会发生什么?
• 如果传入一个包含 100 万个元素的列表,会发生什么?
• 如果依赖调用抛出超时异常,会发生什么?

然后,我会把原始代码的行为告诉你,你对比是否有差异。

这个方法在案例二中发现了 AI 方案的问题，简化后的 pipeline 在某个步骤出错时没有正确清理 goroutine,而原始代码(虽然有其他问题)在异常处理上是正确的。

八、嵌入 CI/CD:让复杂度持续受控而非一次性运动

单个函数的简化可以靠一次重构完成,但如果你不做持续约束,6 个月后又会回到原点。我在三个项目中验证了一套“复杂度门禁”机制,其核心思路是:在 CI/CD 流程中设置阈值,当新提交的代码触发阈值时,Claude Code 自动介入并提出修改建议,阻止合并直到问题解决。

8.1 基础架构:GitHub Actions + Claude Code

以下是我在一个项目中实际使用的 GitHub Actions 配置思路(非完整 YAML,但足以说明逻辑):

触发条件: PR 提交到 main 分支
步骤:

Checkout 代码
运行 radon cc src/ -s,输出圈复杂度报告
提取 CC > 20 的函数列表
如果列表非空:

调用 Claude Code CLI:

"以下函数圈复杂度超过阈值 20:[列表]。

请对这些函数提出简化建议,并输出为 Markdown 评论。

要求:保持接口不变、保持测试通过、一次只改一个函数。"

将 Claude Code 的输出作为 PR 评论发布

设置 PR 状态为"请求变更",阻止合并
当开发者提交修改且 CC 降至阈值以下时,PR 状态恢复

关键设计点:

• 阈值设在 20 而非 10:因为实践中 CC 在 10-20 之间的函数可能是必要的逻辑表达,过于严格会让开发者反感
• 自动生成评论:不是自动合并代码,而是把建议给到开发者,最终决策权在人
• 阻止合并而非阻止提交:开发者可以在自己的分支上自由实验,但无法合并到主干

8.2 进阶:增量分析而非全量分析

上面的方案每次对全项目进行分析,在大型项目中会很慢。更实用的做法是只分析本次 PR 修改的函数:

运行 git diff origin/main…HEAD 找出所有变更的 Python 函数,仅对这些函数运行 radon cc。对于新增函数,阈值设为 15;对于修改的函数,检查其 CC 是否因本次修改而增加，如果增加,阻止合并并要求说明原因。

这个增量策略避免了“因为项目里老代码太烂,所以我的新代码也合不进去”的困境。

8.3 处理老代码:技术债务登记册

“但我们的老代码 CC 全是 100+ 的!”，这是最常见的反对理由。

解决方案是建立“技术债务登记册”:

在项目根目录维护一个 complexity_debt.md 文件,列出所有已知高复杂度函数及其“豁免期限”。对于豁免期内的函数,CI 门禁不阻断。但每次 PR 如果修改了豁免函数,必须附带复杂度改善，改造一处降 1 分也是进步。

我在一个项目中使用这个策略,12 个月内将 48% 的豁免函数从高复杂度清单中移除,且没有专门安排“重构 Sprint”，改善是在日常开发中自然发生的。

8.4 不同项目阶段的取舍

上述方案不能一刀切,需要根据项目阶段调整:

在原型阶段过度约束复杂度,会拖慢验证速度，我犯过这个错误,结果被团队抱怨“连写个临时脚本都要被 radon 卡住”。

8.5 与其他质量工具的配合

Claude Code 的复杂度分析不是孤立运行的,它应该和现有质量基础设施配合:

• SonarQube:如果你的团队已经在用 SonarQube,那么复杂度阈值应该与 SonarQube 的质量门保持一致,避免两个系统给出矛盾信号
• Code Review:Claude Code 生成的简化建议应该作为 Review 的补充而非替代。理想流程:Claude Code 生成建议 → 开发者评估 → Reviewer 以建议为参考进行审查
• 测试覆盖率工具:复杂度门禁应和覆盖率门禁联动。一个高复杂度的函数即使测试覆盖率达到 80%,也依然危险,因为圈复杂度为 30 的函数需要更多用例

九、不同语言/框架的特异性处理

前面的案例主要集中在 Python、TypeScript 和 Go,但实际工作中你可能面对各种技术栈。这一章讨论不同语言在复杂度治理上的特殊考量。

9.1 函数式语言:范式不同,指标需要重新校准

我曾短暂参与过一个 Clojure 项目,用 radon(它只支持 Python)当然不行,用认知复杂度也有偏差，函数式语言天然倾向于大量小函数和组合,如果按命令式语言的标准去衡量,几乎所有代码都会被标记为“高复杂度”。

函数式语言中更应该关注的是:

• 单次变换的复杂度(一个 transduce 内部塞了多少逻辑)
• 宏生成的隐式复杂度(看起来一行,展开后十几层嵌套)
• 核心抽象层数的深度(你为了表达某个概念,嵌套了多少层高阶函数)

对于这类语言,Claude Code 的静态推理模式(3.3 节提到的)比依赖通用工具更有价值。你可以给 Claude Code 一段宏展开的代码,让它评价展开后的实际复杂度。

9.2 基于配置驱动的框架:复杂度可能在别处

在 Spring Boot(Java)或 Django(Python)这类“约定大于配置”的框架中,很多业务逻辑不写在代码里,而是写在注解、配置文件或 ORM 映射中。

曾经有一个 Django 项目的复杂度分析一切正常，所有 View 函数的 CC 都低于 8。但后来发现一个 Model 的 save() 方法被覆盖,其中调用了 3 个信号接收器,每个接收器又触发了不同的 Celery 任务。这种隐式调用链的复杂度不会出现在单个函数的分析中。

对策:

让 Claude Code 分析整个调用链而非单个函数。指令: "追踪这个 Model 的 save 方法被调用后,所有被触发的信号、任务和钩子函数,分析整个调用链的总圈复杂度和认知复杂度。"

9.3 前端代码:状态管理带来的特殊复杂度

React/Vue 等前端框架的组件,复杂度往往不在渲染逻辑里,而在状态管理上:

• 一个 useEffect 的依赖数组是否引入了不必要的重渲染循环
• Redux/Vuex 的 action → mutation → state 链条是否过深
• 组件间 props drilling 的层级

这类问题用传统圈复杂度工具测不出来。但在 Claude Code 中,你可以这样问:

分析这个 React 组件的状态依赖图:找出所有 useState、useReducer、useEffect,标注它们之间的依赖关系。识别是否存在循环依赖或不必要的重渲染风险。评估增加一个新状态变量需要改动多少行代码。

Claude Code 可以读取组件代码并绘制状态流转图,这是普通静态分析工具做不到的。

十、成本效益分析:在 Claude Code 中做复杂度治理划算吗

作为一篇实操指南,不讲清楚投入产出比是不够诚实的。以下是基于我自己的使用数据得出的估算。

10.1 时间投入

10.2 回报

• 减少调试时间:一个圈复杂度 50 的函数,排查一个问题平均需要 2-4 小时;简化后(CC < 10)降到 15-30 分钟。假设一个月遇到 3 次相关问题,每月节省 6-10 小时。
• 降低新人上手成本:一个复杂度被治理过的模块,新人理解时间从 2-3 天降到半天。
• 降低故障率:如 2.1 节图表所示,CC 从 50+ 降到 20 以下,故障概率从 81% 降到 22% 以下。这个价值难以精确量化,但一个 P0 故障的成本(包括处理时间、赔偿、信誉损失)远超所有治理投入。
• 降低 Token 消耗:复杂度降低后,Claude Code 在处理这个模块时需要读入的上下文更少。我在一个频繁使用 Claude Code 的项目中观察到,模块简化后,该模块相关交互的平均 Token 消耗下降了约 35%。

10.3 什么时候不要做

复杂度治理也不是银弹,以下情况应该暂缓或跳过:

• 项目即将下线或重构(投入没有回报期)
• 团队只有 1-2 人且流动率极低(沟通成本低,复杂度可以被人的默契弥补)
• 代码是自动生成的且从未被人工修改(生成器的输出不应手动优化,应该改生成器)
• 项目处于极度早期,核心逻辑仍在变化中(过早优化是万恶之源)

十一、总结与行动建议

18 个月,4 个项目,200+ 次 AI 简化审查,我学到的最重要的一课是:复杂度治理不是技术问题,是决策问题。 工具和 AI 可以帮你量化、分析、提方案,但最终你需要判断四个问题:

1. 改不改:高复杂度但极稳定的代码,不值得主动改
2. 什么时候改:高复杂度且高改动频率的代码,本周就该改
3. 改到什么程度:圈复杂度降到 10 还是 20,取决于模块的重要性和团队规模
4. 怎么验证改对了:三步审查(差异审查、测试验证、边界演练)比信任 AI 更有用

如果你只能记住三件事,请记住这三件:

第一,永远不要凭“感觉”说代码复杂。 跑一次 radon、gocyclo 或 ESLint,把数字贴出来。数字是无可辩驳的,主观感受不是。

第二,把 Claude Code 当作分析执行器,而非决策者。 让它跑工具、画图表、提方案,但最终要不要改、怎么改,由你决定。审查步骤不能省,尤其是行为等价性验证。

第三,复杂度治理的终点不是“代码变干净了”,而是“改代码不再害怕了”。 如果你的团队还是不敢改那个被简化过的模块,说明治理还没成功。真正的成功标志是:任何一个开发者都敢打开那个文件,理解之后自信地改动,并在 30 分钟内确认没有引入问题。

接下来的行动建议(按优先级排序):

1. 今天就跑一次:打开 Claude Code,用第 3.1 节的指令模板,分析你当前项目的复杂度。即使不马上重构,拿到数据本身就有价值。
2. 识别最危险的 3 个函数:交叉复杂度数据和 git 改动频率,找出高风险目标。
3. 先简化一个,走完完整流程:选一个中等复杂度(CC 15-25)的函数,让 Claude Code 简化它,然后严格执行第 7 章的三步审查。整个过程走通之后,你对 AI 的能力边界会有非常具体的认知。
4. 设定团队阈值:和团队讨论一个可接受的复杂度阈值,写在项目文档里。没有阈值就没有标准,没有标准就没有持续改善。
5. 决定是否上 CI 门禁:如果项目已经进入规模化阶段(用户量 > 1000),认真考虑第 8 章的方案。如果还在原型期,先放一放。

代码复杂度不会自己消失。它只会在每一次“先这样吧,以后再说”的妥协中悄悄累积,直到某天一个看起来无害的改动引发线上事故,所有人才惊觉，原来我们一直在炸药堆上跳舞。让 Claude Code 成为你的探测器,在踩雷之前,先把雷标记出来。