用 pytest-archon 阻止 AI 代码蔓延

为什么 AI 写的代码会“蔓延”

AI 编程助手能快速生成大量代码，但如果没有约束，这些代码会像藤蔓一样无序生长：模块边界模糊、依赖关系混乱、重复逻辑遍地。这种现象被称为 AI 代码蔓延（AI code sprawl）。

更隐蔽的问题是 理解债（Comprehension Debt）——团队越来越难理解代码库的整体结构和意图。当 AI 持续产出风格不一、缺乏全局观的代码时，人类开发者需要花更多时间逆向工程，才能安全地修改或扩展系统。

可执行架构：把设计规则变成测试

传统的架构文档容易过时，也无法阻止错误代码合入。可执行架构（Executable Architecture） 的思路是：把架构约束写成可运行的测试，在 CI/CD 流水线中自动执行。一旦有人（或 AI）违反规则，构建就会失败。

这样做的好处：

• 即时反馈：在代码合并前就发现架构违规，而不是等到重构时。
• 对 AI 友好：AI 生成的代码同样受规则约束，减少人工审查负担。
• 活文档：测试即架构说明，永远与代码同步。

用 pytest-archon 落地

pytest-archon 是一个 Python 库，让你用 pytest 编写架构测试。它提供了简洁的 API 来定义模块依赖、层次结构等规则。

安装

pip install pytest-archon

定义架构规则

在测试文件中，你可以这样声明约束：

from pytest_archon import archrule

def test_architecture():
    (
        archrule("Domain should not depend on infrastructure")
        .match("myapp.domain.*")
        .should_not_import("myapp.infrastructure.*")
        .check()
    )

这个测试会检查 myapp.domain 包下的任何模块是否导入了 myapp.infrastructure 包。如果违反，pytest 会失败并给出清晰提示。

集成到 CI/CD

把架构测试和其他单元测试一起运行即可：

pytest tests/architecture/

在 GitHub Actions、GitLab CI 等流水线中，这一步会自动阻止违规代码合入。

谁需要关注

• 使用 AI 辅助编码的团队：AI 生成代码速度快，更需要自动化护栏。
• 维护中大型 Python 项目的开发者：架构腐化往往悄无声息，可执行架构能提前预警。
• 技术负责人与架构师：用代码而非文档来传达设计决策，减少沟通成本。

实用建议

1. 从关键边界开始：先约束核心领域与外部依赖的隔离，再逐步细化。
2. 保持规则精简：过多约束会拖慢开发，聚焦真正重要的架构原则。
3. 让失败信息可操作：在规则描述中写清“为什么”，帮助 AI 和人类理解意图。
4. 定期回顾：随着系统演进，架构规则也需要调整。

AI 代码蔓延不是必然结局。通过 pytest-archon 等工具，你可以把架构约束变成自动化测试，让 AI 生成的代码在既定轨道上运行，从而控制理解债，保持软件设计的长期健康。