AI Coding 玩了一年，最大的坑是—没人管它

本准则是团队 AI Coding 体系化落地的总纲，所有成员必须阅读并遵守。 部署到代码仓库后，各角色 MD 文件即为 AI Agent 的"员工手册"，AI 自动读取、自动约束。

一、为什么要有这份准则

AI Coding 不是装个插件就完事。

没有统一规范，AI 就是散兵游勇——每个人用的工具不同、规范不同、经验不互通，AI 产出的代码质量参差不齐，甚至可能引入安全问题。

我们需要的不是"AI 写代码"，而是 "AI 在规则框内写代码"。

本准则定义的就是这个"规则框"。

二、核心公式

AI Coding 落地 = 

   统一工具 × MD 规范 × 统一 Skill × (Vibe + Spec) 双模式驱动

四样配齐，AI Coding 才不是玩具，是工程化的生产力。

三、双模式驱动：Vibe × Spec

Vibe Coding（探索模式，自由编程）

• 你跟 AI 说"帮我写个支付接口"，它凭上下文感觉写
• 适用：原型验证、技术调研、单模块小改动
• 要求：产出物标注 [vibe]，不能直接合入主分支

Spec Coding（规范模式，约束编程）

• 先把需求、约束、边界写清楚，AI 在规则框里干活
• 必须切 Spec 的场景：
• 改动涉及 2 个以上模块
• 涉及资金/支付/交易逻辑
• 涉及安全/权限/数据隐私
• 涉及公共接口或跨团队依赖

拿不准的时候，默认走 Spec。宁可多写一行 Spec，不要少一个回滚。

四、MD 规范体系：AI 的"员工手册"

MD 文件是整个体系的契约层。AI Agent 启动时自动读取，自动约束。

4.1 文件结构

retail-platform/
├── 通用规范.md        ← 所有角色必读，团队宪法
├── services/
│   └── xxx-service/
│       └── 后端.md    ← 后端开发者 + AI Agent 读取
├── frontend/
│   └── 前端.md        ← 前端开发者 + AI Agent 读取
├── tests/
│   └── 测试.md        ← 测试人员 + AI Agent 读取
├── docs/pm/
│   └── 产品经理.md     ← PM + AI Agent 读取
└── infra/
    └── 运维.md        ← 运维 + AI Agent 读取

4.2 继承关系

                ┌─────────────┐
                │  通用规范.md  │  ← 所有人遵守
                │  团队宪法    │
                └──────┬──────┘
                       │ 继承
        ┌──────┬───────┼───────┬──────┐
        ▼      ▼       ▼       ▼      ▼
    ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
    │前端.md││后端.md││测试.md││PM.md ││运维.md│
    │组件规范││安全红线││覆盖策略││Spec模板││部署红线│
    └──────┘└──────┘└──────┘└──────┘└──────┘
    

   通用继承 + 角色差异，每个角色只看两份文件即可

4.3 各角色规范速览

4.4 MD 是代码，不是文档

• ✅ 进版本控制
• ✅ 走 PR Review
• ✅ 持续迭代
• ✅ 和业务代码同等对待
• ❌ 不是写完就束之高阁的"文档"
• ❌ 不是"参考一下就好"的"建议"

规范不在多，在于被执行。MD 进了版本控制、走了 Review，才有约束力。

五、统一 Skill 体系：能力复用

5.1 两层 Skill

┌─────────────────────────────────────────────────────┐
│              行业标杆 Skill                          │
│  社区验证 · 拿来就用 · 解决通用问题                    │
│  ① -Agent 并行 Code Review（安全/性能/逻辑/风格/测试）│
│  ② Spec Workflow（需求澄清→拆规格→出计划→写代码）      │
│  ③ Planning with Files（AI规划持久化，长任务不失忆）    │
│  ④ Superpowers（社区顶级Skill包，提升整体编码质量）     │
├─────────────────────────────────────────────────────┤
│              团队自沉淀 Skill                         │
│  老员工判断力 → AI 决策树 · 人走经验不走                │
│  ① retail-code-review（交易安全红线、幂等校验、库存一致性）│
│  ② payment-gateway-onboarding（新增支付渠道标准模板）   │
│  ③ api-standard（统一响应格式、错误码、版本管理）       │
└─────────────────────────────────────────────────────┘
                    ↓
          通用问题靠社区，业务特有问题靠自己
                两层叠加，遗漏率大幅下降

5.2 Skill 触发规则

六、统一工具：Claude Code + Qoder

全员统一使用 Claude Code + Qoder。

为什么必须统一？

• 工具不同 → 经验不互通 → 规范无法落地
• 工具统一 → 同一语境 → 经验可沉淀 → 规范有载体

工具分工

工具决定你能走多快，统一决定你能走多远。

七、全员必读清单

每位成员加入团队后，必须完成以下步骤：

Step 1：阅读通用规范

• x读完 通用规范.md，理解双模式规则和全局红线 x特别关注"禁止事项"部分（P0 级违反即事故）

Step 2：阅读角色规范

• x读完自己角色对应的 MD 文件 x后端：重点理解支付安全红线 x前端：重点理解组件规范和性能要求 x测试：重点理解测试分层和 AI 测试规则 xPM：重点理解 Spec 模板和质量自检清单 x运维：重点理解部署检查清单和应急响应流程

Step 3：配置工具

• x安装 Claude Code + Qoder x确认 AI Agent 能自动读取对应目录的 MD 文件 x安装团队约定的 Skill 包

Step 4：首次实操

• x用 Vibe 模式完成一个探索性任务 x用 Spec 模式完成一个正式交付任务 x推一个 PR，使用 Code Review Skill 审查

八、治理机制

8.1 规范迭代

• MD 文件和业务代码一样，走 PR + Review
• 任何人可以提议修改规范，但必须说明原因和影响范围
• 每月 Review 一次规范体系的完整性和时效性

8.2 Skill 沉淀

• 发现新的重复性工作 → 提议沉淀为 Skill
• Skill 编写遵循统一模板：触发场景、执行步骤、产出标准
• 新 Skill 必须经过 3 次实际验证才能合入团队库

8.3 违规处理

• P0 违规：立即修复 + 事故复盘
• P1 违规：PR 打回 + 补充规范说明
• 重复违规：更新 MD 文件或 Skill，堵住规则漏洞
• 目标不是惩罚，是让规范自动防呆

九、效果衡量

我们怎么知道这套体系起效了？

十、文件索引

本准则是活的文档，随团队实践持续迭代。 有问题、有建议，提 PR。规范不是限制，是让 AI 和人协作的通用语言。