在AI代码泛滥摧毁你的软件设计之前，及时止损
内容提要
AI代码生成虽快，却带来“理解债”：代码功能正确但违反架构边界，团队逐渐丧失系统心智模型。文章主张用可执行架构替代文档，通过pytest-archon等工具在CI/CD中强制检查依赖规则，违规即构建失败，并将错误反馈给AI自动修复；同时结合复杂度门禁，使代码审查聚焦依赖与接口变化，而非逐行阅读。
延伸解读
理解债：AI代码的隐藏成本
文章指出，AI生成的代码即使功能正确，也可能违反架构边界，导致团队逐渐丧失对系统的心智模型，形成“理解债”。这种债务比技术债更紧迫，因为代码能通过测试和合并，但人类维护者不再理解系统为何如此设计。理解债的积累会削弱团队应对变更和故障的能力，最终可能引发严重问题。
可执行架构：从文档到CI/CD强制检查
文章主张用可执行架构替代被动文档，通过pytest-archon等工具在CI/CD中定义并强制依赖规则。例如，禁止计费模块导入物流模块，或确保领域模型不依赖基础设施。违规时构建失败，并将错误反馈给AI自动修复。这种方法不依赖人工审查，能有效防止架构漂移。
复杂度门禁与代码审查重点转移
除了架构测试，文章建议结合复杂度门禁工具（如Ruff、Radon、SonarQube）设置硬限制，迫使AI分解大函数。在审查AI生成的PR时，开发者应关注外部变化：新依赖、新API端点或数据模式变更，而非逐行阅读。这样能保护有限的心智资源，维持对系统的整体理解。
Q&A
什么是理解债（Comprehension Debt）？
理解债是指代码编写速度与人类团队对其架构理解程度之间日益扩大的差距。当AI生成功能正确但违反系统边界的代码时，团队会逐渐丧失对系统的心智模型。
为什么AI生成的代码即使功能正确也很危险？
因为AI生成的代码可能功能正确且无bug，但会微妙地违反系统边界，例如将计费服务连接到用户认证组件，或让表现层访问数据库。这类代码能通过测试并合并，但会破坏人类开发者维护系统所依赖的设计假设，导致团队失去对系统架构的理解。
如何用pytest-archon在CI/CD中强制架构规则？
首先安装pytest-archon，然后在测试文件夹中创建test_architecture.py文件，使用archrule定义规则，例如确保billing模块不导入shipping逻辑，或领域模型不导入基础设施。当AI推送PR时，pytest自动运行，若违反规则则构建失败，并将错误反馈给AI自动修复。
除了架构测试，还需要哪些工具来防止理解债？
还需要结合复杂度门禁工具，如Ruff、Radon或SonarQube，在CI流水线中设置硬性复杂度限制，强制AI将大函数分解为小函数。同时，代码审查应关注依赖、API端点和数据模式的变化，而非逐行阅读。
为什么文档不足以约束AI的架构行为？
因为AI代理会寻找更简单的路径来达成目标，如果跳过服务层能更快实现，它就会这么做。而人类审查者越来越难以审查数千个AI生成的PR，这些绕行会未被发现。因此不能依赖文档或人工检测架构漂移，必须依靠CI/CD流水线。
在AI生成PR的代码审查中，开发者应该关注什么？
开发者应停止逐行阅读代码，而是从外部视角关注系统变化：是否有新依赖？是否暴露了新API端点？是否更改了数据模式？如果没有，则心智模型保持完整。
