最近做了一件以前想都不敢想的事：把一个跑了两年的 FastAPI 后端项目，从混乱的单文件架构重构成了分层清晰的标准结构。三天完成。

不是三天加班熬夜，是正常工作节奏，每天大概 4-5 小时。

工具只有一个：Claude Code。

项目背景

这个项目大概 2 万行 Python 代码，典型的"祖传代码"：

• 所有路由写在 3 个巨大的文件里，最长的 4000 多行
• 数据库操作散落在路由函数中，没有 service 层
• 环境变量硬编码在各处
• 测试？不存在的

你们应该懂这种代码——能跑，但没人敢改。

第一天：让 AI 理解你的项目

很多人用 AI 编程工具的第一个错误：打开就干。

Claude Code 不是 ChatGPT，不是你问一句它答一句。它能直接读你的文件、跑你的命令、改你的代码。但前提是——你得先让它理解你的项目。

我做的第一件事是写 CLAUDE.md：

# 项目说明

## 架构
- FastAPI + SQLAlchemy + MySQL
- Redis 做缓存和队列
- 部署在 Ubuntu 22.04

## 目录结构
app/
├── api/v1/          # 路由
├── models/          # 数据模型
├── services/        # 业务逻辑（目标）
├── schemas/         # Pydantic 模型
└── core/            # 配置、数据库连接

## 约定
- 所有 SQL 操作必须在 service 层
- 路由函数只做参数校验和调用 service
- 命名用 snake_case
- 每个 service 文件不超过 300 行

这个文件放在项目根目录，Claude Code 每次启动都会自动读取。相当于给 AI 一份持续生效的"项目规范"。

这一步省了我后面至少一半的纠正时间。

第二天：拆分与重构

有了 CLAUDE.md 的约束，重构就变成了一系列明确的指令：

把 app/api/v1/users.py 里的数据库操作提取到 app/services/user_service.py
保持路由签名不变，只改内部实现

Claude Code 会：

1. 先读完整个 users.py（4000 行）
2. 识别出所有数据库操作
3. 创建 user_service.py，把操作函数提取过去
4. 修改路由函数，改为调用 service
5. 检查 import 是否正确

一个文件的重构大概 5-10 分钟。最关键的是，它不会改你的接口签名，不会"顺手"重命名变量，不会加一堆它觉得"更好"的代码——因为 CLAUDE.md 里约定了。

遇到复杂的业务逻辑（比如支付回调里嵌套了 5 层 if-else），我会追加说明：

这段支付回调逻辑先别动，只提取纯数据库操作部分
if-else 业务判断留在路由层

一个真实的踩坑

重构到第三个文件的时候，出了一个问题：原来代码里有个 SQLAlchemy session 是在路由函数里 commit() 的，提取到 service 后 session 的生命周期变了。

Claude Code 实际上是发现了这个问题的——它在重构后自动跑了一次启动测试，发现 session.commit() 的位置不对，然后自己改了 service 函数的写法，用了依赖注入的方式传递 session。

这件事让我意识到 Claude Code 和 Copilot 最大的区别：它不只是补全代码，它能理解上下文做决策。

第三天：补测试 + 清理

最后一天主要干两件事：

1. 给核心 service 补单元测试

给 user_service.py 的 create_user 和 get_user_by_id 写单测
用 pytest + 内存 SQLite，不要连真实数据库

Claude Code 生成的测试代码质量很稳，包括正常流程、边界情况、异常处理都会覆盖到。

2. 清理死代码

找出 app/ 目录下所有没有被 import 的函数，列出来

它会用 grep 扫描整个项目的引用关系，给出一份清单。我确认后，它批量删除。

最终结果

指标	重构前	重构后
最大单文件行数	4200 行	280 行
Service 层	0 个	12 个
单元测试	0 个	47 个
代码总量	~2 万行	~1.8 万行
敢改代码的人	0 个	所有人

几个实用建议

1. CLAUDE.md 是核心

不要跳过这一步。没有它，AI 会按自己的风格写代码，你后面全在纠正。

2. 一次一个文件

别说"把整个项目重构了"，这种指令 AI 会迷失。一次处理一个文件，每次验证通过再继续。

3. 让它跑测试

每次重构完，让 Claude Code 跑一遍 pytest。它能看到错误输出，自动修复。这个反馈循环比你自己肉眼检查强太多。

4. 不确定的逻辑先标记

遇到你自己都不太确定的业务逻辑，先告诉 AI “这段暂时不动”，等其他部分稳定了再处理。

关于 Claude Code 的使用

Claude Code 目前官方订阅是 $20/月 的 Claude Max，但需要海外信用卡和网络环境。如果这些条件不方便，可以试试 Code2AI（console.code2ai.codes），两行配置接入：

export ANTHROPIC_BASE_URL="https://code2ai.codes"
export ANTHROPIC_AUTH_TOKEN="你的token"
claude

新用户有 3 天免费试用，够你跑完一个小项目的重构了。

最后

三天重构两万行代码，这件事本身不是重点。重点是：有了 AI 编程工具，"重构"这件所有人都知道该做但没人敢做的事，终于有了可行路径。

技术债不会自己消失，但还清它的成本，正在急剧下降。