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 文件为参考配置。
# arch-check rules —— 最简 MVC 分层# 依赖方向(全部 error): controller -> service -> dao -> modelgroups: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
![]()
![]()
欢迎留言一起参与讨论~
