一个运行多年的 Python 后端项目，靠 214 处函数级导入勉强绕过循环依赖问题。开发者借助 Claude Code，把整个代码库的导入关系图交给 AI 编程助手，逐条分析并拆分循环依赖，最终用 8 个工作日完成了 37 个循环导入链的治理。这次实践给出的关键经验是：面对复杂代码问题，不要只把报错交给 AI，而要把系统结构交给 AI。
先建图，再修复：AI 编程助手需要全局视角
该项目是一个约 18 万行代码的 Python 3.12 服务，采用类似 Django 的分层结构，但架构由团队手工维护。长期以来，开发者通过在函数内部延迟导入的方式规避 ImportError，仓库中累计出现了 214 处「avoid circular import」注释。开发者此前曾尝试人工修复，两天只处理了 4 个循环，还导致测试环境的 webhook 处理器出现问题，最终只能放弃。
这次他首先尝试直接把 ImportError 交给 Claude Code 处理，结果 AI 只是又增加了一个函数级导入。问题并非模型能力不足，而是单一报错只能呈现循环中的一条边，无法反映完整依赖关系。随后，开发者使用 pydeps 生成模块依赖，并用 networkx 构建有向图，找出所有包含多个模块的强连通分量，最终确认项目中存在 37 个循环依赖，其中一个循环涉及 14 个模块。
从小循环入手，让 AI 做架构判断而不是补洞
开发者没有直接从最大的 14 模块循环开始，而是让 Claude Code 根据修复成本、隔离程度和风险对循环进行排序，优先处理小规模、独立性强的循环。每修复一个小循环，大循环的关联边也会随之减少。到最后处理最大循环时，其规模已从 14 个模块降至 5 个模块。
对每一个循环，开发者都提供结构化提示，包括循环成员、依赖边、禁止继续使用函数级导入、优先采用的重构方式，以及要求 Claude Code 解释「哪条边是错误的」。其中一个典型案例是账单模型在保存时直接调用邮件服务。Claude Code 判断模型层不应感知邮件模块，最终方案是新增低层事件模块，由模型发布事件，通知层订阅处理。该方式在全部 37 个修复中被归纳为三类：下沉共享类型、依赖 Protocol 接口，以及通过回调或事件反转依赖。
从一次性修复到工程约束
为了避免循环依赖再次出现，开发者在 CI 中加入 import-linter 层约束，要求 api、services、models、types/events 等模块按明确方向依赖。该项目呈现出一种更现实的 AI 编程协作方式：AI 不直接替代架构师，而是承担图分析、候选方案生成、重复修改和影响面排查等繁琐工作，人类开发者负责判断哪些依赖方向不合理，并决定采用哪种结构修复方式。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/claude-code-jin-ru-yi-liu-dai-ma-ku-8-tian-qing-li-37-ge
