AI 编程代理产生的架构技术债应如何管理？

AI 编程代理产生的架构技术债，不能只靠代码审查或事后重构管理。代理可以快速生成局部正确的代码，却未必理解系统边界、长期演进路线和跨团队约束。有效做法是把架构规则转成机器可检查的门禁，并将债务作为有负责人、有期限、有业务影响的工程资产持续管理。

什么是架构技术债

代码技术债通常表现为重复逻辑、复杂函数、低覆盖率或命名混乱；架构技术债则影响模块边界、依赖方向、数据所有权、扩展能力、可靠性和安全模型。后者的修复成本更高，因为它会跨越多个组件与团队。

AI 代理并不是唯一成因。业务变化、时间压力、经验不足和历史决策都会产生债务，但代理提高了变更速度，使错误架构决策更快复制到整个系统。

AI 代理为什么容易放大架构债

• 根据当前任务优化局部代码，而忽略全局依赖。
• 缺少未写入上下文的业务规则和历史决策。
• 倾向复制已有模式，包括已经过时的坏模式。
• 为了通过当前测试增加适配层、例外分支和隐藏耦合。
• 并行代理可能各自引入不同抽象和重复能力。
• 生成速度超过人工审查和架构治理能力。

第一步：定义不可破坏的架构约束

在让代理修改代码前，团队应明确少量关键不变量，例如模块只能单向依赖、领域层不得调用基础设施层、敏感数据不得进入日志、跨服务访问必须经过公开接口。

约束要放在仓库中版本化，并附带具体示例。只有会议纪要或架构师脑中的规则，无法稳定进入代理上下文，也难以在代码审查中形成一致标准。

第二步：把规则变成自动门禁

架构风险	可执行检查
依赖方向被破坏	模块依赖测试和禁止导入规则
接口兼容性退化	契约测试和模式兼容检查
数据边界混乱	数据库所有权、迁移和访问策略检查
性能架构退化	基准测试、查询预算和延迟阈值
安全边界被绕过	静态分析、权限测试和秘密扫描
可观测性缺失	日志、指标和追踪字段的契约检查

这些检查可视为架构适应度函数。每次代理提交都必须通过，才能防止架构约束停留在文档层面。

第三步：限制代理的变更范围

高风险任务不应直接让代理跨仓库、跨服务自由修改。应限定允许编辑的目录、接口和依赖，并要求代理在实施前列出受影响组件、数据迁移、回滚路径和验证方式。

对数据库模式、认证授权、公共 API、支付和基础设施等高影响区域，可要求人工批准设计后再实施。自治程度应随变更风险调整，而不是所有任务使用同一种权限。

第四步：记录架构决策

每个重要决策应记录背景、备选方案、选择理由、已知代价和复审条件。代理后续修改时先读取这些记录，才能区分刻意的权衡与偶然的历史实现。

决策记录不能只描述“采用什么”，还要说明“为什么”和“何时应重新评估”。模型、框架或供应商变化后，旧决策可能失效。

第五步：建立技术债台账

发现架构妥协时，不要只留在代码注释中。债务条目至少应包含：

• 受影响的系统和业务能力。
• 形成原因与当前权衡。
• 性能、可靠性、安全或交付风险。
• 触发偿还的条件。
• 负责人、目标时间和预计成本。
• 验证偿还完成的客观指标。

第六步：按业务风险排序

不是所有债务都要立即清零。优先处理可能导致生产事故、安全事件、数据不一致、关键功能交付受阻或供应商锁定的项目。低影响、稳定且隔离良好的债务可以有意识地保留。

排序时同时考虑发生概率、影响范围、修复成本和延迟成本。只有“代码不优雅”但没有可衡量后果的条目，不应挤占关键风险的修复资源。

第七步：为偿债安排固定容量

如果债务只能等待“以后有空”，它通常会持续累积。团队可以预留每个迭代的固定容量，在重大功能前设置架构修复里程碑，或把债务偿还与相关业务功能绑定。

重点不是固定某个百分比，而是让偿债进入正常规划，并能向业务负责人说明它减少了哪些延期、故障和未来成本。

第八步：审查代理产生的系统性变化

单个差异文件可能看起来合理，但多次提交后会形成整体漂移。应周期性检查模块依赖图、公共接口数量、重复实现、数据库访问路径、关键链路延迟和异常处理一致性。

同时审查代理本身的提示词、技能、工具连接和策略文件。这些资产也是开发系统的一部分，需要版本控制、测试、所有权和淘汰流程。

建议跟踪的指标

• 架构规则违规数量与修复时间。
• 跨模块或跨服务变更的平均范围。
• 回滚率、生产缺陷率和变更失败率。
• 重复能力和临时适配层数量。
• 新增依赖与废弃依赖的清理周期。
• 关键架构债务的比例。

不要只用代理生成代码行数或提交数量衡量生产力。产出增加但变更失败率、认知负担和跨模块耦合同步上升，说明速度正在转化为未来成本。

结论

管理 AI 编程代理带来的架构技术债，核心是让代理在明确边界内工作，并让架构约束能够自动执行。文档、门禁、决策记录、债务台账、风险排序和持续度量需要形成闭环。

技术债并非必须为零，但必须可见、可归责、可衡量。团队应保留有战略价值的短期妥协，同时阻止局部生成速度演变成系统级不稳定和长期交付迟缓。