AI 写代码越来越快,谁来守住章法?
胡嘉乐 2026-11-17 18:01 浙江

AI 拉高了写代码的速度,于是必须有等比例的“约束机制”把质量兜住

这是2026年的第 82 篇文章
( 本文阅读时间:约 10 分钟 )
引言:
AI 写得快,但产出的是“狗屎代码”
Uncle Bob 在 8 月的一期直播中抛出一个判断:AI Agent 写代码确实快,但快不过它制造混乱的速度,产出常常是“狗屎代码”(messy code)。在不拒绝 AI 的前提下,他的解法是给 AI 套上确定性的约束。也就是用 CRAP 分数、环复杂度卡住代码质量,用变异测试验证测试本身够不够硬,再搭一条多代理流水线——Specifier 出题、Coder 写、Cleaner 清理、Hardener 加固、QA 验收,让几个 Agent 互相制约。
这场直播表达的核心观点可以概括为:AI 拉高了写代码的速度,于是必须有等比例的“约束机制”把质量兜住,否则速度就是负债。
01
痛点:AI 让“乱”通货膨胀
写代码的成本正在趋零,这意味着什么?意味着“乱代码”的产能也在指数级上升。要知道,以前一个人乱,是一个人的产能;现在 AI 来乱,是十倍的产能;而且 AI 乱代码有几个非常典型的模式,几乎每个用过 AI 写代码的人都见过。
1.1 功能实现为最高优先级,AI 才不管什么分包分层设计

AI 往往只关注如何完成用户要求的功能,它未必了解项目的分层分包规范,对于个人维护的演示项目,这个问题尚可控制;但面向生产环境的项目如果缺少分层分包设计,代码仓库的腐化速度可想而知。
1.2 方法签名参数越来越多,补丁越打越多


Feature 迭代总是打补丁,总是在往一个方法里面加参数,总是在往一个方法体中加 if else 逻辑,AI 写代码只要能跑就行,方法的入参只会越来越多,if else 的嵌套也只会越来越多。
1.3 注释越写越长
当注释中混入 ADR、PR 链接等信息时,AI 生成的注释会越来越冗长。注释与代码不一致,还可能误导 AI 的后续判断。

AI 特别喜欢写注释,这些注释中还会夹杂用户的澄清话术、ADR 以及 PR 的相关信息,有时甚至包含 AI 的思考过程。当 AI 写的注释和代码实现的逻辑不一致时,只会给 AI 带来更多的噪声。
1.4 AI 其实“不听话”

明明已经在 CLAUDE.md 中标明了,AI 必须先完成代码审查,才能提交代码,可是为什么总是写着写着 AI 就会忘记了呢?这是因为,AI 存在幻觉,由于注意力机制的存在,当 Agent 的上下文越来越大的时候,注意力会被稀释,也就可能导致 AI 的表现变差。
02
思路:规则要硬,提示要明
2.1 规则要硬:制定架构分层规则
首先回答一个前置问题:AI 为什么不能像人一样“天然”知道该怎么分包分层?答案很朴素,因为它的上下文里没有。Architect.md 就是在 AI 的上下文中告诉 AI 该如何分层分包。


上图是 Architect.md 的片段,这份文件是项目架构规范的唯一真相来源。它基于真实项目结构,逐一定义了每个领域分包的职责边界,并把分层规则固化成几条硬约束:通用能力下沉到基础层(foundation),业务层只能向下调用领域层的组件与方法,反向依赖即视为违规。但有规范文件还不够,AI 看不到就不会用。因此我们在项目级 CLAUDE.md 中追加一条约束:AI 执行任何编码任务前,必须先读取并遵循 Architect.md。这一步把“代码该往哪放、依赖怎么走”从 AI 的猜测变成显式引导,让它按规范而非惯例产出代码。
2.2 提示要明:报错信息要告诉 AI 下一步怎么做
为了把问题说得更具体,我们切换一个更小的场景。当用户跑一段脚本,报错了,拿着堆栈去查原因,一个有经验的程序员看到 NullPointerException 会本能地做下一步:跳到报错行号,逐个审视这一行上哪些字段可能为空,顺藤摸瓜定位到上游哪里没赋值。这套动作对人是条件反射,程序员往往不会把这套排查步骤写成文档,因为这些步骤对他们来说太过显而易见。
但 AI 看到同样的堆栈,只会看到一串文本。除非我们在报错信息里明写“请检查第 N 行的字段空值来源”,否则它不会自动触发这套排查链路——它不缺少分析能力,但缺少“遇到 NPE 该先做什么”的默认动作。凡是希望交给 AI 的任务,都应把下一步操作写在 AI 最先能看到的地方;人靠经验补齐的隐式动作,AI 必须靠显式指令补齐。

上述脚本挂在 git hook 的 pre-push 阶段。每当我们执行 git push,脚本会先介入检测;若质量门通过标记不存在或已过期,就拦截本次推送,并在报错信息里把话说完——质量门检测没有通过,并直接附上 AI 接下来该做的事,Step 1、Step 2 依次写清楚。如此一来,AI 拿到报错的第一时间就知道按序往下做,不必再猜测推送被拦截后该如何处理。
03
实战:ARCH-CHECK 如何给 AI 约法三章
基于上述思路,我们在真实项目中使用 ARCH-CHECK,将架构与代码规范转化为可执行的约束,用环复杂度卡住代码质量。下面介绍我们在真实项目中使用的工具:ARCH-CHECK。
3.1 ARCH-CHECK 工作流程
前文把方法论归结为一句话:给 AI 套上确定性的约束。ARCH-CHECK 就是这句话的产品化。一个 Maven 插件,把 Java 项目的架构与代码规则写成一份 YAML,并针对编译产物执行检查;一旦违规,它不只 fail 掉这次 build,还会把“下一步该做什么”直接写进违规信息,引导 AI 接着修。

3.2 ARCH-CHECK 如何使用
快速开始
1.在项目根目录的 pom.xml 中添加以下 Maven 插件配置。
<plugin><groupId>com.anyi</groupId><artifactId>arch-check-maven-plugin</artifactId><version>xxx</version><configuration><rulesFile>${maven.multiModuleProjectDirectory}/.arch-check.yml</rulesFile><report>text</report><failOnError>true</failOnError><verbose>true</verbose></configuration><executions><execution><id>arch-check</id><phase>compile</phase><goals><goal>arch-check</goal></goals></execution></executions></plugin>
2.在项目根目录新建 .arch-check.yml 文件。
注意:需要将 group 的分包名称修改为你当前项目的分包结构和名称,下面的 yml 文件为参考配置。
groups:controller: com.example.shop.controller..service: com.example.shop.service..dao: com.example.shop.dao..model: com.example.shop.model..forbidden:- name: model-must-not-depend-on-othersseverity: errorfrom: { group: [model] }to: { group: [controller, service, dao] }comment: >-Step 1: find the controller/service/dao types imported by the <from> classes.Step 2: move them up into the proper layer; model keeps only pure data.- name: dao-must-not-depend-on-serviceseverity: errorfrom: { group: [dao] }to: { group: [service, controller] }comment: >-Step 1: locate the imports of service/controller types inside dao.Step 2: move the business logic up to service; dao keeps only SQL/mapping.- name: service-must-not-depend-on-controllerseverity: errorfrom: { group: [service] }to: { group: [controller] }comment: >-Step 1: move the shared type down to model or dao,and let controller call service forward.- name: no-circular-dependenciesseverity: errorfrom: { group: [any] }to: { group: [any], circular: true }comment: >-Step 1: trace the cycle to find the A->B and B->A edges.Step 2: sink the shared types into a lower layer to remove the bidirectional reference.methods:- name: all-packages-max-5-paramsseverity: erroron: { group: [any] }assert: { maxParams: 5 }comment: >-Step 1: find the method whose parameter count exceeds the limit.Step 2: collapse the loose parameters into a single Request/Param object.messages:forbidden: "Violation: {from} depends on forbidden target {to}. {comment}"too-many-params: "Method {method} has too many parameters (limit {limit}, actual {actual}). {comment}"
3.执行 mvn compile 触发架构分层分包校验。
3.3 ARCH-CHECK 提供什么能力
3.3.1 forbidden:反向依赖即红线
From 组依赖 to 组即视为违规,例如领域层(core 层)不能反向依赖业务层(biz 层)的代码。检测到违规时,工具会同时输出 comment 中的修复指引,告诉 AI 下一步该做什么。这里指引信息的 Step 1(Step 1: consult the repo-root Architect.md (Layer Model / Dependency Rules / Directory Layout / Common Tasks) for the authoritative layering & packaging rules, and follow its placement before moving any type.)和上文的 Architect.md 文件相呼应。
forbidden:- name: model-must-not-depend-on-othersseverity: errorfrom: { group: [model] }to: { group: [controller, service, dao] }comment: >-Step 1: consult the repo-root Architect.md (layer model / directory layout)for the authoritative layering rules before moving any type.Step 2: find the controller/service/dao types imported by the <from> classes,and move them up into the proper layer;model keeps only pure data — no business types.
3.3.2 methods:方法签名参数个数限制
下面的规则对所有分组生效,所有方法签名都不允许超过 5 个参数,如果超过了则需要将这些参数抽象为 Request DTO 等等。
methods:- name: all-packages-max-5-paramscomment: >-Step 1: find the methodwhoseparametercountexceedsthelimit.Step 2: collapse the loose parameters into a single Request/Param DTOplaced in the appropriate layer, so the signature becomes (Request request).severity: erroron: { group: [any] }assert:maxParams: 5
3.3.3 calls:连“调哪个 API”都能禁
例如,在生产项目中,应避免直接通过 java.util.concurrent.Executors 的工厂方法创建线程池,而应使用业务统一管理的线程池。
calls:- name: no-executors-directseverity: warnfrom: { group: [service] }to: { member: "java.util.concurrent.Executors#new*" }comment: >-Step 1: find the raw Executors.newXxx call site reported in the violation.Step 2: replace it with a bounded shared thread pool,and pass the pool explicitly — never the implicit ForkJoinPool.commonPool.
3.3.4 types:拒绝太大的类
当领域层或业务层中的某个类超过 900 行时,就该考虑拆分类或者提取方法了。
types:- name: no-large-classseverity: warnon: { group: [any] }assert: { maxLinesOfClass: 900 }comment: >-Step 1: find the classwhosebodylinespan (bytecodeLineNumberTable) exceedsthelimit.Step 2: split the class by responsibility, or extract collaborators.(bytecode approximation, threshold intentionally lenient)
3.3.5 comments:减少多余注释
六种注释坏味道:被注释掉的代码、空/占位、复述代码的废话、过期 javadoc、过长行注释、过长 javadoc。
comments:excludes:- "model/"- "enums/"rules:- name: no-commented-out-codeseverity: errorcomment: "Step 1: dead code — delete or restore; note — keep it and state WHY."- name: no-empty-placeholderseverity: errorcomment: "Step 1: delete the empty/TODO comment, or state WHY."- name: no-restating-commentsseverity: errorcomment: "Step 1: delete it, or rewrite as WHY — not HOW."- name: no-stale-javadocseverity: errorcomment: "Step 1: sync or remove the javadoc tags that mismatch the signature."- name: no-long-line-commentsseverity: errormaxLines: 2comment: "Step 1: condense consecutive // lines into ≤ 2 lines of WHY."- name: no-long-javadocseverity: errormaxLines: 2comment: "Step 1: shrink the javadoc prose to ≤ 2 lines; keep the @tags."
3.3.6 duplication:降低代码重复度
使用 pmd-plugin 计算整个代码仓库的代码重复度,当重复率超阈值时,这段 comment 随违规一起输出。Step 1、Step 2 说白了就一句——定位重复代码,提取公共方法或基类,再修改各处调用,消除重复实现。
duplication:maxRate: 10comment: >-Step 1: locate the Duplicate block in the report (file/line, redundant lines).Step 2: extract the duplicated logic into a shared method in the proper layer,or consolidate the near-identical classes.
3.4 ARCH-CHECK 实战效果
3.4.1 mvn compile/verify 强卡点

3.4.2 方法签名参数过多,抽取通用方法

3.4.3 方法嵌套层数过多,抽取方法解耦

3.4.4 多余注释简化

04
从“写代码”走向“定规矩”
AI 时代,整洁代码之道越发重要。代码落在哪一层、一个方法调哪条 API、一段重复代码怎么抽——这些事 AI 比新手写得快,也比新手写得齐。但它永远回答不了另一组问题:层为什么这么划?哪条依赖永远不许反向?Executors 为什么必须禁?参数上限定 5 还是 50?报错时,该如何告诉 AI 下一步做什么? 前一组是执行,后一组是规矩。执行正在被 AI 接走,但规矩没有,也接不走。规矩背后不是知识,是判断,是这个团队踩过的坑、是这个系统不能承受的事故、是“这次先这么定,出事了算我的”的那份担当。 所以你会发现一个越来越反直觉的事实:AI 写得越自由,规矩就得越硬。
以前的约束是软绵绵的,比如写在 Wiki 里、挂在嘴上、靠 code review 里的眼力。这套在人身上勉强够用,因为人会累、会不好意思、会被你盯着。可 AI 不会。它 24 小时满产能,唯一的刹车就是你给它的确定性栅栏。栅栏越不硬,它就越跑越快,你就越被它造的乱代码淹没。
人的位置因此往上挪了一格。不再亲手写每一行代码,转而写那 100 行左右、约束 AI 的 YAML:给层起名、给依赖划线、给方法定阈值、给 API 点名封杀、给报错配一句“下一步该做什么”。这 100 行看着少,分量却比以前写的任何 1000 行业务代码都重,因为它管的是 AI 接下来写的 10 万行。 ARCH-CHECK 这类工具,本质就是给人准备的这把椅子:我们坐在上面,决定要守住哪些规则,AI 在防线里自由跑。谁画赛道、谁在上面跑,分得越来越清。
延伸阅读
用于快速代码库理解的系统模板:https://architecture.md/
Matt Pocock 对话 Uncle Bob 直播回顾(YouTube):https://www.youtube.com/watch?v=zcLPGC-tvgk


欢迎留言一起参与讨论~
本文转载自微信公众号「阿里技术」,查看原文。版权归原作者所有,如有侵权请联系删除。