引言
我让AI Agent（小密）帮我管理一个开发团队——小虾负责开发，小牛负责测试，小白负责运维。听起来很美好对吧？
但运行观察，我发现自己掉进了一个坑：AI写的100多个脚本，互相调用、互相矛盾，最后连它自己都搞不清该调哪个。
这篇文章分享我如何发现并清理这些"技术债"，以及给同样在用AI写代码的开发者的建议。
一、问题是怎么发现的
周五下午，我问小密：“心跳报告为什么重复发？”
小密的回答让我懵了：
“heartbeat调用
auto_review.run_auto_review()进行复核，而ws_server调用review.py --all进行复核。两者功能重叠但实现不同，可能导致重复执行。”
等等，两个复核脚本？ 我明明只设计了一个复核流程啊。
我让小密排查，发现了更严重的问题：
| 模块 | 预期功能 | 实际情况 |
|---|---|---|
auto_review.py | 复核入口 | 400行代码，包含验证、部署、唤醒等逻辑 |
review.py | 复核入口 | 另一套复核逻辑，更完整 |
auto_pipeline.py | 派发测试 | 包含验证、部署、唤醒等独立功能 |
auto_pipeline_db.py | 派发测试 | 另一套派发逻辑，基于DB驱动 |
4个脚本，2套复核逻辑，2套派发逻辑。 谁调谁，没人说得清。
二、根因分析：AI为什么会这样写代码
2.1 缺乏全局视角
AI Agent每次执行任务时，只看到当前的任务MD，看不到整个系统的架构。它会：
- 为了"快速完成任务"，写一个新的脚本
- 不检查是否已有类似功能的脚本
- 不考虑与其他模块的调用关系
2.2 Skill文档与实际代码脱节
我写了一份详细的skill文档（pf-workflow），描述了理想的架构：
- 派发测试 →
auto_pipeline_db.py - 复核 →
review.py - 超时修复 →
diagnose_and_fix_timeout()
但实际代码呢？
auto_pipeline.py里也有auto_dispatch_tests_for_completed_dev()auto_review.py里也有复核逻辑ws_server.py直接调用review.py，不走统一入口
Skill描述的是理想，代码写的是现实。
2.3 没有统一的函数入口
最致命的问题：每个脚本都自己实现了一遍核心逻辑。
复核逻辑出现了3次：
1. auto_review.py: run_auto_review()
2. review.py: run_review()
3. ws_server.py: 直接调用 subprocess.run(['python3', 'review.py', '--all'])
谁是"正确的"？没人知道。
三、清理过程：统一调用链
3.1 第一步：识别所有重复功能
我让小密列出了所有脚本的功能映射：
| 功能 | 脚本A | 脚本B | 问题 |
|---|---|---|---|
| 派发测试 | auto_pipeline.py | auto_pipeline_db.py | 两套逻辑 |
| 复核 | auto_review.py | review.py | 两套逻辑 |
| 超时修复 | auto_pipeline.py | diagnose_and_fix_timeout() | 函数重复 |
| 唤醒Agent | auto_pipeline.py | wake_agent.py | 调用链混乱 |
3.2 第二步：确定唯一入口
我制定了统一规则：
派发测试 → auto_pipeline_db.auto_dispatch_tests_for_completed_dev()
复核 → review.py --all
超时修复 → diagnose_and_fix_timeout()
唤醒Agent → wake_agent.py
3.3 第三步：废弃旧模块
auto_review.py → 废弃（功能合并到review.py）
auto_pipeline.py → 只保留验证工具函数
ws_server.py → 调用统一入口
3.4 第四步：更新skill文档
将"理想架构"和"实际代码"对齐：
- skill描述的函数名 = 代码中实际的函数名
- 调用链 = 代码中的实际调用路径
四、关键教训
教训1：AI写代码需要"代码审查"
AI不会主动检查"这个功能是否已经存在"。每次它写新代码时，你需要：
- 让它先搜索现有代码库
- 检查是否有重复功能
- 确认调用链是否正确
教训2：Skill文档必须与代码同步
Skill不是"写完就忘"的文档，而是活的规范。如果代码变了，skill必须同步更新。
我犯的错误：
- skill描述的是理想架构
- 代码是另一个样子
- 结果：AI按skill写代码，但实际调用的是另一个模块
教训3：统一函数入口是关键
# ❌ 错误：每个模块自己实现
auto_pipeline.py: def auto_dispatch_tests_for_completed_dev()
auto_pipeline_db.py: def auto_dispatch_tests_for_completed_dev()
ws_server.py: subprocess.run(['python3', 'auto_review.py'])
# ✅ 正确：唯一入口
所有模块 → auto_pipeline_db.auto_dispatch_tests_for_completed_dev()
教训4：定期审计AI写的代码
我建立了一个每周审计机制：
- 列出所有Python脚本
- 检查是否有重复函数
- 确认调用链是否正确
- 更新skill文档
五、给同样在用AI写代码的开发者
5.1 建立"代码规范"
在让AI写代码之前，先定义：
- 唯一的函数入口
- 模块职责边界
- 命名规范
5.2 使用"代码审查"提示词
每次AI完成任务后，用这个提示词审查：
请检查你刚才写的代码：
1. 是否有重复功能的现有代码？
2. 调用链是否与其他模块一致？
3. 是否遵循了项目的命名规范？
5.3 建立"技术债"清单
每周花10分钟，列出：
- 重复的函数
- 混乱的调用链
- 过时的skill文档
然后逐个清理。
六、总结
AI Agent写代码很快，但也很容易制造"技术债"。关键是要：
- 统一函数入口 — 一个功能只有一个实现
- Skill与代码同步 — 文档描述的必须是实际的
- 定期审计 — 发现重复及时清理
- 代码审查 — AI写的代码也需要review
现在，我的系统清爽多了：
- 复核只有一个入口：
review.py - 派发只有一个入口：
auto_pipeline_db.py - Skill文档和代码完全一致
清理"技术债"花了3天，但省下的调试时间远不止3天。
如果你也在用AI写代码，建议你今天就检查一下：代码里有没有"两个复核脚本"？
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/2501_93061360/article/details/162796407
