团队 AI 编程公约
✅ 必做
- 每个项目根目录有 CLAUDE.md（架构 / 风格 / 红线）
- PR 描述里说明 AI 介入程度
- 关键改动有自动化测试覆盖
- 使用规范的 commit message（不写"更新代码"等泛化）
⚠️ 建议
- 大改动前先写 spec，再让 AI 实现
- 多轮对话太长时主动开新会话 + 同步上下文
- 同一类需求维护团队 prompt 模板
- 定期复盘 AI 误用案例，沉淀到知识库
❌ 禁止
- 把生产数据 / 密钥 / 客户信息粘进 prompt
- AI 写完未读直接 commit / merge
- Code Review 完全外包给 AI（必须有人类终审）
- 用 AI 绕过权限 / 安全检查（如 --no-verify）
AI 辅助编程工具正在深刻改变软件团队的工作方式。然而，工具的引入如果缺乏规范，往往会带来混乱：代码质量参差不齐、安全风险暗藏其中、责任归属模糊不清。本公约旨在为团队建立一套清晰、可落地的 AI 编程使用框架，让每位成员都能高效、安全、负责任地使用 AI 工具。
一、公约的核心原则
AI 是助手，不是决策者。 所有由 AI 生成的代码，在合并到主干之前，必须经过有资质的工程师审查并承担责任。AI 可以提高生产力，但不能替代工程判断力。
透明优于隐晦。 团队成员应主动说明哪些部分借助了 AI 生成，包括在 PR 描述中注明、在代码注释中标记关键 AI 生成段落。这不是羞耻，而是专业素养的体现。
安全红线不可逾越。 无论 AI 给出何种建议，涉及安全、隐私、合规的决策必须经过人工审核，不得直接采纳 AI 输出。
二、使用边界定义
允许使用的场景
| 场景 | 说明 |
|---|---|
| 样板代码生成 | CRUD、DTO、接口骨架等重复性代码 |
| 单元测试编写 | 基于已有逻辑生成测试用例 |
| 文档与注释 | 函数说明、API 文档草稿 |
| 代码重构辅助 | 在人工主导下完成模式识别与替换 |
| 调试思路提示 | 分析错误堆栈、提供排查方向 |
| 技术方案调研 | 汇总技术背景，辅助技术选型讨论 |
需要谨慎使用的场景
- 核心业务逻辑：AI 生成的业务规则必须逐行核对，确认与产品需求一致。
- 数据库迁移脚本：AI 生成后需经 DBA 或资深工程师二次确认，在测试环境验证后方可执行。
- 第三方 API 集成：AI 可能使用已废弃的 SDK 版本或错误的认证方式，必须对照官方文档核实。
禁止使用的场景
- 将包含真实用户数据、内部密钥、客户信息的代码片段粘贴至公共 AI 服务（如 ChatGPT 网页版）。
- 使用 AI 直接生成用于生产环境的加密、认证或权限控制代码，不经人工审核直接部署。
- 以 AI 生成的合规性声明代替法律或安全团队的正式审查。
三、责任分配框架
AI 生成代码引入了一个关键问题：谁来负责？本团队采用如下原则：
提交者负责制。 将 AI 生成代码提交到代码库的工程师，对该代码承担与手写代码相同的责任。"这是 AI 写的"不构成免责理由。
审查者连带责任。 审查者批准了包含 AI 生成代码的 PR，即意味着认可该代码满足质量标准。审查者不得以"AI 生成"为由降低审查标准。
Tech Lead 兜底职责。 Tech Lead 负责确认团队遵循本公约，并在发现系统性问题时推动公约修订。每季度至少复盘一次 AI 工具使用情况。
以下是可直接复用的 PR 描述模板，所有含 AI 辅助代码的 PR 必须包含此部分：
markdown
## AI 辅助说明
- **使用工具**：GitHub Copilot / Claude / Cursor 等
- **AI 生成比例**：约 xx%
- **AI 参与的模块**：[列出文件或功能]
- **人工校验情况**：[描述校验方式，如单元测试、手动测试]
- **已知风险点**：[若有，列出需要重点关注的地方]四、强制审查规则
以下情形下，AI 生成的代码必须经过至少一名有经验工程师的审查，不得自我批准（Self-approve）：
- 涉及用户认证、权限校验、Session 管理的代码
- 涉及支付、订单、财务数据的处理逻辑
- 数据库 Schema 变更及迁移脚本
- 对外暴露的 API 接口定义
- 配置文件与环境变量处理逻辑
- 任何涉及文件系统写操作或系统命令执行的代码
对于上述场景，PR 标题须包含 [AI-ASSISTED] 标签，以便 Reviewer 重点关注。
提交者自检清单
在提交包含 AI 辅助代码的 PR 之前，请逐项确认：
✓ 理解代码的每一行逻辑，能向他人解释
✓ 验证关键路径的行为（手动测试或自动化测试）
✓ 确认无硬编码密钥、真实凭证、个人数据
✓ 确认符合团队编码规范（命名、注释、错误处理）
✓ 已在 PR 描述中标注 AI 辅助说明
✓ 所有 AI 调用的外部 API 已通过官方文档核实存在五、工具标准化
推荐工具栈
为减少工具碎片化，团队统一使用以下工具集：
| 类型 | 推荐工具 | 备注 |
|---|---|---|
| IDE 内联补全 | GitHub Copilot（企业版） | 团队统一订阅，便于安全管理 |
| 对话式编程 | Claude Teams / ChatGPT Enterprise | 数据不用于模型训练 |
| CLI Agent | Claude Code | 复杂多文件重构场景 |
| 代码审查辅助 | CodeRabbit / PR-Agent | 集成至 CI，结论仅供参考 |
| 离线/敏感项目 | Ollama + 本地模型 | 代码不离开本地网络 |
工具使用登记制度
团队成员引入新的 AI 工具前，须在团队工具登记表中申请，说明：
- 使用场景
- 数据流向（代码是否上传至第三方服务器）
- 数据留存政策与隐私条款链接
未登记工具不得用于处理内部代码库。个人免费账号的使用需特别谨慎，因其数据政策通常允许将内容用于模型训练。
六、数据隐私指南
分级处理原则
| 数据类型 | 可用于公共 AI 服务 | 可用于私有部署 AI | 禁止 AI 处理 |
|---|---|---|---|
| 开源或示例代码 | 是 | 是 | — |
| 内部业务逻辑代码 | 否 | 是（需审批） | — |
| 含用户 PII 的数据或代码 | 否 | 否 | 生产数据 |
| API 密钥、密码、证书 | 否 | 否 | 所有环境 |
| 未公开的产品规划 | 否 | 否（视情况） | — |
操作规范
在向 AI 工具提问前，检查代码片段中是否包含硬编码的密钥或真实数据，如有则先替换为占位符再提问。可在项目根目录配置 AI 工具的忽略文件（如 .cursorignore），排除 .env、证书文件、数据 dump 等敏感路径，避免这些文件被意外纳入 AI 上下文。
如发现 AI 工具的提示词或代码片段被意外上传至第三方，立即联系安全团队，并记录事件经过与时间线。
七、公约模板
以下是可直接复制到项目中使用的公约模板：
markdown
# [项目名称] AI 编程使用公约 v1.0
生效日期：YYYY-MM-DD
技术负责人：[姓名]
## 使用原则
1. AI 是辅助工具，开发者对所有提交代码负完全责任
2. 所有 AI 辅助代码必须在 PR 中注明
3. 安全敏感模块（鉴权、支付）禁止直接使用 AI 生成代码
## 允许工具
- IDE 补全：GitHub Copilot（企业版）
- 对话：Claude Teams 版
## 禁止行为
- 将生产数据输入任何 AI 工具
- 跳过 Review 直接合并 AI 生成代码
## 违规处理
- 首次：技术负责人谈话 + 记录
- 再次：上报工程经理
## 修订记录
| 版本 | 日期 | 变更说明 |
|------|------|----------|
| 1.0 | YYYY-MM-DD | 初版发布 |八、公约的更新与执行
本公约不是一成不变的。随着 AI 工具的快速演进，规范也需要持续迭代：
- 修订周期：每季度由 Tech Lead 组织一次公约回顾，收集团队反馈，评估是否需要更新。
- 例外申请：如有合理理由需要偏离本公约，须提前向 Tech Lead 提出申请并记录在案，不得事后补报。
- 违规处理：初次违规以反馈和教育为主；情节严重或重复违规（尤其是数据安全相关）须上报工程经理。
- 写入 Onboarding：本公约应作为新人入职材料的必读内容，由导师在第一周内完成讲解。
本公约的目标不是限制 AI 工具的使用，而是确保团队在使用 AI 的过程中保持工程严谨性与专业责任感。好的工具需要好的使用规范，才能真正发挥价值。