整洁架构能帮AI编程Agent写代码吗？一次实测

一个被忽视的问题：架构会影响AI写代码的效率吗

当AI编程Agent接手代码开发时，我们习惯性地假设良好的软件架构依然重要。但这个假设成立吗？一位开发者在Reddit上分享了一组亲手完成的对照实验，试图回答这个问题：当写代码的是Agent而非人类时，整洁架构（Clean Architecture）究竟是助力还是负担？

实验设计相当克制：作者用同一个Java示例应用构建了两个版本。一个采用六边形架构（Hexagonal Architecture），配备端口（ports）、适配器（adapters）以及架构测试；另一个则完全不设架构建议或规则，是一个"扁平版本"（flat version）。两者都必须通过同一套外部测试用例来验证行为的正确性。测试环境统一使用本地部署的 Qwen 模型，通过 OpenCode 运行，每次只跑一个任务。

六边形架构（Hexagonal Architecture）由 Alistair Cockburn 于2005年提出，又称"端口与适配器架构"。其核心思想是将应用的业务逻辑置于中心，通过抽象的"端口"（接口）与外部世界交互，而"适配器"则负责将具体的外部技术（数据库、HTTP、消息队列等）转换为端口所定义的格式。这种设计使得替换任何外部依赖时无需修改核心逻辑。"Clean Architecture"是 Robert C. Martin 提出的类似理念的泛化版本，强调依赖方向应始终指向内层业务规则。这类架构在传统人类开发中被广泛推崇，因为它降低了不同模块之间的认知耦合，让开发者能集中关注单一层次。然而，这种"分层降低认知负担"的优势，在AI Agent操作时是否同样成立，正是本实验试图探究的核心问题。

测量了什么，怎么测的

作者的度量维度值得关注：他记录了每个任务从实现、测试到修复直至通过所耗费的时间，同时统计了 token 消耗和工具调用次数。项目的初始搭建时间不计入统计，以避免架构版本因前期脚手架更复杂而被"冤枉"。

实验分阶段推进。第一阶段是九个功能特性，随后是六个更有难度的挑战，分别放在独立的分支上完成。接着，作者又按顺序追加了十五项变更，其中包括对早期需求的修改——这一步刻意模拟真实开发中需求演进带来的返工压力。到实验后期，两个项目的生产级 Java 代码分别达到约 12k 和 15k 行的规模，已经不是玩具项目的量级。

实验使用的 OpenCode 是一款基于终端的 AI 编程工具，支持将本地或远程大语言模型连接到代码库并执行多步骤开发任务。Qwen 是阿里巴巴开源的大语言模型系列，本地部署意味着实验在离线、可控的环境中运行，排除了网络延迟和云端模型版本变动的干扰，但也意味着模型能力受本地硬件限制，可能不及 GPT-4o 或 Claude 3.5 Sonnet 等前沿模型。Token 消耗（包括输入和输出）是衡量 LLM 调用成本的标准指标：输入 token 代表模型需要"阅读"的上下文量，输出 token 代表模型生成的内容量。架构越复杂，相关文件越多，每次任务的输入上下文通常也会越长，这直接反映在 token 计数上。

结果出人意料：扁平版本总体更快

核心发现颇具冲击力：在每一轮实验中，没有架构约束的扁平版本总体耗时都更短。

六边形架构确实在某些单个任务上胜出，但从整体来看，它消耗了更多的输入和输出 token。换句话说，架构带来的规整性并没有转化为Agent的整体效率优势，反而因为需要理解和维护端口、适配器等抽象层，增加了模型的认知与生成成本。

这个结果对"架构越干净、AI越好写"的直觉提出了挑战。对人类开发者而言，清晰的边界能降低心智负担；但对当前的编程Agent来说，更多的结构层次可能意味着更长的上下文、更多的文件跳转和更高的token开销。

六边形架构的高光时刻：数据库扩展

作者随后设计了一个理论上应该偏向端口与适配器模式的场景：在保留 SQLite 正常工作的前提下，新增对 PostgreSQL 的支持。

这正是六边形架构宣称的优势所在——通过适配器隔离外部依赖，替换或新增底层实现时无需触碰核心业务逻辑。实测结果也印证了这一点：六边形版本仅用约 39 分钟就完成了任务，且其核心应用代码保持不变；而扁平版本花了 71 分钟。

但作者诚实地补充了两点关键限定：其一，这次节省的时间并不足以弥补前面十五项功能序列中累积的时间差距；其二，这只是后端层面的数据库支持工作，而非一次真实的、涉及数据迁移的线上切换。架构的收益是真实的，但在这个实验的整体账本中，它没能扭转局面。

如何理性看待这个实验

作者对实验的局限性表达得非常克制，这也是这份报告最值得称道的地方。他明确指出：这只是一个服务、一个模型，没有重复多次试验。它衡量的是"让变更通过测试"这一目标，而非多年的可维护性或生产环境的可靠性。

这些限定至关重要。软件架构的核心价值往往体现在长期维护、团队协作和系统演进中，而不是单次功能交付的速度。一个只跑几十次任务、由单一模型完成的实验，无法覆盖架构在数年生命周期中的复利效应。此外，Qwen 本地模型的表现也未必能代表更强的前沿模型——不同模型对抽象结构的处理能力差异可能很大。

完整的报告和测量数据已发布在 Zenodo（记录编号 22806994），作者也坦诚 AI 工具参与了评估器、编排、图表和文稿的撰写工作。

软件架构的长期价值通常通过"可维护性复利"体现：随着系统规模增长、团队成员更替和需求持续演变，良好的边界隔离能够指数级降低变更成本。著名的"破窗效应"在无架构约束的代码库中尤为显著——早期的快速交付往往以后期的技术债偿还为代价。此外，本实验衡量的是"通过测试"这一单一成功标准，而生产环境中的架构价值还体现在：代码审查效率、新成员上手速度、故障定位难度以及合规审计的可追溯性等维度，这些均无法在短期交付实验中量化。因此，将本实验的结论推广到"AI时代架构无用论"需要极为谨慎。

给开发者的启示

这个实验没有给出"该不该用整洁架构"的最终答案，但它提供了一个有价值的反直觉视角：

• 在纯交付速度的短期指标上，让Agent在无约束的扁平结构中工作可能更快、更省token；
• 在特定的可扩展性场景（如替换基础设施）中，良好的架构隔离依然能显著节省时间；
• 架构的"投资"需要足够长的时间跨度和足够多的变更才能回本，而单次实验很难捕捉这种回报。

对于正在探索AI辅助开发工作流的团队来说，或许真正的问题不是"要不要架构"，而是"在什么规模、什么周期下，架构的收益才能覆盖它对Agent施加的额外成本"。这需要更多样本、更多模型和更长时间的验证。