# 门禁层：让检查先于代码——约束是文本，门禁是执行

> **AI Harness Engineering  · 第五篇** · 王海涛（公众号：Jia言Yi行 · GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

![00-intro.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/dfe63621672d3ec18c99306019945f8a.jpg)

质量管理之父戴明说过一句让很多工厂主不舒服的话：**"质量不是检查出来的。"** 他主张质量要造进流程里，而不是靠出厂前的检验把关。这句话是对的——但它在 AI 编码时代有一个被忽视的另一面：流程里造进去的质量，恰恰要靠检查来确认它真的被造进去了。戴明反对的是"只靠检查"；他从不反对"有检查"。

AI 编码项目里，检查的地位比任何时代都高。原因在前几篇已经铺垫完了：约束写在文件里（战略、架构、契约），但文件不会自己执行；AI 会读文件，也会在压力和歧义面前悄悄偏离文件。从"约束写下来了"到"代码真这么干了"，中间隔着一道无人看守的峡谷。这一篇讲的就是怎么在峡谷上架桥：**门禁——让检查先于代码。**

---

## 一、旧门禁为什么拦不住 AI 生成的代码

![01-old-gates-fail.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/5d5299a028b067a2f5f308a077f45045.jpg)

传统工程不是没有门禁。CI 里跑编译、跑静态检查、跑测试，这是每个成熟团队的基本盘。但这些门禁有一个共同的假设——**代码是人写的**。

人写的代码有人的特征：会忘、会懒，但不会"自信地编造"。AI 生成的代码，特征完全不同。

几组公开数据足以说明问题：

- **幻觉依赖**：针对 GitHub 仓库 PR 的分析（CodeRabbit，2026 Q1，470 个仓库）发现，约 1/5 的 AI 代码样本包含虚假的库引用——它不是写错，是一本正经地编；
- **功能与安全失衡**：Google Research 2025 盲评数据显示，主流 AI 工具生成代码的语法通过率已达 92%，但逻辑正确率仅 78%，并发、事务、异常分支等复杂场景进一步降至 54%；
- **认知落差**：云安全联盟 CSA（2026 年 4 月）报告显示，45%-70% 的 AI 生成代码未能通过基础安全扫描，而同期的开发者调研中 75% 认为"AI 写的代码比自己写的更安全"。

翻译一下：**AI 生成的代码，语法层面几乎挑不出错，错的都在语义层。** 而传统的 lint、编译、格式检查，全部工作在语法层。

这就是旧门禁失效的本质——你拿着查"错别字"的工具，去查一篇"立意错了"的文章。错别字查得再勤，也拦不下一篇文章用看似通顺的句子说了错的话。

TradeOMS 全周期开发里踩的就是这个坑：早期 CI 全绿、测试全过，但 AI 塞进来的逻辑错误照样混进了主干——把 null 断言写成恒真、把异常吞掉当成功、把"相等"写成"赋值"。语法门禁全过了，语义错误一个没拦下。

## 二、门禁的本质：把"约束"变成"事实"

![02-essence.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/9a49e28bb688f20c72b4bf949e4fc00e.jpg)

先分清楚两个词，这是整套体系的关键：

- **约束**是文本（文件、规范、约定）——它声明"应该怎样"；
- **门禁**是执行（脚本、测试、规则）——它验证"实际怎样"；
- 约束不设门禁，就是空话；门禁不挂约束，就是摆设。

第一篇讲约束金字塔时给过结构：战略层 → 架构层 → 契约层 → **门禁层** → 实现层。当时一笔带过，现在展开——**门禁层是约束金字塔的闭环，没有它，上面四层全是纸。**

门禁的物理形态在 derekcoding-framework 里长这样（可验证的真实结构）：

```
dispatch/
├── gates/            # 门禁脚本（提交前逐项检查）
├── fulltest-system/  # 全量回归测试系统
├── triple-track/     # 三轨制（WBS / Issue / Test Case）
└── swarm/            # 多角色并行评审
tests/
└── fulltest-baseline-R1.md   # 回归基线
```

这套体系的核心不是某个脚本，而是一条纪律：**AI 改完代码不能自己通过，必须跑一套它无法修改的门禁。** 门禁由人定义、由脚本执行、结果由独立机制判定。这条纪律的存在，比任何单个门禁都重要——它承认了 AI 的一个缺陷：AI 没有"自我怀疑"，它对自己的产出永远自信。让一个不怀疑自己的执行者给自己打分，分数永远是满分。

## 三、从五道门禁到六阶段：门禁自己也要进化

![03-six-stages.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/3b01e6bd83d6389ad72d944291a8fd60.jpg)

编码侧沉淀了五道门禁，对应写作侧的同构体系：

| 门禁 | 拦什么 | 实现方式 |
|------|--------|---------|
| G1 风格 | AI 味、不规范模式 | 规则评分器（可量化的五维） |
| G2 结构 | 文档/代码与约束脱节 | 结构一致性检查 |
| G3 事实 | 编造的 API、假断言 | 引用溯源 + 断言有效性 |
| G4 一致性 | 改 A 忘了 B | 涟漪扫描（ripple-scan） |
| G5 独立评审 | 自我放水 | 评审与写作分离 + 反谄媚 |

五道门禁是"发布前"的防线。但门禁本身也会老化：规则库会过时、AI 会找到新的绕法、基线会失真。所以我们把它收敛成一套贯穿全生命周期的六阶段体系——**G0 基线 → G1 编译通过 → G2 三层分析 → G3 涟漪扫描 → G4 复测验证 → G5 经验固化 → G6 签发放行**，从"拦截坏产出"升级为"越用越准的自成长门禁"。

三个设计原则，比门禁清单本身更重要：

**原则一：门禁必须能量化。** "代码质量要高"不是门禁，"首次通过率 ≥70%"才是。不能量化的门禁，等于没有门禁——它无法回归、无法对比、无法改进。

**原则二：门禁是发布前，不是写作中。** 编码时逐行套门禁会扼杀产出，写作时逐句套门禁会扼杀表达。门禁的价值在"拦截"，不在"指导"。

**原则三：失败要有返回路径。** 门禁失败不是终点，是路由——G1 失败回改写、G3 失败回素材阶段、G4 失败回涟漪扫描。没有返回路径的门禁，只会制造"提交被卡死"的挫败感，而挫败感会逼人绕开门禁。

门禁的全部意义，浓缩成一句可带走的话：**检查先于代码，错误就拦在上线之前，而不是事发之后——约束是写下"应该怎样"，门禁是证明"确实这样"。**

## 四、成本账：门禁到底贵不贵

![04-cost.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/e218a197e995bcdfed965902670c4f40.jpg)

这是所有人第一个问的问题：多一套门禁，会不会让开发变慢？

答案是：**门禁在 CI 上跑的时间，比一次人工 review 便宜两个数量级。** 我们在编码框架里测过：五道门禁全量跑完，CI 增加的时间在分钟级；而一次跨模块的人工 review，是小时级。这是门禁最直白的经济账——检查是脚本的事，人只审脚本查不出来的东西。

更关键的是另一本账：**返工成本**。CodeRabbit 2026 Q1 对 470 个 GitHub 仓库 PR 的分析给出一个硬数字：AI 共同创作代码的 bug 率是人类写的 1.7 倍（平均每段 AI 代码 10.83 个问题 vs 人类 6.45 个）。GitHub 官方则披露：平均每个 Copilot 用户提交的代码中 46% 是 AI 生成，Java 开发者更高达 61%。

AI 写得越多，语义风险越大。门禁的钱，不是花在"多跑几秒"上，是花在"把小时级的人工排查，换成分钟级的自动拦截"上。

### 反方怎么看：门禁会不会过重

必须诚实面对一个反方：门禁不是免费的，它可能制造误报，也可能重到扼杀产出。这正是门禁设计的边界问题。

- **误报**：规则太死，会把"正常的 AI 输出"误判为违规，逼 AI 走形式、凑规则，反而降低产出质量；
- **过重**：门禁全堆在提交前，一次提交跑十几分钟，开发者会找捷径绕开它——门禁体系反而名存实亡；
- **矫枉过正**：对着每个函数包 try-catch、每条注释都强制规范，最后代码是"干净"了，但没人在意它干不干得了活。

这三条反方都成立，所以门禁设计的真正难点不在"加多少"，而在"怎么不过度"。对策有两条：

1. **门禁分级**——只对真约束（架构、契约、安全红线）设硬门禁，其余用软提示。硬门禁越少，误报越少，越没人想绕；
2. **门禁自成长**——规则库记录失败模式、基线可调、误报可申诉。门禁不是一锤定音，是越用越准。

一句话总结这门反方的账：**没有门禁，语义错误漏进主干；门禁过重，产出被规则拖垮。健康的门禁在两者之间——只拦语义错误，不拦正常发挥。**

## 五、活的注脚：derekinside 的门禁是什么

![05-derekinside.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/e47966bdaefa82e960b9494e2b0a3b44.jpg)

这套"让检查先于代码"的门禁层，在我那个本地知识库副脑 **derekinside** 里，对应物是知识的入库校验和检索质量门禁。

derekinside 里每一条知识进来，都要过一遍结构校验——chunk 格式对不对、实体关系是否合法、与已有知识是否冲突。知识不是"写进去就算数"，是"校验通过才算数"。这跟代码门禁是同一条纪律：**入口可以宽松，出口必须设卡。** 知识库的质量不是靠"写的时候认真"维持的，是靠"进库的时候检查"维持的——这跟 AI 代码的质量不靠"生成的时候认真"、靠"合并之前检查"是同一个道理。

---

## 六、第一天就能做的三道门禁

![06-checklist.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/7b8a66e0a995b88ee550b2670f9596a6.jpg)

不扯理论，给可直接落地的清单。任何项目今天就能加：

**门禁 1 · 断言有效性检查（拦假阳性）**
扫描 AI 生成测试里"恒真断言"——`assertTrue(true)`、只有覆盖没有断言的用例、吞异常的空 try-catch。一行脚本就能筛出第一批。

**门禁 2 · 引用溯源检查（拦幻觉 API）**
对 AI 引用的一切 API/文档/函数，跑一遍真实存在性校验。CodeRabbit 分析显示约 1/5 的 AI 代码样本带虚假库引用——这一道门禁能拦下绝大多数。

**门禁 3 · 涟漪扫描（拦改 A 忘 B）**
提交前检查改动涉及的所有调用方、配置、契约是否同步更新。规则很简单：**任何跨文件改动，必须列出受影响清单，清单上的每一项都要求"已验证"。**

三道门禁加起来，是几百行脚本 + 一个 pre-commit 钩子的事，当天能上线。

最后回到戴明那句话。他说"质量不是检查出来的"，本意是反对把检查当质量的唯一来源；但 AI 编码时代，这句话应该被翻译成另一句更完整的话：**质量不是检查出来的，但没有检查的质量，是声称出来的。** 约束写下来是第一步，让约束被执行是第二步——门禁就是第二步本身，它让"我们遵守了约束"从一个说法，变成一件事实。

下一篇从金字塔的顶往下走，讲顺序问题：实现层：幂等与退化——接口幂等、降级契约，AI 挂了业务不停。

---

*（《驾驭 AI · AI Harness Engineering》系列第六篇。下一篇：幂等与退化——接口幂等、降级契约，AI 挂了业务不停。）*

---

AI Harness Engineering  · 第五篇 · 王海涛（公众号：Jia言Yi行 · GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

驾驭 AI · AI Harness Engineering ·门禁层设计

AI 编码项目里，检查的地位比任何时代都高。“AI 生成的代码，语法层面几乎挑不出错，错的都在语义层", 旧时代的门禁逻辑变了，该如何立新呢？

 CTO

人工智能

架构设计

开发工具

门禁层通过自动化检查确保AI生成代码符合约束，拦截语义错误而非仅语法问题。核心是让检查先于代码，量化门禁标准，分级设置避免过度，实现从拦截坏产出到自成长体系的进化，最终将质量从声称变为事实。

回归测试

代码解释

云安全

路由

GitHub

Java

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

驾驭 AI · AI Harness Engineering ·门禁层设计-腾讯云开发者社区-腾讯云

驾驭 AI · AI Harness Engineering ·门禁层设计

驾驭 AI · AI Harness Engineering ·门禁层设计

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐