AI Coding 工程化：把 AI 助手变成团队的结对程序员

从「个人玩具」到「团队基建」

AI 编程助手最大的讽刺是：个人开发者用得风生水起，团队一推广就哑火。原因不是工具不行，而是「个人用法」和「团队用法」根本是两回事——个人可以接受 AI 偶尔给个垃圾建议，团队不行；个人不需要考虑代码风格一致性，团队必须；个人不在乎上下文泄露，企业客户在乎。

把 AI 编程从个人玩具变成团队基建，需要在上下文、门禁、度量三个层面做工程化。这篇文章讲我们踩过的坑和最终跑通的方案。

一、上下文工程：AI 写得好不好，90% 取决于喂什么

同一款 AI 工具，新手喂一段需求，老手喂「需求 + 相关文件 + 规范 + 反例」，生成质量的差距是数量级的。

团队级上下文工程分三层：

第一层：项目地图。让 AI 知道仓库里有什么——核心模块结构、入口文件、构建方式。现在主流工具都有 repo map 功能，前提是仓库目录规范。没有规范的多层嵌套仓库，repo map 就是灾难。

第二层：工程规范。命名规范、错误处理约定、数据库访问模式、组件使用惯例——写成 AGENTS.md 或团队规范文件，让 AI 在每次生成前读取。这层是拉开团队差距的关键：我们团队把「规范文档化」后，AI 生成代码的返工率降了一半。

第三层：相关代码。工具自动索引 + 手动指定结合。改一个订单接口时，把订单模块的文件显式带进上下文，比让 AI 自己翻仓库快且准。

一条红线：私有代码、客户数据绝不进云端 AI 的上下文。需要本地模型或私有化部署的场景，提前画清楚边界——这条在合规审计时救过我们两次。

二、门禁设计：AI 的代码必须过三道闸

我们对 AI 生成代码的态度是：AI 写，人审，机器把关。三道闸缺一不可：

1. 代码评审（人工）：AI 最擅长风格一致、逻辑简单的代码；最不擅长边界条件、并发、安全。评审重点就放在这三类问题上，而不是逐行看。一个技巧：让评审人只看 diff，且 diff 里标注 AI 生成的部分。

2. 静态检查 + 安全扫描（自动）：SonarQube 这类工具扫质量问题，Semgrep/SAST 扫注入和密钥泄露。AI 生成代码里最常见的坑是「看起来对的错误」——复制粘贴式的 API 误用，恰好是静态分析最擅长的领域。

3. 测试门禁（自动）：AI 每次提交的代码必须过单元测试和集成测试。我们要求 AI 生成代码时同时生成测试——这不仅是验收手段，测试本身就是给 AI 的反馈信号。

三、度量：没有数据，团队推广 AI 编程就是一场辩论

「AI 编程到底提升了多少效率」——这个问题没有数据就是各说各话。我们最终建立了一套朴素的度量体系：

采纳率：AI 建议被保留的比例。低于 20% 说明上下文没喂好；40% 以上说明流程运转正常。

生成代码占比：合并代码里 AI 生成的比例。目标不是 100%，而是稳定在 30%~50%——全 AI 生成通常是规范缺失的信号。

评审耗时：人均 review 时间变化。这才是效率的真相：AI 让「写」变快，但「审」必须跟上，否则瓶颈转移。

月度复盘看三个数字的联动，比任何「我感觉效率提升了」都有说服力。

四、推广的节奏：试点 → 规范 → 规模化

不要一步到位全团队强制。我们走的路径：

试点期（2 周）：选一个质量意识和工具习惯都好的小组，定规范、建门禁、埋度量。

沉淀期（1 个月）：把试点组踩的坑固化成规范文件——哪些场景 AI 好用（CRUD、测试、文档、重构），哪些场景别用（核心算法、复杂并发、安全敏感逻辑）。

规模化：全团队放开。此时规范、门禁、度量都已就位，新成员进来一周就能上手，而不是三个月后还在问「AI 为什么写得这么烂」。

结语

AI Coding 工程化的本质，是把「个人经验」沉淀成「团队流程」。上下文决定质量上限，门禁守住质量下限，度量让改进有方向。做到这三件事，AI 助手就不再是玩具，而是团队的结对程序员——而且它永远不抱怨加班。