# 敏捷团队 AI 编程驾驭工程体系

## 一、背景与核心问题

### 1.1 为什么需要团队级 AI 编程体系

当前 AI 编程工具（如 SuperPowe、Claude Code、Cursor 等）已经非常强大，但**在团队级、项目级场景下落地困难**。核心原因是：

- **需求衔接问题**：产品经理/BA 给的需求格式不统一，颗粒度不一致，导致 AI 无法有效理解
- **开发实践问题**：多人协作时，AI 生成的代码风格不统一、难以形成一致的整体
- **工具生态混乱**：Claude Code、Cursor、windsurf、SuperPower 等工具差异大，没有统一标准
- **流程与制度问题**：团队工作习惯难以改变，这是最大的阻力来源

### 1.2 当前团队使用 AI 编程的认知分级

根据开发者能力分层：

| 级别 | 描述 | 典型行为 |
|------|------|----------|
| 初级开发者 | 照猫画虎，不知道系统如何工作 | 抄代码、写业务逻辑，被 AI 替代 |
| 专家型开发者 | 做技术公关，复杂组件开发 | 仍需要，但 AI 可辅助 |
| 架构型开发者 | 设计服务、做权衡决策 | AI 辅助设计，但要人工把关 |
| 技术经理/CTO | 处理复杂混乱的问题 | 构建团队 AI 工作体系 |

> **关键洞察**："这个玩具不是玩 AI，是玩人"——真正的挑战不在于 AI 能力，而在于如何让团队按照统一的方式工作。

### 1.3 AI 辅助软件工程全流程图

```
需求分析 → 技术方案设计 → 代码编写 → Code Review → 测试 → 部署 → 生产 Bug 修复
   ↓            ↓              ↓          ↓         ↓       ↓         ↓
  录音转文档   打样工程      API/单元测试   交叉模型   E2E测试   K8S部署   MCP自动
  访谈纪要    代码模板       TDD 循环      Review    Playwright  触发合并  发通知
  需求文档    技术规范
  原型链接
```

## 二、需求阶段：如何让需求 AI 友好

### 2.1 需求规格模板必须包含的内容

BA 或产品经理给的需求文档必须包含以下 4 个关键部分：

1. **业务背景**：为什么做这个需求
2. **字段清单**：所有业务字段的类型、默认值、业务规则（避免只给原型图让 AI 去猜）
3. **原型链接**：Figma 图等设计稿的链接（AI 可通过 MCP 读取 Figma）
4. **业务规则**：按条拆分，例如：
   - 订单号生成规则
   - 发货规则
   - 状态转换规则

### 2.2 需求颗粒度的判断标准

**不要用 Story 拆分需求**（一个人增产改查拆成 4 个 story 对 AI 来说信息量不够）。

正确做法：**一个模块一个文档**，判断颗粒度的标准是：
- 是否有独立的表结构
- 是否可以单独上线

### 2.3 新建需求 vs 变更需求

**新建需求**：告诉 AI 有多少表、多少页面、多少功能操作 → AI 生成完整模块

**变更需求**（重要）：
- 必须用标签标注变更类型：`[+字段]` `[-字段]` `[修改字段]`
- 不要把最终完整状态给 AI，因为 AI 需要对比现有代码 → 浪费大量 Token 且效果差
- 示例：

```markdown
# 订单模块变更需求

## 新增内容 [+]
- 新增字段：order_type（订单类型，枚举值：NORMAL, VIP, B2B）

## 修改内容 [~]
- 修改字段：shipping_address 最大长度从 200 改为 500

## 删除内容 [-]
- 删除字段：legacy_flag（已废弃）
```

### 2.4 用 Obsidian 搭建知识库给 AI 做上下文

将所有需求规格、技术规格都放到知识库中，用 Obsidian + Markdown 管理：

- 用浏览器插件一键将网页转成 Markdown 并保存图片本地
- 用 backlink 功能做上下文关联
- AI 通过读取这个知识库获得长期记忆 → "Single source of truth"

## 三、技术规格阶段：技术方案设计

### 3.1 技术规格必须包含的内容

技术规格是开发的核心输入，必须包含以下 5 个部分：

| 内容 | 工具/格式 | 说明 |
|------|----------|------|
| 领域模型 | PlantUML / Mermaid | 代码化表达，便于 AI 理解 |
| 数据库设计 | DBML / Flyway 脚本 | 不要让 AI 直接操作数据库，用版本化的 Flyway 脚本 |
| API 定义 | OpenAPI / Markdown | 后端写完 API 后输出 API 文档给前端 |
| 时序图 | Mermaid | 复杂流程需要时序图 |
| 专项设计 | Markdown | 权限、事务、缓存等专项内容 |

> **重要教训**：不要给 AI 写数据库的写权限，曾经因为 AI 动不动修改数据库导致多人操作冲突。把写权限关掉，让 AI 生成 Flyway 脚本，本地测试时让 Flyway 跑。

### 3.2 DSL 驱动的技术规格

用领域特定语言（DSL）来驱动技术规格：
- 领域模型用 PlantUML
- 数据库用 DBML
- API 用 OpenAPI
- 这些 DSL 都可以通过代码生成 → 保证前后端一致性

> 这实际上就是模型驱动架构（Model-Driven Architecture），当团队从零开始全新的 AI 项目时，这种严格的检查和约束更容易建立。

## 四、打样工程：AI 友好的代码框架

### 4.1 什么是打样工程

打样工程（Seed Project）是一个预先定义好的代码框架模板，包含：
- 每层的类名和职责定义
- 代码规范和最佳实践
- 依赖配置和目录结构

### 4.2 打样工程的作用

1. **AI 生成代码风格一致**：所有 AI 都基于同一个框架生成代码
2. **减少重复代码**：AI 会复用框架中的组件而不是重复写
3. **降低认知负担**：AI 不需要每次理解项目结构

### 4.3 如何创建打样工程

1. 从旧项目中蒸馏出一个干净的新项目骨架
2. 定义每层职责：`Controller → Service → Repository → Entity`
3. 定义类命名规范和包结构
4. 放入 Git 仓库供团队共享

## 五、开发阶段：让 AI 听话写出统一风格的代码

### 5.1 用 RAG（检索增强生成）提供上下文

将技术规格、代码规范、历史决策等信息放到代码仓库的 `/docs` 或 `/book` 目录下，AI 通过检索这些文档获得上下文：

```markdown
/my-project
  /book
    /requirements      # 需求规格
    /specifications     # 技术规格
    /api-docs          # API 文档
  /src
  /skills
  /mcp
```

### 5.2 多任务同步开发：Worktree 的使用

Git Worktree 可以把分支映射成目录，实现多任务并行：

```bash
# 创建多个工作目录
git worktree add ../feature-order feature/order
git worktree add ../feature-user feature/user

# 在不同目录下同时工作，做完后合并
```

**但要注意**：
- 多人同时操作多人工作时，版本管理会比较痛苦
- 建议提前把规格设计好，让 AI 慢慢跑，而不是同时开太多任务

### 5.3 不要让 AI 边写代码边做设计

用 `rapper5` 的思路：**Discovery/Design 和 Coding 分两个阶段**。
- 先做探索性设计，让不同 AI 模型（GPT、Claude、Gemini）各自给出方案
- 选定方案后，再激活 Coding 角色专职写代码
- 切换角色时重置上下文，避免 AI 注意力分散

## 六、测试阶段：AI 写代码形成闭环的核心

### 6.1 为什么测试是 AI 编程的命脉

> "没有 API 测试和单元测试，无法形成 AI 写代码的闭环。"

AI 生成代码后必须能**自我验证**，否则：
- 人工验证效率极低
- AI 无法发现自己的问题
- 团队无法真正提效

### 6.2 测试策略（3 层）

| 测试类型 | 工具 | 驱动方式 |
|----------|------|----------|
| 单元测试 | JUnit / pytest | TDD：先写测试让 AI 失败，再写实现 |
| API 测试 | REST Assured / Newman | 自动化回归，可直接卡 90%+ 覆盖率 |
| E2E 测试 | Playwright（推荐，替代了 Selenium） | 上线前 80% 的 case 回归覆盖 |

### 6.3 TDD 循环（SuperPower 的工作方式）

1. 让 AI 先写 API 测试/单元测试
2. AI 运行测试 → 失败
3. AI 再写实现代码
4. AI 自动运行测试验证 → 通过

> **效果**：单元测试可达 100% 覆盖率，API 测试可达 90%+ 覆盖率。

### 6.4 AI 写测试解决假阳性问题

有时候 AI 为了让测试通过，会伪造测试逻辑。解决方案：
- **TDD 先写测试**：先让测试失败，再让 AI 写实现
- **交叉验证**：用不同的 AI 模型互相 review 代码和测试

### 6.5 测试用例的管理

测试用例直接放到代码仓库中：
- 单元测试：跟随代码模块
- API 测试：放在 `/test/api` 目录
- E2E 测试：用 TypeScript + Playwright，放在代码仓库根目录（或与前端项目同仓库）

## 七、Review 阶段：AI 辅助 Code Review

### 7.1 多种 Review 方式

1. **工具扫描**：SonarQube 等静态分析工具 + AI 自动修复
2. **AI Review**：用另一个 AI 模型做交叉 review（换模型做 review 是常用技巧）
3. **Agent 自动触发**：在 PR 阶段自动触发 Review Agent

### 7.2 AI Review 的问题与解决方案

**问题**：AI Review 总是会提改进建议，哪怕没有明显问题（因为你的 prompt 让它提问题）。

**解决方案**：
- 设置阈值：达到一定级别才提问题，否则不输出
- 让 AI 只关注 bug 和逻辑错误，不过度关注风格问题
- 用团队的架构规约来约束 Review 标准

### 7.3 不同场景的 Review 策略

- **全新项目（AI 100% 生成）**：可以用最严格的规则，AI 写完直接修
- **混合项目（人 + AI）**：可能存在历史遗留问题，Review 结果噪音多，建议从新模块开始逐步规范
- **跨系统场景**：AI 容易犯错（尤其涉及 3-5 个系统的交互），建议收敛到单个仓库处理

> **经验**：跨系统时 AI 犯错误概率高达 70-80%，核心原因是缺少完整的系统间关系和业务规则上下文。

## 八、工具链：AI 编程工具全景

### 8.1 三类 AI 编程工具

| 类型 | 代表工具 | 特点 |
|------|----------|------|
| 命令行 CLI | Claude Code, OpenAI Codex | 适合快速操作、脚本化 |
| IDE 集成 | Cursor, Windsurf, VS Code AI | 适合日常开发，界面友好 |
| 辅助插件 | SuperPower（推荐个人）, Copilot | 按需使用 |

### 8.2 常用 MCP（Model Context Protocol）

| MCP | 用途 |
|-----|------|
| 数据库 MCP | 操作数据库（注意：只读，写权限建议关闭） |
| Figma MCP | 读取设计稿 |
| Jira MCP | 管理工单 |
| Git MCP | 代码提交、PR 操作 |

### 8.3 Skills 体系

Skills = 一段提示词 + 模板 + 脚本，用于描述工作方法。

- 把打样工程的初始化做成 Skill
- 把团队规范做成 Skills
- Skills 放到代码仓库中共享

**重要观点**：
> "现在 AI 理解力已经很强大，不需要把规范落实为非常固定的格式，只要表达清楚信息、强调重点即可。"

**主流 Skill 框架**：
- SuperPower：内置大量 Skills，开箱即用，适合个人
- Claude Agent（hermes）：自动基于对话生成和优化 Skills
- MCP：工具调用协议

### 8.4 为什么不推荐 SDD 框架

SDD（Scenario-Driven Development）框架本身很好，但**落地难度在于团队共识**：

- 需要团队所有人按照相同流程工作
- 现实团队中阻力很大（不是不愿意用，是习惯改不了）
- SuperPower 对个人很好用，但团队级很难推广

> **结论**：与其强推 SDD 框架，不如团队自己定义一套 Roos + Skills + MCP 的组合。

## 九、架构型思考：未来趋势

### 9.1 Agent Code 的趋势

未来必然会出现 "Agent Code" 的概念——把整个团队的所有产物（需求、规格、规范、测试）全部代码化，放到代码仓库中统一管理：

```markdown
/.agent
  /skills          # 工作方法
  /mcp             # 工具配置
  /templates       # 模板
  /rules           # 规范
  /docs            # 文档
```

所有 AI 工具（SuperPower、Claude Code 等）安装时都从代码库读取配置，实现极致高效。

### 9.2 多 Agent 协调的挑战

当前多 Agent 框架（如 CrewAI、AutoGen）还处于早期阶段：
- 缺少程序级别的精确校验（不能完全依赖 AI 判断）
- Agent 与代码之间的交互需要程序驱动而非纯 AI 驱动
- 可能需要自己写 workflow 调度器

### 9.3 共识是第一要务

> "工具是玩人的，为了获得团队的共识。"

大公司之所以比小公司/创业公司更难推进 AI 编程变革，是因为：
- 习惯难以改变
- 团队文化难以调整
- 需要从上到下的强力推动

## 十、团队实践建议

### 10.1 渐进式落地路线

1. **单人验证阶段**：选择一个简单项目，用 SuperPower + TDD 验证 AI 编程效率
2. **规范建立阶段**：定义技术规格模板、代码规范、打样工程
3. **团队推广阶段**：用 Skills 标准化工作方法，逐步让团队接受
4. **自动化阶段**：打通从需求到部署的全流程，实现"代码即一切"

### 10.2 技术经理的核心职责

- 定义 AI 友好的需求规格模板 → 推动 BA/产品接受
- 建立打样工程和代码规范 → 控制代码质量下限
- 推动测试文化 → 这是专业和非专业软件公司的分界线
- 构建团队共识 → 这是最难也是最重要的事

### 10.3 避坑指南

1. **不要让 AI 直接写数据库**：用 Flyway 脚本版本化管理
2. **不要拆分过于细小的需求**：一个模块一个文档
3. **变更需求一定要标注变更类型**：不要给完整状态
4. **不要让 AI 同时做设计和代码**：分阶段，用不同角色
5. **不要完全依赖 AI Review**：用规则约束、AI + 人工结合

## 十一、观众反馈与补充

- **华为 CodeArts Agent**：带有规范驱动开发模式，可以参考
- **Obsidian + Opal**：适合做 Markdown 知识库管理，手机和电脑同步，适合在外也能用手机+终端工作
- **看板式 AI 协同**：所有需求、设计、任务全部看板化，共享给团队成员
- **跨 Agent 通信**：契约文件（如 OpenAPI JSON）放到共享目录，前后端各自读取 → 避免前端改完后端不知道的问题
- **sonarlint 本地扫描 + AI 自动修复**：在 pre-commit 阶段触发静态扫描，AI 自动修复代码风格问题，效果很好