夜雨聆风用 AI 编码 Agent 生成一个 API 服务，早已不是新鲜事。开发者给它一段描述，它就能造出一个能跑起来的应用，甚至能通过大部分功能测试。但这个能力有一个边界，而且这个边界比大多数人意识到的要窄得多。
当你往任务描述里加几条"额外要求"——比如"用 Clean Architecture 分层"、"数据库用 PostgreSQL"、"ORM 用 SQLAlchemy"——Agent 的能力曲线不是缓慢下降，而是断崖式下跌。
这不是某个模型或某个框架的问题。这是一类系统性现象。
从功能正确到结构正确，中间隔着一道悬崖
AI 编码 Agent 在宽松规格下的表现确实出色。近期一项覆盖 8 个 Web 框架、80 个生成任务和 20 个功能实现任务的系统研究发现，在没有任何结构约束的情况下（只要求实现功能），顶尖 Agent 配置的测试通过率超过 85%。
但一旦加上层架构约束，再指定数据库和 ORM，这些 Agent 的测试通过率平均下降 30 个百分点。最严重的配置从基线 73% 跌到了 27.6%，相对性能损失超过六成。
更值得留意的是，这还不是最糟的情况。弱一些的配置在完整约束下几乎归零——它们能生成语法正确的代码，能通过部分功能测试，但几乎无法同时满足功能正确和结构正确。
研究定义了一个关键指标叫全量通过率（pass@1），即一次运行同时通过所有功能测试和结构验证的概率。在完全约束（L3）条件下，最强的 Agent 配置全量通过率仅为 8.3%。这意味着即使是最先进的模型，在追求生产级代码时，每 12 次运行才有 1 次完全达标。
这不是功能实现能力的问题——同一个 Agent 在无约束条件下能轻松通过测试。问题出在约束本身：当 Agent 需要在"代码能跑"和"代码符合架构"之间同时做决策时，它的性能开始崩塌。
数据库指定是最大的隐形杀手
把约束拆开看，不同维度的冲击力差异极大。研究通过匹配对设计，隔离了每种约束的独立影响：
指定数据库引擎是影响最大的单项约束。它带来的性能下降远超架构分层或 ORM 使用。原因在于数据库选择不是孤立的配置项——它会渗透到代码的每一层：连接管理、事务处理、查询语法、错误处理、类型映射——这些细节散布在多个文件中，Agent 在生成过程中很容易在某个文件里偏离正确的数据库实践。
Clean Architecture 分层的约束也有显著影响。这可以理解：它要求 Agent 把代码拆到四个独立目录（路由、服务、模型、数据访问），并维护严格的单向依赖方向。对一个在"一个文件里写完所有逻辑"模式下表现最佳的 Agent 来说，额外增加的跨文件协调负担是实打实的能力损耗。
ORM 约束的影响反而最小。部分 Agent 甚至在有 ORM 约束时表现更好——这可能是因为 ORM 提供了清晰的模式模板，减少了 Agent 在数据访问方式上的决策空间。
框架的隐式约定正在悄悄拖后腿
同一套 API 契约、同一个功能规格，换一个框架就能让 Agent 的测试通过率相差一倍以上。
表现最好的是 Express、Koa 和 Flask——这些框架的 API 面简洁且显式化，没有隐式约定。Agent 不需要猜测框架的行为，直接调用路由函数、返回响应即可。
而 Django 和 FastAPI 则在底部徘徊。Django 的约定驱动结构（自动路由发现、ORM 绑定、应用注册）要求 Agent 同时理解框架内部的自动行为逻辑，这对生成式模型来说是极高的认知负载。FastAPI 的类型注解驱动校验也造成了类似问题——Agent 需要正确定义 Pydantic 模型、理解类型转换规则，一步出错就会导致整个请求链断裂。
Hono 的表现同样不佳，尽管它的 API 面与 Express 相似，但因为它最初面向边缘运行时设计，在 Node.js 上运行时需要兼容适配层——这个设置步骤在训练数据中出现的频率较低，Agent 不太擅长处理。
这揭示了一个反直觉的事实：一个对开发者越友好的框架，对 AI 编码 Agent 越不友好。 框架通过隐式约定降低人类的认知负担，但这些约定恰恰是 Agent 无法"直觉"把握的东西。
失败从来不是因为语法错误
研究者对数百次失败轨迹做了分类分析。结果很清晰：超过 70% 的失败是逻辑错误，而非语法或配置问题。这些逻辑错误中，数据层缺陷占据了近半壁江山。
最突出的两类数据层错误是：
查询逻辑错误：Agent 生成了语义错误的查询（如多表关联时漏掉连接条件、聚合函数使用错误、分页参数不匹配） ORM 运行时违规：Agent 调用了 ORM 中不存在的 API、使用了错误的关系加载策略、或未正确处理事务边界
此外，框架特有行为的误用也占据了相当比例——每个框架都有自己的"坑"：Flask 的请求上下文访问方式、FastAPI 的依赖注入顺序、Django 的查询集惰性求值——Agent 在单一文件生成时能避开这些问题，但在多文件、跨层架构下，这些细节错误开始集中爆发。
"约束衰减"对 AI 应用工程意味着什么
这项研究的一个核心贡献，是把一种业界隐约感知到但从未量化的现象，变成了可测量的工程事实。
在 AI 应用开发的语境下，约束衰减有两个直接启示：
第一，Agent 生成的代码不能跳过结构审查。即使通过全部功能测试，代码也可能在架构合规性、数据层安全性上存在隐患。需要建立独立于功能测试之外的结构验证层——类似研究中使用的静态验证器，自动检查依赖方向、模式约束、ORM 使用规范性。
第二，约束密度与 Agent 能力之间存在明确的工程边界。当前 Agent 适合的工程场景是：功能规格相对完整但结构自由度较高的模块（如独立微服务、无状态接口、原型验证）。一旦涉及多层架构、特定数据库绑定、ORM 集成等生产级要求，就需要引入人工干预节点或分阶段生成策略——先由 Agent 生成功能骨架，再由开发者补充结构细节，而非一次性地把全部约束交给 Agent。
第三，框架选择影响 Agent 生产力。在依赖 AI 编码 Agent 的团队中，选择显式化、轻量级的框架（如 Flask、Express）可以显著降低 Agent 的结构性错误率。当然这不是建议放弃 Django 或 FastAPI，而是说如果团队重度使用编码 Agent，需要在框架选择时把"Agent 友好度"纳入评估维度。
第四，数据层的约束优先级最高，也最容易被 Agent 忽视。如果只做一件事来提升 Agent 生成代码的质量，那就是在约束清单里优先盯住数据库相关的要求——单独验证连接配置、查询语句和事务处理，而不是指望 Agent 在生成过程中自己维护正确性。
这项研究的真正价值不在于给出"Agent 不可靠"的结论——这不是新发现。它在于给出了一个可度量、可复现的约束衰减曲线，让团队在设计 AI 辅助编码流程时，不再凭感觉判断"为什么加了几条要求之后 Agent 就不行了"，而是知道自己踩进了哪一层的约束陷阱。
当你下一次给编码 Agent 追加"用 PostgreSQL，按 Clean Architecture 分层"时，知道测试通过率可能直接腰斩——这不是幻觉，这是约束衰减。
#AI Agent #Agent开发 #LLM应用工程 #AI应用开发 #编码Agent #可靠性与评测 #工程实践
