AI 编程助手团队规范落地实录：从个人提效到组织级规则沉淀的踩坑与解法

个人用 AI 编程助手提效立竿见影，但十个人一起用，一个月内就会出问题：每个人一套提示词习惯，AI 生成的代码风格五花八门；有人图快让 AI 直接改完推上主干，评审形同虚设；最危险的一次，新人把测试环境的数据库连接串完整贴进了对话框。问题的根源不是工具不好用，而是「个人技巧」没有升级成「团队规范」。我们花了一个季度把这件事做成了制度，这篇文章把落地过程与踩过的坑完整记录下来。

规范沉淀到哪：三层规则体系

规范散落在 wiki 和口头约定里必然失效，我们的经验是按效力层级分三层，每层都有明确载体：

组织层（公司级，全仓生效）：安全红线与流程底线。内容最少、效力最高——禁止提交未评审的 AI 代码、禁止在提示词中粘贴凭据与客户数据、AI 产出必须经 CI 全量门禁。
项目层（仓库级，随代码版本化）：每个仓库根目录的规则文件（Cursor 用 .cursor/rules，其他工具普遍支持 AGENTS.md 或 CLAUDE.md）。写技术栈约束、目录约定、常见踩坑点。
个人层（编辑器本地）：个人快捷指令与偏好，允许自由发挥，但不得与上两层冲突。

关键设计是项目层规则随代码走 PR 演进：规则改了要过评审，谁都能提议修改，规则文件才不会烂尾。

推行节奏比规范内容更容易被忽视。我们的做法是先找两个对 AI 工具接受度高的项目做「灯塔试点」，四周后拿着他们的规则文件与 PR 数据在全员会议上讲——真实案例的说服力远大于制度宣讲。试点期间还有个意外收获：两位资深工程师主动把各自私藏的提示词技巧贡献进了项目规则，规范从「管理层的要求」变成了「大家共建的工具」，这是推行成败的分水岭。

项目规则文件怎么写：约束而非简介

规则文件最常见的失败形态是写成「项目简介」，三五百行洋洋洒洒，AI 抓不住重点，开发者也不维护。我们的模板收敛在 100 行以内，只写「约束」：

markdown

# AGENTS.md —— 本仓库 AI 协作规则

## 技术栈硬约束
- Vue3 + TypeScript 严格模式 + Vite，状态管理用 Pinia
- 日期处理统一 dayjs，禁止引入 moment
- 样式使用 UnoCSS 原子类，禁止新增全局 CSS 文件

## 代码约定
- 组件 PascalCase，组合式函数 use 前缀，常量 UPPER_SNAKE
- 错误统一走 utils/error.ts 的 handleError，禁止裸 try-catch 吞异常
- 新增第三方依赖必须在 PR 描述说明理由，先查 lock 文件确认未引入

## AI 生成代码的额外要求
- 修改前先通读目标文件，禁止凭猜测改动不相关代码
- 每个新增业务函数附带一个正常分支 + 一个异常分支的 Vitest 用例
- 不确定的需求细节，先列出问题清单向我确认，不要自行假设

三个写作要点：第一，写「禁止/必须」而不是「我们采用」，AI 不需要项目历史课；第二，把团队历史上真实踩过的坑显式列出（如「禁止引入 moment」通常来自一次打包体积事故）；第三，保持精简——规则本身也占上下文，太长会稀释重点，100 行是经验上限。

规则文件还需要一个「回灌」机制：每次 AI 产出出了问题，评审时多问一句「这是不是规则没写住？」，是就把约束补进规则文件。三个月下来我们的规则文件从 40 行长到 80 行，每一条都对应一个真实事故——这样的规则文件才是活的，AI 产出的问题率也随之逐月下降。

把 AI 代码关进评审笼子：PR 门禁与度量

规范里最重要的一条是流程不等式：AI 生成的代码，评审强度只增不减。落地抓手有两个。其一，PR 模板加勾选项，让 AI 参与度透明化：

markdown

<!-- PULL_REQUEST_TEMPLATE.md（节选）-->
- [ ] 本 PR 包含 AI 生成的代码（含 AI 生成的测试）
- [ ] 我已逐行理解并本地验证全部改动（AI 生成的部分尤其如此）
- [ ] AI 生成的测试：我确认断言不是「实现复述」，覆盖了边界与异常分支
- [ ] 未在对话中粘贴任何密钥、凭据、客户数据

其二，CI 侧加硬门槛，不让规范只靠自觉。以下配置在检测到 AI 标记的 PR 时强制更高覆盖率：

yaml

# .github/workflows/quality-gate.yml（节选）
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run test -- --coverage
      - name: AI 参与 PR 的覆盖率门槛
        # 从 PR 描述解析 AI 勾选项，AI 参与的 PR 要求覆盖率不低于 80%
        run: |
          if grep -q "包含 AI 生成的代码" <(gh pr view ${{ github.event.number }} --json body -q .body); then
            node scripts/check-coverage.mjs --min 80
          else
            node scripts/check-coverage.mjs --min 70
          fi

度量方面我们不追「AI 写了多少行」这种虚荣指标，只看三个结果指标：需求平均交付周期、评审驳回率、变更失败率（上线后回滚/热修占比）。试点团队用这组指标对比推广前四周的数据，交付周期下降约三成、变更失败率没有上升，这组数字才是向管理层争取推广预算的依据。

度量还要防「指标游戏」。有人发现 AI 能快速堆代码量后，提交频率翻倍但单次改动变小，交付周期数字变好、实际吞吐没变。所以我们给三个结果指标各配了约束条件：交付周期必须搭配吞吐量一起看，评审驳回率按驳回原因分类统计，变更失败率追溯到灰度发布记录。指标口径每季度回顾一次，防止度量本身变形。

避坑总结

规则文件写成项目百科：超过几百行后 AI 抓不住重点、开发者懒得维护。只写约束与真实踩坑点，控制在 100 行内，随 PR 演进而不是一次性交付。
允许 AI 产出绕过评审直进主干：AI 的「看起来对」和「真的对」之间隔着边界条件与业务上下文。所有 AI 参与的代码必须走 PR + 人审，这是唯一不能妥协的红线。
凭据与客户数据进提示词：对话内容不等于私有。用环境变量注入密钥、用脱敏脚本处理日志样本，把「贴日志前先过 desensitize 脚本」写进组织层规范。
把 AI 生成的测试当质量保证：AI 写的测试容易变成「实现复述」——怎么写就怎么断言，永远通过。覆盖率门槛之上，要求提交者确认断言覆盖了异常分支，必要时抽查变异测试。
没有度量就全量推广：先选一个两周期的试点项目跑四周，拿交付周期、驳回率、失败率的对比数据说话。没数据的推广要么被抵制，要么出了事故一票否决。

AI 编程助手的团队落地，工具选型只占两成，剩下八成是规则沉淀、评审流程与度量体系。把个人技巧变成团队资产，提效才能从「幸运儿个案」变成「组织能力」。

免责声明

本工具与文章内容仅用于学习测试场景，优化建议仅供参考，请勿直接用于生产环境，由此产生的风险自行承担。

AI 编程助手团队规范落地实录：从个人提效到组织级规则沉淀的踩坑与解法 ​

规范沉淀到哪：三层规则体系 ​

项目规则文件怎么写：约束而非简介 ​

把 AI 代码关进评审笼子：PR 门禁与度量 ​

避坑总结 ​

AI 编程助手团队规范落地实录：从个人提效到组织级规则沉淀的踩坑与解法

规范沉淀到哪：三层规则体系

项目规则文件怎么写：约束而非简介

把 AI 代码关进评审笼子：PR 门禁与度量

避坑总结