352 lines
14 KiB
Markdown
352 lines
14 KiB
Markdown
# 敏捷团队 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 自动修复代码风格问题，效果很好 |